Chapter 4: Document Structure

Contents

• • 4.1. Defining an SVG document fragment: the ‘svg’ element
    • 4.1.1. Overview
    • 4.1.2. Definitions
    • 4.1.3. The ‘svg’ element
  • 4.2. Grouping: the ‘g’ element
    • 4.2.1. Overview
    • 4.2.2. The ‘g’ element
  • 4.3. Defining content for reuse, and the ‘defs’ element
    • 4.3.1. Overview
    • 4.3.2. The ‘defs’ element
  • 4.4. The ‘discard’ element
  • 4.5. The ‘desc’ and ‘title’ elements
    • 4.5.1. Definition
  • 4.6. The ‘metadata’ element
  • 4.7. The ‘symbol’ element
    • 4.7.1. Attributes
    • 4.7.2. Notes on symbols
  • 4.8. The ‘use’ element
  • 4.9. Conditional processing
    • 4.9.1. Conditional processing overview
    • 4.9.2. Definitions
    • 4.9.3. The ‘switch’ element
    • 4.9.4. The ‘requiredFeatures’ attribute
    • 4.9.5. The ‘requiredExtensions’ attribute
    • 4.9.6. The ‘systemLanguage’ attribute
    • 4.9.7. Applicability of test attributes
  • 4.10. Common attributes
    • 4.10.1. Definitions
    • 4.10.2. Attributes common to all elements: ‘id’ and ‘xml:base’
    • 4.10.3. The ‘xml:lang’ attribute
    • 4.10.4. The ‘tabindex’ attribute
  • 4.11. WAI-ARIA attributes
    • 4.11.1. Definitions
    • 4.11.2. Role attribute
    • 4.11.3. State and property attributes (all aria- attributes)
    • 4.11.4. Implicit ARIA Semantics
  • 4.12. DOM interfaces
    • 4.12.1. Interface Document
    • 4.12.2. Interface SVGSVGElement
    • 4.12.3. Interface SVGGElement
    • 4.12.4. Interface SVGDefsElement
    • 4.12.5. Interface SVGDescElement
    • 4.12.6. Interface SVGMetadataElement
    • 4.12.7. Interface SVGTitleElement
    • 4.12.8. Interface SVGSymbolElement
    • 4.12.9. Interface SVGUseElement
    • 4.12.10. Interface SVGSwitchElement
    • 4.12.11. Interface GetSVGDocument

4.1. Defining an SVG document fragment: the ‘svg’ element

4.1.1. Overview

An SVG document fragment consists of any number of SVG elements contained within an ‘svg’ element.

An SVG document fragment can range from an empty fragment (i.e., no content inside of the ‘svg’ element), to a very simple SVG document fragment containing a single SVG graphics element such as a ‘rect’, to a complex, deeply nested collection of container elements and graphics elements.

An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent XML document.

The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the ‘svg’ and ‘ellipse’ elements belong to the SVG namespace:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://example.org"
        xmlns:svg="http://www.w3.org/2000/svg">
   <!-- parent contents here -->
   <svg:svg width="4cm" height="8cm">
      <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" />
   </svg:svg>
   <!-- ... -->
</parent>

This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:

<?xml version="1.0" standalone="no"?>
<svg width="5cm" height="4cm" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Four separate rectangles
  </desc>
    <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/>
    <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/>
    <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/>
    <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

‘svg’ elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.

Another use for ‘svg’ elements within the middle of SVG content is to establish a new viewport. (See Establishing a new viewport.)

In all cases, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace. The following are possible ways to provide a namespace declaration. An ‘xmlns’ attribute without a namespace prefix could be specified on an ‘svg’ element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:

<svg xmlns="http://www.w3.org/2000/svg" …>
  <rect …/>
</svg>

If a namespace prefix is specified on the ‘xmlns’ attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"), then the corresponding namespace is not the default namespace, so an explicit namespace prefix must be assigned to the elements:

<svg:svg xmlns:svg="http://www.w3.org/2000/svg" …>
  <svg:rect …/>
</svg:svg>

Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].

This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.

4.1.2. Definitions

current SVG document fragment

The document sub-tree which starts with the outermost ancestor ‘svg’ element of a given SVG element, with the requirement that all container elements between the outermost ‘svg’ and the given element are all elements in the SVG namespace.

outermost svg element

The furthest ‘svg’ ancestor element that remains in the current SVG document fragment.

SVG document fragment

A document sub-tree which starts with an ‘svg’ element which is either the root element of the document or whose parent element is not in the SVG namespace. An SVG document fragment can consist of a stand-alone SVG document, or a fragment of a parent document enclosed by an ‘svg’ element. When an ‘svg’ element is a descendant of another ‘svg’ element, only the outermost svg element is the root of an SVG document fragment.

SVG elements

Any element in the SVG namespace.

graphics element

One of the element types that can cause graphics to be drawn onto the target canvas. Specifically: ‘audio’, ‘canvas’, ‘circle’, ‘ellipse’, ‘foreignObject’, ‘iframe’, ‘image’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’, ‘text’, ‘use’ and ‘video’.

graphics referencing element

A graphics element which uses a reference to a different document or element as the source of its graphical content. Specifically: ‘audio’, ‘iframe’, ‘image’, ‘use’ and ‘video’.

4.1.3. The ‘svg’ element

Attribute definitions:

Name	Value	Lacuna value	Animatable
x, y	<length>	0	yes

The ‘x’ and ‘y’ attributes specify the top-left corner of the rectangular region into which an embedded ‘svg’ element is placed. On an outermost svg element, these attributes have no effect.

Name	Value	Lacuna value	Animatable
width, height	See ‘width’ and ‘height’	auto	yes

Note that ‘width’ and ‘height’ are presentation attributes.

The Value column does not match the new Attribute syntax description.

For outermost svg elements, the ‘width’ and ‘height’ attributes specify the intrinsic size of the SVG document fragment. For embedded ‘svg’ elements, they specify the size of the rectangular region into which the ‘svg’ element is placed.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

When zero is used on an outer ‘svg’ element, does this disable rendering too? Or does it just affect the intrinsic size?

Name	Value	Lacuna value	Animatable
preserveAspectRatio	defer? <align> [ meet | slice ]?	xMidYMid meet	yes

Specifies the fitting behavior when the aspect ratio of the ‘svg’ element does not match the aspect ratio of the rectangle it is placed in. See the definition of ‘preserveAspectRatio’ for details.

Name	Value	Lacuna value	Animatable
zoomAndPan	disable | magnify	magnify	no

Specifies whether the user agent should supply a means to zoom and pan the SVG content. See the definition of ‘zoomAndPan’ for details.

Name	Value	Lacuna value	Animatable
playbackorder	forwardonly | all	all	no

This attribute may be harmonized and/or replaced with the work done as part of the Web Animation specification.

Indicates whether it is possible to seek backwards in the document. In earlier versions of SVG there was no need to put restrictions on the direction of seeking but with the newly introduced facilities for long-running documents (e.g. the ‘discard’ element) there is sometimes a need to restrict this.

