14 January 2003

23 Extensibility



23.1 Foreign namespaces and private data

SVG allows inclusion of elements from foreign namespaces anywhere with the SVG content. In general, the SVG user agent will include the unknown elements in the DOM but will otherwise ignore unknown elements. (The notable exception is described under Embedding Foreign Object Types.)

Additionally, SVG allows inclusion of attributes from foreign namespaces on any SVG element. The SVG user agent will include unknown attributes in the DOM but with otherwise ignore unknown attributes.

SVG's ability to include foreign namespaces can be used for the following purposes:

To illustrate, a business graphics authoring application might want to include some private data within an SVG document so that it could properly reassemble the chart (a pie chart in this case) upon reading it back in:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in" version="1.1"
     xmlns = 'http://www.w3.org/2000/svg'>
    <myapp:piechart xmlns:myapp="http://example.org/myapp"
                    title="Sales by Region">
      <myapp:pieslice label="Northern Region" value="1.23"/>
      <myapp:pieslice label="Eastern Region" value="2.53"/>
      <myapp:pieslice label="Southern Region" value="3.89"/>
      <myapp:pieslice label="Western Region" value="2.04"/>
      <!-- Other private data goes here -->
  <desc>This chart includes private data in another namespace
  <!-- In here would be the actual SVG graphics elements which
       draw the pie chart -->

23.2 Embedding foreign object types

One goal for SVG is to provide a mechanism by which other XML language processors can render into an area within an SVG drawing, with those renderings subject to the various transformations and compositing parameters that are currently active at a given point within the SVG content tree. One particular example of this is to provide a frame for XML content styled with CSS or XSL so that dynamically reflowing text (subject to SVG transformations and compositing) could be inserted into the middle of some SVG content. Another example is inserting a MathML expression into an SVG drawing.

The 'foreignObject' element allows for inclusion of a foreign namespace which has its graphical content drawn by a different user agent. The included foreign graphical content is subject to SVG transformations and compositing.

The contents of 'foreignObject' are assumed to be from a different namespace. Any SVG elements within a 'foreignObject' will not be drawn, except in the situation where a properly defined SVG subdocument with a proper xmlns (see "Namespaces in XML" [XML-NS]) attribute specification is embedded recursively. One situation where this can occur is when an SVG document fragment is embedded within another non-SVG document fragment, which in turn is embedded within an SVG document fragment (e.g., an SVG document fragment contains an XHTML document fragment which in turn contains yet another SVG document fragment).

Usually, a 'foreignObject' will be used in conjunction with the 'switch' element and the requiredExtensions attribute to provide proper checking for user agent support and provide an alternate rendering in case user agent support is not available.

23.3 The 'foreignObject' element

<!ENTITY % SVG.foreignObject.extra.content "" >
<!ENTITY % SVG.foreignObject.element "INCLUDE" >
<!ENTITY % SVG.foreignObject.content
    "( #PCDATA %SVG.foreignObject.extra.content; )*"
<!ELEMENT %SVG.foreignObject.qname; %SVG.foreignObje\
ct.content; >
<!-- end of SVG.foreignObject.element -->]]>
<!ENTITY % SVG.foreignObject.attlist "INCLUDE" >
<!ATTLIST %SVG.foreignObject.qname;
    x %Coordinate.datatype; #IMPLIED
    y %Coordinate.datatype; #IMPLIED
    width %Length.datatype; #REQUIRED
    height %Length.datatype; #REQUIRED
    transform %TransformList.datatype; #IMPLIED

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the graphics associated with the contents of the 'foreignObject' will be rendered.
If the attribute is not specified, the effect is as if a value of "0" were specified.
Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the referenced document is placed.
If the attribute is not specified, the effect is as if a value of "0" were specified.
Animatable: yes.
width = "<length>"
The width of the rectangular region into which the referenced document is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
Animatable: yes.
height = "<length>"
The height of the rectangular region into which the referenced document is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
Animatable: yes.

23.4 An example

