<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.

The following attributes are available on this element: universal attributes and the attributes defined below.

@encoding (inclusion attributes)
Specifies the character encoding to use when translating the character data from the referenced content. The value should be a valid encoding name. If not specified, processors may make attempts to automatically determine the correct encoding, for example using HTTP headers, through analysis of the binary structure of the referenced data, or the <?xml?> processing instruction when including XML as text. The resource should be treated as UTF-8 if no other encoding information can be determined.

When parse="xml", standard XML parsing rules apply for the detection of character encoding. The necessity and uses of @encoding for non-standard values of @parse are implementation-dependent.

@format (link-relationship attributes)
Specifies the format of the resource that is referenced. See STUB CONTENT for detailed information on supported values and processing implications.
The @format attribute has a default value of svg.
@href (link-relationship attributes)
Specifies a reference to a resource. See STUB CONTENT for detailed information on supported values and processing implications.
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.
@keyref
Specifies a key name that acts as a redirectable reference based on a key definition within a map. See STUB CONTENT for information on using this attribute.

For HDITA, the equivalent of @keyref is @data-keyref

@parse (inclusion attributes)
Specifies the processing expectations for the referenced resource. Processors must support the following values:
text

The contents should be treated as plain text. Reserved XML characters should be displayed, and not interpreted as XML markup.

xml

The contents of the referenced resource should be treated as an XML document, and the referenced element should be inserted at the location of the <include> element. If a fragment identifier is included in the address of the content, processors must select the element with the specified ID. If no fragment identifier is included, the root element of the referenced XML document is selected. Any grammar processing should be performed during resolution, such that default attribute values are explicitly populated. Prolog content must be discarded.

It is an error to use parse="xml" anywhere other than within <foreign> or a specialization thereof.

Processors may support other values for the @parse attribute with proprietary processing semantics. Processors should issue warnings and use <fallback> when they encounter unsupported @parse values. Non-standard @parse instructions should be expressed as URIs.

Note (non-normative):
Proprietary @parse values will likely limit the portability and interoperability of DITA content, so should be used with care.
The @parse attribute has a default value of xml.
@scope (link-relationship attributes)
Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See STUB CONTENT for detailed information on supported values and processing implications.

@type (link-relationship attributes)
Describes the target of a reference. See STUB CONTENT for detailed information on supported values and processing implications.

Examples

This section is non-normative.

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

Example 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>
Example 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>