An SVG "document" can range from a single SVG graphics element such as a rectangle to a complex, deeply nested collection of grouping and graphics elements. Also, an SVG document can be embedded inline as a fragment within a parent document (an expectedly common situation with an XML Web pages) or it can stand by itself as a self-contained graphics file.
The following example shows a simple one-line SVG document embedded as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the <rect> element belongs to the SVG namespace:
<?xml version="1.0"?>
<parent xmlns="..."
xmlns:SVG="http://www.w3.org/...SVG_1.0...">
<!-- ... -->
<SVG:rect ... />
<!-- ... -->
</parent>
This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:
<?xml version="1.0"?> <g xmlns="http://www.w3.org/...SVG_1.0..."> <rect ... /> <rect ... /> <rect ... /> <rect ... /> </g>
The <g> element is the general-purpose element for grouping and naming collections of drawing elements. A complete, stand-alone SVG drawing typically is bracketed between a <g> and a </g>. If several drawing elements share similar attributes, they can be collected together using a <g> element. For example:
...
<g>
<g fillcolor="red">
<rect x="100" y="100" width="100" height="100" />
<rect x="300" y="100" width="100" height="100" />
</g>
<g fillcolor="blue">
<rect x="100" y="300" width="100" height="100" />
<rect x="300" y="300" width="100" height="100" />
</g>
</g>
A group of drawing elements, as well as individual objects, can be given a name. Named groups are needed for several purposes such as animation and re-usable objects. The following example organizes the drawing elements into two groups and assigns a name to each group:
...
<g>
<g id="OBJECT1">
<rect x="100" y="100" width="100" height="100" />
</g>
<g id="OBJECT2">
<circle cx="150" cy="300" r="25" />
</g>
</g>
...
A <g> element can contain other <g> elements nested within it, to an arbitrary depth. Thus, the following is valid SVG:
<g>
<g>
<g>
<g>
</g>
</g>
</g>
</g>
Any drawing element that is not contained within a <g> is treated (at least conceptually) as if it were in its own group.
Every graphics element (???) in SVG can have a child <defs> element. One main purpose of the <defs> element is to provide a place for objects which are not meant to be drawn when they are defined, such as gradients, patterns, styles, scripts, template objects and private data. The following example shows how a undrawn rectangle and a gradient can be defined within a <defs> element so that they can be referenced later in the document:
<g>
<defs>
<rect id="TemplateObject01"... />
<gradient id="Gradient01" ... />
</defs>
<!-- SVG code in here would reference/use
the elements defined in the <defs> -->
</g>
A <style> element can appear as a subelement to any <defs> element. A <style> element is equivalent to the <style> element in HTML and thus can contain any valid CSS definitions. Any CSS definitions within any <style> element have a "global" scope across the entire current SVG document.
The following is an example of defining and using a text style:
<g>
<defs>
<style>
.TitleText { font-size: 16; font-family: Helvetica }
</style>
</defs>
<text class="TitleText">Here is my title</text>
</g>
A <script> element can appear as a subelement to any <defs> element. A <script> element is equivalent to the <script> element in HTML and thus is the place for scripts (e.g., ECMAScript). Any functions defined within any <script> element have a "global" scope across the entire current SVG document.
The following is an example of defining an ECMAScript function and defining an event handler that invokes that function:
<g>
<defs>
<script>
/* Beep on mouseclick */
MouseClickHandler() { beep(); }
</script>
</defs>
<rect onmouseclick="MouseClickHandler()".../>
</g>
Any <g> or graphics element defined within a <defs> and assigned an ID is potentially a template object that can be re-used (i.e., "instanced") anywhere in the SVG document.
The <use> element references a template object and indicates that the contents of that graphics object should be included/drawn at that given point in the document. The <use> element conforms to XLink [??? Include reference to XLink]. (Note that the XLink specification is currently under development and is subject to change. The SVG working group will track and rationalize with XLink as it evolves.)
In the example below, the first <g> element has inline content. After this comes a <use> element whose href value indicates which predefined graphics object should be included/rendered at that point in the document. Finally, the second <g> element has both inline and referenced content. In this case, the referenced content will draw first, followed by the inline content.
<g>
<defs>
<rect id="TemplateObject01"... />
</defs>
<!-- <g> with inline content -->
<g>
<!-- Inline content goes here -->
</g>
<!-- referenced content -->
<use xml:link="simple" show="embed" actuate="auto"
href="#TemplateObject01" />
<!-- <g> with both referenced and inline content -->
<g>
<use xml:link="simple" show="embed" actuate="auto"
href="#TemplateObject01" />
<!-- Inline content goes here -->
</g>
</g>
Any graphics attributes specified on a <use> element override the attributes specified on the template/referenced element. For example, if the stroke-width on the template object is 10 but the <use> specifies a stroke-width of 20, then the object will draw with a stroke-width of 20.
The <use> element does not do the equivalent of a macro expansion. The SVG Document Object Model (DOM) only contains a <use> element and its attributes.