2. Generic CSBL JS Pre-defined Functions and Variables

Valid for any JavaScript in: Full Custom CSBL and CSBL Visual Editor.

In order to make easier for the user to implement basic/fundamental operations which can be useful to send, receive and manage data in the Snap4City CSBL approach, some pre-defined variables and functions have been implemented, which can be used as a sort of function library inside the JavaScript code. First of all, the following CSBL standard JavaScript variables have been defined for every widget (thus, with a scope limited to the code related to each single widget):

• e represents a JSON of parameters and data coming from each widget (for instance, the SURI or array of SURI passed when clicking on a widget graphic element, map, etc., see table in Section 5.1 for reference about data and parameter format sent by each widget) and that may be passed to a pre-defined function after the occurrence of an event, as well as used in your own custom JavaScript;
• connections represent a JSON mapping the connections for each widget.

The pre-defined functions, with details about their parameters, a short description, and a list of supported widget events that can exploit the specific function, are listed in the following table.

Pre-defined function	Parameters and supported OutputTypes	Description	Supported Events Sect. 3.1
sendSURI (<PORT_NAME>, <JSON_DATA>)	<PORT_NAME>: name of the output port to which data are sent <JSON_DATA>:_data related to a single Snap4City Service URI which are sent to the output port specified by <PORT_NAME>. It is typically assigned the value of the pre-defined e variable, as above described. Supported OutputTypes: SURI	Send data, as passed in the <JSON_DATA> parameter (e.g.: high-level type, metric etc.) related to a single Snap4City Service URI to be sent to the output port specified by the parameter <PORT_NAME>	click
sendListSURIAndMetrics (<PORT_NAME>, <JSON_DATA>)	<PORT_NAME>: name of the output port to which data are sent <JSON_DATA>:_data related to an array of multiple Snap4City Service URI which are sent to the output port specified by <PORT_NAME>. It is typically assigned the value of the pre-defined e variable, as above described. Supported OutputTypes: ListSURI	Send data, as passed in the <JSON_DATA> parameter (e.g.: high-level type, metric etc.) related to an array of multiple Snap4City Service URI to be sent to the output port specified by the parameter <PORT_NAME>	legend_item_click
sendMapSURI (<PORT_NAME>, <JSON_DATA>)	<PORT_NAME>: name of the output port to which data are sent <JSON_DATA>:_data related to a single Snap4City Service URI which are sent to the output port specified by <PORT_NAME>. It is typically assigned the value of the pre-defined e variable, as above described. Supported OutputTypes: ListSURI	Send data, as passed in the <JSON_DATA> parameter (e.g.: high-level type, metric etc.) related to an array of multiple Snap4City Service URI (formatted in a specific way for the widgetMap), to be sent to the output port specified by the parameter	click   geo_drill_down
sendTimeRange (<PORT_NAME>, <JSON_DATA>)	<PORT_NAME>: name of the output port to which data are sent <JSON_DATA>: time interval (specified by lower and upper timestamp, t1 and t2 respectively, in Unix milliseconds) sent to the output port specified by <PORT_NAME>. It is typically assigned the value of the pre-defined e variable, as above described. Supported OutputTypes: DateTime, DateTimeInterval	Send time interval, specified in the <JSON_DATA> parameter (in Unix milliseconds) which is typically used to zoom temporal view in widgetCurvedLineSeries	time_zoom   reset_zoom

We can observe from the above table that the user has only to specify the output port name (<PORT_NAME>), since the correct <JSON_DATA> is automatically passed to the pre-defined JavaScript variable. Therefore, handling the correct data format, which may be the most difficult part for non-technically skilled users, is completely transparent to the user.

As an alternative, you can implement your custom CSBL by writing directly JavaScript code from scratch in the CKEditor of the widget (see next Section 4), which can be accessed in the “More Options” tab of the widget in the dashboard editor mode

2.1 Macro functions on CSBL JavaScript for Widgets and dashboards’s connections

Other functions which can be exploited on Actions JavaScript segments:

• Open a New Dashboard: openNewDashboard()
• Get parameters: getParams()
• Etc. other

In this manner, it is possible to activate in a new dashboard some actions on specific elements.

This means that you can from a Dashboard with CSBL JavaScript embedded into a Widget to Open a different dashboard passing to it a parameter, which is in turn passed to the JavaScript into the Widgets. So that the new dashboard can show any kind of data and services according to the parameter received. This approach can be performed to create dashboards focused on showing data for devices of a given type, and receive the specific device ID to focus only by the parameter.

It is assumed that you need to create a system of interfaces (dashboard) that allow the following interaction: Following an event launched by a widget in dashboard A, dashboard B opens and is given the parameters necessary for a widget in dashboard B to retrieve data and display it. 

See Section 9 for an example with call and called dashboard.

2.2 - Time Machine, history of commands as do/undo on Business Intelligence Dashboards

In each dashboard where at least one of its widgets provides a CSBL JavaScript code saved in the CK Editor, the history of all the different actions performed and triggered in the CSBL is locally saved in the browser, until the dashboard is closed. This is done in order to allow the user to come back to different views performed by earlier actions. The history of CSBL actions can be viewed by clicking on the history clock icon which appears in these cases on the top-right corner of the dashboard header.

See Section 8 on the time machine history of commands as do/undo.