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 AggreGate Client, or the AggreGate 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 AggreGate 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 when the binding whose target points to this script is processed. 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 parameter); } |
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) { } } |
Scripts are executed in bindings processing thread, so script those execution takes a long time may hand processing of other widget bindings. It's recommended to create new threads for executing time-consuming tasks from widget scripts.