If ‘playbackorder’ is set to 'forwardonly', the content will likely contain ‘discard’ elements or scripts that destroy resources, thus seeking back in the document fragment's timeline may result in missing content. If ‘playbackorder’ is 'forwardonly', the content should not provide a way, through hyperlinking or script, of seeking backwards in the timeline. Similarly the UA should disable any controls it may provide in the user interface for seeking backwards. Content with playbackorder="forwardonly" that provides a mechanism for seeking backwards in time may result in undefined behavior or a document that is in error.

Can't we define this so that there is no undefined behavior?

Attribute values have the following meanings:

'forwardonly'

This file is intended to be played only in the forward direction, sequentially, therefore seeking backwards should not be allowed.

'all'

Indicates that the document is authored appropriately for seeking in both directions.

Name	Value	Lacuna value	Animatable
timelinebegin	loadend | loadbegin	loadend	no

Controls the initialization of the timeline for the SVG document fragment.

The outermost svg element of an SVG document fragment defines a timeline. Absolute times used by animation elements in an SVG document fragment are relative to the document fragment's timeline.

By default, the timeline is initialized when the document fragment's load event is fired but for progressively loaded animations, the author may set this attribute to 'loadend', thus allowing the timeline to begin as the document loads, rather than waiting until the complete document is loaded.

Attribute values have the following meanings:

'loadend'

The document fragment's timeline starts the moment the load event for the outermost svg element is triggered.

'loadbegin'

The document's timeline starts at the moment the outermost svg element's start-tag (as defined in XML 1.0 [XML10] or HTML [HTML] when using the HTML parser) is fully parsed.

If an SVG document is likely to be referenced as a component of another document, the author will often want to include a ‘viewBox’ attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.

The ‘svg’ element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.

The onblur, ‘onerror’, onfocus, ‘onload’, and ‘onscroll’ event handlers of the Window object, exposed on the ‘svg’ element, replace the generic event handlers with the same names normally supported by SVG elements.

4.2. Grouping: the ‘g’ element

4.2.1. Overview

container element

An element which can have graphics elements and other container elements as child elements. Specifically: ‘a’, ‘defs’, ‘g’, ‘marker’, ‘mask’, ‘pattern’, ‘svg’, ‘switch’ and ‘symbol’.

The ‘g’ element is a container element for grouping together related graphics elements.

A group of elements, as well as individual objects, can be given a name using the ‘id’ attribute. Named groups are needed for several purposes such as animation and re-usable objects.

An example:

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="5cm" height="5cm">
  <desc>Two groups, each of two rectangles</desc>
  <g id="group1" fill="red">
    <rect x="1cm" y="1cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="1cm" width="1cm" height="1cm"/>
  </g>
  <g id="group2" fill="blue">
    <rect x="1cm" y="3cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="3cm" width="1cm" height="1cm"/>
  </g>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm"
        fill="none" stroke="blue" stroke-width=".02cm"/>
</svg>

A ‘g’ element can contain other ‘g’ elements nested within it, to an arbitrary depth.

4.2.2. The ‘g’ element

4.3. Defining content for reuse, and the ‘defs’ element

4.3.1. Overview

SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of URL references [RFC3987] to these other objects. For example, to fill a rectangle with a linear gradient, you first define a ‘linearGradient’ element and give it an ID, as in:

<linearGradient id="MyGradient">...</linearGradient>

You then reference the linear gradient as the value of the ‘fill’ property for the rectangle, as in:

<rect style="fill:url(#MyGradient)"/>

Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.

It is recommended that, wherever possible, referenced elements be defined inside of a ‘defs’ element. Among the elements that are always referenced: ‘clipPath’, ‘cursor’, ‘filter’, ‘linearGradient’, ‘marker’, ‘mask’, ‘pattern’, ‘radialGradient’ and ‘symbol’.

4.3.2. The ‘defs’ element

The ‘defs’ element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a ‘defs’.

The content model for ‘defs’ is the same as for the ‘g’ element; thus, any element that can be a child of a ‘g’ can also be a child of a ‘defs’, and vice versa.

Elements that are descendants of a ‘defs’ are not rendered directly; they are prevented from becoming part of the rendering tree just as if the ‘defs’ element were a ‘g’ element and the ‘display’ property were set to none. Note, however, that the descendants of a ‘defs’ are always present in the source tree and thus can always be referenced by other elements; thus, the value of the ‘display’ property on the ‘defs’ element or any of its descendants does not prevent those elements from being referenced by other elements.

4.4. The ‘discard’ element

Would this element be better as part of the Animation chapter? It also needs to be a member of the element categories that other animation elements are, and an IDL interface needs to be written for it. Covered by ACTION-3727 (Cyril).

Need to define SVGDiscardElement DOM interface for ‘discard’ element. Covered by ACTION-3727 (Cyril).

The ‘discard’ element allows authors to specify the time at which particular elements are to be discarded, thereby reducing the resources required by an SVG user agent. This is particularly useful to help SVG viewers conserve memory while displaying long-running documents. This element will not be processed by static SVG viewers.

The ‘discard’ element may occur wherever the ‘animate’ element may.

Attribute definitions:

Name	Value	Lacuna value	Animatable
href	URL [URL]	(none)	no

An URL reference that identifies the target element to discard. See the definition of ‘href’ on animation elements for details on identifying a target element.

Note that if the target element is not part of the current SVG document fragment then whether the target element will be removed or not is defined by the host language.

If the ‘href’ attribute is not provided, then the target element will be the immediate parent element of the discard element.

Name	Value	Lacuna value	Animatable
begin	<begin-value-list>	0s	no

Attribute syntax needs fixing.

Indicates when the target element will be discarded. See the definition of ‘begin’ on animation elements for details.

The ‘discard’ element has an implicit simple duration of "indefinite". As soon as the element's active duration starts, the SVG user agent discards the element identified by the ‘href’ attribute ([SMIL], section 5.4.5). The removal operation acts as if removeChild were called on the parent of the target element with the target element as parameter. [DOM4] The SVG user agent must remove the target node as well as all of its attributes and descendants.

After removal of the target element, the ‘discard’ element is no longer useful. It must also be discarded following the target element removal. If the ‘href’ attribute has an invalid URL reference (the target element did not exist, for example), the ‘discard’ element itself must still be removed following activation.

Seeking backwards in the timeline ([SMIL], section 5.4.5) must not re-insert the discarded elements. Discarded elements are intended to be completely removed from memory. So, authors are encouraged to set the ‘playbackorder’ attribute to "forwardonly" when using the ‘discard’ element.

The ‘discard’ element itself can be discarded prior to its activation, in which case it will never trigger the removal of its own target element. SVG user agents must allow the ‘discard’ element to be the target of another ‘discard’ element.

The following example demonstrates a simple usage of the ‘discard’ element. The list below describes relevant behavior in the document timeline of this example:

At time = 0:

When the document timeline starts, the blue ellipse starts to move down the page.

At time = 1 second:

The red rectangle starts moving up the page.

At time = 2 seconds:

The ‘animateTransform’ on the ‘ellipse’ ends. The ‘ellipse’ and its children are also discarded, as it is the target element of a ‘discard’ with begin="2". The green ‘polygon’ starts to move across the page.

At time = 3 seconds:

