How To Dev - Development: Client-Side Business Logic

This approach is a prerogative of Snap4City development environment.

• Index: CSBL Client Side Business Logic - Widget Manual for Business Intelligence
• See Client-Side Business Logic Widget Manual: https://www.snap4city.org/download/video/ClientSideBusinessLogic-WidgetManual.pdf

 

In Snap4City, Client-Side Business Logic is a solution to close the loop from user actions and effects on widgets directly on the client side, on the browser. This approach allows to have a separated context for each user since any Business Logic computation is performed on client side at every connection, thus reducing the computational workload on server side. Actually, Client-Side Business Logic, CSBL, and Server-Side Business Logics, SSBL, may be present at the same time behind a Dashboard and thus behind a Business Intelligence / Smart Application. This approach may be used to save some context and share with other users. In CSBL the logic code is formalized in JavaScript only, while in SSBL the logic is formalized in Proc.Logic which is Node-RED plus some JavaScript.

Thus, in CSBL we have IN, OUT and IN/OUT widgets (quite similar to SSBL):

• IN Widgets are those that are prepared to receive some actions/commands from the Users. For example, a click on a button, a click on the map, an action on a synoptic, etc. These IN Widgets can be regarded as Virtual Sensors, and may host JavaScript to specify what the Tools has to do when a certain User Action is performed.
• OUT Widgets are those that are prepared to provide some changes to be shown into the Users’ interface. For example, a view of a barseries on some other data, a rendering of a time series, a rendering of a set of Entities on the map, etc. These OUT Widgets can be regarded as Virtual Actuators.
• IN/OUT Widgets are those that provide capabilities of both IN and OUT Widgets. For example, a map can receive an IN command about a selected PIN, and can receive an OUT command to show a selection of services, devices, etc. These IN/OUT Widgets can be regarded as Virtual Sensors/Actuators.

In the development of the CSBL, the JavaScript code is used, and it is activated by events / actions performed by the User on the IN Widgets. While the OUT Widgets are ready to receive commands from CSBL JavaScript, similarly to what they do when receive commands from SSBL via Web Socket.
The Developers that would like to develop CSBL have to be singularly authorized, please ask to snap4city@disit.org . They will be entitled to go in the widget More Option and to find and edit the CK editor to formalize the JavaScript code according to a specific user manual provided.

Figure: the Dashboard Wizard is used to create widgets in user Dashboards in the context of CSBL.

 

 When working in SSBL, widgets can be created and edited from Node-Red Processing Logic. When working in CSBL context, widgets can be created through the Dashboard Wizard, as shown in the figure here above.

The desired widget type can be chosen from the up-right section of the Wizard showing the available widgets. The desired data source can be chosen from the “Data Sources” table, exploiting the filters on column headers, as well as the text search box in the bottom-right corner of the same table. When the desired choices have been performed, by clicking on the “Next” button a final “Check and Summary” tab is shown for final check. At last, clicking on the “Create widget” magic wand the desired widget(s) are created in the current user dashboard.
In this way, the created widget(s) are in the form of OUT widgets, and they are ready to receive and show data and actions by JavaScript, as described in the table “Commands which are ready to execute from JavaScript” in the next pages.
In order to create IN widgets (those widgets which have this capability are listed in the following table “Users’ Action Description and effects”), an authorized developer can add the desired JavaScript code in the CK Editor box in the widget “More Options” box, as shown in the figure below here. The JavaScript code should be provided as a single JavaScript function named “execute”. Please refer to the specific user manual for more detailed instructions.

Figure: Detail of the CK editor (highlighted in red) in the widget “More Options” box.

 

IN and IN/OUT Widgets which present the possibility of scripting in JavaScript when an action is performed on their graphic user interface are reported in the following table. The performed action by the user provoke the activation of a call back that can be filled in the JavaScript editor of the Widget to formalize the action to be performed. At the action, a number of parameters can be provided. For example, at a click on map the coordinates, etc. Into the JavaScript, the developer can code how this information can be used to command OUT Widgets. Data can also be autonomously recovered by an OUT widget using REST Calls to Smart City API and other activities. Please note that OUT Widget are typically capable of making queries to the Smart City API just sending them the SURI of the Entities to be recovered, etc. This let the developer define a sort of general-purpose widget (i.e., not linked to a specific data source/device) that can retrieve data using API with specific input given at run-time. For example, suppose to have a table widget (IN widget) listing devices and a single pie-chart widget (OUT widget) on a dashboard. After a user’s click on a listed device, the table widget sends the device ServiceURI to the pie-chart widget that can update itself by calling an API to get the data, and show the new information related to the clicked device.

 

IN & IN/OUT Widgets	Users’ Action Description and effects, JavaScript can be associated with
widgetTimeTrend	Drill-Down on time interval selection (zoom), providing, SURI, value name, start and end time stamp
	Reset Drill-Down (under development), returning start datetime, end datetime
	Click on a single time instant, providing time stamp, SURI, value name
	Set start datetime, end datetime without change sources ids (under development)
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)
widgetMap (multidatamap)	Click on a generic point on the map, providing coordinates (under development, currently it works for SSBL)
	Click on a PIN, providing GPS coordinates and ServiceURI of the clicked PIN
	Select the bounding box area shown on the map, and the zoom level in order to perform geographical Drill-Down on the entities (devices identified by SURIs, Points of Interest etc.) which are currently shown on map
