1. Introduction

The following manual has the purpose of describing a feature of the Dashboard Builder which allows some widgets to send or receive actions, events and data through JavaScript code with parameters from other widgets, in order to make them interact with each other.
For example, you may be able to click on a section of a pie chart to extract a piece of data and view it in more detail on a table on another widget, make spatial drill down/drill up on maps, temporal drill down/drill up on time series data etc.

Please refer to the Server-Side Business Logic section on the following document https://www.snap4city.org/download/video/Snap4Tech-Development-Life-Cycle.pdf 
Server-Side Business Logic implies to send commands to the Proc.Logic / IoT App implemented as Node-RED Node.JS processes running on server-side cloud via a visual editor.

---

Please remind that only authorized AreaManager can access at features of the Client-Side Business Logic on Snap4city.org platform, and  they have to perform a request to the administrator by sending an email to snap4city@disit.org : If you need to become an AreaManager, please also ask to the administrator by sending an email to snap4city@disit.org .

---

1.1 Snap4City development environment

This approach is a prerogative of Snap4City development environment.
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 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 Logic, 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 it with other users. In CSBL the logic code is formalized in JavaScript only, while in SSBL the logic is formalized in Processing Logic which is Node-RED plus some JavaScript.

The design and development of the smart application Graphic User Interface, GUI, means to develop views which put in connection the back-office data with some visual representation and provide to the user interactive elements to change the observed view or go for another.

In Snap4City, the views are implemented as Dashboards which are composed by graphical widgets connecting storage on the basis of the Entity Instances, Processing Logic (IoT App) data/nodes in stream, Synoptics, External Services, and Brokers. Widgets can be maps, time trends, chords, spidernet, bar series, tables, buttons, animated elements, sliders, etc., from libraries such as D3 and Highcharts or custom Synoptics widgets by using an SVG-based integrated tool and templates. Moreover, the Dashboard may dress different styles / themes in their rendering and the designer / developer can select them soon or later in the creation process.

The power of the user interface is grounded on the possibility of easily connecting the graphic widgets with the Entity Instances in a smart interactive manner, keeping humans in the loop. For example: selecting an area by clicking on a Pin/service on map and connecting related data to widgets such as a pie chart and time series, as well as producing some computation, for instance calculating the average values or other metrics. To this end, the User Interface needs to provide some business logic which can be on server-side (formalized in Processing Logic/IoT App, Node-red) to serve all the users at the same time, and client-side for evolving user interface behavior on each client device autonomously. Client devices are typically a browser but could also be a mobile app. 

According to SMADE-lc, the design of views starts with the production of Dashboards’ mockups. For each Dashboard, a set of suggested information is requested such as: aim, status, target device, GUI style, list of widgets and their description, and the business logic kind.
The Dashboards are called passive when the data represented come only from storage without any event driven connection from platform to dashboard and vice versa, for business logic or for just presenting/producing data in real time. Active views/dashboards are those that provide those connections. They are initially developed as passive Dashboards in first sprints and get smarter and smarter in successive sprints of the life cycle. Moreover, for fast prototyping the server-side business logic is developed by using IoT App node-RED, which provides a set of nodes corresponding to connect graphical widgets on dashboards (via secure WebSocket), thus overcoming the limitation of Node-RED native dashboards. This approach is very effective and viable for fast prototyping and to realize strictly synchronized smart applications in which all the actions on the web interface are shared with all the users (typically limited) as happens in the IoT world. For example, the monitoring panel of an industrial plant should present the same data to all the users connected to it.
On the other hand, when the users expect to play with the data for some business intelligence, their experience and the evolving data represented in the interface according to their activities is going to change. Those aspects are personal, and context based as one expects to have on a smart application, leading to an evolving user interface that should have a client-side business logic. In Snap4City, the development of client-side business logic can be implemented by adding JavaScript functions attached to the graphic widgets call back actions, which can perform actions on other widgets and on the platform, such as a REST Call to API.

To develop this phase one has to follow the Dashboard descriptions performed in the design phase. And at the same time has to answer a questions such as:

• The user interface has to provide some dynamic changes on the basis of the user actions? Which kind of changes?
• How many users are using it?
• Is it a view for the control room and decision makers of a business intelligence tool for playing with data and solutions?
• Etc.

How to proceed: The developers on Snap4City can visually create dashboards with a drag and drop tool by using Dashboard Builder which is assisted by a number of tools:

• Wizard to match data with widgets. It is an expert system for immediate matching HLT data vs graphics representation for creating Dashboards by rendering and acting on data with a large range of graphics widgets, which may have intelligence in the back by means of:
  
  • Processing Logic (IoT App) on data flow combining powerful Microservices/nodes, Data Analytics and API, to implement Server-Side Business Logic.
  • Client-Side Business Logic implemented as JavaScript on specific Dashboard Widgets listed on Section IV-C-5 of the life cycle document mentioned above.
• Custom Widget production tool for creating new widgets and synoptics using visual tools and templates: for real time rendering data on graphical scenographic tools, and for graphic interaction on the systems from dashboard to actuators through end-to-end secure connection.
• Style Theme modeling for deciding which style to use on the front-end dashboards. It is easy to change the graphical theme and style of the dashboard to have your precise fitting on your applications and portals.
• External Service for integrating external tools via Processing Logic and/or via IFRAME into an External Content Widget.

The list of graphical widgets available in Snap4City to compose the user interface is accessible at the following link: https://www.snap4city.org/download/video/course/das/
In Snap4City, there is a specific tutorial for the Dashboard development with several examples: https://www.snap4city.org/download/video/course/das/

 

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 (input) from the Users. For example, a click on a button, a click on the map, etc. These IN Widgets can be regarded as Virtual Sensors.
• OUT Widgets are those that are prepared to provide some changes to be shown into the Users’ interface as output. For example, a view of a bar series 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 receiving 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 Options tab and to find and edit the CK editor to formalize the JavaScript code according to a specific user manual provided.

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

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. The Javascript code should be provided as a single Javascript function named “execute”. Please refer to the specific user manual for more detailed instructions.

OUT 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 provokes 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 moment in which an action is triggered, a number of parameters can be provided. For example, geographic coordinates can be passed at a click on map, etc. Into the JavaScript, the developer can code how this information can be used to command IN Widgets, and also REST Calls to Smart City API and other activities.

 

In general, a widget may receive commands/events (IN) (from other widget and from the user) and may send commands/events. Moreover, the received commands and events my provoke changes on its own representation as well as to other widgets by sending events, triggers commands. The following figure represent a schema.

The receiving widgets may have some Custom JavaScript editable via CKEditor with the following structure, in which is evident that the widget is going to execute the function execute (), in which the events/commands may be processed with specific JavaScript segments. The JavaScript segment may include calls to SCAPI, as well as sending triggers / commands / events to other widgets (one or more) of the dashboard provided that the IDentifier is known. You can also send commands to open other dashboards.

 

function execute ()

{

Var e = JSON.parse(param)

if (e.event == ‘’……….’’) {

…………………………

}

else if (e.event == ‘’……….’’) {

…………………………

}

else {

…………………………

$(‘body’).trigger ({………});

}

}

 

As a results, a business intelligence application and any smart applications can be built controlling the widgets and defining the client-side business logic with the simple insertion of JavaScripts.

Please note that not all widgets have IN/OUT capabilities. Some of them are limited to OUT other to IN. The following two Tables provide you a short summary. If you need to have more IN/OUT CSBL functionalities on widgets please send an email to snap4city@disit.org

Please note that OUT Widgets are typically capable of making queries to the Smart City API just sending them the SURI of the Entities to be recovered, etc.

OUT and IN/OUT Widgets	Users’ Action Description and effects
widgetTimeTrend	Drill-Down on time interval selection (zoom), providing, SURI, value name, start and end time stamp	Time, SURI, ValueName, starttime, endtime
	Send Reset Drill-Down	Time
	Click on a single time instant, providing time stamp, SURI and value name	Time Selection
widgetMap (multidatamap)	Click on a generic point on the map, providing coordinates	Space Selection
	Click on a PIN, providing coordinates and ServiceURI of the clicked PIN	SURI Selection
	Select the bounding box area shown on the map, and the zoom level in order to perform geographical Drill-Down on the entities click on dedicated button on map (devices identified by SURIs, Points of Interest etc.) which are currently shown on map	Space Selection
widgetPieChart	Click on a sector that identifies the name of a metric, providing: value, timestamp, entity name (from which the SURI can be reconstructed) value name, value type and value unit	SURI Selection
	click on a sector that identifies a device ID or MyKPI ID, providing: value, timestamp, entity name (from which the SURI can be reconstructed) value name, value type and value unit	SURI Selection
	Get date and time from the calendar	Time Selection
	Click on legend, providing the status (e.g.: “checked” or “unchecked”) of the metric/SURI which has been clicked (under development)	SURI Selection
widgetBarSeries	Click on a bar, providing: value, timestamp, entity name (from which the SURI can be reconstructed) value name, value type and value unit	SURI Selection
	Get date and time from the calendar	Time Selection
	Click on legend, providing the visibility status of each metric/SURI	SURI Selection
widgetRadarSeries	Click on a radar axis related to a specific metric of a specific device, providing: value, timestamp, entity name (from which the SURI can be reconstructed) value name, value type and value unit	SURI Selection
	Get date and time from the calendar	Time Selection
	Click on legend, providing the visibility status of each metric/SURI	SURI Selection
widgetCurvedLineSeries (multi series)	Drill-Down on time interval selection (zoom), providing: start and end time stamp, and list of SURI. It is also possible to program the synchronization of multiple widgetCurvedLineSeries widgets.	Time, SURI, ValueName, starttime, endtime
	Click on a single time instant, providing: time stamp and list of objects including SURIs and related entity names and value names	Time Selection, list of SURI, value names
	Click on legend, providing the visibility status of each metric/SURI	SURI Selection
	Get date and time from the calendar	Time Selection
	Send Reset Drill-Down	reset zoom
widgetDeviceTable	Click on the action buttons, providing the action type, the corresponding SURI and a list of attributes with their corresponding values	SURI Action
widgetImpulseButton	Click on button as a trigger (no parameters are provided)	Action
widgetOnOffButton	Click on button, providing the new status	Action (param)
widgetButton	Click on button, providing some action with parameters, a SURI plus type, for exmaple	Action (param)
widgetKnob	Drag on knob, providing the value selected on the knob	Action (param)
	Click on minus and plus action (under development)	Action (param)
widgetNumericKeyboard	Click on the confirm button, providing the numeric value typed on the keyboard	Action (param)
widgetEventTable	Click on the action buttons, providing the action type, the corresponding event SURI and the ordering criteria	SURI Action
widgetExternalContent	It can support HTML pages and SVG Synoptics, in addition to JavaScript, so that it can perform a wide range of actions that can be defined in the HTML/SVG/JS code by the users.	Depending on program

 

IN and IN/OUT Widgets which present the possibility of receiving commands from JavaScript of IN Widgets are reported in the following table. Each IN 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 includes a JSON very similar or identical to the JSON to be sent to the widget from the Node-red in the context of writing CSBL. So, please refer to the same help manual and web pages for the same widgets.

IN and 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.	List of SURI, or data
	set date and time from the calendar	Time
widgetRadarSeries	Receive a JSON containing a list of SURI, metric names and/or values, and show their corresponding values on a Radar/Kiviat graph.	List of SURI, or data
	set date and time from the calendar	Time
widgetBarSeries	Receive a JSON object containing a list of SURI, metric names and/or values, and show their corresponding values on a Bar graph.	List of SURI, or data
	set date and time from the calendar	Time
widgetSingleContent	Receive a SURI and a metric name, or a value, or a text string, and show the corresponding value.	SURI or data, etc.
	Receive and show a HTML/JS page	HTML
widgetSpeedometer	Receive a SURI and a metric name, or a value, and show the corresponding value on a speedometer graph.	SURI, or data
widgetGaugeChart	Receive a SURI and a metric name, or a value, and show the corresponding value on a gauge graph.	SURI, or data
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.	SURI, or data
	Receive reset zoom	reset
widgetTable	Receive a JSON containing a list SURI, metric names and/or values, and show the corresponding time-series on a HTML static table.	List of SURI, or data
	Receive start datetime, end datetime without change sources IDs (under development)
widgetCurvedLineSeries	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.	List of SURI, or data
	Receive start datetime, end datetime without change sources IDs	time interval
	set date and time from the calendar	Time
	Receive reset zoom	reset
widgetDeviceTable	Receive a JSON containing a list of SURI representing IoT devices, and show their related attributes and values on an interactive table which provides action buttons.	List of SURI, or data
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.	List of SURI, or data
widgetMap	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.	List of SURI, or data
widgetOnOffButton	Receive and show a value representing the status	Action
widgetKnob	Receive and show a value	Action
widgetNumericKeyboard	Receive and show a value	Action
WidgetExternalContent	A SURI and a type, eventual parameters	Action

 

 

Other functions which can be exploited on Actions JavaScript segments:

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

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 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.

In each dashboard where at least one of its widgets provides a 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.