The animation on the red rectangle ends. The rectangle and its children are discarded as it is the target of a ‘discard’ element with begin="3".

At time = 4 seconds:

The animation on the green triangle ends. The green ‘polygon’ and its children are discarded as it is the target of a ‘discard’ element with begin="4".

<svg xmlns="http://www.w3.org/2000/svg" width="352" height="240" playbackorder="forwardonly">
    
  <ellipse cx="98.5" cy="17.5" rx="20.5" ry="17.5" fill="blue" stroke="black" 
           transform="translate(9 252) translate(3 -296)">
    <animateTransform attributeName="transform" begin="0s" dur="2s" fill="remove"
                      calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="-18 305"/>
    <discard begin="2s"/>
  </ellipse>
  
  <rect x="182" y="-39" width="39" height="30" fill="red" stroke="black"
        transform="translate(30 301)">
    <animateTransform attributeName="transform" begin="1s" dur="2s" fill="remove"
                      calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="-26 -304"/>
    <discard begin="3s"/>
  </rect>
  
  <polygon points="-66,83.5814 -43,123.419 -89,123.419" fill="green" stroke="black" 
           transform="matrix(1 0 0 1.1798 0 -18.6096)">
    <animateTransform attributeName="transform" begin="2s" dur="2s"
                      fill="remove" calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="460 63.5699"/>
    <discard begin="4s"/>
  </polygon>
</svg>

4.5. The ‘desc’ and ‘title’ elements

4.5.1. Definition

descriptive element

An element which provides supplementary descriptive information about its parent. Specifically, the following elements are descriptive elements: ‘desc’, ‘metadata’ and ‘title’.

The attribute ‘lang’ added to allow internationalization of the ‘desc’ and ‘title’ elements.

Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements.

Is there any updated wording from SVG Tiny 1.2 that we should be using wrt tooltips?

Each container element or graphics element in an SVG drawing can supply one or more ‘desc’ and/or one or more ‘title’ description strings where the description is text-only. When the current SVG document fragment is rendered as SVG on visual media, ‘desc’ and ‘title’ elements are not rendered as part of the graphics. The ‘title’ child element represents advisory information for the element, such as would be appropriate for a tooltip. On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be the image credit or short description of the image; it could be further information about the source; on interactive content, it could be a label for, or instructions for, use of the element; and so forth. The value is text. The ‘desc’ element represents more detailed, textual information, for the element. This is typically exposed to assistive technologies to provide more detailed information, such as help information about the element. The value is text.

Authors are provided two vehicles for providing a visible label with a drawing element. The first way is to embed text within the drawing element. The second is to associate visible text with a drawing element through the use of ‘aria-labelledby’ on the element being labelled. Authors may provide a non-visible label to a drawing element by applying an ‘aria-label’ to it but also by providing a descendant ‘title’ element. An author may also expose a hidden label on an element to an assistive technologies through the use of ‘aria-labelledby’ when it points to content that is hidden and contains text. It is common for user agents to render the ‘title’ element as a tooltip. Tooltips are an important way to convey alternative text information for a drawing object where the text label is either not readily visible or could be rendered in a clearer way in response to passing over the drawing element with a pointing device. One benefit of using a descendant 'title' element can be seen when using SVG to to produce an image button or small drawing that has no visible text but it is important to be able to render a short textual equivalent label, or tooltip, when a pointing device passes over the button.

Authors should provide a ‘title’ child element to the outermost svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the outermost svg element available to users. The mechanism for doing so depends on the user agent (e.g., as a caption, spoken).

If the SVG document is embedded in an HTML document, the outermost svg element may only serve to act as a container for SVG drawings and applying a ‘title’ child element may not be of value. Applying a ‘title’ element to the outermost SVG element in this may may result in a tooltip being generated.

Unlike the desc element, authors also have the ability to associate more detailed information with content that includes visible text. This can be achieved by applying ‘aria-describedby’ to the element, or container of elements being described and passing an ID reference to content that includes text that describes the element in question. However, if the text describing the object is hidden the text within the description would be exposed to assistive technologies as detailed text information, similar to a descendant ‘desc’ element. The ‘aria-describedby’ attribute takes precedence over the child ‘desc’ when providing a description, consequently authors should only use ‘aria-describedby’ when an element is described by visible text on the screen, otherwise the use of a child ‘desc’ is preferred.

User agents may, however, for example, display the ‘title’ element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the ‘desc’ and ‘title’ elements but do not display ‘path’ elements or other graphics elements. For deep hierarchies, and for following ‘use’ element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.

More than one ‘desc’ or ‘title’ may be present with different ‘lang’ attributes. The text displayed will be the text from the element where the ‘lang’ attribute best matches the language set by the user agent. If no match exists, the text from the first element is used (to allow default text to be given for legacy renderers). If multiple equally valid matches exist, the first match is used.

The following is an example. In typical operation, the SVG user agent would not render the ‘desc’ and ‘title’ elements but would render the remaining contents of the ‘g’ element.

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     width="4in" height="3in">
  <g>
    <title>Company sales by region</title>
    <title lang="fr">Chiffre d'affaires par région</title>
    <desc>Bar chart which shows company sales by region.</desc>
    <desc lang="fr">Graphique illustrant les ventes par région.</desc>
    <!-- Bar chart defined as vector data -->
  </g>
</svg>

Description and title elements can contain marked-up text from other namespaces.

We should say what purpose including other-namespaced markup in ‘title’ and ‘desc’ has. If it is just that these are basically metadata extension points for other profiles or uses of SVG, then we should say that.

We have this sentence here about tooltips which is stronger than the earlier note that some implementations do this. We should look at how HTML describes the ‘title’ attribute and whether a tooltip is required, suggested, etc., and follow that.

Once we have said how ARIA attributes can be used in SVG, we might want to define ‘title’ and ‘desc’ in a manner consistent with them, so that it is clear what it means for example for an element to have both a ‘desc’ element child and an ‘aria-describedby’ attribute.

4.6. The ‘metadata’ element

Metadata which is included with SVG content should be specified within ‘metadata’ elements. The contents of the ‘metadata’ should be elements from other XML namespaces, with these elements from these namespaces expressed in a manner conforming with the Namespaces in XML Recommendation [XML-NS].

Authors should provide a ‘metadata’ child element to the outermost svg element within a stand-alone SVG document. The ‘metadata’ child element to an ‘svg’ element serves the purposes of identifying document-level metadata.

