8.4 KiB

Raw Blame History

The Container Component (app/container)

The container component is the most basic building block for icingaweb. Even when displaying an empty controller, you always have at least two containers in your viewport which are implicitly created: The main and the detail container.

Container handle the following tasks:

Updating the url part responsible for the container
Handling Url changes like they occur when the browser history is used by synchronizing their content with the associated Url part
Informing subcomponents about changes in the container

The Container Api

You can find the sourcecode for containers along with jsdoc comments at ./public/js/icinga/components/container.js. Here we will discuss the most important calls and their synopsis:

Accessing Containers:

The container component returns a 'Container' object which allows you to access responsible containers for dom nodes via the following methods:

using new Container($myDomNodes) which returns a stateless container object wrapping the container responsible for the first node in $myDomNodes
using Container.getMainContainer() or Container.getDetailContainer() which remove the main or detail container (this one is stateful with a few notes, read on)

Note: new Container($('#icingamain')) != Container.getMainContainer(), but (new Container($('#icingamain'))).containerDom == Container.getMainContainer().containerDom

** Example #1 getting the container responsible for a dom node **

HTML

<div id="icingamain">
    <div class="myNode">
        Some kind of node
    </div>
    <div id="somecontainer" data-icinga-component="app/container">
        <div class="mySecondNode">
            Some other kind of node
            <p>
                Insert your lorem ipsum here
            </p>
        </div>
    </div>
</div>

JS:

require(['jquery', 'app/container'], function($, Container) {
    var firstContainer = new Container($('.myNode')); // firstContainer wraps '#icingamain'
    var mainContainer = Container.getMainContainer(); // also wraps '#icingamain'
    var secondContainer = new Container($('.myNode p')); // #somecontainer is wrapped by secondContainer

    firstContainer.someProperty = 'What a nice property!';
    mainContainer.someState = 'I have some state';
    console.log(firstContainer.someProperty);              // return 'What a nice property'
    console.log(main.someProperty);                        // return 'undefined'
    console.log(Container.getMainContainer().someState)    // return 'I have some state' when page hasn't been refreshed
});

Containers And The Browser Url

As noted before (and indicated by the getMainContainer() and getDetailContainer() function), the main and detail container have a special role. Considering the following Url:

http://my.monitoringhost.org/icingaweb/monitoring/list/host?page=4&detail=%2Fmonitoring%2Fshow%2Fhost%3Fhost%3Dlocalhost

This URL displays the 4th page of your host list in the main container (monitoring/list/host?page=4) and the host information for localhost in the detail container (monitoring/show/host?host=localhost). When you split this Url up in logical pieces it looks like this:

http://my.monitoringhost.org/icingaweb/monitoring/list/host?page=4&detail=%2Fmonitoring%2Fshow%2Fhost%3Fhost%3Dlocalhost
\___________  _______________________/\_________  ______________/ \_  ____/\________________  _______________________/
            \/                                  \/                  \/                      \/
        1. Base URL              2.Main container URL and Query   3.Detail param       4. Encoded detail URL and params

Base URL : I don't think this needs much explanation.
Main container URL and query : This is the normal part of your Url and denotes the controller route that is being displayed in your main container
Detail parameter: This parameter will be ignored by the main container and used for rendering the detail container, if omitted there's simple no detail view to be displayed 4 Encoded detail URL: The value of the "detail" parameter is the Url (without the base Url) that returns the content of the detail area

Updating A Container's Url

If you want your container to display content from a different Url, you can use the replaceDomFromUrl() on your Container object:

Example #2 Updating A Containers URL

HTML:

<div id="icingamain">
    <div id"mainSub"></div>
</div>
<div id="icingadetail">
    <div id"detailSub"></div>
</div>

JS:

// this loads the page with the new main container
require(['jquery', 'app/container'], function($, Container) {
    new Container('#mainSub').replaceDomFormUrl('/another/url');
}

// this loads the page with the new detail container
require(['jquery', 'app/container'], function($, Container) {
    new Container('#detailSub').replaceDomFormUrl('/another/url');
}

// this does NOT work:
require(['jquery', 'app/container'], function($, Container) {
    Container.getMainContainer().replaceDomFormUrl('/another/url');
    // will never be reached due to a reload
    Container.getMainContainer().replaceDomFormUrl('/another/url2');
}

// this loads the page with both main and detail changed (this is rarely needed and should be avoided)
require(['icinga', 'jquery', 'app/container'], function('Icinga', $, Container) {
    // it's better to use this:
    var mainContainer = Container.getMainContainer();
    var detailContainer = Container.getDetailContainer();

    mainContainer.updateContainerHref('/another/url'); // first update the main container href
    detailContainer.updateContainerHref('/another/url2');   // update the detail href

    var url = mainContainer.getContainerHref(detailContainer.getContainerHref()); // fetch the new url
    Icinga.replaceBodyFromUrl(url); // and update manual
}

This results in the URL changing to './another/url?detail=%2Fanother%2Fdetail%2Furl. The advantage of using a Container instance with the subelements (i.e. '#mainSub') over calling getMain/DetailContainer directly is that you don't need to know in what container your view is displayed - when you move 'mainSub' into the detail container, the detail container would be updated afterwards.

NOTE: You should read the '...' section in order to understand why you shouldn't do it like in this example

How container refresh states are handled

If you refresh containers content (load url or replace dom), the container displaya a loading mask as default behaviour. To disable this mask and handle it yourself, you can register own events:

Example #3 Load indicator events

require(['icinga', 'jquery', 'app/container'], function('Icinga', $, Container) {
    var mainContainer = Container.getMainContainer();

    // Detach the default behaviour from container
    mainContainer.removeDefaultLoadIndicator();

    var showFunction = function() {
        console.log('container is loading');
    };

    var hideFunction = function() {
        console.log('container content refreshed');
    };

    // Install new handlers
    mainContainer.registerOnShowLoadIndicator(showFunction);
    mainContainer.registerOnHideLoadIndicator(hideFunction);
};

Example #4 Use this for your components

Please have a look into components documentation for detailed information about components.

define(['components/app/container', 'jquery', 'logging', 'URIjs/URI', 'URIjs/URITemplate'],
function(Container, $, logger, URI) {
    "use strict";

    /**
     * Master/Detail grid component handling history, link behaviour, selection (@TODO 3788) and updates of
     * grids
     *
     * @param {HTMLElement} The outer element to apply the behaviour on
     */
    return function(gridDomNode) {
        /**
         * Constructor method for this component
         */
        this.construct = function(target) {
            // Container object for the component
            this.container = new Container(target);

            // Detach default handlers
            this.container.removeDefaultLoadIndicator();
        };

        this.construct(gridDomNode);
    };
};

8.4 KiB Raw Blame History