Widget Scripts

Widget scripts allow performing custom operations with widget components and server data. Scripts are written in Java. Every script is executed in the Java Virtual Machine (JVM) that executes the widget (this may be the JVM running Iotellect Client, or the Iotellect Server JVM if the widget is executed in the web interface). Thus, the scrip has access to all in-memory objects and structures of the widget. Scripts are very powerful, and provide the ability to fully control the widget.

Script permissions are not restricted in any way. A single unintentional error in a script, or some malicious code, may cause the Iotellect server or client to function improperly, hang, get 100% CPU time, corrupt its data or even corrupt data on the machine running it!

Widget script is executed in two cases:

• When a binding whose target points to this script is processed;
• When a binding expression calls script() function.

Scripts are executed in bindings processing thread, so script those execution takes a long time may and processing of other widget bindings. It's recommended to create new threads for executing time-consuming tasks from widget scripts.

Scripts are created and managed by editing the Scripts property of widget root panel.

Every script is a single Java class that must implement a WidgetScript interface:

public interface WidgetScript
{
public void execute(WidgetScriptExecutionEnvironment environment, Object... parameters);
}

This interface declares a single execute() method that is called when the script is executed.

Result of binding expression's evaluation is passed to the widget script as parameter object.

Every script has access to an object implementing WidgetScriptExecutionEnvironment interface that is passed as an argument to execute() method. Here is what WidgetScriptExecutionEnvironment look like:

public interface WidgetScript
{
public void execute(WidgetScriptExecutionEnvironment environment, Object parameter);
}

Instance of WidgetScriptExecutionEnvironment provides access to an object implementing GUIEngine interface (it is obtained by calling getEngine() method). GUIEngine provides access to objects responsible for widget execution.

getCause() method returns reference (object of type Reference) that caused processing of binding that gave rise to script execution. This reference may point to some server data or property of widget component.

When a new script is created, its text is not empty. It contains an auto-generated stub of a class implementing WidgetScript interface with an empty execute() method. Here is the default script text:

import com.tibbo.platform.guibuilder.*;
public class users_admin_widgets_scripts_refresh implements WidgetScript
{
public void execute(WidgetScriptExecutionEnvironment environment, Object parameter)
{
}
}

See Programming Guidelines section for common practices of developing Iotellect widget scripts.

Basically, scripts should do several things:

• Read/write properties of widget components
• Generate widget component events
• Read/write server context variables (i.e. hardware device settings and server resource properties)
• Call server and device operations (functions)

In most cases, all activities should be performed via Context interface.

To obtain a Context matching any server-side object, use the following code:

WidgetEngine engine = environment.getEngine();
ContextManager contextManager = engine.getServerContextManager();
Context serverContext = contextManager.get("server.context.path");

To obtain a Context matching a certain widget component, write the following code:

Context componentContext = environment.getComponentContext("widget_component_name");

Once an instance of Context is retrieved, you can read/write variables using getVariable() and setVariable() methods. For widget component contexts, most variables directly match component properties (e.g. Font, Width, Color, etc.)

For example, to apply custom processing to a Data Table stored in the Data Table Editor component, use the following code:

Context dataTableEditorContext = environment.getComponentContext("dataTableEditor1");
DataTable dataTable = dataTableEditorContext.getVariable("dataTable");
// Process the data here

This example illustrates how a widget can close another widget, e.g. upon a button click.

The script calls ClientUtils.removeFrame() static method and passes the key (name) of frame to close. The widget's frame key is constructed by ClientUtils.createWidgetFrameKey() method that accepts path of widget context and path of its default context (or root context path, i.e. empty string, in the case of absolute widget).

import com.tibbo.aggregate.common.script.*;
import com.tibbo.aggregate.common.widget.*;
import com.tibbo.aggregate.client.util.*;

public class %ScriptClassNamePattern% implements WidgetScript
{
public Object execute(WidgetScriptExecutionEnvironment environment, Object... parameters)
{
ClientUtils.removeFrame(ClientUtils.createWidgetFrameKey("users.admin.widgets.test", ""));
return null; 
}
}

This example illustrates how to open a certain website in browser. The below script can be launched upon button click, it accepts an URL as an only parameter.

import java.awt.*;
import java.net.*;
import com.tibbo.aggregate.common.widget.*;

public class %ScriptClassNamePattern% implements WidgetScript
{
public Object execute(WidgetScriptExecutionEnvironment environment, Object... parameters)
{
try
{
Desktop.getDesktop().browse(new URI(parameters[0].toString()));
}
catch (Exception ex)
{
throw new IllegalStateException("Error opening url '" + parameters[0].toString() + "'", ex);
}

return null;
}
}

Was this page helpful?

Tell us more

Send

Thank you!