SVG 1.2 - 27 October 2004

Previous | Top | Next

3 XML Binding Language for SVG

3.1 Introduction

SVG 1.2 supports sXBL for custom markup extensibility via pre-packaged components. sXBL allows developers to create re-usable, higher-level components expressed in a custom XML vocabulary (tag set), where the implementation of these components is defined in terms of a shadow tree containing SVG content. For instance, with sXBL, it is possible to define a set of flowcharting components expressed in a custom flowcharting XML grammar. The sXBL-enabled flowcharting components would achieve their effects by attaching appropriate shadow trees of low-level SVG path and text elements to the SVG document. The shadow trees could include any SVG facilities, such as SVG container elements, SVG graphics elements, animation elements, and low-level event handlers for interactivity.

Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for all XBL features used by SVG is the sXBL specification.

3.2 Simple example

The following simple example is provided to introduce the reader to the most basic aspects of how sXBL works. For detailed processing rules and further examples, refer to the sXBL specification.

The following is a simple SVG example where a custom element, myNS:HelloWorld, acquires the alternate presentation behavior defined by the xbl:definition element at the top of the file. The myNS:HelloWorld element will be rendered by using the contents of the shadow tree which is attached by the binding. The shadow tree consists of a text element which has the string "Hello, world, using sXBL" inside:

<?xml version="1.0"?>
<svg width="10cm" height="3cm" viewBox="0 0 200 60"
     xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:xbl="http://www.w3.org/2004/xbl"
     xmsns:myNS="http://www.example.com">
  <title>Example xbl01.svg - "hello world" sample file</title>
  <desc>A simple "Hello, world" sXBL example where the
         rendering behavior of a custom element 'myNS:HelloWorld'
         consists of an 'svg:text' element which has the string 
         "Hello, world, using sXBL" inside.</desc>
  <defs>
    <xbl:xbl>

      <!-- The following 'xbl:definition' element defines the
         presentation and interactive behavior that must be used
         for all 'myNS:HelloWorld' elements in this document. -->
      <xbl:definition element="myNS:HelloWorld>
        <xbl:template>
          <text>Hello, world, using sXBL</text>
        </xbl:template>
      </xbl:definition>

    </xbl:xbl>
  </defs>

  <rect x="1" y="1" width="198" height="58" fill="none" stroke="blue"/>
  <g font-size="14" font-family="Verdana" transform="translate(10,35)">

    <!-- Here is an instance of an 'myNS:HelloWorld' element.
       The above binding definition attaches a shadow tree which
       defines alternative rendering and interactive behavior for this element.
       Instead of the standard SVG behavior where unknown elements are not rendered,
       the binding definition causes an 'svg:text' element to be rendered. -->
    <myNS:HelloWorld/>

  </g>

</svg>

The above example results in equivalent rendering to the following SVG. The highlighted sections below (i.e., the g and text elements) represent the shadow tree which the binding definition (i.e., the xbl:definition element defined above) attaches to the custom element. The SVG user agent renders the shadow tree in place of the custom element.

<svg width="10cm" height="3cm" viewBox="0 0 200 60"
       xmlns="http://www.w3.org/2000/svg" version="1.2">
    <title>Example xbl01-equivalent.svg - 
           equivalent rendering for "hello world" sample file</title>

    <rect x="1" y="1" width="198" height="58" fill="none" stroke="blue"/>
    <g font-size="14" font-family="Verdana" transform="translate(10,35)">

      <!-- The document is rendered as if the 'myNS:HelloWorld' element 
           were replaced by an SVG 'g' element with a 'text' element inside. -->
      <g>
        <text>Hello, world, using sXBL</text>
      </g>

    </g>

  </svg>

The result is as if the g element contained the text directly.

Simple XBL example

View this image as SVG (SVG 1.2 enabled browsers only)

3.3 sXBL restrictions with SVG

3.3.1 Standalone SVG documents restriction

The sXBL specification defines the terms bound document and the binding source document. The bound document contains the custom element (the "bound element"). The binding source document contains the binding definition (i.e., the xbl:definition element) for the custom element.

This specification only defines sXBL processing rules or stand-alone SVG documents where either of the following is true:

Future W3C specifications may define sXBL behavior in additional contexts (e.g., when an XBL-enabled SVG document fragment is embedded inline within a parent XHTML document).

