<svgref>

The <svgref> element references a non-DITA XML document that contains scalable vector graphic (SVG) markup.

Usage information

The <svgref> element enables the use of SVG markup by reference. The reference must be to a SVG <svg> element that is stored in a separate, non-DITA XML document. The reference can be one of the following:

  • A URI that addresses an XML document which has a SVG <svg> element as the root element
  • A URI that addresses an XML document and contains a fragment identifier that is the XML ID of a <svg> element within the document

The reference can be direct, using the @href attribute, or indirect, using the @keyref attribute. For indirect referencing, only the key name should be specified. The ID of the <svg> element must be specified as part of the value for the @href attribute on the key definition.

For example, to refer to the <svg> element with the @id of svg-fragment-02 within a larger document using a key reference, you would define the key in the following way:

<keydef keys="svg-fragment-0002" href="svg/svg-library.xml#svg-fragment-02"/>

You reference this key by using just the key name:

<svg-container>
  <svgref keyref="svg-fragment-0002"/>
</svg-container>

Processing information

Processors SHOULD process the SVG as though the <svg> element occurs directly in the content of the containing <svg-container> element.

Specialization hierarchy

The <svgref> is specialized from <include>. It is defined in the SVG domain module.

Attributes

The following attributes are available on this element: inclusion attributes, link-relationship attributes, universal attributes, and @keyref.

For this element:
  • The @format attribute has a default value of svg.
  • The @href attribute is a reference to an SVG document or SVG element. If the <svg> element is the root element of the referenced resource, then no fragment identifier is required. Otherwise, a fragment identifier must be specified, where the fragment identifier is the XML ID of the <svg> element.
  • The @parse attribute has a default value of xml.

Examples

This section contains examples of how the <svgref> element can be used.

Figure 1. Referencing an SVG that is a root element

The following code sample shows how an <svgref> element can be used to reference an <svg> element that is the root element of its containing document:

<fig>
  <title>Figure with an SVG container</title>
  <svg-container>
    <svgref href="media/svg/svg-graphic-01.xml"/>
  </svg-container>
</fig>
The svg-graphic-01.xml file contains the following content. Note that the <svg> element sets the SVG namespace as the default namespace, so there are no namespace prefixes on the SVG markup.
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <defs>
    <filter id="f1" x="0" y="0">
      <feGaussianBlur in="SourceGraphic" stdDeviation="15"/>
    </filter>
  </defs>
  <rect width="90" height="90" stroke="green" stroke-width="3" fill="yellow" 
        filter="url(#f1)"/>
</svg>
Figure 2. Referencing a specific SVG within a document

The following code sample shows an <svgref> element can be used to reference a specific <svg> element in a containing XML file:

<fig>
  <title>Figure with SVG container</title>
  <svg-container>
    <svgref href="media/svg/svg-library.xml#frag-0001" />
  </svg-container>
</fig>
The svg-library.xml file contains the following content:
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <part>
    <svg id="frag-0001" xmlns="http://www.w3.org/2000/svg" width="100" height="100">
      <defs>
        <filter id="f1" x="0" y="0">
          <feGaussianBlur in="SourceGraphic" stdDeviation="15"/>
        </filter>
      </defs>
      <rect width="90" height="90" stroke="green" stroke-width="3" fill="yellow" 
            filter="url(#f1)"/>
    </svg>
    <!-- ... -->
  </part>
</root>