fenix-ui-dashboard

FENIX Dashboard

var Dashboard = require('fx-dashboard/start');

var dashboard = new Dashboard({
        uid : "FENIX_resource_uid",
        items : [
            { 
            id : "chart-1",
             /* item configuration goes here */ 
            }, 
            { ... }
        ]
    });

<div data-item='chart-1'></div>

Configuration

Check fx-dashboard/config/config.js to have a look of the default configuration.

Parameter	Type	Default Value	Example	Description
uid	string	-	"UNECA_Education"	FENIX resource uid to use to build the dashboard
version	string	-	1.0	FENIX resource version to use to build the dashboard
el	CSS3 Selector/JavaScript DOM element/jQuery DOM element	-	"#container"	Optional component container. if specified items's will be searched within it otherwise within the whole document.
items	Object	-	-	The dashboard's visualization items to render. Check the Item configuration.
environment	string	'develop'	'production'	Server environment
preProcess	FENIX resource process	-	-	Common initial process to be applied to each dashboard item. Check Process composition flow for more details
postProcess	FENIX resource process	-	-	Common final process to be applied to each dashboard item. Check Process composition flow for more details
filter	FENIX filter plain format. Keys are resource dimensions' id, values are array containing the values to include	-	{ year : ["2002", "2003"], product : ["cod_1", "code_2"] }	Common filter values to be applied to each dashboard item. Check Process composition flow for more details
cache	boolean	false	true	whether or not to use FENIX bridge cache
itemsRegistry	object	{ 'chart': { path: selectorPath + 'chart' }, 'map': { path: selectorPath + 'map' }, 'table': { path: selectorPath + 'table' } }	-	Keyset: plugins' ids. Value: object. path: plugin module path

Item configuration

Parameter	Type	Default Value	Example	Description
id	string	-	"chart-1"	Specifies the visualization item id and its container. The param is used to search for the HTML with the `data-item=:id` attribute within the dashboard `el`. If no `el` is specified the whole document is considered
type	string	-	chart || map || table || box	The visualization item type. For native plugin, rendering process will be proxied to FENIX chart, table, map creators or to FENIX Visualization box accordingly. In case custom plugin are used, specify here the plugin id
config	object	-	-	Configuration proxied to visualization component. Its content is linked to the item `type` configuration. Check FENIX creators documentation for configuration details. (e.g. if `item.type="chart"` than `config` is the FENIX chart creator config)
preProcess	FENIX resource process	-	-	Initial process to be applied to item. Check Process composition flow for more details
postProcess	FENIX resource process	-	-	Final process to be applied to item. Check Process composition flow for more details
filter	FENIX filter plain format. Keys are resource dimensions' id, values are array containing the values to include	-	{ year : ["2002", "2003"], product : ["cod_1", "code_2"] }	Filter values to be applied to item. Check Process composition flow for more details
filterFor	Array of dimensions' id || object: keys are step process rid, values are Array of dimensions' ids	-	["year"]	Used to define what filter values should be applied to the item process. Check Process composition flow

API

//This is an example
dashboard.refresh({...});

• new dashboard( config ) : dashboard creator
• dashboard.refresh( values ) : refresh dashboard items with new filter values (FENIX filter plain format)
• dashboard.on(event, callback[, context]) : pub/sub
• dashboard.dispose() : dispose the dashboard instance

Events

• ready : triggered when the dashboard and all its items are rendered

Process composition flow

FENIX dashboard composes dynamically the FENIX process to be use to retrieve the data for each dashboard item. The FENIX process composition is based on the nature (typeof) of item.filterFor: if it is defined as array or as object.

The request is actually performed by FENIX Bridge, using the process created by the FENIX dashboard

item.filterFor as array

• dashboard.preProcess
• item.preProcess
• calculated filter step from item.filter and item.filterFor
• item.postProcess
• dashboard.postProcess

Example

...

filterFor : ["year"],
    
preProcess : [
    { 
        rid : "step_1",
        ...
    }
    ],

postProcess : [
    { 
        rid : "step_2",
        ...
    }
    ],
...

In the previous example the filter step will be placed between preProcess and postProcess

item.filterFor as object

• dashboard.preProcess
• item.preProcess
• item.postProcess
• dashboard.postProcess

item.filter is now applied as following: given item.filterFor as object, its key set represents the set of step to consider for filtering. Each key of the key set represents in fact a step rid (i.e. the identification of a step). The array relative to each key is used to calculate a FENIX process filter step that will extend the original step.

Example

...

filterFor : {
        step_1 : ["year"],
        step_2 : ["indicator"]
    },
    
preProcess : [
    { 
        rid : "step_1",
        ...
    }
    ],
preProcess : [
    { 
        rid : "step_2",
        ...
    }
    ],
...

In the previous example the filter step will extend step_1 ( for year values) and to step_2 ( for indicator values).

Custom Plugin

Mandatory configuration

Parameter	Type	Default Value	Example	Description
controller	FENIX dashboard instance	-	-	FENIX dashboard that is the controller of the custom plugin
el	CSS3 Selector/JavaScript DOM element/jQuery DOM element	-	"#container"	Plug container.

Mandatory API

• new plugin( config ) : plugin creator
• plugin.refresh( values ) : refresh plugin with new filter values (FENIX filter plain format)
• plugin.on(event, callback[, context]) : pub/sub
• plugin.dispose() : dispose the plugin instance

Events

Trigger Event

A custom event can be triggered from within the plugin using the `trigger` function of the `controller`.

this.controller._trigger(event,data);

// Example use
this.controller._trigger('indicators_ready',{payload: {size: this.model.data.length}});

Handle Event

An event handler is added to the dashboard instance (for which the plugin is registered) using the `on` function.

this.dashboard.on(event, handler);

// Example use
this.dashboard.on('indicators_ready', function (data) {
    if(data.payload.size > 0){
        $(this.el).show();
    }
});