previous next contents elements attributes properties index

14 January 2003

# 17 Linking

### Contents

## 17.1 Links out of SVG content: the 'a' element

SVG provides an 'a' element, analogous to HTML's 'a' element, to indicate links (also known as hyperlinks or Web links). SVG uses XLink ([XLink]) for all link definitions.

SVG 1.0 only requires that user agents support XLink's notion of simple links. Each simple link associates exactly two resources, one local and one remote, with an arc going from the former to the latter.

A simple link is defined for each separate rendered element contained within the 'a' element; thus, if the 'a' element contains three 'circle' elements, a link is created for each circle. For each rendered element within an 'a' element, the given rendered element is the local resource (the source anchor for the link).

The remote resource (the destination for the link) is defined by a URI specified by the XLink href attribute on the 'a' element. The remote resource may be any Web resource (e.g., an image, a video clip, a sound bite, a program, another SVG document, an HTML document, an element within the current document, an element within a different document, etc.). By activating these links (by clicking with the mouse, through keyboard input, voice commands, etc.), users may visit these resources.

Example link01 assigns a link to an ellipse.

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
      "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
    <svg width="5cm" height="3cm" viewBox="0 0 5 3" version="1.1"
         xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <desc>Example link01 - a link on an ellipse
      </desc>
      <rect x=".01" y=".01" width="4.98" height="2.98"
            fill="none" stroke="blue"  stroke-width=".03"/>
      <a xlink:href="http://www.w3.org">
        <ellipse cx="2.5" cy="1.5" rx="2" ry="1"
                 fill="red" />
      </a>
    </svg>

Example link01

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