Here is an example:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in" version="1.1"
 xmlns = 'http://www.w3.org/2000/svg'>
  <desc>This example uses the 'switch' element to provide a 
        fallback graphical representation of an paragraph, if 
        XMHTML is not supported.</desc>
  <!-- The 'switch' element will process the first child element
       whose testing attributes evaluate to true.-->
    <!-- Process the embedded XHTML if the requiredExtensions attribute
         evaluates to true (i.e., the user agent supports XHTML
         embedded within SVG). -->
    <foreignObject width="100" height="50"
      <!-- XHTML content goes here -->
      <body xmlns="http://www.w3.org/1999/xhtml">
        <p>Here is a paragraph that requires word wrap</p>
    <!-- Else, process the following alternate SVG.
         Note that there are no testing attributes on the 'text' element.
         If no testing attributes are provided, it is as if there
         were testing attributes and they evaluated to true.-->
    <text font-size="10" font-family="Verdana">
      <tspan x="10" y="10">Here is a paragraph that</tspan>
      <tspan x="10" y="20">requires word wrap.</tspan>

It is not required that SVG user agent support the ability to invoke other arbitrary user agents to handle embedded foreign object types; however, all conforming SVG user agents would need to support the 'switch' element and must be able to render valid SVG elements when they appear as one of the alternatives within a 'switch' element.

Ultimately, it is expected that commercial Web browsers will support the ability for SVG to embed content from other XML grammars which use CSS or XSL to format their content, with the resulting CSS- or XSL-formatted content subject to SVG transformations and compositing. At this time, such a capability is not a requirement.

23.5 Adding private elements and attributes to the DTD

The SVG DTD allows for extending the SVG language within the internal DTD subset. Within the internal DTD subset, you have the ability to add custom elements and attributes to most SVG elements.

The DTD defines an extension entity for most of SVG elements. For example, the 'view' element is defined in the DTD as follows:

<!ENTITY % viewExt "" >
<!ELEMENT view (%descTitleMetadata;%viewExt;) >
<!ATTLIST view
  externalResourcesRequired %Boolean; #IMPLIED
  viewBox %ViewBoxSpec; #IMPLIED
  preserveAspectRatio %PreserveAspectRatioSpec; 'xMidYMid meet'
  zoomAndPan (disable | magnify) 'magnify' 
  viewTarget CDATA #IMPLIED >

The entity viewExt can be defined in the internal DTD subset to add custom sub-element or custom attributes to the 'view' element within a given document. For example, the following extends the 'view' element with an additional child element 'customNS:customElement' and an additional attribute customNS:customAttr:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
<!ENTITY % viewExt "| customNS:customElement" >
<!ATTLIST view
  xmlns:customNS CDATA #FIXED "http://www.example.org/customNS"
  customNS:customAttr CDATA #IMPLIED >
<!ELEMENT customNS:customElement EMPTY>
<!ATTLIST customNS:customElement
  xmlns:customNS CDATA #FIXED "http://www.example.org/customNS"
<svg width="8cm" height="4cm" version="1.1"
  <desc>Extend the 'view' element via the internal DTD subset</desc>
  <!-- Presumably, some great graphics would go here. -->
  <view viewBox="100 110 20 30" customNS:customAttr="123">
    <customNS:customElement info="abc"/>

23.6 Extensibility Module

Elements Attributes Content Model
foreignObject Core.attrib, Conditional.attrib, External.attrib, Style.attrib, Presentation.attrib, GraphicsElementEventAttrs, transform, x, y, width, height, content #PCDATA

23.6.1 Extensibility Content Set

The Extensibility Module defines the Extensibility.class content set.

Content Set Name Elements in Content Set
Extensibility.class foreignObject

23.7 DOM interfaces

The following interfaces are defined below: SVGForeignObjectElement.

Interface SVGForeignObjectElement

The SVGForeignObjectElement interface corresponds to the 'foreignObject' element.

IDL Definition
interface SVGForeignObjectElement : 
                events::EventTarget { 
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;

readonly SVGAnimatedLength x
Corresponds to attribute x on the given 'foreignObject' element.
readonly SVGAnimatedLength y
Corresponds to attribute y on the given 'foreignObject' element.
readonly SVGAnimatedLength width
Corresponds to attribute width on the given 'foreignObject' element.
readonly SVGAnimatedLength height
Corresponds to attribute height on the given 'foreignObject' element.