4.8 KiB

Raw Blame History

Frontend components

Frontend components are JavaScript modules that can be required directly through the HTML markup of your view, to provide additional functionality for the user. Although its best practice to make all features available without JavaScript, these components can be used to provide a richer and more comfortable user experience in case JavaScript is available.

There is a certain set of frontend components which come directly with the Icinga2-Web core application, but it is also possible to define new components directly in Icinga2-Web modules.

How do components work?

Components are defined in JavaScript files that provide a set of functionality that will be added to the targeted HTML node. Icinga2-Web uses RequireJS to load all frontend components, so each frontend component is in fact defined exactly like a RequireJS-Module .

The important difference to plain RequireJS is, that the loading and execution of these components is done automatically through the HTML markup. The attribute data-icinga-component in a DIV element will indicate that this element is a container for a frontend component and will trigger the component loader to create a component instance for this HTML node. The component loader keeps track of all available components and makes it possible to retrieve this instance when needed.

Component names

A component name consists of two parts: the namespace and the name of the component itself. The component is named exactly like its JavaScript file, while the namespace is the name of the Icinga2-Web module that contains the component. Each Icinga2-Web module can contain its own components in the folder public/js.

<module>/<component>

NOTE: The namespace used for modules defined in the Icinga2-Web core application is "app". In opposition to the modules the core application keeps its modules located in public/js/icinga/components instead of public/js.

Example Names

The full name for the component modules/monitoring/public/js/someComponent.js in the module "monitoring" would be:

"monitoring/someComponent"

The full component name for the component public/js/icinga/components/datetime.js in the Icinga2-Web core application would:

"app/datetime"

Creating a component

As described in the chapters above, components are defined exactly like RequireJS modules, but with the additional requirement that they must always return a class constructor. The component below will search all date pickers, set the time format and create a JavaScript date picker when there is no native one available.

/**
 * Ensures that our date/time controls will work on every browser (natively or javascript based)
 */
define(['jquery', 'datetimepicker'], function($) {
    "use strict";

    var DateTimePicker = function(target) {
        $(target).find('.datetime input')
            .attr('data-format', 'yyyy-MM-dd hh:mm:ss');

        $(target).find('.datetime')
            .addClass('input-append')
            .append('<span class="add-on">' +
                '<i data-time-icon="icon-time" data-date-icon="icon-calendar"></i></span>')
            .datetimepicker();
    };
    return DateTimePicker;
});

Loading a component

The following code will load the module datetime, which will ensure that there is always a datetime-picker with right time-format available.

<div id="date-time-picker" data-icinga-component="app/datetime">

    <div class="datetime">
        <input data-format="dd/MM/yyyy hh:mm:ss" type="text"/>
    </div>

</div>

Component ids

When an ID is assigned to the HTML element, it will be used by the component loader to reference this component. Otherwise an ID in the form "icinga-component-<ID>" will be created and the ID attribute in the HTML Element will be updated accordingly.

Component "target"

The div-element with the data-icinga-component will be used as the "target" for the loaded component, which means that the component will perform its actions on this HTML node.

Retrieving a component

Sometimes it can be necessary to retrieve the instances of the components itself, for example when they implement additional functions that can be called. The component loader is available in the Icinga object and can be used to retrieve component instances using their ID or their full component name.

By component id

var component = Icinga.components.getById("component-id");
component.doSomething();

By full component name

var components = Icinga.components.getByType("app/datetime");
// ... do something with every component of the type app/datetime

All components

var components = Icinga.components.getComponents();
// ... do something with every component

4.8 KiB Raw Blame History