Hawk Framework

List of things

AJAX Communication

The client-server communication in the framework is very simple. Each component which uses the back-end responses has the appropriate Request and Response structure descripted. The thing that keeps them in the same root is the status field which should take one of the following values informing about the result's state. The communication is always in the JSON format.

Hawk.RequestStatus

Name Value Description
SUCCESS 0 Everything went well.
ERROR 1 There occurred a controlable problem during processing the request. I.e. the data are invalid.
EXCEPTION 2 There occurred an unexpected problem.

Layered section

Layered section

Layered section allows to shift fragment of the website in a elegant way. It is especially useful when there is a special information after sending a form or just making local overlayer for showing details of something.

Well, it is amazing!

This mechanism might be very helpful and useful.

This is another layer.

And you can juggle them as you want.

Every layer is binded with corresponding button through the nameAttribute (data-name by default, look below). Base layer is the special one, which is visible as first and sets the section's size.

  • <section id="exemplary-layered-section" class="hawk-layered-section">
        <div class="hawk-layered-section__base-layer">
            <div class="hawk-layered-section__base-layer-inner">
                <header class="simple-header">
                    <h3 class="subsection-title">
                        Layered section
                    </h3>
                </header>

                <div class="text">
                    <p>
                        <em class="em">Layered section</em> allows to shift
                        fragment of the website in a elegant way. It is especially
                        useful when there is a special information after sending
                        a form or just making local overlayer for showing details
                        of something.
                    </p>
                </div>

                <div class="button-container">
                    <button class="button hawk-layered-section__button" data-name="above">
                        <div class="button__wrapper">
                            <div class="button__inner">
                                Check it out!
                            </div>
                        </div>
                    </button>
                </div>
            </div>
        </div>

        <div class="hawk-layered-section__above-layer" data-name="above">
            <div class="hawk-layered-section__above-layer-inner">
                <!-- some layer -->
            </div>
        </div>

        <div class="hawk-layered-section__above-layer" data-name="another">
            <div class="hawk-layered-section__above-layer-inner">
                <!-- some layer -->

                <div class="button-container">
                    <button class="button hawk-layered-section__button" data-name="base">
                        <div class="button__wrapper">
                            <div class="button__inner">
                                Back to base layer
                            </div>
                        </div>
                    </button>
                </div>
            </div>
        </div>
    </section>
  • var layeredSection = new Hawk.LayeredSection($('#exemplary-layered-section'), {
        // options and callbacks
    });
    layeredSection.run();

Properties (options)

Name Default value Description
containerClass
string
 hawk-layered-section -
baseLayerClass
string
 hawk-layered-section__base-layer -
baseLayerInnerClass
string
 hawk-layered-section__base-layer-inner -
aboveLayerClass
string
 hawk-layered-section__above-layer -
aboveLayerInnerClass
string
 hawk-layered-section__above-layer-inner -
buttonClass
string
 hawk-layered-section__button -
nameAttribute
string
 data-name Layer-pointing attribute's name.
baseLayerName
string
 base Name of the base layer.

Callbacks

Name Arguments Description
onAboveLayerShow
  • layeredSection
    Hawk.LayeredSection
    current Layered Section instance
  • aboveLayer
    jQuery object
    current layer
Is being executed immediately after the layer is shown.

Public methods

Name Arguments Description
showBaseLayer
Hawk.LayeredSection
Shows the base layer.
hideBaseLayer
Hawk.LayeredSection
Hides the base layer.
hideLayers
Hawk.LayeredSection
Hides all the layers.
showLayer
boolean
  • name
    string
    Layer's name.
Shows the indicated layer. Returns true when the layer exists and may be shown or false otherwise.
run
Hawk.LayeredSection
Launches the Layered Section and binds the DOM elements with necessary events.

More content manager

Vestibulum tortor at libero. Pellentesque habitant morbi tristique purus. Integer egestas, nunc faucibus sem pede eget elit.

Aliquam tellus tortor, hendrerit magna sit amet, elementum consequat. Cum sociis natoque penatibus et ultrices posuere quis, porttitor sem luctus metus nonummy enim quis dui. Class aptent taciti sociosqu ad litora torquent per inceptos hymenaeos. Fusce nisl eros, varius egestas, orci ac dolor. Vestibulum dignissim dapibus dui, porta elementum. Nunc arcu nunc pede ac augue nec pede tortor nibh, dignissim massa. Duis luctus

  • <div class="text">
        <p>
        Vestibulum tortor at libero. Pellentesque habitant morbi tristique purus. Integer egestas, nunc faucibus sem pede eget elit. 
        </p>

        <p class="hawk-more-content" data-more-content-manager="1" data-id="1">
            Aliquam tellus tortor, hendrerit magna sit amet, elementum consequat. Cum sociis natoque penatibus et ultrices posuere quis, porttitor sem luctus metus nonummy enim quis dui. Class aptent taciti sociosqu ad litora torquent per inceptos hymenaeos. Fusce nisl eros, varius egestas, orci ac dolor. Vestibulum dignissim dapibus dui, porta elementum. Nunc arcu nunc pede ac augue nec pede tortor nibh, dignissim massa. Duis luctus
        </p>
    </div>

    <div class="button-container">
        <button class="button hawk-more-content-button" data-more-content-manager="1" data-id="1" data-opposite-text="Read less" type="button">
            <div class="button__wrapper">
                <div class="button__inner hawk-more-content-button__content">
                Read more
                </div>
            </div>
        </button>
    </div>
  • var moreContentManager = new Hawk.MoreContentManager(1, {
        // options and callbacks
    });
    moreContentManager.run();

Properties (options)

Name Default value Description
buttonClass
string
 hawk-more-content-button Classname of the button which works with the hidable content.
buttonContentClass
string
 hawk-more-content-button__content Classname of the button's element where the text should be changed after the content is toggled.
contentClass
string
 hawk-more-content Classname of the content which is being toggled by clicking the button.
IDAttrName
string
 data-id Name of the binding button with content attribute.
managerIDAttrName
string
 data-more-content-manager Name of the attribute that indicates the Hawk.MoreContentManager instance which should handle the action. Binded to the button.
buttonOppositeTextAttr
string
 data-opposite-text Name of the attribute which contains the text that is placed in the button when the content is shown.
eventName
string
 click.moreContent Name of the button click event.

Callbacks

Name Arguments Description
actionShow
  • content
    jQuery object
    current content to display
Makes the content visible. Velocity's slideDown by default.
actionHide
  • content
    jQuery object
    current content to disappear
Makes the content hidden. Velocity's slideUp by default.
onShow
  • mcm
    Hawk.MoreContentManager
    current manager instance
  • button
    jQuery object
    -
  • content
    jQuery object
    -
Is being executed immediately when the content starts to show. Changes the button's text to the one from buttonOppositeTextAttr attribute by default.
onHide
  • mcm
    Hawk.MoreContentManager
    current manager instance
  • button
    jQuery object
    -
  • content
    jQuery object
    -
Is being executed immediately when the content starts to hide. Changes the button's text to the initial value by default.

Ajax Overlayer Manager

Ajax Overlayer Manager allows to show some content above the page, i.e. some details about things presented in the text which don't need to be visible all the time. The content that should be displayed on the overlayer is being loaded from the server using the AJAX technology.

This Component needs the special HTML structure at the end of the document. The buttons that launch the mechanism should have the certain form as well. They need to have the ajax-overlayer-button classname (could be changed in the options), the data-id attribute whose value indicates the content to load and the data-overlayer-id that contains the ID of the Ajax Overlayer Manager which should handle the request. They can also have the data-bundle attribute which keeps the extra values being sent to the server. The Bundle is in the inline key=value shape.

  • <button class="button ajax-overlayer-button" type="button" data-overlayer-id="1" data-id="1">
        <div class="button__wrapper">
            <div class="button__inner">
                See the overlayer
            </div>
        </div>
    </button>

    <!-- (...) page's structure goes on -->

    <!-- ...and the overlayer's structure at the end of the body -->

    <section id="overlayer" class="overlayer std-overlayer" data-overlayer-id="1">
        <div class="std-overlayer__wrapper">
            <div class="overlayer__content-container std-overlayer__inner">
                <div class="overlayer__content">

                </div>
            </div>

            <div class="overlayer__close std-overlayer__close ajax-overlayer-close">
                <div class="icon-plus icon-plus--rotated icon-plus--light"></div>
            </div>
        </div>

        <div class="overlayer__loading-layer std-overlayer__loading-layer">
            <div class="icon-loader icon-loader--light icon-loader--animated"></div>
        </div>
    </section>
  • App.Components.DefaultAjaxOverlayerManager = new Hawk.AjaxOverlayerManager($('#overlayer'), {
        // options and callbacks
    });
    App.Components.DefaultAjaxOverlayerManager.run();

Properties (options)

Name Default value Description
path
string
 /ajax/load-overlayer Path to the endpoint which processes the Request and returns a JSON Response with the content that is going to be shown on the layer. The Request and Response structure is descripted below.
mode
Hawk.AjaxOverlayerManagerConstants.Modes
 DEFAULT Click event assignment mode.
fadeSpeed
integer
 200 The speed of the overlayer's appearing and disappearing (in miliseconds).
slideSpeed
integer
 200 The speed of expanding the content on the layer (in miliseconds).
closeOnClickOutside
boolean
 false Whether to close the overlayer when user clicks outside the content's container or not.
eventName
string
 click.ajaxOverlayerManager A name of the JavaScript click event that the Hawk.AjaxOverlayerManager instance should use to control buttons connected with this instance.
popstateEventName
string
 popstate.ajaxOverlayerManager A name of the JavaScript popstate event that the Hawk.AjaxOverlayerManager instance should use to control the browser's back button.
wrapperClass
string
 overlayer__wrapper The class' name of the wrapper.
contentContainerClass
string
 overlayer__content-container The class' name of the content's container.
contentClass
string
 overlayer__content The class' name of the content element.
loadingLayerClass
string
 overlayer__loading-layer The class' name of the layer which is visible when the content is loading.
buttonClass
string
 ajax-overlayer-button The class' name of the elements which open the overlayer. They are descripted wider above.
closeButtonClass
string
 ajax-overlayer-close The class' name of the element which closes the overlayer. This element needs to be inside the overlayer container (may be in the loaded part, though).
baseZIndexValue
integer
 9000 Base value of z-index feature that is being increased and being set for following instances of Hawk.AjaxOverlayerManager.

Callbacks

Name Arguments Description
onLoad
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
  • id
    string
    ID of the loaded content.
  • result
    object
    The whole result object returned by the server.
It is invoked when the content has been loaded.
onLoading
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
  • id
    string
    ID of the loaded content.
  • result
    object
    The whole result object returned by the server.
It is invoked when the AJAX request is completed and the content is going to be changed.
onShow
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
It is invoked when the overlayer is being shown.
onHide
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
It is invoked when the overlayer is being hidden.
onInitialize
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
  • hash
    string
    The value of the window.location.hash
It is invoked when the page has been loaded and the overlayer has already been initialized. It should process the hash and possibly load the appropriate content.
changeContent
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
  • content
    jQuery object
    -
  • callback
    function
    The function that should be invoked when content is placed in the overlayer
It is invoked when the content is going to be put in the overlayer.
hide
  • ajaxOverlayerManager
    Hawk.AjaxOverlayerManager
    Current instance of Hawk.AjaxOverlayerManager
This function hides the overlayer.

Public methods