The definitions of many of SVG's elements (particularly, container and text elements) place no restriction on the placement or number of the ‘metadata’ sub-elements. This flexibility is only present so that there will be a consistent content model for container elements, because some container elements in SVG allow for mixed content, and because the mixed content rules for XML ([XML10], section 3.2.2) do not permit the desired restrictions. Future versions of the SVG language might provide more restrictive mixed content rules. It is strongly recommended that at most one ‘metadata’ element appear as a child of any particular element, and that this element appear before any other child elements (except possibly ‘desc’ or ‘title’ elements) or character data content. If metadata-processing user agents need to choose among multiple ‘metadata’ elements for processing it should choose the first one.

Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
    xmlns = 'http://www.w3.org/2000/svg'>
    <desc xmlns:myfoo="http://example.org/myfoo">
      <myfoo:title>This is a financial report</myfoo:title>
      <myfoo:descr>The global description uses markup from the
        <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr>
      <myfoo:scene><myfoo:what>widget $growth</myfoo:what>
      <myfoo:contains>$three $graph-bar</myfoo:contains>
        <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene>
   </desc>
    <metadata>
      <rdf:RDF
           xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
           xmlns:dc = "http://purl.org/dc/elements/1.1/" >
        <rdf:Description about="http://example.org/myfoo"
             dc:title="MyFoo Financial Report"
             dc:description="$three $bar $thousands $dollars $from 1998 $through 2000"
             dc:publisher="Example Organization"
             dc:date="2000-04-11"
             dc:format="image/svg+xml"
             dc:language="en" >
          <dc:creator>
            <rdf:Bag>
              <rdf:li>Irving Bird</rdf:li>
              <rdf:li>Mary Lambert</rdf:li>
            </rdf:Bag>
          </dc:creator>
        </rdf:Description>
      </rdf:RDF>
    </metadata>
</svg>

4.7. The ‘symbol’ element

4.7.1. Attributes

Name	Value	Lacuna value	Animatable
refX	<length> | left | center | right	0	yes
refY	<length> | top | center | bottom	0	yes

New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on ‘marker’.

Add refX/refY to symbol element. Resolved at Leipzig F2F.

We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'.

The ‘refX’ and ‘refY’ attributes define the reference point of the symbol which is to be placed exactly at the symbol's position as defined by the ‘use’ element. They are interpreted as being in the coordinate system of the symbol contents, after application of the ‘viewBox’ and ‘preserveAspectRatio’ attributes.

4.7.2. Notes on symbols

The ‘symbol’ element is used to define graphical template objects which can be instantiated by a ‘use’ element.

The use of ‘symbol’ elements for graphics that are used multiple times in the same document adds structure and semantics.

The key distinctions between a ‘symbol’ and a ‘g’ are:

• A ‘symbol’ element itself is not rendered. Only instances of a ‘symbol’ element (i.e., a reference to a ‘symbol’ by a ‘use’ element) are rendered.
• A ‘symbol’ element has attributes ‘viewBox’ and ‘preserveAspectRatio’ which allow a ‘symbol’ to scale-to-fit within a rectangular viewport defined by the referencing ‘use’ element.

Closely related to the ‘symbol’ element are the ‘marker’ and ‘pattern’ elements.

‘symbol’ elements are never rendered directly; their only usage is as something that can be referenced using the ‘use’ element. The ‘display’ property does not apply to the ‘symbol’ element; thus, ‘symbol’ elements are not directly rendered even if the ‘display’ property is set to a value other than none, and ‘symbol’ elements are available for referencing even when the ‘display’ property on the ‘symbol’ element or any of its ancestors is set to none.

4.8. The ‘use’ element

The ‘use’ element references another element and indicates that the graphical contents of that element is included/drawn at that given point in the document.

‘use’ is described as referencing template objects, but the parameters of the template are limited – just different inherited property values.

The graphical contents are any ‘svg’, ‘symbol’, ‘g’, graphics element or other ‘use’ elements, that a ‘use’ element references.

The ‘use’ element has optional attributes ‘x’, ‘y’, ‘width’ and ‘height’ which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.

The effect of a ‘use’ element is as if the graphical contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the ‘use’ element as its parent and all of the ‘use’ element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the ‘use’ element and its attributes. The SVG DOM does not show the referenced element's contents as children of ‘use’ element.

We should define the behavior of ‘use’ in terms of Web Components. See ACTION-3729 (Tab)

There are lots of details to define, but one to remember is what should happen when the ‘use’ element is display:none. Does that prevent a shadow tree from being created? This is important for elements in the shadow tree that have side effects, like ‘script’, ‘audio’, ...

Consensus from Sydney F2F: display:none doesn't stop the shadow tree from being created. Script doesn't run in instances. The original audio will be inactive, but each instance will play when used.

For user agents that support Styling with CSS, the conceptual deep cloning of the referenced element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) on the referenced element and its contents. CSS2 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS2 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.

We should be requiring CSS styling in SVG 2. Also, hopefully, how styles can apply or not to elements in the shadow tree (and how event handling works, below) should be specified by how we define ‘use’ to work in terms of Web Components.

Property inheritance, however, works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element. The referenced element inherits properties from the ‘use’ element and the ‘use’ element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.

If event attributes are assigned to referenced elements, then the actual target for the event will be the element within the "instance tree" corresponding to the given referenced element.

The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element, and events are dispatched according to the shadow tree event dispatching algorithm [SHADOWDOM]. The event's target and currentTarget attributes are set to the instance tree element that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going from the root element to the ‘use’ element and then through non-exposed tree elements in the capture phase, followed by the target phase at the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in bubbling phase. In order to maintain encapsulation events must use the event retargeting algorithm [SHADOWDOM] when crossing from a non-exposed tree to the regular tree.

The behavior of the ‘visibility’ property conforms to this model of property inheritance. Thus, specifying 'visibility:hidden' on a ‘use’ element does not guarantee that the referenced content will not be rendered. If the ‘use’ element specifies 'visibility:hidden' and the element it references specifies 'visibility:hidden' or 'visibility:inherit', then that one element will be hidden. However, if the referenced element instead specifies 'visibility:visible', then that element will be visible even if the ‘use’ element specifies 'visibility:hidden'.

Why is ‘visibility’ called out specially? It might be better just to include an example that shows this.

How should @media rules work when an external resource is referenced? Is there a viewport defined in all cases? See ACTION-3730 (ed).

Should scripts run in external resources?

Should animations run in external resources?

Animations on a referenced element will cause the instances to also be animated.

A ‘use’ element has the same visual effect as if the ‘use’ element were replaced by the following generated content:

Except that the replaced content shouldn't affect how styles are matched.

In the generated content, the ‘use’ will be replaced by ‘g’, where all attributes from the ‘use’ element except for ‘x’, ‘y’, ‘width’, ‘height’ and ‘xlink:href’ are transferred to the generated ‘g’ element. An additional transformation translate(x,y) is appended to the end (i.e., right-side) of the ‘transform’ property on the generated ‘g’, where x and y represent the values of the ‘x’ and ‘y’ attributes on the ‘use’ element.

• If the ‘use’ element references a ‘symbol’ element:

  The referenced ‘symbol’ and its contents are deep-cloned into the generated tree, with the exception that the ‘symbol’ is replaced by an ‘svg’. This generated ‘svg’ will always have explicit values for attributes ‘width’ and ‘height’. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these attributes will be transferred to the generated ‘svg’. If attributes ‘width’ and/or ‘height’ are not specified, the generated ‘svg’ element will use values of '100%' for these attributes.

• If the ‘use’ element references an ‘svg’ element:

  The referenced ‘svg’ and its contents are deep-cloned into the generated tree. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these values will override the corresponding attributes on the ‘svg’ in the generated tree.

• Otherwise:

  The referenced object and its contents are deep-cloned into the generated tree.

