SVG Tiny 1.2 – 20081222

- Top
- Contents
- Previous
- Next
- Elements
- Attributes

# 19 Extensibility

## Contents

## 19.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 the Embedding foreign object types section, below.)

Extension elements in the SVG namespace must not be used.

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 will otherwise ignore unknown attributes. Unprefixed attributes on elements in the SVG namespace must not be used for extensions.

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

- Application-specific information so that authoring applications can include model-level data in the SVG content to serve their "roundtripping" purposes (i.e., the ability to write, then read a file without loss of higher-level information).
- Supplemental data for extensibility. For example, suppose you have an extrusion extension which takes any 2D graphics and extrudes it in three dimensions. When applying the extrusion extension, you probably will need to set some parameters. The parameters can be included in the SVG content by inserting elements from an extrusion extension namespace.

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:

Example: 23_01.svg

    <?xml version="1.0"?>
    <svg xmlns="http://www.w3.org/2000/svg" version="1.2" baseProfile="tiny"
         width="4in" height="3in">

      <defs>
        <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 -->
        </myapp:piechart>
      </defs>

      <desc>This chart includes private data in another namespace</desc>

      <!-- In here would be the actual SVG graphics elements which
           draw the pie chart -->
    </svg>

## 19.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 [MATHML].

### 19.2.1 The 'foreignObject' element

The 'foreignObject' element is an extensibility point which allows user agents to offer graphical rendering features beyond those which are defined within this specification.

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 user agent must treat all of the content within a 'foreignObject' as foreign content which is to be handed off to an appropriate content handler for rendering. User agents are not required to support any particular content types via 'foreignObject'. In particular, user agents are not required to support SVG content embedded within or referenced by 'foreignObject'; SVG content within 'foreignObject' represents an extension just as with any other type of content.

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.

A conformant SVG user agent is not required to support any particular foreign namespace content within 'foreignObject' itself nor is it required to invoke other user agents to handle particular embedded foreign object types. Ultimately, it is expected that 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 then subject to SVG transformations and compositing. At this time, such a capability is not a requirement. The CDF Working Group is expected to provide this functionality.

The rendered content of a foreignObject must be treated as atomic from the point of view of SVG compositing and transformation, as if it was a single replaced element.

The 'foreignObject' element has two ways of including foreign content. One is to reference external content by using the 'xlink:href' attribute, the other is to include child content of the 'foreignObject' element. When the 'xlink:href' attribute is specified the child content of the 'foreignObject' element must not be displayed.

All mouse events that are dispatched to a 'foreignObject' element, including mouse events that bubble from the embedded content, must have their clientX/clientY attributes adjusted so that they represent values within the initial viewport coordinate system.

Schema: foreignObject

        <define name='foreignObject'>
          <element name='foreignObject'>
            <ref name='foreignObject.AT'/>
            <ref name='foreignObject.CM'/>
          </element>
        </define>

        <define name='foreignObject.AT' combine='interleave'>
          <ref name='svg.Core.attr'/>
          <ref name='svg.Conditional.attr'/>
          <ref name='svg.XLinkEmbed.attr'/>
          <ref name='svg.Focus.attr'/>
          <ref name='svg.External.attr'/>
          <ref name='svg.Properties.attr'/>
          <ref name='svg.FocusHighlight.attr'/>
          <ref name='svg.Transform.attr'/>
          <ref name='svg.XYWH.attr'/>
        </define>

        <define name='foreignObject.CM'>
          <zeroOrMore>
            <choice>
              <ref name='svg.Desc.group'/>
              <ref name='svg'/>
            </choice>
          </zeroOrMore>
        </define>

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.

  The lacuna value is '0'.

  Animatable: yes.

y = "<coordinate>"

  The y-axis coordinate of one corner of the rectangular region into which the referenced document is placed.

  The lacuna value is '0'.

  Animatable: yes.

width = "<length>"

  The width of the rectangular region into which the referenced document is placed.

  A negative value is unsupported. A value of zero disables visual rendering of the element. The lacuna value is '0'.

  Animatable: yes.

height = "<length>"

  The height of the rectangular region into which the referenced document is placed.

  A negative value is unsupported. A value of zero disables visual rendering of the element. The lacuna value is '0'.

  Animatable: yes.

xlink:href = "<IRI>"

  An IRI reference. If this attribute is present, then the foreign content must be loaded from this resource and what child content the 'foreignObject' element may have must not be displayed. If this attribute is not present then the 'foreignObject' child content must be displayed if the user agent is capable of handling it.

  Animatable: yes.

focusable = "true" | "false" | "auto"

  See attribute definition for description.

  Animatable: yes.

Navigation Attributes

  See definition.

### 19.2.2 Examples of 'foreignObject'

Here are several examples using a switch and the 'foreignObject' element.

This is an example of an arbitrary XML language, with comments to explain what happens at each step:

Example: requiredExtensions-foreignObject.svg

    <svg xmlns="http://www.w3.org/2000/svg"
         width="4in" height="3in">

      <desc>
        This example uses the 'switch' element to provide a fallback
        graphical representation of the text, if weirdML is not supported.
      </desc>

      <!-- The 'switch' element will process the first child element
      whose testing attributes evaluate to true.-->
      <switch>

        <!-- Process the embedded weirdML if the requiredExtensions
        attribute evaluates to true (i.e., the user agent supports
        weirdML embedded within SVG). -->
        <foreignObject x="50" y="20" width="100" height="50"
                       requiredExtensions="http://example.com/weirdMLplusSVG">

          <!-- weirdML content goes here -->
          <FreakyText xmlns="http://example.com/weirdML">
            <sparklies q="42"/>
            <throbber seed="1234"/>
            <swirl twist="yeah, baby"/>
            <txt>This is throbbing, swirly text with sparkly bits</txt>
          </FreakyText>
        </foreignObject>

        <!-- Else, process the following alternate SVG.
        Note that there are no testing attributes on the 'textArea'
        element.  If no testing attributes are provided, it is as
        if there were testing attributes and they evaluated to true.-->
        <textArea x="50" y="20" width="100" height="50"
                  font-size="10" font-family="Verdana">
          This is plain, conservative SVGT 1.2 text in a
          textArea.  The text wraps within the confines
          of the element's dimensions.
        </textArea>

      </switch>
    </svg>

