XUL 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:

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

Note that all scripts are managed by the XUL scriptHelper library.

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 XUL 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
• 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.

For example:

      <script src="myScript.js" />

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>

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 XUL Javascript scripts, see accessing the document.

Helper and context

The global context and helper are available in all the XUL 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();
      }

Accessing services

Subscribing to services

Each script has a subscribe(service) method which will be notified for each service notification on the module. For example:

      <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
      <window id="vboxExample" title="Example" width="200" height ="200"
              xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">  
         <script>
            function subscribe(service) {
              var value = service.getData("value").getValueAsInt();      
              document.getElementById("label").value = value;
            }       
         </script>   
         <hbox>
            <button id="button" label="Positive Step" oncommand="toggle()" />
            <label id="label" value="0" />
         </hbox>
      </window>

Invoking services

The context has two methods which allow to get a particular service:

• The getService(serviceName) method allows to get the service of a specified name
• The getService(serviceName, serviceURI) method allows to get the service of a specified name and namespace

The returned service can be used to invoke a service provided by the module. For example:

      <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
      <window id="vboxExample" title="Example" width="200" height ="200"
              xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">  
         <script>
            var positive = true;
            function toggle() {   
              positive = !positive;
              if (!positive) {
                document.getElementById("button").label = "Positive Step";
              } else {
                document.getElementById("button").label = "Negative Step";		
              }		
              var service = context.getService("event");
              service.getData("event").setBooleanValue(positive);
              service.invoke();
            }            
         </script>  
         <hbox>
            <button id="button" label="Positive Step" oncommand="toggle()" />
            <label id="label" value="0" />
         </hbox>
      </window>