SVG Parameters 1.0, Part 2: Language
W3C
- This version:
-
- Latest version:
-
- Editors:
- Doug Schepers, W3C <schepers@w3.org>
- Authors:
- The authors of this specification are the participants of the W3C SVG Working Group.
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 defines the markup and interfaces used by SVG Parameters.
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 Parameters 1.0, Part 1: Primer that lists the ways SVG Parameters 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 Parameters introduces new SVG Parameters 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 SVG Parameters 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 Parameters 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.
By allowing parameters on the 'use' element, content that is referenced can be customized.
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.
A tree fragment that is not part of the DOM tree, but which is attached to a referencing element (e.g. 'use' element) in a non-parent-child relationship, for the purpose of rendering and event propagation. The shadow tree is composed as if it were deep-structure clone of the referenced element in the rendering tree. The shadow tree is kept in synchronization with the contents of the referenced element, so that any animation, DOM manipulation, or non-DOM interactive state occurring on the referenced element are also applied to all the referencing instances. In SVG Tiny 1.2, only a subset of all SVG DOM methods to access the shadow tree are available.
Also referred to as an "instance tree".
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.
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.
The 'content-value' attribute may be placed on any textual element, such as the 'text', 'tspan', or 'tref' elements, and takes as a value the ‘param’ attribute value. For any matching parameter name, the corresponding parameter value shall be placed into the DOM as the child of the textual element, replacing any existing child content.
Attribute definitions:
The 'content-value' attribute must must have as a value a ‘param’ attribute value. The matching name-value parameter pair's value shall replace the element's child content.
Animatable: yes.
The 'parameters' property shall acts as a mechanism to pass parameters to referenced resources, by means of a comma-separated list of name-value string pairs. Each name-value pair shall consist of a string representing the name, followed by a colon (":"), followed by a string representing the value. If either the name or value string contains spaces or punctuation marks, it must be enclosed in double or single quotes [note: define this better]. If this property value does not conform to this syntax, all name-value pairs after the first error must be discarded.
This property may be expressed as an attribute or as a CSS property in a class, style attribute, or other CSS mechanism. This property is inheritable and animatable.
The 'param' element shall acts as a mechanism to pass parameters to referenced resources, in a manner similar to the HTML 'param' element of the HTML 'object' element [HTML4].
Every 'param' element shall have a 'name' attribute and an 'value' attribute to represent both portions of a name-value pair, which shall be available to the referenced element. If a 'param' element does not have a value for either or both of the 'name' or 'value' attributes, the 'param' element shall not be passed to the referenced content.
The name-value parameter pair shall be passed to to the content referenced in the 'param' element's parent element. If the parent element does not reference any content, all child 'param' elements shall be ignored. Note that not all referenced content may have the ability to accept parameters, for instance if it does not have a DOM, as with a raster image. How non-SVG referenced content deals with parameters is outside the scope of this document.
Attribute definitions:
The 'name' attribute must be a string that represents, in a case-sensitive manner, the 'name' portion of the name-value pair. Note that the referenced language may or may not be case-sensitive.
Animatable: yes.
The 'value' attribute must be a string that represents, in a case-sensitive manner, the 'value' portion of the name-value pair. Note that the referenced language may or may not be case-sensitive.
Animatable: yes.
In SVG, there are several elements which reference content. This content may normally be either a local or external resources, and it may be SVG content or other types of content (e.g. a raster image or HTML document).
The following SVG elements may reference SVG replacement content, and must pass on parameters from child 'param' elements: 'animate', 'foreignObject', 'image', and 'use'. Other elements which reference content, such as 'audio', 'script', and 'video', may pass on parameters, but the result of such behavior is not defined in this specification.
In the case of the 'use' element, the element may have child 'param' elements, and these name-value parameter pairs must be passed on to the referenced content. The 'use' element's shadow tree must implement the Parameters and WindowParameters interfaces. These instances of the interfaces must be scoped to the shadow tree, and must not apply to content outside the shadow tree, including even the referenced document fragment. In the case of local references, if the document has parameters, these parameters are imported into the 'use' element's shadow tree, and any parameters specific to the 'use' element will override the parameters from the document's Parameters interface.
The following interfaces are defined below, using WebIDL [WebIDL]: Parameters, and WindowParameters.
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 pairs 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 Parameters interface:
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 pairs. 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 WindowParameters 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 pairs 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;
};
The schema for SVG Parameters 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.