The 'contentScriptType' attribute on the 'svg' element specifies the default scripting language for the given document fragment.
It is also possible to specify the scripting language for each individual script or handler elements by specifying a type attribute on the script and handler elements.
A script element may either contain or point to executable content (e.g., ECMAScript [ECMAScript] or Java [JAVA] JAR file). Executable content can come either in the form of a script (textual code) or in the form of compiled code. If the code is textual, it can either be placed inline in the script element (as character data) or as an external resource, referenced through xlink:href attribute. Compiled code must be an external resource.
Scripting languages (such as ECMAScript) that have a notion of a "global scope" or a "global object" such that a single global object must be associated with the document (unique for each uDOM Document node). This object is shared by all elements contained in that document. Thus, an ECMAScript function defined within any script element must be in the "global" scope of the entire document to which the script belongs. The global object must have all the methods and attributes from the SVGGlobal interface. It must be made available from an SVGDocument through the global
attribute. Event listeners attached through event attributes and handler elements are also evaluated using the global scope of the document in which they are defined.
For compiled languages (such as Java) that don't have a notion of "global scope", each script element, in effect, provides a separate scope object. This scope object must perform an initialization as described in the uDOM chapter and serves as event listener factory for the handler element.
Any scripting logic associated with a given script element is
executed at most once. Script execution happens just after the load
event occurs
for the given script element. Removing,
inserting or altering script elements after script execution has taken place has
no effect.
Exact details on how this element works depend on the executable content's type. SVG Tiny 1.2 does not require support for any particular programming language. However, SVG defines the behavior for two specific script types in the case where an implementation supports it:
This type of executable content must be source code for the ECMAScript programming language. This code must be executed in the context of this element's owner document's global scope as explained above.
SVG implementations that load external resources through protocols such as HTTP that support content coding must accept external script files that have been encoded using gzip compression (flagged using "Content-Encoding: gzip" for HTTP).
This type of executable content must be an external resource that contains a Java JAR archive. The manifest file in the JAR archive must have an entry named SVG-Handler-Class. The entry's value must be a fully-qualified Java class name for a class contained in this archive. The user agent must instantiate the class from the JAR file and cast it to
the EventListenerInitializer2 interface. Then the initializeEventListeners
method must be called with the script element object itself as a parameter. If a class listed in SVG-Handler-Class does not implement EventListenerInitializer2, it is an error.
Note that the user agent may reuse classes loaded from the same URL, so the code must not assume that every script element or every document will create its own separate class object. Thus, one cannot assume, for instance, that static fields in the class are private to a document.
Implementations should also accept the script type "text/ecmascript" for backwards compatibility with SVG 1.1. However, this type is deprecated and should not be used by content authors.
Other language bindings are encouraged to adopt a similar approach to either of the two described above.
Example 18_01 defines a
function circle_click
which is called when the 'circle' element is being clicked. The drawing
below on the left is the initial image. The drawing below on
the right shows the result after clicking on the circle. The example uses the
handler element which is described further down in this chapter.
Note that this example demonstrates the use of the click
event for
explanatory purposes. The example presupposes the presence of
an input device with the same behavioral characteristics as a
mouse, which will not always be the case. To support the widest
range of users, the activate
event attribute should be used instead
of the click
event attribute.
<?xml version="1.0"?> <svg width="6cm" height="5cm" viewBox="0 0 600 500" xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" xmlns:ev="http://www.w3.org/2001/xml-events"> <desc>Example: invoke an ECMAScript function from an click event </desc> <!-- ECMAScript to change the radius with each click --> <script type="application/ecmascript"> <![CDATA[ function circle_click(evt) { var circle = evt.target; var currentRadius = circle.getFloatTrait("r"); if (currentRadius == 100) circle.setFloatTrait("r", currentRadius*2); else circle.setFloatTrait("r", currentRadius*0.5); } ]]> </script> <!-- Outline the drawing area with a blue line --> <rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/> <!-- Act on each click event --> <circle cx="300" cy="225" r="100" fill="red"> <handler type="application/ecmascript" ev:event="ev:click"> circle_click(evt); </handler> </circle> <text x="300" y="480" font-family="Verdana" font-size="35" text-anchor="middle"> Click on circle to change its size </text> </svg>
<define name='script'> <element name='script'> <ref name='script.AT'/> <ref name='script.CM'/> </element> </define> <define name='script.AT' combine='interleave'> <ref name='svg.CorePreserve.attr'/> <ref name='svg.External.attr'/> <ref name='svg.ContentType.attr'/> </define> <define name='script.CM'> <choice> <group> <ref name='svg.XLinkRequired.attr'/> </group> <text/> </choice> </define>
Attribute definitions:
XML Events is an XML syntax for integrating event listeners and handlers with DOM 2 and DOM 3 Event interfaces. Declarative event handling in SVG 1.1 was hardwired into the language, in that the developer was required to embed the event handler in the element syntax (e.g. an element with an onclick attribute). SVG Tiny 1.2 does not support the event attributes (onload, onclick, onactivate, etc.). Instead SVG Tiny 1.2 uses XML Events to provide the ability to specify the event listener separately from the graphical content.
SVG Tiny 1.2 uses XML Events and makes the following modifications:
The list of events supported by SVG Tiny 1.2 is given in the Interactivity chapter.
There are two ways to place a handler in SVG Tiny 1.2 content. The first method is most suitable for simple cases:
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" xmlns:ev="http://www.w3.org/2001/xml-events"> <rect x="10" y="20" width="10" height="20" fill="red"> <handler type="application/ecmascript" ev:event="ev:click"> var myRect = evt.target; var width = myRect.getFloatTrait("width")); myRect.setFloatTrait("width", (width+10)); </handler> </rect> </svg>
In this method the handler element is a child element of the observer. For instance one can place a handler as a child of a rect element, which becomes the observer. This causes the handler element to be invoked whenever the event that it is interested in (e.g.: "click") occurs on the rect.
The following is an example of an SVG document using XML Events where the handler element can be reused on several objects. The listener element from XML Events is used to specify the observer and handler for a particular event.
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" xmlns:ev="http://www.w3.org/2001/xml-events"> <desc>An example of the handler element.</desc> <rect xml:id="myRect1" x="10" y="20" width="10" height="20" fill="red"/> <rect xml:id="myRect2" x="10" y="40" width="10" height="20" fill="green"/> <ev:listener event="ev:click" observer="#myRect1" handler="#myClickHandler"/> <ev:listener event="ev:click" observer="#myRect2" handler="#myClickHandler"/> <handler xml:id="myClickHandler" type="application/ecmascript"> var myRect = evt.target; var width = myRect.getFloatTrait("width")); myRect.setFloatTrait("width", (width+10)); </handler> </svg>
In the above example, the ev:listener element registers that the myClickHandler element should be invoked whenever a click
event happens on "myRect1" or "myRect2".
The combination of the XML Events syntax and the new handler element allows event handling to be more easily processed in a compiled language. Below is an example of an event handler using the Java language:
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:foo="http://www.example.com/foo" xmlns:xlink="http://www.w3.org/1999/xlink"> <desc>Example of a Java handler</desc> <rect xml:id="myRect" x="10" y="20" width="200" height="300" fill="red"/> <!-- reference a jar containing an EventListenerInitializer2 object --> <script type="application/java-archive" xml:id="init" xlink:href="http://example.com/myJar.jar"/> <!-- register a listener for a myRect.click event --> <ev:listener event="ev:click" observer="#myRect" handler="#myClickHandler" /> <handler xml:id="myClickHandler" type="application/java-archive" xlink:href="#init" foo:offset="10"/> </svg>
In this case, the handler element specifies a reference to the script element that specificies the location of compiled code that conforms to the EventListenerInitializer2 interface. The user agent invokes the createEventListener
method within the targeted interface.
In this case, the MyEventListenerInitializer2 referenced by the SVG-Handler-Class entry of the myJar.jar manifest has the following definition:
package com.example; import org.w3c.svg.EventListenerInitializer2; import org.w3c.dom.Document; import org.w3c.dom.Element; import org.w3c.dom.events.Event; import org.w3c.dom.events.EventListener; public class MyEventListenerInitializer2 implements EventListenerInitializer2 { Document document; public void initializeEventListeners(Element scriptElement) { document = scriptElement.getOwnerDocument(); } public EventListener createEventListener(final Element handlerElement) { return new EventListener() { public void handleEvent(Event event) { Element myRect = document.getElementById("myRect"); float width = Float.parseFloat(myRect.getAttributeNS(null, "width")); float offest = Float.parseFloat(handlerElement.getAttributeNS("http://www.example.com/foo", "offset"); myRect.setAttributeNS(null, width, "" + (width + 10)); } }; } }
The EventListenerInitializer2 interface is currently defined in the SVG package. Future specifications may move this package though it is guaranteed to always be available in the SVG package.
The 'listener' element from XML Events [XML-EVENTS] must be supported. The definition for the 'listener' element is provided in [XML-EVENTS]. Any additional restrictions from this specification must also apply.
Whenever a 'listener' element is removed (via uDOM, discard, ...), the behavior is the same as if the removeEventListener
method was called on the observer element on which the event listener was registered. Note that if the 'observer' attribute is not present, the observer is the parent of the 'listener' element.
Please note that the 'listener' element must be specified in the XML Events namespace, and that an element in the SVG namespace with 'listener' as its local name must not be understood as being the element described in this chapter. Furthermore, the XML Events attributes that are available on other elements only when they are in the XML Events namespace, are only available on this element when they are in no namespace.
<define name='listener'> <element name='listener'> <ref name='listener.AT'/> <ref name='listener.CM'/> </element> </define> <define name='listener.AT' combine='interleave'> <ref name='svg.Core.attr'/> <optional> <attribute name='event' svg:animatable='false' svg:inheritable='false'> <ref name='XSLT-QName.datatype'/> </attribute> </optional> <optional> <attribute name='phase' svg:animatable='false' svg:inheritable='false'> <choice> <value>default</value> <value>capture</value> </choice> </attribute> </optional> <optional> <attribute name='propagate' svg:animatable='false' svg:inheritable='false'> <choice> <value>continue</value> <value>stop</value> </choice> </attribute> </optional> <optional> <attribute name='defaultAction' a:defaultValue='perform' svg:animatable='false' svg:inheritable='false'> <choice> <value>perform</value> <value>cancel</value> </choice> </attribute> </optional> <optional> <attribute name='observer' svg:animatable='false' svg:inheritable='false'> <ref name='IRI.datatype'/> </attribute> </optional> <optional> <attribute name='target' svg:animatable='false' svg:inheritable='false'> <ref name='IRI.datatype'/> </attribute> </optional> <optional> <attribute name='handler' svg:animatable='false' svg:inheritable='false'> <ref name='IRI.datatype'/> </attribute> </optional> </define> <define name='listener.CM'> <empty/> </define>
Attribute definitions:
The handler element is similar to the script element: its contents, either included inline or referenced, are code that is to be executed by the scripting engine(s) used by user agent.
However, where the script element executes its contents when the document is loaded, the handler element must only execute its contents in response to an event. This means that SVG Tiny 1.2 uses handler to get the functionality equivalent to that provided by SVG Full event attributes. Removing, inserting or altering handler elements after their content has been loaded has no effect on executable content, but changes made to the parameters that are available from a given handler element must be reflected when the handler content is executed.
For example, consider the following SVG 1.1 document:
<svg xmlns="http://www.w3.org/2000/svg" version="1.1">
<rect id="#myRect" x="10" y="20" width="200" height="300" fill="red"
onclick="evt.target.width.baseVal.value += 10"/>
</svg>
The above example must be rewritten to use the handler element and XML Events (described below) as shown:
<?xml version="1.0" encoding="utf-8"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.2" xmlns:ev="http://www.w3.org/2001/xml-events"> <desc>handler element example</desc> <rect xml:id="myRect" x="10" y="20" width="200" height="300" fill="red"> <handler type="application/ecmascript" ev:event="ev:click"> var myRect = evt.target; var width = myRect.getFloatTrait("width"); myRect.setFloatTrait("width", (width+10)); </handler> </rect> </svg>
In ECMAScript, the contents of the handler element behave as if they are the contents of a new Function object, created as shown:
Function(evt) {
//contents of handler
}
Other interpreted languages should behave in a similar manner.
The 'evt' parameter shown above is an Event object corresponding to the event that has triggered the handler.
<define name='handler'> <element name='handler'> <ref name='handler.AT'/> <ref name='handler.CM'/> </element> </define> <define name='handler.AT' combine='interleave'> <ref name='svg.CorePreserve.attr'/> <ref name='svg.External.attr'/> <attribute name='ev:event' svg:animatable='false' svg:inheritable='false'> <ref name='XSLT-QName.datatype'/> </attribute> <ref name='svg.ContentType.attr'/> </define> <define name='handler.CM'> <choice> <group> <ref name='svg.XLinkRequired.attr'/> </group> <text/> </choice> </define>
Attribute definitions:
For compiled languages, the xlink:href attribute must reference a script element that itself references a JAR archive holding a manifest with an SVG-Handler-Class entry pointing to an EventListenerInitializer2 implementation.
In many situations, the script author uses the handler as a template for calling other functions, using the content of the handler element to pass parameters. However, for compiled languages the handler element does not have any executable content.
In this case, the author should embed the parameters into the handler as custom content under the form of element children in a foreign namespace, or attributes on the handler element also in foreign namespaces.
Below is an example of using parameters on the handler element:
<svg xmlns="http://www.w3.org/2000/svg" version="1.2" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:foo="http://www.example.com/foo" xmlns:xlink="http://www.w3.org/1999/xlink"> <desc>An example of parameters on the handler element.</desc> <rect xml:id="myRect" x="10" y="20" width="200" height="300" fill="red"/> <!-- reference a jar containing an EventListenerInitializer2 object --> <script type="application/java-archive" xml:id="init" xlink:href="http://example.com/myJar.jar"/> <!-- register a listener for a myRect.click event --> <ev:listener event="ev:click" observer="#myRect" handler="#myClickHandler" /> <handler xml:id="myClickHandler" type="application/java-archive" xlink:href="#init"> <foo:offset value="10"/> <foo:person> <foo:name>Victor Vector</foo:name> <foo:age>42</foo:age> </foo:person> </handler> </svg>
In this case, the object referenced by the SVG-Handler-Class entry of the myJar.jar manifest has its createEventListener
method called and the returning EventListener registered. Whenever a click
event on the 'myRect' object is observed, the handleEvent
method of the listener is called. The object can then access of the handler element in order to obtain its parameters from elements in the "foo" namespace.
Events must cause scripts to execute when either of the following has occurred:
Related sections of the spec:
The Scripting Module contains the following element:
[RNG] [Feature String]The Handler Module contains the following element:
[RNG] [Feature String]The Listener Module contains the following element:
[RNG] [Feature String]