3.3.2 Non-SVG element restriction

Within an SVG document fragment, sXBL binding definitions can only be applied to elements which are not in the SVG namespace. Documents which contain binding definitions for elements in the SVG namespace are in error.

The following sample code shows a binding definition for a custom element. This binding definition is conformant to this specification because the custom element belongs to a namespace different than the SVG namespace:

<svg xmlns="http://www.w3.org/2000/svg"
      xmlns:xbl="http://www.w3.org/2004/xbl"
      xmlns:zzz="http://example.com">
  <xbl:xbl>
    <!-- This binding definition is allowed. -->
    <xbl:definition element="zzz:Widget1">
      <!-- ... -->
    </xbl:definition>
  </xbl:xbl>

  <zzz:Widget1/>
</svg>

The following example shows three binding definitions that are not allowed:

<svg xmlns="http://www.w3.org/2000/svg"
      xmlns:svg="http://www.w3.org/2000/svg">
      xmlns:xbl="http://www.w3.org/2004/xbl">
  <xbl:xbl>
    <!-- This binding definition is not allowed because
         it attempts to define a custom element in the SVG namespace.
         (Note that in this example the default namespace
         is the SVG namespace.) -->
    <xbl:definition element="MySVGWidget1">
      <!-- ... -->
    </xbl:definition>
    <!-- Also not allowed. (This time the SVG prefix is used explicitly.) -->
    <xbl:definition element="svg:MySVGWidget2">
      <!-- ... -->
    </xbl:definition>
    <!-- Redefining SVG elements is also an error. -->
    <xbl:definition element="svg:path">
      <!-- ... -->
    </xbl:definition>
  </xbl:xbl>

  <MySVGWidget1/>
  <svg:MySVGWidget2/>
</svg>

3.4 sXBL rendering and event handling rules with SVG

When a custom element has an sXBL binding definition, the SVG user agent processes binding definitions according to the rules defined in the sXBL specification. SXBL processing of bindings may result in shadow content being attached to custom elements. If shadow content is attached to a custom element (i.e., if the xblShadowTree DOM attribute on the NodeXBL interface is not null), then the custom element's rendering and interactive behavior is defined by the shadow content. More specifically, except for other sXBL-specific details described in this chapter or the sXBL specification, the custom element is renderered and events are handled as follows:

It is important to note that all attributes on custom elements, including SVG-defined attributes, have no direct effect on rendering or interactive behavior. For example, suppose a custom element's schema allowed for fill and stroke attributes (which are SVG-defined attributes), and further suppose that the following custom element appeared within an SVG file:

<svg...>
<xbl:import bindings="..."/>
<MyNS:MyCustomElement fill="red" stroke="blue"/>
</svg>

The fill and stroke attributes are not processed as SVG presentation attributes. As far as the SVG user agent is concerned, unless the binding itself has specific logic to recognize these attributes, the user agent treats these attributes as custom attributes on a custom element and thus the attributes have no effect on rendering or interactive behavior. Note also that attributes in the SVG namespace (e.g., svg:fill or svg:transform) are treated in the same manner — the user agent treats these attributes as custom attributes on a custom element.

3.5 sXBL bindings for SVG resources

In the context of SVG, sXBL can be used to define custom gradients, patterns, solid color definitions, markers, clipping paths, masks, and filters. Here is an example of an sXBL binding which defines a custom linear gradient:

<!-- Binding source document -->
<?xml version="1.0"?>
<svg
     xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:xbl="http://www.w3.org/2004/xbl"
     xmsns:myNS="http://www.example.com">
  <defs>
    <xbl:xbl>

      <xbl:definition element="myNS:BlackWhiteGradient">
        <xbl:template>
          <linearGradient>
            <stop offset="0" stop-color="black"/>
            <stop offset="1" stop-color="white"/>
          </linearGradient>
        </xbl:template>
      </xbl:definition>

    </xbl:xbl>
  </defs>
</svg>

<!-- Bound document -->
<?xml version="1.0"?>
<svg width="10cm" height="3cm" viewBox="0 0 200 60"
     xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:xbl="http://www.w3.org/2004/xbl"
     xmsns:myNS="http://www.example.com">
  <title>Example xbl02.svg - defining a custom gradient</title>

  <xbl:import bindings="xbl02-bindings.svg"/>

  <!-- Instantiate the custom gradient -->
  <myNS:BlackWhiteGradient xml:id="grad1"/>

  <!-- Use the custom gradient to fill a rectangle -->
  <rect x="1" y="1" width="198" height="58" 
        fill="url(#grad1)" stroke="blue"/>
