W3C

SVG Referenced Parameter Variables 1.0, Part 1: Primer

W3C Working Draft 30 April 2009

This version:
http://www.w3.org/TR/2009/WD-SVGParamPrimer-20090430/
Latest version:
http://www.w3.org/TR/SVGParamPrimer/
Editors:
Doug Schepers, W3C <schepers@w3.org>
Authors:
The authors of this specification are the participants of the W3C SVG Working Group.

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. 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 Referenced Parameter Variables 1.0, Part 2: Language specification that defines the features of SVG Referenced Parameter Variables 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.


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

Table of Contents

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

2 Passing Values to SVG Files

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

2.2 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:


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

2.3 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:

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>

2.4 Examples

These examples show how this proposal would work in practice, by use of a prototyping script, ref.js. Obviously, this wouldn't be needed in a working native implementation.

Note that the text parameter aspects of these examples don't quite work in Firefox, since it doesn't support the <tref> element as of the date of this publication. They could be made to work with only a little extra script, by directly inserting the text strings into the relevant text element, but the whole point is that it makes use of SVG's IDREF architecture. All other aspects should work in Opera, Firefox, and Safari, and maybe others (Chrome? Plugins?).

These examples will be updated for the next draft, to use the 'param()' syntax.

2.4.1 No Parameters


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

2.4.2 Object Parameters


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

2.4.3 URL Parameters


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

2.4.4 URL and Object Parameters


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

2.4.5 Parameterizing Position


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

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

2.4.7 Fallback Values

This example will be provided soon.

3 References

[Param]
SVG Referenced Parameter Variables 1.0, Part 2: Language , D. Schepers, editor. World Wide Web Consortium, work in progress, 30 April 2009.
This edition of SVG Referenced Parameter Variables 1.0, Part 1: is http://www.w3.org/TR/2009/WD-SVGParam-20090430/.
The latest edition of SVG Referenced Parameter Variables 1.0, Part 2: Language is available at http://www.w3.org/TR/SVGParam/.