For user agents that support Styling with CSS, the generated ‘g’ element carries along with it the "cascaded" property values on the ‘use’ element which result from the CSS cascade ([CSS21], chapter 6). Additionally, the copy (deep clone) of the referenced resource carries along with it the "cascaded" property values resulting from the CSS cascade on the original (i.e., referenced) elements. Thus, the result of various CSS selectors in combination with the ‘class’ and ‘style’ attributes are, in effect, replaced by the functional equivalent of a ‘style’ attribute in the generated content which conveys the "cascaded" property values.

Example Use01 below has a simple ‘use’ on a ‘rect’.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc>
  <defs>
    <rect id="MyRect" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="20" y="10" xlink:href="#MyRect" />
</svg>

Example Use01

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc>
  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,10)">
    <rect width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

Example Use02 below has a ‘use’ on a ‘symbol’.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use02 - 'use' on a 'symbol'</desc>
  <defs>
    <symbol id="MySymbol" viewBox="0 0 20 20">
      <desc>MySymbol - four rectangles in a grid</desc>
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </symbol>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="45" y="10" width="10" height="10" 
       xlink:href="#MySymbol" />
</svg>

Example Use02

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use02-GeneratedContent - 'use' on a 'symbol'</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(45, 10)" >
    <!-- Start of referenced 'symbol'. 'symbol' replaced by 'svg',
         with x,y,width,height=0,0,100%,100% -->
    <svg width="10" height="10" 
         viewBox="0 0 20 20">
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </svg>
    <!-- End of referenced symbol -->
  </g>
  <!-- End of generated content -->

</svg>

Example Use03 illustrates what happens when a ‘use’ has a ‘transform’ property.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use03 - 'use' with a 'transform' attribute</desc>
  <defs>
    <rect id="MyRect" x="0" y="0" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use xlink:href="#MyRect"
       transform="translate(20,2.5) rotate(10)" />
</svg>

Example Use03

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,2.5) rotate(10)">
    <rect x="0" y="0" width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

Example Use04 illustrates a ‘use’ element with various methods of applying CSS styling.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3cm" viewBox="0 0 1200 300"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use04 - 'use' with CSS styling</desc>
  <defs style=" /* rule 9 */ stroke-miterlimit: 10" >
    <path id="MyPath" d="M300 50 L900 50 L900 250 L300 250"
                     class="MyPathClass"
                     style=" /* rule 10 */ stroke-dasharray:300,100" />
  </defs>
  <style type="text/css">
    <![CDATA[
      /* rule 1 */ #MyUse { fill: blue }
      /* rule 2 */ #MyPath { stroke: red }
      /* rule 3 */ use { fill-opacity: .5 }
      /* rule 4 */ path { stroke-opacity: .5 }
      /* rule 5 */ .MyUseClass { stroke-linecap: round }
      /* rule 6 */ .MyPathClass { stroke-linejoin: bevel }
      /* rule 7 */ use > path { shape-rendering: optimizeQuality }
      /* rule 8 */ g > path { visibility: hidden }
    ]]>
  </style>

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style=" /* rule 11 */ stroke-width:40">
    <use id="MyUse" xlink:href="#MyPath" 
         class="MyUseClass"
         style="/* rule 12 */ stroke-dashoffset:50" />
  </g>
</svg>

Example Use04

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document. Observe that some of the style rules above apply to the generated content (i.e., rules 1-6, 10-12), whereas others do not (i.e., rules 7-9). The rules which do not affect the generated content are:

• Rules 7 and 8: CSS selectors only apply to the formal document tree, not on the generated tree; thus, these selectors will not yield a match.
• Rule 9: The generated tree only inherits from the ancestors of the ‘use’ element and does not inherit from the ancestors of the referenced element; thus, this rule does not affect the generated content.

In the generated content below, the selectors that yield a match have been transferred into inline ‘style’ attributes for illustrative purposes.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3cm" viewBox="0 0 1200 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use04-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'style' and 'defs' sections left out -->

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style="/* rule 11 */ stroke-width:40">

    <!-- Start of generated content. Replaces 'use' -->
    <g style="/* rule 1 */ fill:blue;
                 /* rule 3 */ fill-opacity:.5;
                 /* rule 5 */ stroke-linecap:round;
                 /* rule 12 */ stroke-dashoffset:50" >
      <path d="M300 50 L900 50 L900 250 L300 250"
            style="/* rule 2 */ stroke:red; 
                   /* rule 4 */ stroke-opacity:.5; 
                   /* rule 6 */ stroke-linejoin: bevel; 
                   /* rule 10 */ stroke-dasharray:300,100" />
    </g> 
    <!-- End of generated content -->

  </g>
</svg>

When a ‘use’ references another element which is another ‘use’ or whose content contains a ‘use’ element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in References and the ‘defs’ element.

Attribute definitions:

Name	Value	Lacuna value	Animatable
x, y	<length>	0	yes
width, height	<length>	(see below)	yes

The ‘x’, ‘y’, ‘width’ and ‘height’ attributes specify the positioning of the referenced element. The ‘width’ and ‘height’ attributes have different lacuna values depending on the type of the referenced element:

‘svg’

The lacuna values are the ‘width’ and ‘height’ values from the referenced ‘svg’ element.

anything else

The lacuna values are '100%'.

A negative value for ‘width’ or ‘height’ is an error (see Error processing). If ‘width’ or ‘height’ is zero then rendering of the ‘use’ element is disabled.

Name	Value	Lacuna value	Animatable
href	URL [URL]	(none)	yes

An URL reference to the element/fragment within an SVG document to be cloned for rendering.

4.9. Conditional processing

4.9.1. Conditional processing overview

SVG contains a ‘switch’ element along with attributes ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.

Attributes ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ act as tests and return either true or false results. The ‘switch’ renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.

It sounds strange to talk about attributes "returning" a value. However it is the test, not the attribute, tat returns a value.

Similar to the ‘display’ property, conditional processing attributes only affect the direct rendering of elements and do not prevent elements from being successfully referenced by other elements (such as via a ‘use’).

In consequence:

• ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes affect ‘a’, ‘foreignObject’, ‘textPath’, and ‘tspan’ elements.
• ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes will have no effect on the ‘clipPath’, ‘filter’, ‘marker’, ‘mask’, ‘pattern’ and ‘symbol’ elements or on gradient elements.
• ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes do not apply to the ‘defs’, and ‘cursor’ elements because they are not part of the rendering tree.
• ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes affect ‘animate’, ‘animateMotion’, ‘animateTransform’, and ‘set’ elements. If the conditional statement on these animation elements fails, the animation will never be triggered.

4.9.2. Definitions

conditional processing attribute

A conditional processing attribute is one that controls whether or not the element on which it appears is processed. Most elements, but not all, may have conditional processing attributes specified on them. See Conditional processing for details. The conditional processing attributes defined in SVG 1.1 are ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’.

4.9.3. The ‘switch’ element

The ‘switch’ element evaluates the ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a ‘g’, then the entire subtree is either processed/rendered or bypassed/not rendered.

Note that the values of properties ‘display’ and ‘visibility’ have no effect on ‘switch’ element processing. In particular, setting ‘display’ to none on a child of a ‘switch’ element has no effect on true/false testing associated with ‘switch’ element processing.

