Requirements and Use Cases for Referenced Parameter Variables in SVG

Often, users may wish to create a single resource, and reuse it several times with specified variations. This is is currently possible by the use of script access to URL parameters or the <param> element in the HTML <object> element, but this approach has several drawbacks:

script may be disabled in the browser, making the reused resource unusable
authors must understand how to use the script
script increases the file size
script may introduce security issues (though none are currently known in this scenario)
no easy-to-use and consistent fallback/default values can be specified without modifying the script (requiring knowledge of the functioning of the script)

For this reason, this document examines some of the requirements and use cases involved in this issue, and proposes a solution for a declarative extension to SVG to fulfill these requirements. (Note: This issue is orthogonal to the CSS Variables proposal.)

For the sake of simplicity in this document, referenced parameter variables will be called variables in the general case, or <ref> elements in the specific case of a proposed solution.

Requirements

variables must be allowed as text content or attribute values for any attribute (and possibly properties, if the CSS WG agrees)
variables must be able to get their values from URL parameters, or from mechanisms such as the <param> element in the HTML <object> element
must be smooth, consistent, and clear inheritance when used through other mechanisms, such as stylesheets
it must be possible for an author to specify a default value for a variable
variable references with no matching parameter and no specified default value will be treated as if they have the default or lacuna value
must share common functionality and syntax for both declarative and scripted solutions
must not require, but may permit, the use of script
existing parameter keywords, such as those defined in WICD, must not be overridable (requires a registry?)

Use Cases

reuse of common graphical assets with small variations, such as buttons or other controls
input of arbitrary data into graphical visualizations, such as charts or graphs
easy skinning to match themes or colors of a site
simple distributed content creation, separation of designer and developer duties

Edge Cases and Tests

when <param> names or values are changed, the SVG document must be updated
when new <param> elements are added to the <object>, the SVG document must be updated
when new <ref> elements or references to it are added to the SVG document, the rendering must be updated (where applicable)
when the attribute value is changed by script, to or from a reference, the rendering must reflect the new value
when the attribute value using a reference is animated, the base value must be the reference value

Proposals

<ref> Element

One proposed solution is to specify a new SVG element, the <ref> element, which acts in a roughly similar way to a reference entity. This element would have a 'param' attribute which matches the parameter name, a 'default' attribute which provides a default value, and which is referenced by its 'id' attribute like any paint server. This differs from a paint server in that it can also be used to provide text content for a <tref> element, and attribute values for all attributes, not just presentation properties.

Advantages

gives a single source for all references throughout document
consistent with all value types

Disadvantages

creates content that is not backwards compatible
requires new parser for attribute values

<ref> Element Syntax

HTML:

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

SVG:

    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
         viewBox="0 0 100 100" width="100%" height="100%">

       <title>Reusable Button</title>
       <desc>Takes parameters from parent document's embedding element.</desc>

       <defs id="defs-1">
         <ref id="paramRound" param="corners" default="15"/>
         <ref id="paramFill" param="color" default="blue"/>
         <ref id="paramText" param="text-label" default="button"/>
         <ref id="paramStroke" param="outline" default="navy"/>
       </defs>

       <g>
          <rect id="button_rect" x="5" y="5" width="100" height="30" rx="url(#paramRound)" ry="url(#paramRound)" 
                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>

'param()' Attribute Value for Animation Elements

Another proposed solution is to specify a new attribute value for declarative animation elements, the 'param()' attribute value. This attribute value would take an argument which matches the parameter name. The default for the attribute in question would simply be specified in the attribute's initial value.

Advantages

backwards compatible content
uses (mostly) existing mechanisms
doesn't require new element, has shorter syntax
works when applied to imported content (separates behavior from appearance)

Disadvantages

still needs model for changing text values
more verbose
changes animated value, not DOM value

'param()' Attribute Value Syntax

HTML:

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

SVG:

    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
         viewBox="0 0 100 100" width="100%" height="100%">

       <title>Reusable Button</title>
       <desc>Takes parameters from parent document's embedding element.</desc>

       <defs id="defs-1">
         <set xlink:href="#button_rect" attributeName="fill" to="param(color)" begin="0s" fill="freeze" />
         <set xlink:href="#button_rect" attributeName="stroke" to="param(outline)" begin="0s" fill="freeze" />
         <set xlink:href="#button_rect" attributeName="rx" to="param(corners)" begin="0s" fill="freeze" />
         <set xlink:href="#button_rect" attributeName="ry" to="param(corners)" begin="0s" fill="freeze" />
         <set xlink:href="#button_label" attributeName="???" to="param(text-label)" begin="0s" fill="freeze" />
       </defs>

       <g>
          <rect id="button_rect" x="5" y="5" width="100" height="30" rx="15" ry="15" 
                fill="blue" stroke="navy" />
          <text id="button_label" x="55" y="30" text-anchor="middle" 
                font-size="25" fill="black" font-family="Verdana"> </text>
       </g>

    </svg>

Open Questions

Comments and questions may be sent to schepers@w3.org. Some open questions and details are:

could this be used with the <use> element to provide parameters to inline-document resources? (note that this may be combined with the 'buffered-rendering' property, and could dictate whether the reference is allowed?)
what are the performance costs? this seems to be on par with any referenced paint server, perhaps slightly more of a hit
what are the implementation ramifications? prototyping in script seemed to indicate it would be easy
if conflicting parameters are specified, whether through the same mechanism or different mechanisms, a consistent way of resolving these must be defined in the spec