Hawk Framework

List of things

Main concepts

  1. All the widgets need appropriate HTML structure. So they most often consist of two BRM blocks – one, starting of hawk- prefix, is responsible only for working of the widget – some elements must have some CSS properties to make the widget work properly. The second one, starting of std- prefix, is responsible only for some standard appearance of the widget. You should always override only the appearance block.

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.

Ajax Loading Items Manager

Ajax Loading Items Manager is used to load some objects asynchronously from the server. Not all items are loaded – user decides if there should be shown more of them. Some data are passed to the back-end – how many objects should be returned, how many have been loaded yet, if and what filters should be applied and custom bundle which is set by the developer.

Properties (options)

Name Default value Description
path
string
 /ajax/load-items Path to the endpoint which processes the Request and returns a JSON Response with the items that are going to be shown. The Request and Response structure is described below.
itemsPerLoading
integer
 6 Number of items that should be loaded. It is being sent to the server with the Request.
itemsDisplayingType
string
 block CSS value of the display feature which should be applied to the loaded items after they are shown.
bundle
function
 () : {} A function that returns the JS object with extra data that should be sent to the server to prepare appropriate items to return.
itemClass
string
 hawk-ajax-loading-items-manager__item A classname of loaded items. Necessary if items can be being hidden.
buttonClass
string
 hawk-ajax-loading-items-manager__button A classname of button which launches the loading.
contentContainerClass
string
 hawk-ajax-loading-items-manager__content-container A classname of the container where loaded items should be placed in.
loadingLayerClass
string
 hawk-ajax-loading-items-manager__loading-layer A classname of the node that should be shown during loading.
slideSpeed
integer
 400 The speed of expanding the loading items (in miliseconds).
fadeSpeed
integer
 400 The speed of appearing and disappearing of the loaded items (in miliseconds).

Callbacks

Name Arguments Description
appendItems
  • contentContainer
    jQuery object
    Container for items.
  • items
    jQuery object
    Already loaded items as HTML wrapped in jQuery object.
It should append loaded items to container with necessary way.
prepareHTML
  • rawHTML
    string
    Loaded items as raw HTML string
  • items
    JS objects collection
    Loaded items as JS objects collection
It should prepare jQuery object from loaded data (a raw HTML or a JS objects collection) to pass them to appendItems function.
onLoad
  • buttons
    jQuery object
    Buttons launching the loading.
  • contentContainer
    jQuery object
    The element where loaded items are placed in.
It is invoked when items are loaded and placed into content container.
onDone
  • buttons
    jQuery object
    Buttons launching the loading.
  • contentContainer
    jQuery object
    The element where loaded items are placed in.
It is invoked when all items are loaded and placed into content container and there's no more to load.
onError
  • buttons
    jQuery object
    Buttons launching the loading.
  • contentContainer
    jQuery object
    The element where loaded items are placed in.
It is invoked when there an error occurred during loading.

Public methods

Name Arguments Description
isDone
bool
Informs if loading is completed or not.
load
void
  • offset
    integer
    Number of items which should be skipped.
Loads more items by sending a request to the backend.
setFilter
void
  • offset
    integer
    Number of items which should be skipped.
Sets a filter, which should be send with next requests.

Items Manager

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();

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