</svg>

A reference to a given resource type (e.g., fill="url(#grad1)") is a legal reference if the URI reference resolves to either of the following:

The following resource types can be defined using sXBL custom elements:

3.6 sXBL bindings for visual effects

In the context of SVG, sXBL can be used to define custom effects such as custom animations, custom filter primitives, custom vector effects, custom gradient stops, and custom geometry for clipping paths. Here is an example of an sXBL binding which defines a custom opacity fade animation:



<?xml version="1.0"?>
<svg width="10cm" height="3cm" viewBox="0 0 200 60"
     xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:xbl="http://www.w3.org/2004/xbl"
     xmsns:myNS="http://www.example.com">
  <title>Example xbl02.svg - defining a custom animation</title>
  <defs>
    <xbl:xbl>

      <xbl:definition element="myNS:FadeOnClick">
        <xbl:template>
          <animate attributeName="opacity" begin="click" dur="3s" from="1" to="0"/>
        </xbl:template>
      </xbl:definition>

    </xbl:xbl>
  </defs>

  <rect x="1" y="1" width="198" height="58" fill="red" stroke="blue">
    <!-- The rectangle will fade to invisible when the user clicks on it. -->
    <myNS:FadeOnClick/>
  </rect>
</svg>

For all of these custom visual effects scenarios, a visual effect can be defined in either of the following ways:

If the custom element fulfills some of the requirements for a custom visual effect, but does not fulfill all of the requirements, then the custom element is in error.

Animation elements in SVG change the attributes or properties over time on a target element. If the animation element has an xlink:href attribute, then the URI reference defined by the xlink:href identifies the target element; otherwise, the target element is the parent of the animation element. For XBL-defined custom animations, however, SVG's standard rules for identifying the target element are not workable because XPointer references within the shadow tree are relative to the binding source document, not the bound document, and because the DOM Core parent element in the shadow tree is not the bound element. Because of these issues, the following additional rules apply to identify the target element for any animation elements within shadow trees:

3.7 The traitDef element

A trait is a potentially animatable parameter associated with an element. A trait is the value that gets assigned through an XML attribute or CSS style or SMIL animation. In the case of sXBL, it describes an attribute on a custom element, allowing it to be exposed to the animation engine and allowing typed-base DOM access using method calls such as getFloatTrait().

Traits for custom elements are described using the traitDef element.

traitDef Schema

  <define name='traitDef'>
    <element name='traitDef'>
      <ref name='attlist.traitDef'/>
    </element>
  </define>

  <define name='attlist.traitDef' combine='interleave'>
    <ref name='SVG.Core.attrib'/>
    <attribute name='name' svg:animatable='false' svg:inheritable='false'/>
    <attribute name='namespace' svg:animatable='false' svg:inheritable='false'>
      <ref name='URI.datatype'/>
    </attribute>
    <attribute name='valueType' svg:animatable='false' svg:inheritable='false'>
      <choice>
        <value>http://www.w3.org/2001/XMLSchema#string</value>
        <value>http://www.w3.org/2001/XMLSchema#float</value>
        <value>http://www.w3.org/2000/svg#SVGLength</value>
        <value>http://www.w3.org/2000/svg#SVGMatrix</value>
        <value>http://www.w3.org/2000/svg#SVGPath</value>
        <value>http://www.w3.org/2000/svg#SVGRect</value>
        <value>http://www.w3.org/2000/svg#SVGRGBColor</value>
      </choice>
    </attribute>
  </define>

The name and namespace attributes respectively specify the name and namespace of the attribute.

The valueType attribute defines the datatype for the given attribute as a URI in a format compatible with XML Schema Datatypes. For example, a "float" datatype is defined by the URI of "http://www.w3.org/2001/XMLSchema#float". The following values are supported:

Below is an example that defines traits for the x, y, width and height attributes for a custom foo:button element:

<xbl:definition element="foo:button">
  <traitDef name="x" namespace="" valueType="http://www.w3.org/2000/svg#SVGLength"/>
  <traitDef name="y" namespace="" valueType="http://www.w3.org/2000/svg#SVGLength"/>
  <traitDef name="width" namespace="" valueType="http://www.w3.org/2000/svg#SVGLength"/>
  <traitDef name="height" namespace="" valueType="http://www.w3.org/2000/svg#SVGLength"/>
  <xbl:template>
    ....
  </xbl:template>
</xbl:definition>

3.8 Trait mutation events

If a trait value or the animated value of a trait changes for any reason, a TraitMutationEvent is fired.

interface TraitMutationEvent : events::Event
{
         // event is dispatched to the element and does not bubble
         // event names are "TraitValueChanged" and "TraitAnimValueChanged"
         DOMString traitNamespace;
         DOMString traitLocalName;
}

A trait change is different from a regular attribute change. For instance a numeric trait changing its attribute value from "1" to "1.0" does not change the value of the trait. The value of the trait is not attached to the event, because traits can be of different types. The value must be retrieved from the element.

3.9 Document loading

The sXBL specification defines the term binding source document to represent a document which contains sXBL binding definitions. Binding definitions can be in the original document (what sXBL refers to as the bound document) or in a separate, externally referenced document.

Externally referenced source binding documents are managed in the same manner as SVG manages all externally referenced documents.

3.10 Scripts and handlers

Any script and handler elements in the SVG namespace contained within sXBL subtrees are treated in the same manner as script elements contained directly within SVG content. The defined scripting logic belongs to the document referenced by the ownerDocument DOM attribute on the DOM object corresponding to the given script or handler element. The scripting context for any scripting logic invoked within shadow trees is the same as any scripting logic defined within the binding source document. Thus, in ECMAScript, if the binding source document has a script element which defines a findAttribute function which is available on a document-global basis, then shadow trees are able to invoke the findAttribute function in the same way as the original content of the binding source document.

3.11 CSS Stylesheets

For binding source documents, any CSS stylesheets embedded within a style element in the SVG namespace or referenced by an XML stylesheet processing instruction or a style element in the SVG namespace are applied to the document which embeds or contains the reference to the given stylesheet, even if the style element is embedded within an sXBL subtree. In particular, any CSS stylesheets embedded within or referenced by a style element in the SVG namespace apply to the document referenced by the ownerDocument DOM attribute on the DOM object corresponding to the given style element.

Because shadow trees can be regenerated repeatedly during the time a document is presented to the user, there is a potentially difficult specification and implementation issue if style elements were allowed to be built dynamically by sXBL binding definitions and inserted into shadow trees. In order to avoid these complications, this specification includes the restriction that is an error to include style elements and xml-stylesheet processing instructions in shadow trees. If either is included within a shadow tree, the document is in error. Note that it is possible to include style elements and xml-stylesheet processing instructions within binding source documents and that the corresponding style sheets will apply to the shadow content; thus, this restriction only has to do with the shadow content that is generated by the binding definitions. (Note: Future W3C specifications might remove this restriction partially or completely.)

3.12 Focus and navigation

Shadow content participates in keyboard focus and navigation (e.g., via tabbing between focusable fields) as if the shadow content is replacing the corresponding custom element. For example, suppose there is an sXBL-defined custom element MyNS:NameWidget which creates a shadow tree of three SVG editable text elements. SVG user agents must allow navigation from editable text elements in the original SVG document into the shadow content's three editable text elements and back again as if the focusable fields in the shadow content were part of the original document.

The one difference in field navigation behavior due to the presence of sXBL shadow content is that the 'nav-index' property has hierarchical behavior when an sXBL-defined custom element contains focusable elements. The definition for this hierachical behavior for 'nav-index' can be found in the focus section in the sXBL specification.

DOM interfaces for custom elements

All non-SVG elements within an SVG document support the xbl::NodeXBL interface defined in the sXBL specification and also support all of the same interfaces as the g element (e.g., all of the methods and properties of SVGElement, SVGTests, SVGLangSpace, SVGExternalResourcesRequired, SVGStyleable, SVGTransformable, events::EventTarget). This allows, for example, the ability to call method getBBox() on a custom element which has renderable content in its shadow tree.

3.13 Error handling

sXBL content within an SVG document is subject to the same error processing rules as the rest of the SVG document. In addition to the standard SVG rules about correct document formulation, an SVG document containing sXBL elements is technically in error when: