Scripts

Scripts in XUL files allow to listen to widget events, or modify XUL widgets attributes.

Types of scripts languages

The following script languages are supported:

• Javascript scripts. Javascript scripts are more tightly integrated than other scripting languages and therefore have additional capabilities
• Groovy scripts
• Python scripts
• Ruby scripts

Note that all scripts are managed by the scriptHelper library.

Scripts signature

By default the scripts are free to have any script signature, but it is possible to customize the ScriptFactory to specify that the script have to implement a specified interface. This can be useful for the integration between your scripts and your own Java API (see also XUL scripts integration).

Script MIME type

The type attribute of the script element defines the MIME type of the script.

• If the type attribute is not defined, and the script is embedded, the script will be assumed to be a Javascript script
• If the type attribute is not defined, and the script is external the script will be inferred from the file extension

See also Inferring script types.

Script import declarations

Several classes are imported by default in all scripts. Additional import declaration syntax depend on the scripting language. See:

• Groovy import declarations for Groovy
• Python import declarations for Python
• Ruby import declarations for Ruby
• Javascript import declarations for Javascript

Types of scripts

There are two types of scripts define in XUL files. They are both defined through the script element:

• External scripts which are script files referenced in your XUL file
• Embedded scripts which are scripts defined inside your XUL file

Embedded scripts

Embedded scripts are scripts defined inside your XUL file.

For example:

      <script>
      function clicked(){
        alert('Hello World!');
      }
      </script>           

or:

      <script type="application/groovy">
      public int getValue(){
        return 10;
      }
      </script>           

External scripts

External scripts are script files referenced in your XUL file. Note that external scripts can be local or global to the XUL file (see Setting scripts as global to all XUL files for more information).

For example:

      <script src="myScript.js" />       

Scripting architecture

Scripting in javaXUL use the scriptHelper library. By default there are no constraints on the scripts method declaration, but it is possible to customize the cration of scripts, for example to make them implement specific interfaces, for all sccripts or only for some of them.

Bindings from XUL widgets to scripts

The value of the parameter defined in a command attribute (such as oncommand, onclick, or onchange) must refer to a function or method defined for a script associated with the XUL script^[1]

This script can be embedded or defined externally for the XUL script

.

Note that the framework will take care of the function or method signature when determining which script to execute.

For example:

      <window title="Hello" orient="horizontal" width="250" height="100"  
      xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">        
          <script>
      function clicked() {
        alert('Hello World!');
      }
          </script>         
          <button label="Push Me!" oncommand="clicked()" />
      </window>      

Bindings from XUL widgets to non-Javascript scripts

Note that by default only Javascript scripts can be triggered by widget events. However it is possible to specify that all scripts referenced by the XUL document can be triggered by ScriptManager.listAllScriptTypes(boolean).

For example, if this option has been set to true, this XUL script is valid:

      <window title="Hello" orient="horizontal" width="250" height="100"  
      xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">        
          <script type="text/groovy" >
      public int clicked() {
        context.echo("Hello World!");
      }
          </script>         
          <button label="Push Me!" oncommand="clicked()" />
      </window>      

Accessing the owner document

The getCurrentDocument() and getCurrentWidget() on the helper will return the XUL document or widget from which originates the last event.

It will return:

• The first document for which the script has been added before any event have been triggered for the getCurrentDocument() method
• null before any event have been triggered for the getCurrentWidget() method

Note that there is a much simpler way to access the widgets for Javascript scripts, see accessing the document.

Helper and context

The global context and helper are available in all the scripts.

The context is available through the context field in your script. For example:

      public void clicked() {
        context.echo("Hello World");
      }

The script helper is available through the helper field in your script. For example:

      public void clicked() {
        XULWidget widget helper.getCurrentWidget();
      }