Pages

Button Script Widget

Overview

The Button Script widget provides advanced button behavior by executing PLCVisu macro scripts. It can be used to create custom interactions between widgets, manipulate displayed values, submit form data, write values to communication paths, navigate between pages, and control popups.

Purpose

The Button Script widget is intended for use cases where a normal button action is not sufficient and multiple actions must be executed in sequence.

Typical use cases include:

• writing a value to a PLC variable
• changing the value of an Outputbasic widget
• appending or truncating displayed text
• checking whether a value is inside a defined range
• enabling or disabling another Button Script widget
• submitting values from one container or from all containers
• navigating to another page
• closing a popup
• executing logic when the page is entered or exited

Script Execution Points

The widget supports three separate script inputs.

On Load Script

The On Load script is executed when the widget appears on the page.

Execution is delayed by approximately 200 ms after the page is entered. This allows the page and widgets to be initialized before the script runs.

Example use case:
elementById(display).set(0);

On Click Script

The On Click script is executed when the Button Script widget is clicked.

Example use case:
elementById(display).append(1);

On Close Script

The On Close script is executed when the page is exited.

Example use case:
submitAll();

Script Syntax

Scripts are written as command chains.

Each command must use function-style syntax:

commandName(parameter1, parameter2);

Multiple commands can be chained in one line:

elementById(display).append(1).checkRange(0,100,submitButton);

Multiple script lines can be separated by semicolons:

elementById(display).set(10); submitContainer();

Important: scripts must end with a semicolon. The current parser splits the script by ; and removes the last item. Without a trailing semicolon, the last command may not be executed.

Command Chaining

Commands can pass a return value to the next command.

For example:

elementById(display).getValue().setWs();

Execution flow:

elementById(display)selects the widget.
getValue() reads the value from the selected widget.
setWs() writes the value to the configured WebSocket path.

Supported Commands

elementById(elementId)

Selects another widget by its HTML element ID.

Syntax:
elementById(elementId)

Returns an internal widget reference that can be used by following commands.

Supported target widget types:

Angular Element	Internal Type
APP-OUTPUT	outputbasic
APP-BUTTON-SCRIPT	button-script

Example:
elementById(myOutput).set(123);

set(value)

Sets the value of a selected widget.

Syntax:
elementById(elementId).set(value);

Supported widget types:

Widget Type	Behavior
outputbasic	Sets the text inside the output span

Example:
elementById(display).set(100);

append(value)

Appends text to the current value of an Outputbasic widget.

Syntax:
elementById(elementId).append(value);

Supported widget types:

Widget Type	Behavior
outputbasic	Appends the value to the existing displayed text

Example:
elementById(display).append(5);

If the current display value is 12, the result becomes:
125

appendRangeCheck(value, min, max)

Appends a value only if the resulting value is inside the defined range.

Syntax:
elementById(elementId).appendRangeCheck(value, min, max);

The min and max parameters can be either numeric values or IDs of other Outputbasic widgets.

Example with numeric range:
elementById(display).appendRangeCheck(5, 0, 100);

Example with range references:
elementById(display).appendRangeCheck(5, minOutput, maxOutput);

Behavior:

• Reads the current value from the selected Outputbasic widget.
• Appends the requested value.
• Checks whether the resulting value is within the defined range.
• If the value is valid, the display is updated.
• If the value is outside the range, the command is stopped with an error.

Supported widget types:

Widget Type	Behavior
outputbasic	Appends only if the result is within range

checkRange(min, max, targetElementId)

Checks whether the selected Outputbasic value is inside a defined range. If the value is outside the range, the target Button Script widget is disabled.

Syntax:
elementById(sourceOutput).checkRange(min, max, targetButton);

The min and max values can be either numeric values or IDs of other Outputbasic widgets.

Example:
elementById(display).checkRange(0, 100, submitButton);

Behavior:

• If display is inside the range 0 to 100, submitButton stays enabled.
• If display is outside the range, submitButton is disabled.

Supported source widget types:

Widget Type	Behavior
outputbasic	Reads and validates displayed value