If the above SVG file is viewed by a user agent that supports both SVG and HTML, then clicking on the ellipse will cause the current window or frame to be replaced by the W3C home page.

    <!ENTITY % SVG.a.extra.content "" >
    <!ENTITY % SVG.a.element "INCLUDE" >
    <![%SVG.a.element;[
    <!ENTITY % SVG.a.content
        "( #PCDATA | %SVG.Description.class; | %SVG.Animation.class;
           %SVG.Structure.class; %SVG.Conditional.class; %SVG.Image.class;
           %SVG.Style.class; %SVG.Shape.class; %SVG.Text.class; %SVG.Marker.class;
           %SVG.ColorProfile.class; %SVG.Gradient.class; %SVG.Pattern.class;
           %SVG.Clip.class; %SVG.Mask.class; %SVG.Filter.class; %SVG.Cursor.class;
           %SVG.Hyperlink.class; %SVG.View.class; %SVG.Script.class;
           %SVG.Font.class; %SVG.a.extra.content; )*"
    >
    <!ELEMENT %SVG.a.qname; %SVG.a.content; >
    <!-- end of SVG.a.element -->]]>
    <!ENTITY % SVG.a.attlist "INCLUDE" >
    <![%SVG.a.attlist;[
    <!ATTLIST %SVG.a.qname;
        %SVG.Core.attrib;
        %SVG.Conditional.attrib;
        %SVG.Style.attrib;
        %SVG.Presentation.attrib;
        %SVG.GraphicalEvents.attrib;
        %SVG.XLinkReplace.attrib;
        %SVG.External.attrib;
        transform %TransformList.datatype; #IMPLIED
        target %LinkTarget.datatype; #IMPLIED
    >

Attribute definitions:

xmlns [:prefix] = "resource-name"
  Standard XML attribute for identifying an XML namespace. This attribute makes the XLink [XLink] namespace available to the current element. Refer to the "Namespaces in XML" Recommendation [XML-NS].
  Animatable: no.
xlink:type = 'simple'
  (See generic description of xlink:type attribute.)
xlink:role = '<uri>'
  (See generic description of xlink:role attribute.)
xlink:arcrole = '<uri>'
  (See generic description of xlink:arcrole attribute.)
xlink:title = '<string>'
  (See generic description of xlink:title attribute.)
xlink:show = 'new | replace'
  Indicates whether, upon activation of the link, traversing to the ending resource should load it in a new window, frame, pane, or other relevant presentation context or load it in the same window, frame, pane, or other relevant presentation context in which the starting resource was loaded. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:actuate = 'onRequest'
  An application should traverse from the starting resource to the ending resource only on a post-loading event triggered for the purpose of traversal. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:href = "<uri>"
  The location of the referenced object, expressed as a URI reference. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: yes.
target = "<frame-target>"
  This attribute has applicability when there are multiple possible targets for the ending resource, such as when the parent document is a multi-frame HTML or XHTML document. This attribute specifies the name of the target location (e.g., an HTML or XHTML frame) into which a document is to be opened when the link is activated. For more information on targets, refer to the appropriate HTML or XHTML specifications.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs; %langSpaceAttrs;, class, transform, %graphicsElementEvents;, %testAttrs;, externalResourcesRequired style, %PresentationAttributes-All;.

## 17.2 Linking into SVG content: URI fragments and SVG views

### 17.2.1 Introduction: URI fragments and SVG views

On the Internet, resources are identified using URIs (Uniform Resource Identifiers) [URI]. For example, an SVG file called MyDrawing.svg located at http://example.com might have the following URI:

    http://example.com/MyDrawing.svg

A URI can also address a particular element within an XML document by including a URI fragment identifier as part of the URI. A URI which includes a URI fragment identifier consists of an optional base URI, followed by a "#" character, followed by the URI fragment identifier. For example, the following URI can be used to specify the element whose ID is "Lamppost" within file MyDrawing.svg:

    http://example.com/MyDrawing.svg#Lamppost

Because SVG content often represents a picture or drawing of something, a common need is to link into a particular view of the document, where a view indicates the initial transformations so as to present a closeup of a particular section of the document.

### 17.2.2 SVG fragment identifiers

To link into a particular view of an SVG document, the URI fragment identifier needs to be a correctly formed SVG fragment identifier. An SVG fragment identifier defines the meaning of the "selector" or "fragment identifier" portion of URIs that locate resources of MIME media type "image/svg+xml".

An SVG fragment identifier can come in three forms:

- Shorthand bare name form of addressing (e.g., MyDrawing.svg#MyView). This form of addressing, which allows addressing an SVG element by its ID, is compatible with the fragment addressing mechanism for older versions of HTML and the shorthand bare name formulation in "XML Pointer Language (XPointer)" [XPTR]. (The bare name form of addressing #MyView is equivalent to the XPointer formulation #xpointer(id('MyView')).)
- XPointer-compatible ID reference (e.g., MyDrawing.svg#xpointer(id('MyView'))). This form of addressing, which also allows addressing an SVG element by its ID, is compatible with "XML Pointer Language (XPointer)" [XPTR] syntax and the XPath syntax for referencing IDs.
- SVG view specification (e.g., MyDrawing.svg#svgView(viewBox(0,200,1000,1000))). This form of addressing specifies the desired view of the document (e.g., the region of the document to view, the initial zoom level) completely within the SVG fragment specification. The contents of the SVG view specification are the five parameter specifications, viewBox(...), preserveAspectRatio(...), transform(...), zoomAndPan(...) and viewTarget(...), whose parameters have the same meaning as the corresponding attributes on a 'view' element, or, in the case of transform(...), the same meaning as the corresponding attribute has on a 'g' element).

An SVG fragment identifier is defined as follows:

    SVGFragmentIdentifier ::= BareName |
                              XPointerIDRef |
                              SVGViewSpec

    BareName ::= XML_Name
    SVGViewSpec ::= 'svgView(' SVGViewAttributes ')'
    SVGViewAttributes ::= SVGViewAttribute |
                          SVGViewAttribute ';' SVGViewAttributes

    SVGViewAttribute ::= viewBoxSpec |
                         preserveAspectRatioSpec |
                         transformSpec |
                         zoomAndPanSpec |
                         viewTargetSpec
    viewBoxSpec ::= 'viewBox(' ViewBoxParams ')'
    preserveAspectRatioSpec = 'preserveAspectRatio(' AspectParams ')'
    transformSpec ::= 'transform(' TransformParams ')'
    zoomAndPanSpec ::= 'zoomAndPan(' ZoomAndPanParams ')'
    viewTargetSpec ::= 'viewTarget(' ViewTargetParams ')'

where:

- XPointerIDRef conforms to the rules for referencing IDs in XPointer (see [XPTR] and XPath syntax for referencing IDs). For example, `xpointer(id('MyView'))`.
- ViewBoxParams corresponds to the parameter values for the viewBox attribute on the 'view' element. For example, viewBox(0,0,200,200).
- AspectParams corresponds to the parameter values for the preserveAspectRatio attribute on the 'view' element. For example, preserveAspectRatio(xMidYMid).
- TransformParams corresponds to the parameter values for the transform attribute that is available on many elements. For example, transform(scale(5)).
- ZoomAndPanParams corresponds to the parameter values for the zoomAndPan attribute on the 'view' element. For example, zoomAndPan(magnify).
- ViewTargetParams corresponds to the parameter values for the viewTarget attribute on the 'view' element. For example, viewTarget(MyElementID).

Spaces are not allowed in fragment specifications; thus, commas are used to separate numeric values within an SVG view specification (e.g., #svgView(viewBox(0,0,200,200))) and semicolons are used to separate attributes (e.g., #svgView(viewBox(0,0,200,200);preserveAspectRatio(none))).

When a source document performs a link into an SVG document via an HTML [HTML4] anchor element (i.e., <a href=...> element in HTML) or an XLink specification [XLINK], then the SVG fragment identifier specifies the initial view into the SVG document, as follows:

- If no SVG fragment identifier is provided (e.g, the specified URI did not contain a "#" character, such as MyDrawing.svg), then the initial view into the SVG document is established using the view specification attributes (i.e., viewBox, etc.) on the outermost 'svg' element.
- If the SVG fragment identifier addresses a 'view' element within an SVG document (e.g., MyDrawing.svg#MyView or MyDrawing.svg#xpointer(id('MyView'))) then the closest ancestor 'svg' element is displayed in the viewport. Any view specification attributes included on the given 'view' element override the corresponding view specification attributes on the closest ancestor 'svg' element.
- If the SVG fragment identifier addresses specific SVG view (e.g., MyDrawing.svg#svgView(viewBox(0,200,1000,1000))), then the document fragment defined by the closest ancestor 'svg' element is displayed in the viewport using the SVG view specification provided by the SVG fragment identifier.
- If the SVG fragment identifier addresses any element other than a 'view' element, then the document defined by the closest ancestor 'svg' element is displayed in the viewport using the view specification attributes on that 'svg' element.

### 17.2.3 Predefined views: the 'view' element

The 'view' element is defined as follows:

    <!ENTITY % SVG.view.extra.content "" >
    <!ENTITY % SVG.view.element "INCLUDE" >
    <![%SVG.view.element;[
    <!ENTITY % SVG.view.content
        "( %SVG.Description.class; %SVG.view.extra.content; )*"
    >
    <!ELEMENT %SVG.view.qname; %SVG.view.content; >
    <!-- end of SVG.view.element -->]]>
    <!ENTITY % SVG.view.attlist "INCLUDE" >
    <![%SVG.view.attlist;[
    <!ATTLIST %SVG.view.qname;
        %SVG.Core.attrib;
        %SVG.External.attrib;
        viewBox %ViewBoxSpec.datatype; #IMPLIED
        preserveAspectRatio %PreserveAspectRatioSpec.datatype; 'xMidYMid meet'
        zoomAndPan ( disable | magnify ) 'magnify'
        viewTarget CDATA #IMPLIED
    >

Attribute definitions:

viewTarget = "XML_Name [XML_NAME]*"
  Indicates the target object associated with the view. If provided, then the target element(s) will be highlighted.
  Animatable: no.

Attributes defined elsewhere:
  %stdAttrs;, viewBox, preserveAspectRatio, zoomAndPan externalResourcesRequired.

##
17.3 Hyperlinking Module

Elements | Attributes | Content Model
--- | --- | ---
a | Core.attrib, Conditional.attrib, Style.attrib, transform, target, GraphicalEvents.attrib, Presentation.attrib, External.attrib, XLinkReplace.attrib | (#PCDATA | Structure.class | Description.class Shape.class | Image.class | | View.class | Conditional.class | HyperinkingElements | Font.class | Script.class | Style.class | Marker.class | Clip.class | Mask.class | Gradient.class | Pattern.class | Filter.class | Cursor.class | Animation.class | ColorProfile.class)*

###
17.3.1 Hyperlinking Content Set

The Hyperlinking Module defines the Hyperlink.class content set.

Content Set Name | Elements in Content Set
--- | ---
Hyperlink.class | a

## 17.4 XLink Attribute Module

The XLink Attribute Module defines the XLink.attrib, XLinkRequired.attrib, XLinkEmbed.attrib and XLinkReplace.attrib attribute sets.

Collection Name | Attributes in Collection
--- | ---
XLink.attrib | xlink:type, xlink:href, xlink:role, xlink:arcrole, xlink:title, xlink:show, xlink:actuate
XLinkRequired.attrib | xlink:type, xlink:href, xlink:role, xlink:arcrole, xlink:title, xlink:show, xlink:actuate
XLinkEmbed.attrib | xlink:type, xlink:href, xlink:role, xlink:arcrole, xlink:title, xlink:show, xlink:actuate
XLinkReplace.attrib | xlink:type, xlink:href, xlink:role, xlink:arcrole, xlink:title, xlink:show, xlink:actuate

##
17.5 ExternalResourcesRequired Attribute Module

The ExternalResourcesRequired Attribute Module defines the External.attrib attribute set.

Collection Name | Attributes in Collection
--- | ---
External.attrib | externalResourcesRequired

## 17.6 View Module

Elements | Attributes | Content Model
--- | --- | ---
view | Core.attrib, External.attrib, viewBox, preserveAspectRatio, zoomAndPan, viewTarget | (Description.class)

### 17.6.1 View Content Set

The View Module defines the View.class content set.

Content Set Name | Elements in Content Set
--- | ---
View.class | view

## 17.7 DOM interfaces

The following interfaces are defined below: SVGAElement, SVGViewElement.

### Interface SVGAElement

The SVGAElement interface corresponds to the 'a' element.

IDL Definition

      interface SVGAElement :
                      SVGElement,
                      SVGURIReference,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {
        readonly attribute SVGAnimatedString target;
      };

Attributes
  readonly SVGAnimatedString target
    Corresponds to attribute target on the given 'a' element.

### Interface SVGViewElement

The SVGViewElement interface corresponds to the 'view' element.

IDL Definition

      interface SVGViewElement :
                      SVGElement,
                      SVGExternalResourcesRequired,
                      SVGFitToViewBox,
                      SVGZoomAndPan {
        readonly attribute SVGStringList viewTarget;
      };

Attributes
  readonly SVGStringList viewTarget
    Corresponds to attribute viewTarget on the given 'view' element. A list of DOMString values which contain the names listed in the viewTarget attribute. Each of the DOMString values can be associated with the corresponding element using the getElementById() method call.

previous next contents elements attributes properties index