5.1. Defining an SVG document fragment: the ‘svg’ element
5.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
HTML or 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:
‘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 SVG viewport. (See
Establishing a new
SVG viewport.)
5.1.2. Namespace
When SVG is parsed as a XML, for compliance with the
Namespaces in XML Recommendation
[xml-names], an SVG namespace
declaration must be provided so that all SVG elements are identified
as belonging to the SVG namespace.
When using the HTML syntax, the namespace is provided automatically by the HTML parser.
As the example shows there's no need to have an ‘xmlns’
attribute declaring that the element is in the SVG namespace when using the HTML parser.
The HTML parser will automatically create the SVG elements in the proper namespace.
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.
The SVG 2 namespace is http://www.w3.org/2000/svg,
which is the same as for earlier versions of SVG.
The following are possible ways to
provide a namespace declaration when SVG is parsed as XML. 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:
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:
Namespace prefixes can be specified on ancestor elements (illustrated
in the above example). For more
information, refer to the Namespaces in XML Recommendation
[xml-names].
5.1.3. Definitions
structural element
The structural elements are those which define the primary
structure of an SVG document. Specifically, the following
elements are structural elements:
‘defs’, ‘g’, ‘svg’, ‘symbol’ and ‘use’.
structurally external element
Elements that define its structure by reference to an external resource.
Specifically, the following elements are structurally external elements when
they have an ‘href’ attribute:
‘foreignObject’, ‘image’, ‘script’ and ‘use’.
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.
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.
However, an ‘svg’ element that is a direct child of another SVG-namespaced element
is not the root of an SVG document fragment.
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.
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.
In either case, a computed style of auto
is treated equivalent to 100%.
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 SVG viewport.
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 viewport using 'rect' element -->
<rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm"
fill="none" stroke="blue" stroke-width=".02cm"/>
</svg>
5.3. Defining content for reuse, and the ‘defs’ element
5.3.1. Overview
SVG allows a graphical object to be defined for later reuse.
To do this, SVG makes extensive use of the URL reference
construct [rfc3987].
For example, to fill a rectangle with a linear gradient, a
‘linearGradient’ element may be defined with an
‘id’ property that may be referenced in the value for
the rectangle's fill property, as in the following:
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, where possible, referenced elements be defined
prior to the elements that use them, in document order.
Collecting all referenced elements
inside of a single ‘defs’ element
near the top of the file
can make the markup easier to read and understand.
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;
the display value for the ‘defs’ element
must always be set to none
by the user agent style sheet,
and this declaration must have importance over any other CSS rule or presentation attribute.
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 does not
prevent those elements from being referenced by other elements.
5.4. The ‘symbol’ element
The ‘symbol’ element is used to define graphical templates
which can be instantiated by a ‘use’ element but which are not rendered
directly.
A ‘symbol’ establishes a nested coordinate system
for the graphics it contains.
When a symbol is instantiated
as the referenced element of a ‘use’ element,
it is therefore rendered very similarly to a nested ‘svg’ element.