widgetPieChart	Click on a sector that identifies the name of a metric, providing: value, timestamp, value name, value type (SURI can be reconstructed)
	click on a sector that identifies a device ID or MyKPI ID, providing: value, timestamp, value name, value type (SURI can be reconstructed)
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)
widgetBarSeries	Click on a bar, providing: value, timestamp, value name, value type (SURI can be reconstructed)
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)
widgetRadarSeries	Click on a radar axis related to a specific metric of a specific Entity Instance (device), providing: value, timestamp, value name, value type (SURI can be reconstructed) – (under development)
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)
widgetCurvedLineSeries (multi series)	Drill-Down on time interval selection (zoom), providing: start and end time stamp, and list of SURI
	Reset Drill-Down (under development), returning start datetime, end datetime
	Click on a single time instant, providing: time stamp, and list of SURI
	Set start datetime, end datetime without change sources ids (under development)
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)
widgetDeviceTable	Click on the action buttons, providing the action type, the corresponding SURI and a list of attributes with their corresponding values
widgetImpulseButton	Click on button as a trigger (no parameters are provided)
widgetOnOffButton	Click on button, providing the new status
widgetKnob	Drag on knob, providing the value selected on the knob
widgetNumericKeyboard	Click on the confirm button, providing the numeric value typed on the keyboard
widgetExternalContent	It hosts on Iframe dynamic: HTML pages, CSS, JS and thus SVG Synoptics. In addition, it may embed static: HTML, JavaScript and CSS, so that it can perform a wide range of actions that can be defined in the HTML/SVG/JS code by the users.
widgetEventTable (see DeviceTable)	Click on the action buttons, providing the action type, the corresponding event SURI and the ordering criteria

OUT and IN/OUT Widgets which present the possibility of receiving commands from JavaScript of IN Widgets are reported in the following table. Each OUT Widget to be controlled has to be identified. The identifier of each Widget is accessible from the More Options of the widget, the so-called Widget name.

 

In most cases, the command to be sent to OUT Widget include a JSON very similar or identical to the JSON to be send to the widget from the Node-RED in the context of writing CSBL. So that, please refer to the same help manual and web pages for the same widgets.
 

OUT & IN/OUT Widgets	Commands which are ready to be executed from Widget according to JavaScript in some IN Widget
widgetPieChart	Receive a JSON containing a list of SURI, metric names and/or values, and show their corresponding values on a Pie Chart graph.
widgetBarSeries	Receive a JSON object containing a list of SURI, metric names and/or values, and show their corresponding values on a Bar graph.
widgetRadarSeries	Receive a JSON object containing a list of SURI, metric names and/or values, and show their corresponding values on a Radar graph.
widgetSingleContent	Receive a SURI and a metric name, or a value, or a text string, and show the corresponding value.
	Receive and show a HTML/JS page
widgetSpeedometer	Receive a SURI and a metric name, or a value, and show the corresponding value on a speedometer graph.
widgetGaugeChart	Receive a SURI and a metric name, or a value, and show the corresponding value on a gauge graph.
widgetTimeTrend	Receive a SURI and a metric name, or a value, and show the corresponding time-series on a line, spline, area or stacked area graph.
	Receive start datetime, end datetime without change sources IDs (under development)
widgetCurvedLineSeries (Multiseries)	Receive a JSON containing a list of SURI, metric names and/or values, and show the corresponding time-series on a line, spline, area or stacked area graph.
	Receive start datetime, end datetime without change sources IDs (under development)
widgetTable	Receive a JSON containing a list SURI, metric names and/or values, and show the corresponding the time-series on a HTML static table.
widgetDeviceTable	Receive a JSON containing a list of SURI representing Entity Instances (IoT devices), and show their related attributes and values on an interactive table which provides action buttons.
widgetMap (multidatamap)	Receive a JSON containing a list of SURI or entities (such as heatmaps, categories of Points of Interest etc.) and show them on an interactive map as clickable markers, dynamic SVG pins, traffic flows, heatmaps etc.
widgetOnOffButton	Receive and show a value representing the status (under development), possible via SSBL
widgetKnob	Receive and show a value (under development), possible via SSBL
widgetNumericKeyboard	Receive and show a value (under development), possible via SSBL
widgetExternalContent	It hosts on Iframe dynamic: HTML pages, CSS, JS and thus SVG Synoptics. In addition, it may embed static: HTML, JavaScript and CSS, so that it can perform a wide range of actions that can be defined in the HTML/SVG/JS code by the users.
widgetEvent	Receive a JSON containing a list of SURI representing events as virtual devices, and show their related attributes (e.g., start and end date) and values on an interactive table which provides action buttons.

 

Other functions which can be exploited on Actions JavaScript segments:

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

In this manner, using the openNewDashboard() function after receiving an event (e.g., an user’s click), it is possible to open a new dashboard and sent to it some parameters. Widgets in the new dashboard can then implement the getParams() function to retrieve the sent data. This approach gives the possibility to implement a kind of template dashboard, where several widgets are included but not linked to specific devices. When the template dashboard is called (with the openNewDashboard() function) its widget can be populated with data (obtained with the getParams() function). The passed data can include a full JSON, such as those used to configure the widget in Node-RED, or simply a list of ServiceURIs of some devices of interest, in which case the widget will use the Snap4City API to get the device measurements.