Name Arguments Description
getOverlayerID
integer
Returns the overlayer's id number.
getLang
string
Returns the language code which is inferred from the lang attribute of the html element.
hide
void
Closes the overlayer.
show
void
Shows the overlayer.
load
void
  • id
    string
    The ID of the content that should be loaded (sent with the Request). Helps the server to return the appropriate result.
  • bundle
    object
    The extra parameters that can be used by the backend service.
Loads the content. Sends the Request to the endpoint defined in the options and shows the overlayer with the already loaded content.
changeContent
void
  • content
    string
    The string containing the HTML code that is going to be shown in the overlayer.
  • callback
    function
    The callback that is being invoked after the content is changed.
Changes the content inside the overlayer.
run
void
Launches the Ajax Overlayer Manager and binds the DOM elements with necessary events.

Request

Name Description
id
string
 The ID of the content that is going to be loaded.
bundle
array
 A bundle of extra values that can be required to load the appropriate content.
lang
string
 The language code that is taken from the lang attribute of html element.

Response

Name Description
status
Hawk.RequestStatus (integer)
 The status of the processed response. See more
html
string
 The HTML content that should be displayed on the overlayer.
id
string
 The ID of the content that is loaded (should be the same as in the Request).

Details List

Details List is very useful to show the detailed content on demand.

  • Quisque iaculis, metus vitae lobortis posuere, purus elit mattis felis?

    Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Maecenas facilisis mi sed lorem posuere, id auctor purus mollis. Quisque iaculis, metus vitae lobortis posuere, purus elit mattis felis, at gravida leo urna sagittis lectus.

  • Suspendisse sollicitudin, lorem in luctus vulputate, dolor nibh venenatis elit?

    Praesent tellus nibh, consequat a euismod ut, malesuada vel nulla. Praesent eu feugiat dui. Curabitur ac aliquam ipsum. Quisque ornare hendrerit augue, sit amet tincidunt tellus porttitor et. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Fusce aliquam nibh ligula, at ultricies nunc aliquet non.

  • <ul id="details-list" class="hawk-details-list">
        <li class="hawk-details-list__item details-list-item">
            <header class="hawk-details-list__header details-list-item__header">
                <h3 class="simple-title simple-title--small">Quisque iaculis, metus vitae lobortis posuere, purus elit mattis felis?</h3>

                <div class="details-list-item__icon-container">
                    <div class="details-list-item__icon icon-arrow icon-arrow--primary icon-arrow--south"></div>
                </div>
            </header>

            <div class="hawk-details-list__content-container details-list-item__content-container">
                <div class="hawk-details-list__content">
                    <div class="text">
                        <p>
                        Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Maecenas facilisis mi sed lorem posuere, id auctor purus mollis. Quisque iaculis, metus vitae lobortis posuere, purus elit mattis felis, at gravida leo urna sagittis lectus.
                        </p>
                    </div>
                </div>
            </div>
        </li>

        <!-- (...) more items -->
    </ul>
  • App.Components.detailsList = new Hawk.DetailsList($('#details-list'), {
        // options and callbacks
    });
    App.Components.detailsList.run();

Properties (options)

Name Default value Description
autoHide
boolean
 true Indicates whether to hide all the currently displayed contents when the new one is going to be visible.

Callbacks

Name Arguments Description
onShow
  • detailsList
    Hawk.DetailsList
    Current instance of Hawk.DetailsList
  • header
    jQuery object
    Current Header element.
  • contentContainer
    jQuery object
    Current Content Container element.
It is invoked when the content is going to be displayed.
onHide
  • detailsList
    Hawk.DetailsList
    Current instance of Hawk.DetailsList
  • header
    jQuery object
    Current Header element.
  • contentContainer
    jQuery object
    Current Content Container element.
It is invoked when the content is going to be hidden.

Public methods

Name Arguments Description
show
void
  • header
    jQuery object
    The header which the content is related with.
Shows the content.
hide
void
  • header
    jQuery object
    The header which the content is related with.
