@ -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 <ahref="${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
@ -21,7 +21,34 @@ A JavaScript function invoked when user clicks on SVG element with specific tag.
<divclass="divider"></div>
##### Examples
##### Examples without setting values for callAction function
**Invoke widget click action**
<br>
This JavaScript snippet demonstrates triggering a <ahref="${siteBaseUrl}/docs${docPlatformPrefix}/user-guide//ui/widget-actions/#action-types"target="_blank">widget action</a> using the <ahref="${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 <ahref="${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
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 <ahref="${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
// 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
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.
* Enable and disable the “On” button based on the state of the "active" (avoid or prevent click action)
<br>
```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”
<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);
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
Max Petrov
2 years ago
GitHub