Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 defines the markup and interfaces used by SVG Referenced Parameter Variables.
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 1: Primer that lists the ways SVG Referenced Parameter Variables may be used.
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 draft of SVG Referenced Parameter Variables introduces new Referenced Parameter Variables syntax and markup for the SVG language. One of the goals is that this specification can be re-used more easily by other specifications that want to have advanced Referenced Parameter Variables features. This specification introduces syntax that may not be backwards compatible with older SVG User Agents, and the use of this syntax should be accompanied by a fallback using the 'switch' element.
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]", and a short keyword that identifies the area of the specification the comment is referring to (e.g "[Params] 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 specification describes a declarative syntax and associated interfaces 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. Further, there is no general way to set and access all parameter inputs into the file, which may come from multiple sources.
To address this, this specification defines an interface to provide a generic and secure means of passing parameters into a referenced file. This interface is intended to be implemented on all objects that implement the Window interface.
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.
This document is normative.
This document contains explicit conformance criteria that overlap with some RNG definitions in requirements. If there is any conflict between the two, the explicit conformance criteria are the definitive reference.
The following usage scenarios illustrate some of the ways in which SVG Referenced Parameter Variabless might be used for various applications.
Color values can be passed into a graphic to match other aspects of the document. Note that in some scenarios, this can also be done via CSS.
In addition to making the whole image scalable by changing the ‘viewBox’, values can be passed in to change the size or position of particular elements as needed. For example, a dot on a map could be changed by merely passing in a parameter.
Particular elements of the image can be hidden or revealed based on parameters. Note that in some scenarios, this can also be done via CSS.
Labels on buttons or other reusable controls can be changed simply by setting the desired text as a parameter.
By passing in a URL as a parameter, links inside the SVG document can be changed, for ads or other purposes.
Reuse: User Agents may fetch resources multiple times when the query string is different, once for each unique URL. This undermines some of the benefit of reusing resources: it does not take advantage of local caching, it increases the overall bandwidth, and it may introduce delay in slow or high-latency networks. Providing parameters through other means, such as the 'param's element, does not have the same drawback.
Memory and processor requirements: What are the requirements on memory or processing resources?
Implementation commitments: How difficult, or what details are needed, for implementation?
Ease of authoring: What considerations need to be borne in mind for authors?
This chapter defines a number of common data types used in the definitions of SVG properties and attributes.
A host language is a syntax which incorporates one or more SVG document fragments by inclusion or by reference, and which defines the interactions between document fragments; an example of this is WICD Core 1.0, an XML framework which defines how XHTML, SVG, MathML, XForms, SMIL, and other syntaxes interact.
A value is in error if it is specifically stated as being "in error" or "an error" in the prose of this specification. See C.3 Error processing in SVG Tiny 1.2 for more detail on handling errors.
An invalid IRI reference is an IRI reference that is syntactically invalid, cannot be resolved to a resource or takes a form that is not allowed for a given attribute, as defined in SVG Tiny 1.2 14.1.4 Reference restrictions.
An IRI reference is an Internationalized Resource Identifier with an optional fragment identifier, as defined in Internationalized Resource Identifiers [RFC3987]. An IRI reference serves as a reference to a resource or (with a fragment identifier) to a secondary resource. See References in SVG Tiny 1.2 [SVGT12].
A local IRI reference is an IRI reference that references a fragment within the same resource.
A non-local IRI reference is an IRI reference that references a different document or an element within a different document.
The rootmost ‘svg’ element is the furthest ‘svg’ ancestor element that does not exit an SVG context. See also SVG document fragment.
An SVG context is a document fragment where all elements within the fragment must be subject to processing by an SVG user agent according to the rules in this specification.
If SVG content is embedded inline within parent XML (such as XHTML), the SVG context does not include the ancestors above the rootmost 'svg' element. If the SVG content contains any ‘foreignObject’ elements which in turn contain non-SVG content, the SVG context does not include the contents of the ‘foreignObject’ elements.
An SVG document fragment is the XML document sub-tree whose rootmost element is an ‘svg’ element (that is, the rootmost 'svg' element.)
An SVG document fragment consists of either a stand-alone SVG document, or a fragment of a parent XML document where the fragment is enclosed by the rootmost 'svg' element.
An SVG user agent is a user agent that is able to retrieve and render SVG content.
An unsupported value is a value that does not conform to this specification, but is not specifically listed as being in error.
The general definition of a user agent is an application that retrieves and renders Web content, including text, graphics, sounds, video, images, and other content types. A user agent may require additional user agents that handle some types of content. For instance, a browser may run a separate program or plug-in to render sound or video. User agents include graphical desktop browsers, multimedia players, text browsers, voice browsers; used alone or in conjunction with assistive technologies such as screen readers, screen magnifiers, speech synthesizers, onscreen keyboards, and voice input software [UAAG].
A user agent may or may not have the ability to retrieve and render SVG content; however, an SVG user agent must be able to retrieve and render SVG content.
This section proposes two alternate mechanisms (and associated syntaxes) which the SVG WG is evaluating. Feedback on preferences is encouraged and welcome. While the two mechanisms are not necessarily mutually exclusive, the SVG WG is likely to settle on one, for sake of simplicity. The first mechanism uses only the ‘param’ functional attribute value, while the second proposes a ‘ref’ element which would serve as an referent for a <FuncIRI> attribute value.
The ‘param’ attribute value is a is a functional notation value (like a <FuncIRI>), which must take a string as a parameter a string with Name Token production (i.e., the same syntax as allowed in a query string parameter name). This string parameter must be evaluated to match, in a case-sensitive manner, the the 'name' portion of the name-value parameter pair passed into the document and exposed through the Parameters interface. If this parameter value does match a parameter name, it must return a string which shall be the corresponding 'value' portion of the matching name-value parameter pair, which shall serve as the attribute value of the attribute. If this parameter value does not match a parameter name, or if this parameter value is not a Name Token, the he ‘param’ attribute value function must return an empty string (""), and the value of the attribute shall be the attribute's fallback value, or if there is no fallback value provided, the value of the attribute shall be the attribute's lacuna value.
‘param’ attribute value parameters which do not match any 'name' portions of a parameter must not raise any errors, and it must not constitute an unresolved reference. Error-handling must not be applied because of a missing parameter.
‘param’ attribute values must be evaluated immediately upon the loading of the file, or whenever the parameter information becomes available. If the parameter information changes, all ‘param’ attribute values must be updated to reflect the new values, and any rendering changes must be applied. If the parameter information changes, and a the new information does not contain a name that was previously matched by the ‘param’ attribute values parameter, then the affected attribute value must be processed as described above.
For user agents which conform to this specification, the ‘param’ attribute value must be available as a value on any SVG attribute. For attributes which take a list as a value, each ‘param’ attribute value used shall constitute a separate value on that list. For attributes which do not take a list as a value, the following syntax must be applied to attribute values which use a ‘param’ attribute value:
attribute-name="param(string) [optional-string]"
where the optional string is a fallback value that would otherwise be a permitted value for that attribute.
Every ‘ref’ element has an associated value, which is determined based on the ‘param’ attribute and the set of name-value parameter pairs that are available for reference.
The ‘ref’ element shall act as both a paint server and a source of character data content for a referencing element, such as a ‘tref’ element. When acting as a paint server, the child character data content shall be treated as the value (as text) of the ‘ref’ element; this is unlike other paint servers, which provide the value of the paint as an attribute value, the ‘ref’ element. When acting as a source for a text reference, the value shall be the child character data content, as normal.
The value of the ‘ref’ element shall be derived from the value of the name-value pair whose name matches the value of the ‘param’ attribute, as accessed through the Parameters interface, and this value must replace any existing child character data content immediately upon the loading of the file, or whenever the parameter information becomes available. If the parameter information changes, all ‘ref’ elements and any referencing content must be updated to reflect the new values. If no parameter name exists that matches the value of the ‘param’ attribute, then the existing child character data content shall be the value of the ‘ref’ element. If the parameter information changes, and a the new information does not contain a name that was previously matched by the value of the ‘param’ attribute, then the existing child character data content shall reflect the existing content; it must not change back to the original child character data content. If the ‘ref’ element is an empty element, the lacuna value shall be an empty string.
The ‘ref’ element can also act as a mechanism to pass parameters to externally referenced resources, in a manner similar to the HTML ‘param’ element of the HTML ‘object’ element [HTML4]. In this case, the ‘param’ attribute must act as the 'name' portion of the name-value pair, and the child character data content must act as the 'value' portion of the name-value pair.
Attribute definitions:
The ‘id’ attribute is the method by which attributes on other elements must reference this ‘ref’ element.
Animatable: yes.
The ‘param’ attribute must be a string that matches, in a case-sensitive manner, the 'name' portion of the name-value pair of the desired parameter.
Animatable: yes.
The ‘ref’ element shall be referenced in two ways:
In previous SVG specifications, only presentation attribute such as ‘stroke’, ‘fill’, or ‘filter’ could reference values via the <FuncIRI> syntax. This specification extends earlier attribute definitions to allow any attribute to reference content using a <FuncIRI>. The fragment identifier of the <FuncIRI> provides a link to the ‘ref’ element that shall be used to paint or provide the value for the current element. SVG user agents are only required to support local IRI references. If the IRI reference is invalid (for example, it points to an object that doesn't exist or the object is not a valid paint server or it is a non-local IRI reference and the viewer does not support it), then the fallback value (if specified) is used; otherwise it must be treated as if none was specified.
The following interfaces are defined below, using WebIDL [WebIDL]: Parameters.
The Parameters interface provides a unified API to access all parameters that have been passed into a file as name-value pairs, by whatever means, and independent of whether the file is a standalone resource or is embedded into another document by reference. The user agent must make all of these parameters which have been set at the load time of the target file immediately available, and must also update the list of parameters immediately within the file when they are changed in the referencing file, or in the URL query string.
Ordering of the parameters should follow document-order, in the case of HTML ‘param’ elements, SVG ‘ref’ elements, or similar constructs, and string-order in the case of URL query strings. In the case where duplicate names are provided that match in a case-sensitive manner, the corresponding later values must overwrite the corresponding earlier values, and values from the URL query string must be processed last, to overwrite all other values.
The Parameters interface must only handle name-value parameter sets which are string values. For parameters that are passed in via the HTML ‘param’ element, the user agent must add to this list only values which have the ‘valuetype’ of 'data'.
Objects that implement the defaultView or Window interfaces must also implement the WindowParameters interface:
interface WindowParameters {
readonly Parameters parameters;
};
interface Parameters {
readonly attribute unsigned long length;
[IndexGetter] DOMString name (in unsigned long index);
[NameGetter] DOMString getValue (in DOMString name);
};
0 and upper bound shall be n-1, where n is the number of name-value parameter sets. If there are no supported indexed properties, then length shall be 0.n.
in unsigned long index:
|
The index of the name, where the first item in the list must have an index of 0.
|
| DOMString: | The name at the indicated index in the list. |
| DOMException: |
INDEX_SIZE_ERR: Raised if the
index is
negative or is greater than or equal to the number of entries in the list.
|
Parameters object are the keys of each name-value pair
currently present in the list associated with the object, as derived from the parameters.
| DOMString: | The value associated with the given name, as provided in the parameters to this document. If no match for the given string is found, or no parameter is provided, the return value must be null. |
This interface is read-only. Should there be a read-write interface available to the referencing document, to allow easy script access to parameters, so they can be changes without modifying the URL query string or creating 'param' elements?
Does allowing the author of the referencing document to override parameters defined in the URL strings constitute a security or propriety risk? What if a site serves a customized resource based on a URL string, and that is overridden at the param or script layer, so that what is served (think of an ad) is not what what intended by the SVG's content provider. Changing the URL in this case would let the content provider know, while changing the 'param's or modifying the parameters list through script would not. Is this a legitimate concern?
Should we expose where the parameter came from, in terms of URL query string, 'param' element, or other? Should we expose the domain of the document where the parameter was set?
The schema for SVG Referenced Parameter Variables 1.0 is written in RelaxNG [RelaxNG], a namespace-aware schema language that uses the datatypes from XML Schema Part 2 [Schema2]. This allows namespaces and modularity to be much more naturally expressed than using DTD syntax. The RelaxNG schema for SVG Filter 1.2 may be imported by other RelaxNG schemas, or combined with other schemas in other languages into a multi-namespace, multi-grammar schema using Namespace-based Validation Dispatching Language [NVDL].
Unlike a DTD, the schema used for validation is not hardcoded into the document instance. There is no equivalent to the DOCTYPE declaration. Simply point your editor or other validation tool to the IRI of the schema (or your local cached copy, as you prefer).
The editors would like to acknowledge and thank the following people for substantive aid with this specification: Erik Dahlström, Cameron McCormack, Jeff Schiller.