SVG Referenced Parameter Variables 1.0, Part 1: Primer (2024)

Abstract

The Referenced Parameter Variables 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 Referenced Parameter Variables, for the use of the average developer or author.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document is the first public working draft of this specification. There is an accompanying SVG Referenced Parameter Variables 1.0, Part 2: Language specification that defines the features of SVG Referenced Parameter Variables described in this specification.

This document has been produced by the W3C SVG Working Group as part of the W3C Graphics Activity within the Interaction Domain.

We explicitly invite comments on this specification. Please send them to [email protected] (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 [email protected] with the word subscribe in the subject line.

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 of this document does not imply endorsem*nt by the W3C membership. A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite a W3C Working Draft as anything other than a work in progress.

How to read this document and give feedback

This is a primer for the SVG Referenced Parameter Variables specification. It gives guidelines on how to use the SVG Referenced Parameter Variables 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 [email protected]. 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.

Table of Contents

Referenced Parameter Variables in SVG

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 Referenced Parameter Variables 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.

Note that even though this specification references parts of SVG 1.1 and SVG Tiny 1.2, it does not require a complete implementation of those specifications.

Passing Values to SVG Files

Passing Values via object param

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

HTML:

 <object type="image/svg+xml" data="button.svg"> <param name="param1" value="value1" /> <param name="param2" value="value2" /> </object>

SVG Javascript:

 // get param elements from referencing object element var params = document.defaultView.frameElement.getElementsByTagName("param"); // get attribute values of param @name and @value ... // find elements that need to be changed, then set values to to param @value ...

Passing Values via URL Parameters

With the <object>, <iframe>, and <embed> 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 via script.

HTML:

 <object type="image/svg+xml" data="button.svg?param1=value1&param2=value2"> </object>

SVG Javascript:

<![CDATA[ // get param elements from referencing object element var params = document.defaultView.location.href.split("?")[1].split("&"); // split name/value pairs ... // find elements that need to be changed, then set values to to parameter value ...]]>

Syntax

The SVG Referenced Parameter Variables 1.0, Part 2: Language specification adds a new element, the <ref> element. This has two main attributes, 'param' (for matching incoming parameters from either the <param> element or URL query string), 'default' (an optional value for setting a default value if there is no parameter provided), and 'id' (for referencing with an IDREF attribute like 'xlink:href' or the 'url(#foo)' syntax). Additionally, the element has child element content, which acts as the default value if there is no matching parameter provided. This element acts much as the various paint servers in SVG (<linearGradient>, <radialGradient>, <solidColor>, etc.), in that it can be referenced to provide a value to an element's attribute. It also serves as the target for a <tref> reference, for text values.

The various values in the code examples are color-coded as follows:

• parameter name
• parameter value
• default value
• id and idref
• (value which is used is outlined)

HTML:

 <object type="image/svg+xml" data="button.svg"> <param name="color" value="red" /> <param name="text-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> <defs> <ref id="paramFill" param="color" default="blue"/> <ref id="paramText" param="text-label">button</ref> <ref id="paramStroke" param="outline" default="navy"/> </defs> <g> <rect id="button_rect" x="5" y="5" width="100" height="30" rx="15" ry="15" fill="url(#paramFill)" stroke="url(#paramStroke)" /> <text id="button_label" x="55" y="30" text-anchor="middle" font-size="25" fill="black" font-family="Verdana"> <tref xlink:href="#paramText" /> </text> </g> </svg>

 <object type="image/svg+xml" data="button.svg"> </object>

 <object type="image/svg+xml" data="button.svg"> <param name="color" value="red" /> <param name="text-label" value="stop" /> </object>

 <object type="image/svg+xml" data="button.svg?color=cornflowerblue&text-label=fnord"> </object>

 <object type="image/svg+xml" data="button.svg?color=cornflowerblue&text-label=fnord"> <param name="color" value="purple" /> <param name="text-label" value="override" /> </object>

 <object type="image/svg+xml" data="map.svg"> <param name="x" value="125" /> <param name="y" value="108" /> </object> <object type="image/svg+xml" data="map.svg?y=103&x=523"> </object>

 <ref id="paramX" param="x" default="-10"/> <ref id="paramY" param="y" default="-10"/> <circle id="coord" cx="url(#paramX)" cy="url(#paramY)" 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>

 <ref id="targetURL" param="buylink" default="/"/> <a xlink:href="url(#targetURL)" target="_new">...</>

References

[SVGRefs]

SVG Referenced Parameter Variables 1.0, Part 2: Language, D. Schepers, editor. W3C, 23 April 2009 (Editor's Draft). See http://dev.w3.org/SVG/modules/ref/SVGRef.html