SVG Parameters 1.0, Part 1: Primer
W3C
- This version:
- Latest version:
- Previous version:
- Editors:
- Doug Schepers, W3C <schepers@w3.org>
- Authors:
- The authors of this specification are the participants of the W3C SVG Working Group.
The SVG Parameters specification is an SVG 2.0 Module to provide a declarative way to incorporate parameter values into SVG content. Often, users may wish to create a single resource, and reuse it several times with specified variations, and this specification provides a means to do so without the use of script.
Although originally designed for use in SVG, some aspects of this specification are defined in XML and are accessed via presentation properties, and therefore could be used in other environments, such as HTML styled with CSS and XSL:FO.
This document introduces the features used by SVG Parameters, for the use of the average developer or author.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the first public working draft of this specification. There is an accompanying SVG Parameters 1.0, Part 2: Language specification that defines the features of SVG Parameters described in this specification.
We explicitly invite comments on this specification. Please send them to www-svg@w3.org (archives), the public email list for issues related to vector graphics on the Web. Acceptance of the archiving policy is requested automatically upon first post to either list. To subscribe to this list, please send an email to www-svg-request@w3.org with the word subscribe in the subject line.
This document has been produced by the W3C SVG Working Group as part of the W3C Graphics Activity within the Interaction Domain.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The latest information regarding patent disclosures related to this document is available on the Web. As of this publication, the SVG Working Group are not aware of any royalty-bearing patents they believe to be essential to SVG.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This is a primer for the SVG Parameters specification. It gives guidelines on how to use the SVG Parameters specification with SVG 1.2. In many cases the reader will have to be familiar with the SVG language.
The main purpose of this document is to encourage public feedback. The best way to give feedback is by sending an email to www-svg@w3.org. Please include in the subject line of your message the string "[Params Primer]", and a short keyword that identifies the area of the specification the comment is referring to (e.g "[Params Primer] Section X.Y - Foo attribute values"). If you have comments on multiple areas of this document, then it is probably best to split those comments into multiple messages.
The public are welcome to comment on any aspect in this document, but there are a few areas in which the SVG Working Group are explicitly requesting feedback. These areas are noted in place within this document.
This document is informative.
This specification describes some of the common uses cases for declarative parameters in SVG, and how to use them features defined in the SVG Parameters 1.0, Part 2: Language specification.
It is possible to provide parameters to standalone files or files referenced through another document. Often, it is useful to allow parameter values to be used directly in the content of the SVG file, without the need for script. These parameters may be provided to the document context through a variety of means, including, but not limited to, URL query strings or the <param> element in the HTML <object> element.
Access to these parameters is currently possible by the use of script, but this does not work in scenarios where script is undesirable or unavailable.
Using the <object> element, you can pass parameters by the use of child <param> elements. Each <param> element should have name/value pairs with the 'name' and 'value' attributes; these will be exposed to the embedded SVG document.
HTML:
<object type="image/svg+xml" data="button.svg">
<param name="param1" value="value1" />
<param name="param2" value="value2" />
</object>
With the <object>, <iframe>, <embed>, and <img> elements, you can pass parameters via the URL. The URL query syntax allows you to pass sets of name/value pairs separated by an ampersand (&); as with object params, these will be exposed to the embedded SVG document.
HTML:
<object type="image/svg+xml" data="button.svg?param1=value1¶m2=value2">
</object>
The SVG Parameters 1.0, Part 2: Language specification adds a new functional attribute value, the 'param()' function. This attribute takes a string as as a value, which matches the name part of a parameter name-value pair that's been passed into the document.
To provide a default value for the attribute for the case where no parameters are passed into the document, the author can simply give an attribute value after the 'param()' function, like this:
attributename="param(parameter-name) default-value"
fill="param(color) red"
The specification also introduces the <param> element into SVG. As with HTML, this element has two attributes, 'name' and 'value', and it passes these parameters to referenced content (such as from a <use> or <image> element), like so:
<param name="parameter-name" value="parameter-value" />
<param name="color" value="blue" />
The usage of the 'param()' function is outlined in this section.
The various values in the code examples are color-coded as follows:
HTML:
<object type="image/svg+xml" data="button.svg">
<param name="color" value="red" />
<param name="label" value="stop" />
</object>
SVG:
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 110 40" width="100%" height="100%">
<title>Reusable Button</title>
<desc>Takes parameters from parent document's embedding element.</desc>
<g>
<rect id="button_rect" x="5" y="5" width="100" height="30" rx="15" ry="15"
fill="param(color) blue" stroke="param(outline) navy" />
<text id="button_label" x="55" y="30" text-anchor="middle"
font-size="25" fill="black" font-family="Verdana"
content-value="param(label)">
button
</text>
</g>
</svg>
The following examples demonstrate how this work in practice, by use of a prototyping script, param.js. Obviously, this wouldn't be needed in a working native implementation.
Note that these examples are emulated by a Javascript prototype. It should work in Opera, Firefox, and Safari, and maybe others (Chrome? Plugins?). The script may be used as is, and is released under a CC license, but it is not intended as production code. Content authors are encouraged to experiment with this code, and to comment to the SVG WG at www-svg@w3.org with suggestions and critiques of the specification based on experience.
<object type="image/svg+xml" data="button.svg">
</object>
<object type="image/svg+xml" data="button.svg">
<param name="color" value="red" />
<param name="label" value="stop" />
</object>
<object type="image/svg+xml" data="button.svg?color=cornflowerblue&label=fnord">
</object>
<object type="image/svg+xml" data="button.svg?color=cornflowerblue&label=fnord">
<param name="color" value="purple" />
<param name="label" value="override" />
</object>
<object type="image/svg+xml" data="map.svg">
<param name="x" value="255" />
<param name="y" value="172" />
</object>
<object type="image/svg+xml" data="map.svg?y=167&x=655">
</object>
<circle id="coord" cx="param(x)" cy="param(y)" r="5" fill="tan" stroke="brown" stroke-width="3" />
<object type="image/svg+xml" data="ad.svg">
<param name="buylink" value="http://example.com/shop" />
</object>
<object type="image/svg+xml" data="ad.svg?buylink=http%3A%2F%2Fexample.com%2Fbargains">
</object>
<a xlink:href="param(buylink)" target="_new">...</>
This example shows the use of the param element with the use element, to pass on multiple values to a referenced graphic, to customize several aspects of it at once. If no parameters are passed along, the flower will simply be colored with shades of white, black, and gray; with parameters, different parts of the flower can be given different colors for stroke and fill.
<defs>
<g id="flower">
<radialGradient id="petals" cx="220" cy="250" gradientUnits="userSpaceOnUse">
<stop offset="0%" stop-color="param(petal1) white" />
<stop offset="50%" stop-color="param(petal2) gray" />
</radialGradient>
<path fill="param(base) black" d="..."/>
<path fill="param(heart) darkgray" stroke="param(petal2)" stroke-width="2" d="..."/>
<path fill="url(#petals)" d="..."/>
<path fill="url(#petals)" d="..."/>
<path fill="url(#petals)" d="..."/>
<path fill="url(#petals)" d="..."/>
<path fill="url(#petals)" d="..."/>
</g>
</defs>
<use id="use_0" xlink:href="#flower"/>
<use id="use_1" xlink:href="#flower" x="330" y="170" transform="scale(1.3)" >
<param name="base" value="brown" />
<param name="petal1" value="navy" />
<param name="petal2" value="ghostwhite" />
<param name="heart" value="pink" />
</use>
<use id="use_2" xlink:href="#flower" x="300" y="0">
<param name="base" value="cornflowerblue" />
<param name="petal1" value="white" />
<param name="petal2" value="blue" />
<param name="heart" value="darkslateblue" />
</use>
<use id="use_3" xlink:href="#flower" x="490" y="100">
<param name="base" value="gold" />
<param name="petal1" value="yellow" />
<param name="petal2" value="red" />
<param name="heart" value="darkorange" />
</use>
<use id="use_4" xlink:href="#flower" x="530" y="10" transform="scale(0.6)" >
<param name="base" value="pink" />
<param name="petal1" value="magenta" />
<param name="petal2" value="purple" />
<param name="heart" value="lightpink" />
</use>
This example demonstrates the use of the 'param' attribute value with a complex reusable component, in this case a bar chart. The component author has created a chart with a set number of bars, one for each month, and set the labels and the bar height to the value of the parameter for each month. The content author using the component passes in the value for each month as a parameter, and the chart is presented accordingly. There are limitations to this approach, e.g. you cannot add new bars, and the range of values is limited, but for certain kinds of complex components, the 'param' attribute value can be very useful.
<object type="image/svg+xml" data="year-chart.svg" style="width:660px; height:320px; display:inline;">
<param name="jan" value="10"/>
<param name="feb" value="30"/>
<param name="mar" value="30"/>
<param name="apr" value="100"/>
<param name="may" value="80"/>
<param name="jun" value="20"/>
<param name="jul" value="55"/>
<param name="aug" value="71"/>
<param name="sep" value="6"/>
<param name="oct" value="89"/>
<param name="nov" value="45"/>
<param name="dec" value="8"/>
</object>
Parameters should be easy to use even in simple graphics for everyday users.