SVG Parameters 1.0, Part 1: Primer

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.

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

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

1 SVG Parameters in SVG

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.

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.

2.2 Passing Values via URL Parameters

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.

2.3 Syntax

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:

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:

2.4 Examples

The usage of the ‘param()’ function is outlined in this section.

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

parameter name
parameter value
default value
(value which is used is outlined)

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.

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="label" value="stop" />
  </object>

2.4.3 URL Parameters

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

2.4.4 URL and Object Parameters

        
  <object type="image/svg+xml" data="button.svg?color=cornflowerblue&label=fnord">
    <param name="color" value="purple" />
    <param name="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>

      
  <circle id="coord" cx="param(x)" cy="param(y)" r="5" fill="tan" stroke="brown" stroke-width="3" />

2.4.6 Parameterizing Links

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

2.4.7 Setting Multiple Aspects of Reused Content

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>

2.4.8 Complex Reusable Components

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>