The ‘switch’ element does not affect the processing of ‘script’ and ‘style’ elements.

For more information and an example, see Embedding foreign object types.

4.9.4. The ‘requiredFeatures’ attribute

Name	Value	Lacuna value	Animatable
requiredFeatures	list-of-features	(none)	no

Need a grammar for list-of-features.

The value is a list of feature strings, with the individual values separated by white space. Determines whether all of the named features are supported by the user agent. Only feature strings defined in the Feature String appendix are allowed. If all of the given features are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘requiredFeatures’, the attribute returns "false".

‘requiredFeatures’ is often used in conjunction with the ‘switch’ element. If the ‘requiredFeatures’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

4.9.5. The ‘requiredExtensions’ attribute

The ‘requiredExtensions’ attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.

Name	Value	Lacuna value	Animatable
requiredExtensions	list-of-extensions	(none)	no

Need a grammar for list-of-extensions.

The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.

If a given URL reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘requiredExtensions’, the attribute returns "false".

‘requiredExtensions’ is often used in conjunction with the ‘switch’ element. If the ‘requiredExtensions’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

The URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.

4.9.6. The ‘systemLanguage’ attribute

The attribute value is a comma-separated list of Language-Tag values, as defined in BCP 47 [BCP47].

Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

Multiple languages MAY be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within the object on which the ‘systemLanguage’ test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the ‘systemLanguage’ test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a ‘switch’, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a ‘switch’ which is acceptable in all cases.

For the ‘systemLanguage’ attribute: Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘systemLanguage’, the attribute returns "false".

‘systemLanguage’ is often used in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

Should have an attribute definition table in this section.

4.9.7. Applicability of test attributes

The following list describes the applicability of the test attributes to the elements that do not directly produce rendering.

This was already mentioned in the "Conditional processing overview" section. We should just describe this once.

• the test attributes do not effect the ‘mask’, ‘clipPath’, ‘linearGradient’, ‘radialGradient’ and ‘pattern’ elements. The test attributes on a referenced element do not affect the rendering of the referencing element.
• the test attributes do not effect the ‘defs’, and ‘cursor’ elements as they are not part of the rendering tree.
• an animation element (‘animate’, ‘animateMotion’, ‘animateTransform’ and ‘set’) will never be triggered if it has a test attribute that evaluates to false.

4.10. Common attributes

4.10.1. Definitions

core attributes

The core attributes are those attributes that can be specified on any SVG element. This includes Common attributes, and styling attributes. The core attributes are ‘id’, ‘tabindex’, ‘xml:base’, ‘xml:lang’ and ‘xml:space’ and ‘class’ and ‘style’.

4.10.2. Attributes common to all elements: ‘id’ and ‘xml:base’

The ‘id’ and ‘xml:base’ attributes are available on all SVG elements:

Name	Value	Lacuna value	Animatable
id	(see below)	(none)	no

Reflects the element's ID [DOM4]. The ‘id’ attribute must be any value other than the empty string.

Name	Value	Lacuna value	Animatable
xml:base	URL [URL]	(none)	no

Specifies a base URL other than the base URL of the document or external entity. Refer to the XML Base specification [XML-BASE].

Are we happy to keep promoting the use of ‘xml:base’? Is it a use case worth trying to include a more HTML-like syntax for – the ‘base’ element? We anyway need to define somewhere what effect the HTML ‘base’ element has on any SVG document fragments. For some more context on making <base> apply to svg, see this AngularJS issue.

4.10.3. The ‘xml:lang’ attribute

Elements that might contain character data content can have the attribute ‘xml:lang’.

Should we be moving 'lang'? instead of ‘xml:lang’? At minimum allow both lang and xml:lang (then needs a priority if both specified).

Name	Value	Lacuna value	Animatable
xml:lang	Language-Tag [ABNF]	(none)	no

Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].

Name	Value	Lacuna value	Animatable
xml:space	(see below)	default	no

Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are the strings 'default' and 'preserve'. White space is not allowed. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.

New content should use the ‘white-space’ property instead.

4.10.4. The ‘tabindex’ attribute

Name	Value	Lacuna value	Animatable
tabindex	<number>	(none)	no

We should explicit refer to the algorithm HTML uses to parse ‘tabindex’ numbers.

This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable using sequential focus navigation, and what is to be the relative order of the element for the purposes of sequential focus navigation

The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements that can be reached using sequential focus navigation.

4.11. WAI-ARIA attributes

4.11.1. Definitions

ARIA attributes

These are the attributes used consisting of WAI-ARIA states and properties as well as the role attribute whose values are defined defined in WAI-ARIA. See WAI-ARIA WAI-ARIA Definition of Roles and WAI-ARIA Supported States and Properties. The aria attributes are ‘aria-activedescendant’, ‘role’, ‘aria-autocomplete’, ‘aria-busy’, ‘aria-checked’, ‘aria-controls’, ‘aria-describedat’, ‘aria-describedby’, ‘aria-disabled’, ‘aria-dropeffect’, ‘aria-expanded’, ‘aria-flowto’, ‘aria-grabbed’, ‘aria-haspopup’, ‘aria-hidden’, ‘aria-invalid’, ‘aria-label’, ‘aria-labelledby’, ‘aria-level’, ‘aria-atomic’, ‘aria-modal’, ‘aria-multiline’, ‘aria-multiselectable’, ‘aria-orientation’, ‘aria-owns’, ‘aria-posinset’, ‘aria-pressed’, ‘aria-readonly’, ‘aria-relevant’, ‘aria-required’, ‘aria-selected’, ‘aria-setsize’, ‘aria-sort’, ‘aria-valuemax’, ‘aria-valuemin’, ‘aria-valuenow’, ‘aria-valuetext’ and ‘aria-live’.

4.11.2. Role attribute

SVG elements having native semantics that are not limited to presentation (having "no role"), may have an ARIA role attribute specified. The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to. These tokens are role values defined in Definition of Roles ([ARIA], section 5.4).

The WAI-ARIA role that an SVG element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.

Name	Value	Lacuna value	Animatable
role	(see below)	(see below)	no

The ‘role’ attribute must be a set of white-space, space-separated tokens having values defined in Definition of Roles ([ARIA], section 5.4)

The role value is a set of white-space separated machine-extractable semantic information used to define the purpose of the element.

We should perhaps call into HTML's algorithm to parse a "set of space-separated tokens".

The lacuna value for the ‘role’ attribute, for each SVG element, is the corresponding default implied ARIA semantic for SVG elements.

4.11.3. State and property attributes (all aria- attributes)

SVG elements having native semantics that are not limited to presentation (having "no role"), may have an may have WAI-ARIA state and property attributes specified. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([ARIA], section 6.6).

These attributes, if specified, must have a value that is the WAI-ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate SVG value type according to Mapping WAI-ARIA Value types to languages using the SVG mapping ([ARIA], section 10.2).

WAI-ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. Unlike some other host languages, SVG is not considered to have strong native host language semantics in terms of the user interface, consequently state and property attributes are processed according to the ARIA and SVG Accessibility API Mappings specification specifications. [ARIA] [SVG-AAM]

