TC1.22a: Create and configure a Snap4City SVG Custom Widget for real-time interaction

Test Case Title	TC1.22a: Create and configure a Snap4City SVG Custom Widget for real-time interaction
Goal	Create a Snap4City SVG custom widget and configure it to be embedded in a Snap4city dashboard.
Prerequisites	To know how to create SVG grphics file using an editor; To be logged in the Snap4city platform; To know how to create dashboards.
Expected successful result	A Snap4City SVG custom widget is correctly shown in a dashboard and interact in realt time with the system.
Steps	See details below

This tutorial aims at training you in creating Snap4City SVG Custom Widgets.

The second part of this tutorial aims to training in the instantiation of the Synoptic and in the creation of a dashboard with the instantiated synoptic: TC1.22b: Create and configure a Snap4City SVG Custom Widget for real-time interaction

The full process explained in this tutorial is simplified in the following image.

Please note that Custom Widget can be created by using: (i) the newly procedure presented in this technical case as well as (ii) in PHP JavaScript HTML5 by programmers as described in TC3.11 - New graphics widget can be easily created, Dashboard Widget Creation.

Please note that Custom Widgets can be directly controlled from IOT Applications to create event driven solutions: TC9.19: Custom Widgets / Synoptics controlled by IOT Applications

Snap4City SVG Custom Widgets can be used to create a synoptic panel in widget of a dashboard as well as a single graphic widget also embedded in a Snap4City dashboard.

see for example: https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=MjU0NA==

In the following we have two phases:

• How to create the Snap4City SVG Custom widget (part a);
• How to use one Snap4City SVG Custom widget (part b).

SVG files are vector graphical representations that can be embedded into a Snap4City widget dashboards and that can show data and interact with the platform, for example showing the data from different devices deployed in an industrial plant or interacting with physical devices to send command and/or data. Synoptic panels are extensively used in Industry plants but are flexible enough and can be profitably used also in different contexts. Examples of different custom synoptics and widgets based on SVG are available in this page: Custom Synoptics and Widgets for Dashboards.

In this example we will create and configure a SVG file representing 5 different coloured faces that could be used to collect the feedback from users of a service. The 5 faces represent the rating of the services and will have the following values: very angry, angry, neutral, happy, very happy. Each faces represent the following numeric values respectively: -2, -1, 0, +1, +2.

Once the SVG file is correctly configured and finalised, it has to be saved in Snap4City as a template to be used in different dashboards and contexts (instances).

In this example the idea is to create a SVG template where each time a user clicks on a face to rate the service, the information is send to the Snap4City platform that save the corresponding value data as MyKPI. In the SVG also the total number of clicks and the mean of the values collected are shown in real time.

This SVG custom widget is an example that has the scope to demonstrate the potentiality and flexibility of using SVG custom widget interaction.

How to create a Snap4City SVG Custom Widget

