Custom Sections API

Custom Sections API#

The custom sections JavaScript API provides a means to manage the sections of a dashboard.

Dashboard Sections#

Each dashboard consists of sections, and sections consist of widgets. Sections are essentially pieces of the dashboard grouped by positioning and visibility conditions.

During the lifecycle of a dashboard, upon certain triggers, sections evaluate their visibility condition and either show or hide themselves depending on the results of this evaluation.

Managing Sections#

The easiest way to manipulate sections is through the Dashboard Loaders. All examples below are examples of such loaders, and unless explicitly done so already, are expected to be the bodies of customLoad methods of their respective dashboard loaders.

Sections definition is stored in a Backbone collection encapsulated in the Dashboard model, like so:

loader.js

return Loaders.Base.extend({
    customLoad: function () {
        console.log(this.dashboard.sections.toJSON());
    },
})

By default, every newly dashboard receives a center positioned section with an empty (always evaluating to true) visibility condition. This section can be edited in the Squirro Dashboard Edit UI. Other sections need to be added manually to the sections collection.

Adding Sections#

Since sections are Backbone models, they can be added by their JSON definition, like so:

loader.js

this.dashboard.sections.add({
    widgets: [],           // Required. An array of JSON definitions of widgets inside the section
    pin: 'left',           // Optional. left (sidebar), right (sidebar), or null for center (default)
    condition: 'Assignee'  // Optional. A Squirro Condition determining the visibility, defaults to true (always visible)
})

Defining widgets

The widget definition is a JSON object, which can contain the following properties:

loader.js

this.dashboard.sections.add({
    widgets: [
        {
            type: 'Frequency',          // Required.
            row: 1,                     // Required for center sections only. Grid coordinate.
            col: 1,                     // Required for center sections only. Grid coordinate.
            size_x: 16,                 // Required for center sections only. Width of the widget in grid units.
            size_y: 4,                  // Required for center sections only. Height of the widget in grid units.
            iconClass: 'facets',        // Used optionally for side sections only. Allows defining the icon class of the sidebar button.


            // Any other configuration the widget might require.
            // This is essentially a serialized widget property page. Any standard and custom properties go here.
            // For the list of required properties for each widget, look at Custom Widgets Property Pages.
        },
    ],
})

Pinning Sections

Sections can be pinned either to left or right. If a section is not pinned, it gets positioned in the center of the dashboard.

By pinning a section, a toggle-able sidebar is formed, which displays one widget at a time, and allows switching between widgets using buttons in a column next to the sidebar.

Visibility Conditions#

The visibility condition gets evaluated against two entities, the dashboard query and the dashboard store. This happens automatically during the initial load, and whenever any of them changes.

To construct a visibility condition, a Logic module is provided in the scope of a dashboard loader.

Constructing a Visibility Condition

loader.js

this.dashboard.sections.add({
    widgets: [/*...*/],
    condition: Logic.Condition('Assignee'), // shorthand: "condition: 'Assignee'"
})

The variant above is the easiest form of a visibility condition, which evaluates to true if a facet Assignee has been selected on the dashboard.

The visibility condition language allows also for using operators and nesting conditions. It uses a Polish Notation (operator first) for constructing the conditions.

Consider the following logical statement

statement

Assignee:John OR (Assignee:Mary AND State:CA)

It can be written using the Logic module as a section visibility condition as follows:

loader.js

this.dashboard.sections.add({
    widgets: [/*...*/],
    condition: Logic.Condition(Logic.Or('Assignee:John', Logic.And('Assignee:Mary', 'State:CA'))),
})

The available operators in the Logic module are: Logic.And, Logic.Or, Logic.Not, and the operands can be constructed with Logic.Condition or Logic.Expression.

Using Expressions

The condition engine supports evaluating against expressions too. To take advantage of that, use the Logic.Expression operand constructor.

loader.js

this.dashboard.sections.add({
    widgets: [/*...*/],
    condition: Logic.Condition(Logic.Expression('true')),
})

The Logic.Expression evaluates the string passed as parameter to true or false. By itself, this isn’t useful yet. But Logic.Expression also supports passing in Underscore.js templates, with a few parameters passed into the template as default for convenience, like store.

loader.js

this.dashboard.sections.add({
    widgets: [/*...*/],
    condition: Logic.Condition(Logic.Expression('<%- !!store.get('my_flag') %>')),
})

In this usage, the section will be reactive to changes on the dashboard store, and will show itself (the condition will evaluate to true), whenever the my_flag property has been set on the dashboard store. The store is the global dashboard store, and can be accessed trough all the custom widgets like so:

widget.js

return Widgets.Base.extend({
    customEvents: {
        'click button': '_onButtonClick',
    },


    _onButtonClick: function () {
        this.dashboard.store.set('my_flag', true);
    },
})
Contents