4.11.4. Implicit ARIA Semantics

The following table defines the implicit native semantics and corresponding default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.

4.12. DOM interfaces

4.12.1. Interface Document

The DOM Core specification defines a Document interface, which this specification extends.

In the case where an SVG document is embedded by reference, such as when an HTML document has an ‘object’ element whose ‘href’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an ‘svg’ element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document.

For historical reasons, Window objects must also have a writable, configurable, non-enumerable property named SVGDocument whose value is the Document interface object.

partial interface Document {
  readonly attribute SVGSVGElement rootElement;
};

Attributes:

rootElement (readonly SVGSVGElement)

The root ‘svg’ in the document hierarchy.

This attribute is deprecated, and may be removed in a future SVG specification. Authors are encouraged to use the documentElement attribute on Document instead.

The following IDL fragment must be supported only if the SVG implementation is also a Web browser or other interactive user agent, and therefore implements HTML.

// must only be implemented in certain implementations
partial interface Document {
  readonly attribute DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute Element? activeElement;
};

This is because the interface members above are already defined in HTML, and in implementations that support SVG and HTML they cannot be duplicated.

The title, referrer, domain and activeElement IDL attributes must behave the same as the corresponding IDL attributes defined in HTML.

4.12.2. Interface SVGSVGElement

A key interface definition is the SVGSVGElement interface, which is the interface that corresponds to the ‘svg’ element. This interface contains various miscellaneous commonly-used utility methods, such as matrix operations and the ability to control the time of redraw on visual rendering devices.

interface SVGSVGElement : SVGGraphicsElement {

  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute DOMRectReadOnly viewport;
  readonly attribute boolean useCurrentView;
  readonly attribute SVGViewSpec currentView;
           attribute float currentScale;
  readonly attribute DOMPointReadOnly currentTranslate;

  unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
  void pauseAnimations();
  void unpauseAnimations();
  boolean animationsPaused();
  float getCurrentTime();
  void setCurrentTime(float seconds);
  NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement referenceElement);
  NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement referenceElement);
  boolean checkIntersection(SVGElement element, DOMRectReadOnly rect);
  boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect);
  void deselectAll();
  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  DOMPoint createSVGPoint();
  DOMMatrix createSVGMatrix();
  DOMRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);
};

SVGSVGElement implements SVGFitToViewBox;
SVGSVGElement implements SVGZoomAndPan;
SVGSVGElement implements WindowEventHandlers;

Attributes:

x (readonly SVGAnimatedLength)

Corresponds to attribute ‘x’ on the given ‘svg’ element.

y (readonly SVGAnimatedLength)

Corresponds to attribute ‘y’ on the given ‘svg’ element.

width (readonly SVGAnimatedLength)

Corresponds to attribute ‘width’ on the given ‘svg’ element.

height (readonly SVGAnimatedLength)

Corresponds to attribute ‘height’ on the given ‘svg’ element.

viewport (readonly DOMRectReadOnly)

The position and size of the viewport (implicit or explicit) that corresponds to this ‘svg’ element. When the user agent is actually rendering the content, then the position and size values represent the actual values when rendering. The position and size values are unitless values in the coordinate system of the parent element. If no parent element exists (i.e., ‘svg’ element represents the root of the document tree), if this SVG document is embedded as part of another document (e.g., via the HTML ‘object’ element), then the position and size are unitless values in the coordinate system of the parent document. (If the parent uses CSS or XSL layout, then unitless values represent pixel units for the current CSS or XSL viewport, as described in the CSS2 specification.) If the parent element does not have a coordinate system, then the user agent should provide reasonable default values for this attribute.

The DOMRectReadOnly object, as its name suggests, is read only.

useCurrentView (readonly boolean)

The initial view (i.e., before magnification and panning) of the current SVG document fragment can be either the "standard" view (i.e., based on attributes on the ‘svg’ element such as ‘viewBox’) or to a "custom" view (i.e., a hyperlink into a particular ‘view’ or other element - see Linking into SVG content: URL fragments and SVG views). If the initial view is the "standard" view, then this attribute is false. If the initial view is a "custom" view, then this attribute is true.

currentView (readonly SVGViewSpec)

The definition of the initial view (i.e., before magnification and panning) of the current SVG document fragment. The meaning depends on the situation:

• If the initial view was a "standard" view, then:
  • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly
  • the values for transform and viewTarget within currentView will be null
• If the initial view was a link into a ‘view’ element, then:
  • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will correspond to the corresponding attributes for the given ‘view’ element
  • the values for transform and viewTarget within currentView will be null
• If the initial view was a link into another element (i.e., other than a ‘view’), then:
  • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly for the closest ancestor ‘svg’ element
  • the values for transform within currentView will be null
  • the viewTarget within currentView will represent the target of the link
• If the initial view was a link into the SVG document fragment using an SVG view specification fragment identifier (i.e., #svgView(...)), then:
  • the values for viewBox, preserveAspectRatio, zoomAndPan, transform and viewTarget within currentView will correspond to the values from the SVG view specification fragment identifier

The object itself and its contents are both read only.

currentScale (float)

On an outermost svg element, this attribute indicates the current scale factor relative to the initial view to take into account user magnification and panning operations, as described under Magnification and panning. DOM attributes currentScale and currentTranslate are equivalent to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. If "magnification" is enabled (i.e., zoomAndPan="magnify"), then the effect is as if an extra transformation were placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).

The value of a transform property on the outermost svg element does not affect the value of this attribute.

When accessed on an ‘svg’ element that is not an outermost svg element, this attribute must return 1 as scaling factor.

currentTranslate (readonly DOMPointReadOnly)

On an outermost svg element, the corresponding translation factor that takes into account user "magnification".

The value of a transform property on the outermost svg element does not affect the value of this attribute.

When accessed on an ‘svg’ element that is not an outermost svg element, this attribute must return an DOMPointReadOnly at the coordinates (0, 0).

Operations:

unsigned long suspendRedraw(unsigned long maxWaitMilliseconds)

This method is deprecated, and is only kept for compatibility with legacy content. Calling this method has no effect on redrawing.

Parameters

1. unsigned long maxWaitMilliseconds
   This parameter is ignored.

Returns

The returned value is always 1.

void unsuspendRedraw(unsigned long suspendHandleID)

This method is deprecated, and is only kept for compatibility with legacy content. Calling this method has no effect on redrawing.

Parameters

1. unsigned long suspendHandleID
   This parameter is ignored.

void unsuspendRedrawAll()

This method is deprecated, and is only kept for compatibility with legacy content. Calling this method has no effect on redrawing.

void forceRedraw()

This method is deprecated, and is only kept for compatibility with legacy content. Calling this method has no effect on redrawing.

void pauseAnimations()

Suspends (i.e., pauses) all currently running SVG animations that are defined within the SVG document fragment corresponding to this ‘svg’ element, causing the current time of the timeline for this document fragment to stand still until it is unpaused. If this ‘svg’ element is not the outermost svg element this method has no effect.

This method only affects animations defined using SVG's animation elements. It does not affect CSS Animations [CSSANIMATIONS], CSS Transitions [CSS3TRANSITIONS] or animations created using script.

