The Apache FOP Project

The Apache™ Batik Project

Scripting with ECMAScript

This page is a brief introduction to scripting SVG documents with ECMAScript, and how Batik’s ECMAScript environment can be extended.

Scripting basics

As the ECMAScript language (the standardised version of JavaScript) is one of the most popular scripting languages, and as the SVG specification states that an SVG conforming implementation must support it, SVG documents processed by Batik support scripting with ECMAScript using Mozilla’s ECMAScript interpreter, Rhino.

There are two places in an SVG file where you can put scripts.

The first one is in the script element, where you can place any code, including function definitions, to be executed just before the document SVGLoad event is fired.

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <script type="text/ecmascript">
    // ECMAScript code to be executed
  </script>

  <!-- Remainder of the document... -->
</svg>

You can also attach script to respond to user or document events using attributes on SVG elements. As shown in the previous example, the scripting language must be set on the script element. However, for event handling the default language type text/ecmascript is assumed. If you want to change it you can use the contentScriptType attribute on the svg element.

The event attribute can contain any script code to execute when the event reaches the element (as described by the DOM event flow) in either the bubbling or at-target phases. The following example will change the rect to be filled in blue when it is clicked.

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <rect x="0" y="0" width="10" height="10"
        onclick="evt.target.setAttribute('fill', 'blue')"/>
</svg>

Note that inside the event attribute script, there is a variable called evt that is a reference to the Event object that represents the event that is being handled.

For more information on using scripting in SVG you can have a look at:

Using Rhino features

Rhino has a number of features beyond those supported by standard ECMAScript interpreters, and these can be used with Batik. One useful feature is that ECMAScript code can use Java classes and objects, and not just the standard ECMAScript primitive types and host objects exposed by Batik.

To create an instance of a Java class from ECMAScript, you first need to import the package in which it resides. This is done using the importPackage global function that Rhino provides. For example, to import the javax.swing.JFrame class, you use:

importPackage(Packages.javax.swing);

This then exposes a global property for each class in the javax.swing package that you can use to create a new object of this class, similar to a import javax.swing.*; statement in Java. We can use the exposed JFrame property to create a new instance of this class:

var frame = new JFrame("My test frame");

Note how an ECMAScript string value is passed as the parameter to JFrame ’s constructor. Rhino will attempt to convert ECMAScript values into appropriate Java primitive types or objects to make underlying constructor or method calls. In this instance, the ECMAScript string value is converted into a java.lang.String object to be passed to the constructor.

Now that we have a reference to this Java object, we can call any method on it as we usually would from Java code. The following complete example demonstrates this, where clicking the green circle will pop up a frame:

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <circle cx="50" cy="50" r="50" fill="green" onclick="showFrame()"/>
  <script type="text/ecmascript">
    importPackage(Packages.javax.swing);

    function showFrame() {
      var frame = new JFrame("My test frame");
      var label = new JLabel("Hello from Java objects created in ECMAScript!");
      label.setHorizontalAlignment(SwingConstants.CENTER);
      frame.getContentPane().add(label);
      frame.setSize(400, 100);
      frame.setVisible(true);
      frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE);
    }
  </script>
</svg>

For more information on scripting Java classes from ECMAScript code, see Rhino's Scripting Java document.

Customizing the Rhino interpreter

A useful example of customization of the Rhino interpreter comes from the fact that the ECMAScript specification doesn’t provide any predefined I/O facilities to interact with the console. However, it is very common for ECMAScript compatible languages to provide a function named print to output messages to the console. We will describe here an example of cutomization of the Batik Rhino interpreter to add such functionality to it.

You should first subclass the default Batik ECMAScript interpreter to add the functionality to it as below.

import org.apache.batik.script.rhino.RhinoInterpreter;

import java.net.URL;

import org.mozilla.javascript.Context;
import org.mozilla.javascript.Function;
import org.mozilla.javascript.Scriptable;
import org.mozilla.javascript.ScriptableObject;
import org.mozilla.javascript.PropertyException;

public class ExtendedRhinoInterpreter extends RhinoInterpreter {

    public ExtendedRhinoInterpreter(URL documentURL) {
        super(documentURL);

        // Array of functions to put in the global object.
        final String[] names = { "print" }
        try {
            // Add the functions to the global object.
            getGlobalObject().defineFunctionProperties
                (names, ExtendedRhinoInterpreter.class,
                 ScriptableObject.DONTENUM);
        } catch (PropertyException e) {
            throw new Error(e);
        }
    }

    public static void print(Context cx, Scriptable thisObj,
                             Object[] args, Function funObj) {
        for (int i = 0; i < args.length; i++) {
            if (i > 0) {
                System.out.print(" ");
            }

            // Convert the ECMAScript value into a string form.
            String s = Context.toString(args[i]);
            System.out.print(s);
        }
        System.out.println();
    }
}

Now, you need to tell to Batik to use this interpreter instead of the default one. For that, you must first define a factory to create instances of your interpreter.

import org.apache.batik.script.Interpreter;
import org.apache.batik.script.rhino.RhinoInterpreterFactory;

public class ExtendedRhinoInterpreterFactory extends RhinoInterpreterFactory {

    public Interpreter createInterpreter(URL documentURL, boolean isSVG12) {
        return new ExtendedRhinoInterpreter(documentURL);
    }
}

Then, you must build an IntepreterPool that will use this factory, and then set the pool on the BridgeContext of your application.

org.apache.batik.bridge.BridgeContext ctx = ...;
org.apache.batik.script.InterpreterPool pool =
    new org.apache.batik.script.InterpreterPool();
InterpreterFactory f = new ExtendedRhinoInterpreterFactory();

// Register the interpreter factory for all four MIME types that
// Batik normally supports for ECMAScript.
pool.putInterpreterFactory("text/ecmascript", f);
pool.putInterpreterFactory("text/javascript", f);
pool.putInterpreterFactory("application/ecmascript", f);
pool.putInterpreterFactory("application/javascript", f);
ctx.setIntepreterPool(pool);

For example if you are using the Batik SVG browser application you should be able to use the previous piece of code on a subclass of the JSVGCanvas class in the createBridgeContext() method.

For further information on working with Rhino, consult the Rhino website.