Supported target widget types:

Widget Type	Behavior
button-script	Enables or disables the button

truncate(numChars)

Removes characters from the end of an Outputbasic value.

Syntax:
elementById(elementId).truncate(numChars);

Example:
elementById(display).truncate(1);

If the current display value is:
12345

The result becomes:
1234

Special behavior:

• If numChars is 0, the complete value is removed.
• If numChars is larger than the current text length, the complete value is removed.

Supported widget types:

Widget Type	Behavior
outputbasic	Removes characters from the end of the displayed text

getValue()

Reads the value from the selected widget.

Syntax:
elementById(elementId).getValue();

Supported widget types:

Widget Type	Behavior
outputbasic	Reads the text from the output span

Example:
elementById(display).getValue().setWs();

setWs(value?, connectionId?, path?)

Writes a value to a WebSocket communication path.

Syntax using explicit parameters:
setWs(value, connectionId, path);

Syntax using a chained value:
elementById(display).getValue().setWs();

Behavior:

• If connectionId and path are provided, the value is written to the specified connection and path.
• If no explicit connection and path are provided, the widget writes to its own configured WebSocket connection and path.
• If a value is provided by the previous command in the chain, that value is used.

Examples:

setWs(1, 1, Application.GVL.Start);
elementById(display).getValue().setWs();

setWsOnPosition(value?, mapName?, connectionId?, path?)

Writes a value to a WebSocket path depending on the current page index.

Syntax:
setWsOnPosition(value, mapName, connectionId, path);

Behavior:

• If the current page index is 0, the value is written to all mapped positions except index 0.
• The placeholder $$GI$$ in the path is replaced by the target page index.
• If the current page index is not 0, the value is written to the widget’s own configured WebSocket path.

Example:

setWsOnPosition(1, DeviceMap, 1, Application.GVL.Device[$$GI$$].Start);

setConnRef(value?)

Writes a value using the widget’s configured connection reference.

Syntax using chained value:
elementById(display).getValue().setConnRef();

Syntax using explicit value:
setConnRef(123);

Behavior:

• Uses the widget’s configured connRef.
• Parses the connection reference into connection ID and path.
• Writes the value using the remote data service.
• If no connection reference exists, the command returns the input value without writing.

evalValue(script)
Executes a JavaScript expression against the internal value variable and returns the resulting value.
Syntax:
evalValue(value = 10 + 5)
Example:
evalValue(value = 5 * 2).setWs();
Result:
10
Note: this command uses JavaScript evalValue() internally. It should be used carefully and only with trusted scripts.

changeSign()

Changes the sign of a numeric Outputbasic value.

Syntax:

elementById('elementId').changeSign();

Example:
elementById('display').changeSign();

If the current value is:
25

The result becomes:
-25

If the current value is not numeric, the command does nothing.

Supported widget types:

Widget Type	Behavior
outputbasic	Multiplies the displayed numeric value by -1

closePopup()

Closes the currently opened popup.

Syntax:

closePopup();

Example:

submitContainer();
closePopup();

getCurrentPageIndex()

Returns the current page index from the URL.

Syntax:

getCurrentPageIndex();

Example:

getCurrentPageIndex().setWs();

This can be used to write the current page index to a variable or pass it to another command.

goToPage(proceed?, pageId?, index?, forceProceed?)

Navigates to another page.

Syntax:
goToPage(proceed, pageId, index, forceProceed);

Typical usage:
goToPage(true, '5');

This navigates to:

/home/5

Parameters:

Parameter	Description
proceed	Boolean-like signal that controls whether navigation is allowed
pageId	Target page ID
index	Currently not used by the implementation
forceProceed	Used by the internal proceed check

Behavior:

• If pageId is provided, the router navigates to /home/{pageId}.
• If the proceed signal prevents execution, the command is stopped.

Example with range validation:

elementById('display').getValue().goToPage(true, '3');

navigateToPageIndex(pageIndex, mapName?, pageId?)

Navigates to a page using a page index value.