void unpauseAnimations()

Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment corresponding to this ‘svg’ element, causing the timeline for the document fragment to continue from its current time. If this ‘svg’ element is not the outermost svg element this method has no effect.

This method only affects animations defined using SVG's animation elements. It does not affect CSS Animations [CSSANIMATIONS], CSS Transitions [CSS3TRANSITIONS] or animations created using script.

boolean animationsPaused()

Returns true if the timeline for the current SVG document fragment is in a paused state.

Returns

Boolean indicating whether the timeline for the current SVG document fragment is in a paused state.

float getCurrentTime()

Returns the current time in seconds relative to the start time for the timeline of the current SVG document fragment. If getCurrentTime is called before the current SVG document fragment's timeline has begun, then 0 is returned.

For example, if the outermost svg element of an SVG document fragment has a ‘timelinebegin’ value of loadend, any script running in a ‘script’ element that does not wait for the document fragment's load event to fire, will run before the timeline begins and any calls to this method will return 0.

Returns

The current time in seconds, or 0 if the current SVG document fragment timeline has not yet started.

void setCurrentTime(float seconds)

Adjusts the clock for this SVG document fragment, establishing a new current time. If setCurrentTime is called before the document timeline has begun, the value of seconds in the last invocation of the method gives the time that the document will seek to once the document timeline has begun.

If this ‘svg’ element is not the outermost svg element this method has no effect.

Parameters

1. float seconds
   The new current time in seconds relative to the start time for this SVG document fragment.

NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement referenceElement)

Returns the list of graphics elements whose rendered content intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.

Shadow tree elements must not be returned in the list, if such an element is matched then the corresponding ‘use’ element is to be returned.

Parameters

1. DOMRectReadOnly rect
   The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
2. SVGElement referenceElement
   If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.

Returns

A list of Elements whose content intersects the supplied rectangle. The NodeList that is returned is static ([DOM4], section 5.2.7).

NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement referenceElement)

Returns the list of graphics elements whose rendered content is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.

Shadow tree elements must not be returned in the list, if such an element is matched then the corresponding ‘use’ element is to be returned.

Parameters

1. DOMRectReadOnly rect
   The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
2. SVGElement referenceElement
   If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.

Returns

A list of Elements whose content is enclosed by the supplied rectangle. The NodeList that is returned is static ([DOM4], section 5.2.7).

boolean checkIntersection(SVGElement element, DOMRectReadOnly rect)

Returns true if the rendered content of the given element intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.

Parameters

1. SVGElement element
   The element on which to perform the given test.
2. DOMRectReadOnly rect
   The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.

Returns

True or false, depending on whether the given element intersects the supplied rectangle.

boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect)

Returns true if the rendered content of the given element is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.

Parameters

1. SVGElement element
   The element on which to perform the given test.
2. DOMRectReadOnly rect
   The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.

Returns

True or false, depending on whether the given element is enclosed by the supplied rectangle.

void deselectAll()

Removes any selections from the document. The effect of this method is to remove all ranges from the document's selection and then to set the selection's direction to forwards. [DOM4][EDITING]

This is equivalent to calling document.getSelection().removeAllRanges() on the document that this ‘svg’ element is in.

This method is deprecated, as it duplicates functionality from the Selection API.

SVGNumber createSVGNumber()

Creates an SVGNumber object outside of any document trees. The object is initialized to a value of zero.

Returns

An SVGNumber object.

SVGLength createSVGLength()

Creates an SVGLength object outside of any document trees. The object is initialized to the value of 0 user units.

Returns

An SVGLength object.

SVGAngle createSVGAngle()

Creates an SVGAngle object outside of any document trees. The object is initialized to the value 0 degrees (unitless).

Returns

An SVGAngle object.

DOMPoint createSVGPoint()

Creates an DOMPoint object outside of any document trees. The object is initialized to the point (0,0) in the user coordinate system.

Returns

An DOMPoint object.

DOMMatrix createSVGMatrix()

Creates an DOMMatrix object outside of any document trees. The object is initialized to the identity matrix.

Returns

An DOMMatrix object.

DOMRect createSVGRect()

Creates an DOMRect object outside of any document trees. The object is initialized such that all values are set to 0 user units.

Returns

An DOMRect object.

SVGTransform createSVGTransform()

Creates an SVGTransform object outside of any document trees. The object is initialized to an identity matrix transform (SVG_TRANSFORM_MATRIX).

Returns

An SVGTransform object.

SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix)

Creates an SVGTransform object outside of any document trees. The object is initialized to the given matrix transform (i.e., SVG_TRANSFORM_MATRIX). The values from the parameter matrix are copied, the matrix parameter is not adopted as SVGTransform::matrix.

Parameters

1. DOMMatrixReadOnly matrix
   The transform matrix.

Returns

An SVGTransform object.

4.12.3. Interface SVGGElement

interface SVGGElement : SVGGraphicsElement {
};

4.12.4. Interface SVGDefsElement

interface SVGDefsElement : SVGGraphicsElement {
};

4.12.5. Interface SVGDescElement

interface SVGDescElement : SVGElement {
};

4.12.6. Interface SVGMetadataElement

interface SVGMetadataElement : SVGElement {
};

4.12.7. Interface SVGTitleElement

interface SVGTitleElement : SVGElement {
};

4.12.8. Interface SVGSymbolElement

interface SVGSymbolElement : SVGElement {
};

SVGSymbolElement implements SVGFitToViewBox;

4.12.9. Interface SVGUseElement

The SVGUseElement interface corresponds to the ‘use’ element.

interface SVGUseElement : SVGGraphicsElement {
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
};

SVGUseElement implements SVGURIReference;

Attributes:

x (readonly SVGAnimatedLength)

Corresponds to attribute ‘x’ on the given ‘use’ element.

y (readonly SVGAnimatedLength)

Corresponds to attribute ‘y’ on the given ‘use’ element.

width (readonly SVGAnimatedLength)

Corresponds to attribute ‘width’ on the given ‘use’ element.

height (readonly SVGAnimatedLength)

Corresponds to attribute ‘height’ on the given ‘use’ element.

4.12.10. Interface SVGSwitchElement

interface SVGSwitchElement : SVGGraphicsElement {
};

4.12.11. Interface GetSVGDocument

This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references, such as the DOM Element object that corresponds to an HTML ‘object’ element. Such DOM objects are often also required to implement the EmbeddingElement defined in the Window specification [WINDOW].

This interface is deprecated and may be dropped from future versions of the SVG specification. Authors are suggested to use the contentDocument attribute on the EmbeddingElement interface to obtain a referenced SVG document, if that interface is available.

[NoInterfaceObject]
interface GetSVGDocument {
  SVGDocument getSVGDocument();
};

Operations:

SVGDocument getSVGDocument()

This method must return the Document object embedded content in an embedding element, or null if there is no document.

Note that this is equivalent to fetching the value of the EmbeddingElement::contentDocument attribute of the embedding element, if the EmbeddingElement interface is also implemented. The author is advised to check that the document element of the returned Document is indeed an ‘svg’ element instead of assuming that that will always be the case.

Returns

The Document object for the referenced document, or null if there is no document.