From 29b75e968ec9645a0a923bb2fae04e111dfc59b5 Mon Sep 17 00:00:00 2001 From: Artem Dzhereleiko Date: Thu, 26 Sep 2024 16:58:59 +0300 Subject: [PATCH] UI: Complete scada help examples --- .../en_US/scada/symbol_state_render_fn.md | 74 ++++++++- .../help/en_US/scada/tag_click_action_fn.md | 144 +++++++++++++++++- .../help/en_US/scada/tag_state_render_fn.md | 63 +++++--- 3 files changed, 255 insertions(+), 26 deletions(-) diff --git a/ui-ngx/src/assets/help/en_US/scada/symbol_state_render_fn.md b/ui-ngx/src/assets/help/en_US/scada/symbol_state_render_fn.md index 9a2c811817..7a384157f6 100644 --- a/ui-ngx/src/assets/help/en_US/scada/symbol_state_render_fn.md +++ b/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 +
+```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} ``` + +
+ +**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 ScadaSymbolApi to update the visual appearance of these elements based on the context properties. +
+This approach ensures that both the icon and label elements are dynamically shown or hidden based on context properties, with appropriate styling applied. + +
+ +```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} +``` diff --git a/ui-ngx/src/assets/help/en_US/scada/tag_click_action_fn.md b/ui-ngx/src/assets/help/en_US/scada/tag_click_action_fn.md index 8675419803..10ff5f2ebf 100644 --- a/ui-ngx/src/assets/help/en_US/scada/tag_click_action_fn.md +++ b/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.
-##### Examples +##### Examples without setting values for callAction function + + +**Invoke widget click action** + +
+ +This JavaScript snippet demonstrates triggering a widget action using the ScadaSymbolContext API 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.). + +
+ +```javascript +ctx.api.callAction(event, 'click'); // Trigger widget action 'click' on event +{:copy-code} +``` + +
+ +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. + +
+ +**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 Scada Symbol API: @@ -34,10 +61,9 @@ For more detailed guidelines on device interaction, consider reviewing the { // 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} ``` + +
+ +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** + +
+ +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 ScadaSymbolContext API 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. + +
+ +```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} +``` + +
+ +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. + +
+ +```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} +``` + +
+ +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. diff --git a/ui-ngx/src/assets/help/en_US/scada/tag_state_render_fn.md b/ui-ngx/src/assets/help/en_US/scada/tag_state_render_fn.md index c16ad96c58..15e48b1453 100644 --- a/ui-ngx/src/assets/help/en_US/scada/tag_state_render_fn.md +++ b/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. + +
```javascript -if(ctx.values.active){ - element.attr({fill: ctx.properties.activeColor}); -} else { - element.attr({fill: ctx.properties.inactiveColor}); -} -{:copy-code} -``` - -* Enable and disable the “On” button based on the state of the "active" (avoid or prevent click action) - -```javascript -if (ctx.values.active) { - ctx.api.disable(element); -} else { +// Context values +var active = ctx.values.active; // Device connectivity status +// Colors from context properties +var activeColor = ctx.properties.activeColor || '#4CAF50'; // Color for enabled state +var inactiveColor = ctx.properties.inactiveColor || '#A1ADB1'; // Color for disabled state +// Check if the device is active +if (active) { + // Set the background color to activeColor if active + element.attr({fill: activeColor}); + // Enable the element to allow click actions 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” +
+ +**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. + +
```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); +var animation = ctx.api.cssAnimation(element); // Retrieve any existing animation on the 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) - .rotate(360).loop().speed(speed); + animation = ctx.api.cssAnimate(element) // Create new animation if not already active + .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(); }