UI: Complete scada help examples

ui-ngx/src/assets/help/en_US/scada/symbol_state_render_fn.md

@@ -20,12 +20,15 @@ A JavaScript function used to render SCADA symbol state.
 
 ##### Examples
 
+**Handle volume buttons state and appearance**
+
 This JavaScript snippet manages the enablement and appearance of SVG buttons used to control volume settings based on device connectivity and value thresholds.
-The 'Up' button is disabled when the volume reaches its maximum allowable value (`maxValue`), and the 'Down' button is disabled when the volume is at its minimum allowable value (`minValue`). 
+The 'Up' button is disabled when the volume reaches its maximum allowable value `maxValue`, and the 'Down' button is disabled when the volume is at its minimum allowable value `minValue`. 
 Both buttons are disabled when the device is offline. The visual cues for enabled/disabled states are represented by color changes.
 
-```javascript
+<br>
 
+```javascript
 var levelUpButton = ctx.tags.levelUpButton; // Button for increasing volume
 var levelDownButton = ctx.tags.levelDownButton; // Button for decreasing volume
 var levelArrowUp = ctx.tags.levelArrowUp; // Visual arrow for 'Up' button
@@ -61,3 +64,70 @@ if (levelDownEnabled) {
 
 {:copy-code}
 ```
+
+<br>
+
+**Manage icon and label visibility and styling**
+
+This JavaScript code snippet dynamically handles the visibility and styling of an icon and label within a SCADA symbol.
+It checks the `showIcon` and `showLabel` properties from the context to determine whether to display the icon and/or label. 
+If the icon or label is shown, the script sets their respective properties like size, color, and position. 
+The script utilizes the <a href="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/scada/scada-symbols-dev-guide/#scadasymbolapi" target="_blank">ScadaSymbolApi</a> to update the visual appearance of these elements based on the context properties.
+<br>
+This approach ensures that both the icon and label elements are dynamically shown or hidden based on context properties, with appropriate styling applied.
+
+<br>
+
+```javascript
+// Retrieve the first icon and label elements from the context tags
+var iconTag = ctx.tags.icon[0];
+var labelTag = ctx.tags.label[0];
+
+// Check whether the icon should be displayed, based on the context property
+var showIcon = ctx.properties.showIcon;
+var showLabel = ctx.properties.label;
+
+if (showIcon) {
+  // Show the icon if the 'showIcon' property is true
+  iconTag.show();
+  // Set icon attributes such as icon type, size, and color
+  var icon = ctx.properties.icon;
+  var iconSize = ctx.properties.iconSize;
+  var iconColor = ctx.properties.iconColor;
+
+  // Use the ScadaSymbolApi to apply the icon, size, and color to the iconTag
+  ctx.api.icon(iconTag, icon, iconSize, iconColor, true);
+  
+  // If the label is not shown, adjust the icon's position
+  if (!showLabel) {
+    iconTag.transform({translateX: 83, translateY: 137});
+  }
+} else {
+  // Hide the icon if 'showIcon' is false
+  iconTag.hide();
+}
+
+if (showLabel) {
+  // Show the label if the 'showLabel' property is true
+  var labelTextFont = ctx.properties.labelTextFont;
+  var labelTextColor = ctx.properties.labelTextColor;
+
+  // Apply font and color to the label using the ScadaSymbolApi
+  ctx.api.font(labelTag, labelTextFont, labelTextColor);
+
+  // Set the text content of the label
+  ctx.api.text(labelTag, ctx.properties.labelText);
+
+  // If the icon is not shown, adjust the label's position
+  if (!showIcon) {
+    labelTag.transform({translateX: 10});
+  }
+
+  // Show the label
+  labelTag.show();
+} else {
+  // Hide the label if 'showLabel' is false
+  labelTag.hide();
+}
+{:copy-code}
+```

ui-ngx/src/assets/help/en_US/scada/tag_click_action_fn.md

@@ -21,7 +21,34 @@ A JavaScript function invoked when user clicks on SVG element with specific tag.
 
 <div class="divider"></div>
 
-##### Examples
+##### Examples without setting values for callAction function
+
+
+**Invoke widget click action**
+
+<br>
+
+This JavaScript snippet demonstrates triggering a <a href="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide//ui/widget-actions/#action-types" target="_blank">widget action</a> using the <a href="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/scada/scada-symbols-dev-guide/#scadasymbolcontext" target="_blank">ScadaSymbolContext API</a> when the click event occurs. The widget action will be linked to the behaviorId 'click', which defines the action that will be executed upon the event.
+The behavior of this action depends on the type of widget action configured in the ThingsBoard platform (e.g., navigating to a dashboard state, updating the current state, opening a URL, etc.).
+
+<br>
+
+```javascript
+ctx.api.callAction(event, 'click');  // Trigger widget action 'click' on event
+{:copy-code}
+```
+
+<br>
+
+This action is executed automatically upon the 'click' event, making it useful for scenarios where the user interacts with a widget by clicking on it.
+*Example Use Case*
+
+- **Navigate to Dashboard State:** If the 'click' action is configured to navigate to a new dashboard state, the user will be redirected to that state when clicking on the widget.
+- **Open URL:** If configured to open a URL, clicking on the widget will take the user to a specified web resource.
+
+<br>
+
+**Handle device activation toggle**
 
 The example demonstrates how to dynamically call the 'turnOn' or 'turnOff' actions based on the 'active' status from the context. The actions are implemented using the following methods from the <a href="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/scada/scada-symbols-dev-guide/#scadasymbolapi" target="_blank">Scada Symbol API</a>:
 
@@ -34,10 +61,9 @@ For more detailed guidelines on device interaction, consider reviewing the <a hr
 ```javascript
 var active = ctx.values.active; // Current active status from context
 var action = active ? 'turnOn' : 'turnOff'; // Determine action based on active status
-var parameter = "any object or primitive"; // Parameter to pass with the action
 
 // Call the action with observer callbacks for next and error handling
-ctx.api.callAction(event, action, parameter, {
+ctx.api.callAction(event, action, undefined, {
   next: () => {
     // Action succeeded; toggle the 'activate' status for debugging
     ctx.api.setValue('activate', !active);
@@ -47,4 +73,116 @@ ctx.api.callAction(event, action, parameter, {
     ctx.api.setValue('activate', active);
   }
 });
+{:copy-code}
 ```
+
+<br>
+
+This example utilizes two specific action behaviors, `turnOn` and `turnOff`, which interact with the target device based on the `active` status from the context:
+1. **turnOn Behavior**
+  * **Type**: Action
+  * **Default Value**: `true`
+  * **Description**: This behavior is triggered when the device is activated. It sends a command to the target device to turn it on, indicating that the device should be in an operational state. The default value of `true` signifies that the action is intended to activate or enable the device.
+2. **turnOf Behavior**
+* **Type**: Action
+* **Default Value**: `false`
+* **Description**: This behavior is triggered when the device is deactivated. It sends a command to the target device to turn it off, indicating that the device should be in a non-operational state. The default value of `false` signifies that the action is intended to deactivate or disable the device.
+
+
+##### Example with setting values for callAction function
+
+**Temperature Adjustment Handler**
+
+<br>
+
+This JavaScript code demonstrates click actions for buttons that either increase or decrease the temperature value within a predefined range.
+The behavior triggered by the click event updates the time series data for the temperature and ensures that the value stays within the defined limits.
+The widget uses the <a href="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/scada/scada-symbols-dev-guide/#scadasymbolcontext" target="_blank">ScadaSymbolContext API</a> to manage both temperature changes and the corresponding actions.
+
+1. **Decrease Temperature (levelDown button)**:
+  * The user clicks the levelDown button to decrease the temperature. If the system is running, the temperature decreases by a step defined by `temperatureStep`, but it will never go below the `minTemperature`.
+  * The updateTemperatureState action is then triggered to update the time series value for temperature.
+  * In case of an error during the action, the temperature reverts to its previous value.
+
+<br>
+
+```javascript
+if (ctx.values.running) {
+  // Retrieve the current temperature from the context values
+  var temperature = ctx.values.temperature;
+
+  // Retrieve the minimum allowable temperature from the context properties
+  var minTemperature = ctx.properties.minTemperature;
+
+  // Retrieve the step size by which the temperature should change
+  var step = ctx.properties.temperatureStep;
+
+  // Calculate the new temperature, ensuring it does not go below the minimum temperature
+  var newTemperature = Math.max(minTemperature, temperature - step);
+
+  // Set the new temperature value in the context
+  ctx.api.setValue('temperature', newTemperature);
+
+  // Trigger the action to update the temperature state, passing the new temperature value
+  ctx.api.callAction(event, 'updateTemperatureState', newTemperature, {
+    // In case of an error, revert to the original temperature
+    error: () => {
+      ctx.api.setValue('temperature', temperature);
+    }
+  });
+}
+{:copy-code}
+```
+
+<br>
+
+2. **Increase Temperature (levelUp button)**:
+  * The user clicks the levelUp button to increase the temperature. If the system is running, the temperature increases by the step, but will not exceed the `maxTemperature`.
+  * The action `updateTemperatureState` is called to update the time series value for temperature.
+  * If an error occurs, the previous temperature is restored to ensure consistency.
+
+<br>
+
+```javascript
+if (ctx.values.running) {
+  // Retrieve the current temperature from the context values
+  var temperature = ctx.values.temperature;
+
+  // Retrieve the maximum and minimum allowable temperature from the context properties
+  var maxTemperature = ctx.properties.maxTemperature;
+  var minTemperature = ctx.properties.minTemperature;
+
+  // Retrieve the step size by which the temperature should change
+  var step = ctx.properties.temperatureStep;
+
+  // Calculate the new temperature:
+  // - Add the step to the current temperature
+  // - Ensure it doesn't exceed the maxTemperature
+  // - If temperature is null/undefined, use minTemperature as the initial value
+  var newTemperature = temperature || minTemperature === 0 ? Math.min(maxTemperature, temperature + step) : minTemperature;
+
+  // Set the new temperature value in the context
+  ctx.api.setValue('temperature', newTemperature);
+
+  // Trigger the action to update the temperature state, passing the new temperature value
+  ctx.api.callAction(event, 'updateTemperatureState', newTemperature, {
+    // In case of an error, revert to the original temperature
+    error: () => {
+      ctx.api.setValue('temperature', temperature);
+    }
+  });
+}
+{:copy-code}
+```
+
+<br>
+
+The `updateTemperatureState` action is triggered to update the temperature value in the system. The action is configured with the following behavior:
+
+*Action Behavior*: 'updateTemperatureState'
+  * **Type**: action
+  * **Value Type**: double
+  * **Default Settings**: Add time series
+  * **Time Series Key**: 'temperature'
+
+This behavior updates the time series data for the temperature key, ensuring that the new temperature value is stored and displayed correctly.

ui-ngx/src/assets/help/en_US/scada/tag_state_render_fn.md

@@ -21,43 +21,64 @@ A JavaScript function used to render SCADA symbol element with specific tag.
 
 ##### Examples
 
-*  Change the background of the element based on the value of the “active”
+**Update element state based on device activity**
+
+This JavaScript snippet demonstrates how to dynamically change the background color of an SVG element based on the `active` status from the context. 
+Additionally, it enables or disables the element’s click functionality depending on the `active` status. 
+If the device is active, the element is given the activeColor and click actions are allowed. Otherwise, it is assigned the inactiveColor and the click action is disabled.
+
+<br>
 
 ```javascript
-if(ctx.values.active){
+// Context values
-  element.attr({fill: ctx.properties.activeColor});
+var active = ctx.values.active; // Device connectivity status
-} else {
+// Colors from context properties
-  element.attr({fill: ctx.properties.inactiveColor});
+var activeColor = ctx.properties.activeColor || '#4CAF50'; // Color for enabled state
-}
+var inactiveColor = ctx.properties.inactiveColor || '#A1ADB1'; // Color for disabled state
-{:copy-code}
+// Check if the device is active
-```
+if (active) {
-
+  // Set the background color to activeColor if active
-* Enable and disable the “On” button based on the state of the "active" (avoid or prevent click action)
+  element.attr({fill: activeColor});
-
+  // Enable the element to allow click actions
-```javascript
-if (ctx.values.active) {
-  ctx.api.disable(element);
-} else {
   ctx.api.enable(element);
+} else {
+  // Set the background color to inactiveColor if not active
+  element.attr({fill: inactiveColor});
+  // Disable the element to forbid click actions
+  ctx.api.disable(element);
 }
 {:copy-code}
 ```
 
-* Smooth infinite rotation animation based on the value of the “active” with speed based on the value of the “speed”
+<br>
+
+**Smooth rotation based on activity and speed**
+
+This JavaScript snippet creates a smooth, infinite rotation animation for an element based on the `active` status and adjusts the animation speed dynamically according to the `speed` value.
+If the element is active, the animation starts or continues rotating with a speed proportional to the speed value. If inactive, the animation pauses.
+
+<br>
 
 ```javascript
+// Get the 'active' status and the current speed
 var on = ctx.values.active;
-var speed = ctx.values.speed ? ctx.values.speed / 60 : 1;
+var animation = ctx.api.cssAnimation(element); // Retrieve any existing animation on the element
-var animation = ctx.api.cssAnimation(element);
+var speed = ctx.values.speed ? ctx.values.speed / 60 : 1; // Calculate speed, default to 1 if not provided
+var animationDuration = 2000; // Duration for one full rotation (optional, can be adjusted)
+var rotationAngle = 360; // Full rotation in degrees
 
 if (on) {
+  // If active, either create a new rotation animation or adjust the existing one
   if (!animation) {
-    animation = ctx.api.cssAnimate(element, 2000)
+    animation = ctx.api.cssAnimate(element) // Create new animation if not already active
-      .rotate(360).loop().speed(speed);
+      .rotate(rotationAngle) // Set rotation angle to 360 degrees
+      .loop() // Loop the animation infinitely
+      .speed(speed); // Adjust speed based on the 'speed' value from the context
   } else {
-    animation.speed(speed).play();
+    animation.speed(speed).play(); // If animation exists, adjust its speed and continue playing
   }
 } else {
+  // If inactive, pause the animation
   if (animation) {
     animation.pause();
   }