To design and configure the SVG file, the InkScape open source software is used (https://inkscape.org). The following image is the SVG file used as example. The Custom Synoptics/Widgets are created by using SVG standard. To this end we suggest to use the freely available open-source tool, namely the SAGE - SCADA Animation Graphic Editor, is the recommended tool for the development of SVG documents. https://sourceforge.net/projects/sage-scada/

In the following examples, Inkscape v0.48 is used. Some differences with respect to newer versions could be present in the user interface.

In this example, the five coloured faces is a single PNG image file that has been imported in the InkScape canvas and that will remains in the background of the SVG file.

By using the SVG editor, five circle have been added above each face so that each face has a vector circle designed above (that in the image is not visible) and that will be the interactive element to be used to activate the different rates.

To add a circle, in the Tool Box on the left, select the “Eclipse, Circle, and Arcs” tool and design five different circles above the different faces. The circles have to overlap the 5 faces and have to fit perfectly.

It now necessary to manually edit the XML of the SVG file since we have to add attributes to the different elements of the SVG image that have to send or retrieve data to/from the Snap4City platform. In this manner the SVG template is correctly configured by defining the new attributes describing the read/write operations to be executed on the new variables that will be defined.

To instruct the system to read a variable and use the value read to modify some aspect (textual content, attribute value, style property value) of an element in the SVG custom widget, it is necessary to add to that element a data-siow attribute, whose value will be a JSON array (with appropriate escapes of the double quotes and so on), whose elements are JSON objects each describing a set of operations to be performed on the basis of the variable read.

In our case we will add attributes for:
- the five coloured faces, that have to send to the platform the corresponding value (from -2 to 2, according to the different value associated to the faces);
- the total number of clicks;
- the mean value calculated on the basis of the different values collected by the system.

Please note that we have to consider as output data a message that is sent from the client (the user device) to the server (snap4city platform), and as input data a message that is retrieved from the server and are shown by the client. So that in our case, the five faces values have to be provided as output and the total number of click and the mean values, that are recovered from the server, are input values.

We add now an attribute to the red face representing the value “-2” that is the output value that will be sent to the Snap4City platform each time a user click on it:

1. Enter in XML edit mode by selecting Edit --> XML Editor in the main menu (or by clicking SHIFT-CTRL-P). The XML Editor is opened on the right. It displays the entire XML tree of the document. By using the XML Editor it is possible to edit any text, element, or attribute nodes and see the result on your canvas.

2. Click on the circle above the red face. The circle is selected and the XML Editor shows the code corresponding to the element selected.
3. In the XML editor column, also the yet existing attributes for the selected element are shown in another box on the right of the XML code, as in the image below;

 

4. To edit an attribute, click on it, for example click on the attribute name Id. The attribute value is shown, as in the following image;

 

5. You can change the Attribute Value by editing the corresponding text in the box. For example delete the Id value and write “very-bad”. Click the Set button to confirm the change (or press CTRL+Enter). The new value is shown in the attribute box.

 

6. Every time a change is performed, it is necessary to commit all changes by pressing Ctrl + Enter when doing editing, or by pressing the Set button.

 

7. Change all remaining IDs of all the other faces in “bad”, “so-and-so”,  “quite-good”, “good” respectively. Press the Set button to confirm each changes or press Ctrl-Enter to commit the changes. The final result will be as in the following image;

 

8. Now we add a new attribute called “data-siow” that allows the SVG file to send the corresponding value to the platform. Click on the red face and select the hidden circle above it.
9. In the empty field below the attributes of the selected element, write a new attribute name: data-siow;
10. As attribute value, below the new data-siow attribute name, copy the following text:

[  {   "event": "click",   "originator": "client",   "actions": [    {     "input": "attribute data-value",     "target": "write", "format": "{ \"attr\": \"set\", \"tag\": \"s4csvg_userFeedback\", \"src\": \"{0}\" }"    }   ]  } ]

11. Click Set to confirm;

Please note that to be automatically recognised by the system, the new added variables have to have the prefix “s4csvg_” as placeholder.

12. Write another new attribute name: data-value;
13. As attribute value, below the new data-value attribute name, write “-2”. The final result will be as in the following image.

 

14. Repeat the same actions from 9 to 12 for all the other faces, but add as data-value -1, 0, 1, 2 respectively.
15. Now all values for the five faces have been defined.
16. Click on the text inside the Total click box to define the corresponding attributes. In this case we will define the attribute to read the total number of clicks.
17. In the XML Editor select the <svg:tspan> element. In the case of a text, the new data-siow attribute has to be defined inside the svg:tspan element.

 

18. In the empty field below the attributes of the selected element, write a new attribute name: data-siow;
19. As attribute value, below the new data-siow attribute name, copy the following text:

[  {   "event": "s4csvg_total_feedback_clicks",   "originator": "server",   "actions": [    {     "input": "$.lastValue",     "target": "textContent" }  ]  } ]

Please note that to be automatically recognised by the system, the new added variables have to have the prefix “s4csvg_” as placeholder.

20. Select the Id and change the Id value in “s4csvg_total_feedback_clicks”
21. Click Set to confirm. The result will be as in the following image;

 

22. Click on the text inside the Mean rate value box to define the corresponding attributes. Also in this case we will define the attribute to read the mean value calculated on the basis of the different feedbacks received.
23. Also in this case, in the XML Editor select the <svg:tspan> element;
24. As attribute value, below the new data-siow attribute name, copy the following text:

[  {   "event": "s4csvg_feedback_mean_rate_value",   "originator": "server",   "actions": [    {     "input": "$.lastValue",     "target": "textContent" }  ]  } ]

25. Select the Id and change the Id value in “s4csvg_feedback_mean_rate_value”;
26. Click Set to confirm. The result will be as in the following image;

 

27. Save the new SVG file.
28. Send / Commit the SVG file to snap4city@disit.org, it will be included into the suite of possible Snap4City SVG Custom Widgets by the administrator. In the next future for ToolAdmin users, it will be possible to directly upload SVG Custom Widgets on the platform.

If you are also an user, please follow the next section.

Please take in mind as SVG developer that only variable with “s4csvg_” prefix could be accessible for connection with actual variable input and outputs of the platform.

---

---

Exploit animation in a SVG custom widget

SVG allows to include different kind of animations that can be used for example to provide to users a feedback on the basis of an action performed. In the following example we use a pure SVG (without any PNG image in the background) with the 5 faces. When the user clicks on a face, it is animated with a zoom in and zoom.

In this example we use the <animate> element to animate a circle of a face by zooming in on user click and a second <animate> element  to zoom out the circle after the previous animation.

1. In the XML editor of Inkskape SVG editor, select the circle element to animate. In this example we animate the circle with id “circle-darkgreen”.

 

2. Click the “New Element Node” small button above the SVG code, as in the image below;

3. In the box insert the following code: svg:animate id=”darkgreen” as in the following image. Click the Create button to confirm.

4. The new element is indented in the previous element. The level of the new animation element has to not be indented. Click the “Unindent node” button as in the following image.

5. With the new node <svg:animate> selected, on the right part of the editor add the following attributes:

• attributeNAme                r

• begin                                   click

• dur                                        1s

• from                                     10%

• to                                          14%

• href                                      #circle-dargreen

Remember to click the Set button for each element to be added in the node.

• The “r” attribute specify that the animation specified in the node is referred to a radius.
• The “begin” attribute specifies that the animation has to start on a click (mouse click or touch on a screen)
• The duration of the animation is set to 1 second
• The animation will be from 10% to 14% so it is a zoom in effect
• The element to be animated is specified in the href element, that in this case is the element with id circle-darkgreen that is the if od the dark green circle.

To make the circle zooming out, a new element node has to be added below the previous <svg:animate id=”darkgreen”> . Follow the same steps illustrated above to add a new node <svg:animate> with the following attributes:

• • attributeNAme                r
  • begin                                   darkgreen.end
  • dur                                        1s
  • from                                     14%
  • to                                          10%
  • href                                      #circle-darkgreen

The begin: darkgreen.end element indicates that the animation will start automatically after the animation defined above with id “darkgreen”.

The final result is shown in this dashboard: https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=MjU0NA==

How to dynamically fill a tank in a SVG custom widget

In this example how to dynamically fill the level of a tank is explained. The level changes according to the variable value. In this example the levels of a recycle bin is used, but the same procedure can be used to represent any other element that has to be filled according to a variable value.

To represent in the SVG the level, it is necessary to draw the figure that has to change its dimension according to the variable value. In the example, the square in the middle of the bins represents the level of fill that will change its high according to the percentage of fill: the lower the percentage, the lower the filling level starting from the bottom of the bin.

1. In the Inkskape SVG Editor, select the rectangle to be associated to the data-siow variable. The corresponding node in the XML Editor is highlighted accordingly, with their attributes on the right box.
2. Add a new data-siow attribute and copy the following text:

[  {   "event": "s4csvg_smartwaste_organic_fill",   "originator": "server",   "actions": [    {     "input": "$.lastValue",     "normalize":"0 0 100 189", "format": "{0}px", "target": "style height" }, {     "input": "$.lastValue",     "normalize":"100 104 0 293", "target": "attribute y" }  ]  } ]

1. Click Set to confirm. The result is as in the following figure.

“s4csvg_smartwaste_organic_fill” is the variable name

“target”: “style height” means that the fill will be represented by changing the height of the image. You can set “target”: “style width” to change the fill in horizontal;

The first “normalize” in the data-siow code contains four number representing:

• The minimum value of the variable;
• The corresponding minimum value in height of the rectangle (in pixel);
• The maximum value of the variable;
• The corresponding maximum value in height of the rectangle (in pixel).

So that, in the example above, when the value is 0% the fill is 0 pixel, when the value is 100 (i.e. at 100%) the fill is 189px.

The second “normalize” in the data.siow code contains the following four number: “100 104 0 293” representing respectively:

• 100 is the maximum value of the variable (in this case is 100% that means that the tank is full)
• 104 is the distance in pixel of the vertex of the filled box when it is full calculated from the top of the canvas (identified by the n. 2 in the following image)
• 0 is the minimum value of the variable (in this case is 0% that means that the tank is empty)
• 293 is the distance in pixel of the vertex of the filled box when it is empty, calculated from the top of the canvas (identified by the n. 3 in the following image)

Below the bin, the percentage of fill is represented. The “###” text will be replaced by the real value of the percentage.

1. In the XML Editor click on the “###” text and select the <svg:tspan> element, a in the example of the SVG faces;
2. In the empty field below the attributes of the selected element, write the new attribute name: data-siow;
3. As attribute value, below the new data-siow attribute name, copy the following text:

[  {   "event": "s4csvg_smartwaste_organic_fill",   "originator": "server",   "actions": [    {     "input": "$.lastValue",     "target": "textContent" }  ]  } ] 

Please note that the variable name “event”: “s4csvg_smartwaste_organic_fill” is the same specified in the data-siow of the bin design.

4. Click Set to confirm. 

The final result is shown in this dashboard: https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=MjU3MA==  

How to dynamically change a color of a SVG custom widget

In this example how to set a SVG that change its color on the basis of the variable value is explained. For the scope of this tutorial a SVG representing a street with smart lights is used. Every smart light pole is represented by a circle on the map. The intensity of the light can be changed from 0 (the light is switched off) to 10 (the light is at the maximum intensity).

Select a circle representing a smart light pole and, on the right part of the XML editor, add the following data-siow attribute:

[  { "event": "s4csvg_SmartLightFI_fa2014",  "originator": "server", "actions": [ { "target": "style fill", "input": "$.lastValue", "thresholds": "gray 0 #000000 1 #7f7f00 2 #949400 3 #aaaa00 4 #afaf00 5 #bfbf00 6 #cfcf00 7 #dfdf00 8 #efef00 9 #ffff00" } ] } ]

Press Set to confirm.

The “event”: “s4csvg_SmartLightFI_fa2014” specifies the variable name.

The thresholds represents the different colors to be set according to the different values. The first color “gray” is the color that will be set in case the value is not included in the following values. In the case of this example, 10 values are defined from 0 to 9 and each of them has a color in HEX: value zero will fill the circle with the #000000 color; value 1 will fill the circle with the #7f7f00, etc.

Every circles represented on the map, has a different variable name and is completely independent of the others.

The final result is shown in this dashboard: https://www.snap4city.org/dashboardSmartCity/view/index.php?iddasboard=MjU2OA==