This is an example of MathML in SVG:

Example: requiredExtensions-MathML.svg

    <svg xmlns="http://www.w3.org/2000/svg"
         width="100%" height="100%" viewBox="0 0 600 500">

      <title>Quadratic Equation</title>
      <desc>
        A sample of MathML in SVG, using the 'foreignObject' element
        to represent a quadratic equation, with a graphical SVG
        representation for fallback.
      </desc>

      <switch>
        <foreignObject x="20" y="20" width="600" height="500"
                       requiredExtensions="http://www.w3.org/1998/Math/MathML">
          <math xmlns="http://www.w3.org/1998/Math/MathML">
            <mrow>
              <mrow>
                <mi>f</mi>
                <mfenced>
                    <mi>x</mi>
                </mfenced>
              </mrow>
              <mo>=</mo>
              <mrow>
                <msup>
                  <mi>x</mi>
                  <mn>2</mn>
                </msup>
                <mo>+</mo>
                <mrow>
                  <mn>4</mn>
                  <mi>x</mi>
                </mrow>
                <mo>-</mo>
                <mrow>
                  <mn>3</mn>
                </mrow>
              </mrow>
            </mrow>
          </math>
        </foreignObject>

        <g fill="gray" transform="translate(300,250)">
          <rect x="-300" y="-250" width="600" height="500" fill="white" stroke="gray" />
          <g id="axes" font-family="monospace" text-anchor="middle">
            <line id="x-axis" x1="-300" y1="0" x2="300" y2="0" stroke="gray"/>
            <line id="x-axis-markers" x1="-300" y1="0" x2="300" y2="0"
                  stroke="gray" stroke-width="7" stroke-dasharray="1,99"/>

            <line id="y-axis" x1="0" y1="-250" x2="0" y2="250" stroke="gray"/>
            <line id="y-axis-markers" x1="0" y1="-200" x2="0" y2="250"
                  stroke="gray" stroke-width="7" stroke-dasharray="1,99"/>

            <text x="-200" y="20" font-size="10">-4</text>
            <text x="-100" y="20" font-size="10">-2</text>
            <text x="100" y="20" font-size="10">2</text>
            <text x="200" y="20" font-size="10">4</text>

            <text x="15" y="-198" font-size="10">4</text>
            <text x="15" y="-98" font-size="10">2</text>
            <text x="15" y="102" font-size="10">-2</text>
            <text x="15" y="202" font-size="10">-4</text>
          </g>

          <path id="graph" stroke-width="1" stroke="blue" fill="none"
                d="M-200,-250 Q-50,650 100,-250"/>

          <circle id="vertex" cx="-50" cy="200" r="2" fill="blue" />
          <circle id="y-intercept-1" cx="0" cy="150" r="2" fill="red" />
          <circle id="x-intercept-1" cx="-150" cy="0" r="2" fill="red" />
          <circle id="x-intercept-2" cx="50" cy="0" r="2" fill="red" />
        </g>
      </switch>
    </svg>

This is an example of XHTML in SVG:

Example: requiredExtensions-XHTML.svg

    <svg xmlns="http://www.w3.org/2000/svg"
         width="100%" height="100%" viewBox="0 0 300 140">

      <title>Chinese-English Unicode Table</title>
      <desc>
        A sample of XHTML in SVG, using the 'foreignObject' element
        to include an XHTML 'table' with some Chinese-to-English
        correspondances, with an ad-hoc SVG representation for
        fallback.
      </desc>

      <switch>
        <foreignObject width="300" height="140"
                       requiredExtensions="http://www.w3.org/1999/xhtml">
          <table xmlns="http://www.w3.org/1999/xhtml">
             <caption>Using Chinese Characters in SVG</caption>
             <tr>
               <th>English</th>
               <th>Chinese</th>
             </tr>
             <tr y="75">
               <td>moon</td>
               <td>&#x6708;</td>
               <td>6708</td>
             </tr>
             <tr y="100">
               <td>tree</td>
               <td>&#x6728;</td>
               <td>6728</td>
             </tr>
             <tr y="125">
               <td>water</td>
               <td>&#x6c34;</td>
               <td>6c34</td>
             </tr>
           </table>
        </foreignObject>

        <text font-size="18" fill="crimson" text-anchor="middle">
          <tspan x="150" y="25" font-weight="bold">Using Chinese Characters in SVG</tspan>
          <tspan y="50">
            <tspan x="50">English</tspan>
            <tspan x="150">Chinese</tspan>
            <tspan x="250">Unicode</tspan>
          </tspan>
          <tspan y="75">
            <tspan x="50">moon</tspan>
            <tspan x="150">&#x6708;</tspan>
            <tspan x="250">6708</tspan>
          </tspan>
          <tspan y="100">
            <tspan x="50">tree</tspan>
            <tspan x="150">&#x6728;</tspan>
            <tspan x="250">6728</tspan>
          </tspan>
          <tspan y="125">
            <tspan x="50">water</tspan>
            <tspan x="150">&#x6c34;</tspan>
            <tspan x="250">6c34</tspan>
          </tspan>
        </text>
      </switch>
    </svg>