Hides the content.

Sliding layer manager

Sliding layer manager allows to hide the additional content out of the screen and slide it when it's necessary.

Listing 7 HTML code of exemplary sliding layer manager
<section class="hawk-sliding-layer-section" data-sliding-layer-manager="1" data-id="1">
    <!-- some section's content -->

    <section class="hawk-sliding-layer-section__layer">
        <section class="edge-section">
            <div class="edge-section__edge hawk-sliding-layer-section__button" data-sliding-layer-manager="1" data-id="1">
                <div class="edge-section__edge-inner">
                    <button class="button button--static" type="button">
                        <div class="button__wrapper">
                            <div class="button__inner">
                                Open
                            </div>
                        </div>
                    </button>
                </div>
            </div>

            <div class="edge-section__content">
                <!-- some layer's content -->
            </div>
        </section>
    </section>
</section>
Listing 8 sample JS code of use
const slidingLayerManager = new Hawk.SlidingLayerManager(managerID, options);
slidingLayerManager.run();

Ajax Loading Items Manager

Forms

Static Form Sender

Listing 8 sample JS code use of the Hawk.StaticFormSender
const staticFormSender = new Hawk.StaticFormSender($('#exemplary-static-form'), [
    new Hawk.TextFormField("chess-figure-name", {
        validate: Hawk.Validator.isNotEmpty
    })
], (formSender) => {
    const validationResult = formSender.validate();

    if (validationResult.length == 0) {
        const field = formSender.getField('chess-figure-name');
        const value = field.getValue().toLowerCase();
        const chessFigures = [
            'knight', 'queen', 'king', 'bishop', 'tower',
            'skoczek', 'koń', 'hetman', 'król', 'goniec', 'laufer', 'wieża'
        ];

        if (chessFigures.indexOf(value) > -1) {
            formSender.options.onCorrect({
                message: "Ok, great!"
            });
        } else {
            formSender.options.onError({
                message: "Cannot you play chess, really?"
            });
        }
    } else {
        formSender.changeMessage("Please fill the fields correctly.");
    }

    formSender.finishWorking();
});
staticFormSender.run();

Ajax Form Sender

Choose your favourite light figure

Listing 8 sample JS code use of the Hawk.StaticFormSender
const staticFormSender = new Hawk.StaticFormSender($('#exemplary-static-form'), [
    new Hawk.TextFormField("chess-figure-name", {
        validate: Hawk.Validator.isNotEmpty
    })
], (formSender) => {
    const validationResult = formSender.validate();

    if (validationResult.length == 0) {
        const field = formSender.getField('chess-figure-name');
        const value = field.getValue().toLowerCase();
        const chessFigures = [
            'knight', 'queen', 'king', 'bishop', 'tower',
            'skoczek', 'koń', 'hetman', 'król', 'goniec', 'laufer', 'wieża'
        ];

        if (chessFigures.indexOf(value) > -1) {
            formSender.options.onCorrect({
                message: "Ok, great!"
            });
        } else {
            formSender.options.onError({
                message: "Cannot you play chess, really?"
            });
        }
    } else {
        formSender.changeMessage("Please fill the fields correctly.");
    }

    formSender.finishWorking();
});
staticFormSender.run();

Ajax request manager

  • var ajaxRequestContainer = {
        result: $('.simple-ajax-request-container__result'),
        button: $('.simple-ajax-request-container__button')
    };

    var ajaxRequestManager = new Hawk.AjaxRequestManager({
        // options and callbacks
    });

    ajaxRequestContainer.button.click(function() {
        ajaxRequestManager.get("/examples/ajax-request-manager/draw-a-colour", {
            onSuccess: function(result) {
                ajaxRequestContainer.result.html(result.colour);
            },
            onError: function() {
                ajaxRequestContainer.result.html("");
            },
            onException: function() {
                ajaxRequestContainer.result.html("");
            }
        });
    });

Pager

Ajax Items Manager