Syntax:
navigateToPageIndex(pageIndex, mapName, pageId);

Example:
navigateToPageIndex(2, 'DeviceMap', '10');

The command uses the page index service to navigate according to the configured page index mapping.

submitContainer()

Submits form elements from the current container.

Syntax:
submitContainer();

Behavior:

• Submits the form elements belonging to the current widget container.
• Uses the widget’s containerIndex.

Example:
submitContainer();

submitAll()

Submits all form elements.

Syntax:
submitAll();

Example:
submitAll();

This is useful when a button should submit all configured input values on the page.

sleep(ms, forceProcess?)

Delays execution of the command chain.

Syntax:
sleep(ms, forceProcess);

Example:
setWs('1');
sleep(500);
setWs('0');

Parameters:

Parameter	Description
ms	Delay time in milliseconds
forceProcess	If set, the command returns true after the delay

Behavior:

• Waits for the defined time.
• Returns the previous chain value by default.
• IfforceProcess is set, returns true.

Example with forced continuation:
sleep(500, true).goToPage(true, '2');

factor(factoring)

Multiplies the input value by a factor.

Syntax:
factor(factoring)

Example:
elementById('display').getValue().factor(10).setWs();

If the display value is:
12

The written value becomes:
120

Behavior:

• Converts the input value to a number.
• Converts the factor to a number.
• If both are valid numbers, the result is inputValue * factor.
• If conversion fails, the original value is returned.

Example Scripts

Set an Outputbasic Value on Button Click
elementById('display').set('100');

Append Digits to an Outputbasic Widget
elementById('display').append('1');
elementById('display').append('2');
elementById('display').append('3');

Result:
123

Backspace Function
elementById('display').truncate(1);

Clear Display
elementById('display').truncate(0);

Change Sign of Displayed Number
elementById('display').changeSign();

Submit Current Container and Close Popup
submitContainer();
closePopup();

Write Display Value to PLC
elementById('display').getValue().setWs();

Multiply Display Value Before Writing
elementById('display').getValue().factor(1000).setWs();

Validate Value and Disable Submit Button
elementById('display').checkRange('0', '100', 'submitButton');

Navigate to Page
goToPage(true, '5');

Delayed Pulse
setWs('1');
sleep(500);
setWs('0');

Supported Widget Interaction

The current implementation supports only a limited set of widget interactions.

Source Widget	Supported Commands
Outputbasic	getValue(), set(), append(), appendRangeCheck(), checkRange(), truncate(), changeSign()
Button Script	Can be enabled or disabled internally by checkRange()

Limitations

The Button Script widget currently has the following limitations:

• Only selected widget types are supported.
• APP-OUTPUT
  -APP-BUTTON-SCRIPT
• Script commands must follow the supported function syntax.
• Scripts should end with a semicolon.
• Unsupported widget types will stop the current command line with an error.
• Unsupported commands are ignored because only explicitly implemented commands are executed.
  -evalValue() uses JavaScripteval() internally and should only be used with trusted script content.
• The parser is simple and is intended for macro-like commands, not complex JavaScript code.
• Parameter parsing is comma-based, so parameter values containing commas are not supported safely.

Error Handling

Each script line is executed inside a try-catch block.

If one command line fails:

• the error is logged to the browser console
• the failing line is stopped
• other script lines can still continue

Typical console warning:

buttons-script::run line::stopped

Click execution errors are logged as:

button-script eval failed

Configuration Inputs

The Button Script widget supports the following input properties.

Input	Description
style	Widget style definition
label	Button label
img	Default image
imgPress	Pressed-state image
script	Script executed on click
onloadscript	Script executed when the page is entered
onclosescript	Script executed when the page is exited
containerIndex	Index of the container used by submitContainer()

Recommended Usage

Use the Button Script widget when the button needs to execute more than one action or when the action depends on another widget value.

Recommended scenarios:

• numeric keypad buttons
• submit buttons
• popup confirmation buttons
• page navigation buttons
• value validation buttons
• PLC write buttons
• delayed pulse actions
• local display manipulation before writing a value