Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document specifies a set of XPath functions that can be used to manipulate the Delivery Context associated with a request for an item of content. These functions have been designed to satisfy the requirements to adapt content based on the Delivery Context. While designed to work with Device Independent Content Selection then can be used in any XPath processor.
There is a companion document which provides introductory information concerned with this specification [DI Primer].
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 is the First Public Working Draft of a possible future W3C Recommendation.
This is a Last Call W3C Working Draft of the Delivery Context: XPath Access Functions specification, for review by W3C members and other interested parties.
This Last Call review period ends on 07 November 2006 at 2359Z. Please send review comments before the end of the review period to public-diselect-editors@w3.org. This list is archived at http://lists.w3.org/Archives/Public/public-diselect-editors/.
Following completion of Last Call, the Device Independence Working Group plan to produce formal responses to all comments received by the Working Group and then advance the specification to a Candidate Recommendation.
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 document is published as part of the W3C Device Independence Activity by the Device Independence Working Group (Member-only link).
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.
1 Introduction
1.1 Towards a Device Independent Markup Language
Profile
1.2 Reading the Specification
1.2.1 Conformance Information
1.2.1.1 Normative and Informative
Parts
1.2.1.2 Normative Language for
Conformance Requirements
1.2.2 XPath1.0 Compliance
1.3 Documentation Conventions
2 General XPath Functions for
Manipulating the Delivery Context
2.1 The dcn:delivery-context function
2.2 The dcn:getProperty function
2.3 The dcn:setProperty function
2.4 The dcn:search function
3 Convenience XPath Functions for Accessing the
Delivery Context
3.1 Default Values
3.2 The dcn:cssmq-width
function
3.3 The dcn:cssmq-height
function
3.4 The dcn:cssmq-device-width
function
3.5 The
dcn:cssmq-device-height function
3.6 The
dcn:cssmq-device-aspect-ratio function
3.7 The
dcn:cssmq-device-aspect-ratio-width function
3.8 The
dcn:cssmq-device-aspect-ratio-height function
3.9 The dcn:cssmq-color
function
3.10 The dcn:cssmq-color-index
function
3.11 The dcn:cssmq-monochrome
function
3.12 The dcn:cssmq-resolution
function
3.13 The dcn:cssmq-scan function
3.14 The dcn:cssmq-grid function
4 Units
4.1 Length Units
4.2 Resolution Units
4.3 Unit Conversion
A References
A.1 Normative References
A.2 Informative References
B Changelog (Non-Normative)
B.1 Changes in this Version
C Acknowledgements (Non-Normative)
This specification represents one part of the approach being developed within DIWG for the provision of a markup language that supports creation of web sites that can be used from a wide variety of devices with a wide variety of characteristics.
The overall approach being taken by DIWG is based on the development of a device independent profile for XHTML. The profile will be based on XHTML Version 2 [XHTML 2], XForms [XForms] and current and forthcoming versions of CSS [CSS]. DIWG is developing additional modules that can be added to this combination of specifications to complete the profile.
This specification defines functions that can be used to access information in the Delivery Context. This information can be used, for example, as the basis for selecting between different versions of materials supplied by authors. This use of these functions is described in Content Selection for Device Independence [DISelect].
The functions described in this specification conform to XPath 1.0 [XPath 1.0].
The normative and informative parts of this specification are identified by use of labels within various sections. Generally, everything in the specification is considered to be normative, apart from the examples.
Individual conformance requirements or testable statements are identified in the specification by the use of specific key words. In particular, the key words must, must not, required, shall, shall not, should, should not, recommended, may, and optionalin this specification are to be interpreted as described in [IETF RFC 2119].
The functions described in this specification are designed to work within processors that support XPath 1.0 [XPath 1.0]. In particular, type conversion associated with arguments to the functions follows the rulesdescribed in the XPath 1.0 specification.
The following namespace prefixes and corresponding namespace identifiers are used in this document:
The Delivery
Context namespace has the URI:
http://www.w3.org/2005/dcn.
A number of functions are provided to facilitate access to any part of the Delivery Context . . .
In future, it is anticipated that additional sets of functions will be developed to provide more comprehensive access to the delivery context. It is also anticipated that access mechanisms that make explicit use of the underlying structure of the metadata within the delivery context will also be developed in future. These might, for example, make use of future capabilities to query RDF [RDF Primer].
This section is normative.
node-set dcn:getProperty(string path, string unit?, string default?)
The location path and name of the property to be retrieved
An optional specification of the units in which the requested property is to be returned. If omitted it is returned in the units specified in the Delivery Context.
An optional specification of a default value that is to be returned if the named property cannot be located.
This section is normative.
node-set dcn:setProperty(string path, string value, string unit?)
The location path and name of the property to be modified.
The value that is to be used to calculate the new value to be assigned to the specified property.
An optional specification of the units in which the supplied property value is specified. If omitted, no conversion takes place.
This section is normative.
node-set dcn:search(string propertyName, string nameSpace?)
The name of the property to be retrieved
An optional specification of the namespace to be searched for the property. If omitted, the search is performed for properties in the delivery context namespace http://www.w3.org/2005/dcn. If the value '*' is supplied, the search is performed for properties in all namespaces. If a specific namespace URI is provided, the search is performed in that particular namespace.
These functions are intended to provide convenient access to the delivery context from within XPath expressions. They provide convenient short hand forms for use by authors. The functions are based on those describe in the specification of CSS Media Queries [Media Queries].
These functions are considered to be a minimum set for delivery context access. It is not intended that definition of this set of functions should limit the provision of additional mechanisms for access to the delivery context.
The convenience functions include a two stage mechanism for providing default values. Default values are returned by the functions when a value is not available from the delivery context.
First, authors can supply values to be returned in the event that the delivery context does not contain the appropriate information. They do this through the optional default argument available on each function.
Second, each function provides a predefined default value that is returned if the delivery context does not contain the appropriate information and the author has not supplied a value through the default argument to the function.
This section is normative.
number dcn:cssmq-width(string units, number default?)
The units in which the value is to be returned. The possible values of this argument are described in detail in Length Units.
An optional default value to be returned by the function if the usable display width cannot be determined from the delivery context.
This function returns the usable width of the display associated with the
device as a decimal number. This value may be smaller than that returned by
the dcn:cssmq-device-width
function. Some devices, for example, have fixed areas of their display that
are unavailable to applications.
The function returns the value supplied in the default
argument if the usable width cannot be determined from the delivery context.
It returns 0 if the usable width cannot be determined from the delivery
context and no default argument is provided.
The function returns the special value NaN if it cannot interpret the unitsargument as an appropriate unit of measure.
This section is informative.
The expression
dcn:cssmq-width("px", 500) > 400
returns the boolean value
true, if the display has a usable width of more than 400 pixels,
and false otherwise. If the width cannot be determined from the
delivery context, the function returns the default value 500, and
consequently the expression evaluates to true.
Similarly the expression
dcn:cssmq-width("cm") < 2.54
returns the boolean value
true, if the display has a usable width of less than 2.54
centimeters and false otherwise.
This section is normative.
number dcn:cssmq-height(string units, number default?)
The units in which the value is to be returned. The possible values of this argument are described in detail in Length Units.
An optional default value to be returned by the function if the usable display height cannot be determined from the delivery context.
This function returns the usable height of the display associated with the
device as a decimal number. This value may be smaller than that returned by
the dcn:cssmq-device-height
function. Some devices, for example, have fixed areas of their display that
are unavailable to applications.
The function returns the value supplied in the
defaultargument if the usable height cannot be determined from
the delivery context. It returns 0 if the usable height cannot be determined
from the delivery context and no defaultargument is provided.
The function returns the special value NaN if it cannot interpret the unitsargument as an appropriate unit of measure.
This section is informative.
The expression
dcn:cssmq-height("px") > 200
returns the boolean value
true, if the display has a usable height of more than 200
pixels, and falseotherwise.
The expression
dcn:cssmq-height("cm", 2.54)
returns the usable height of the display in centimeters as an
xs;decimalvalue or the value 2.54 if the height
cannot be determined from the delivery context.
This section is normative.
number dcn:cssmq-device-width(string units, number default?)
The units in which the value is to be returned. The possible values of this argument are described in detail in Length Units.
An optional default value to be returned by the function if the physical display width cannot be determined from the delivery context.
This function returns the physical width of the display associated with
the device as a decimal number. This value may be larger than that returned
by the dcn:cssmq-width
function. Some devices, for example, have fixed areas of their display that
are unavailable to applications.
The function returns the value supplied in the
defaultargument if the physical width cannot be determined from
the delivery context. It returns 0 if the physical width cannot be determined
from the delivery context and no defaultargument is provided.
The function returns the special value NaN if it cannot interpret the unitsargument as an appropriate unit of measure.
This section is informative.
The expression
dcn:cssmq-device-width("px") < 640
returns the boolean value
true, if the display has a physical width of less than 640
pixels, and falseotherwise. Similarly the expression
dcn:cssmq-device-width("in") < 3.6
returns the boolean value
true, if the display has a usable width of less than 3.6 inches
and falseotherwise.
This section is normative.
number dcn:cssmq-device-height(string units, number default?)
The units in which the value is to be returned. The possible values of this argument are described in detail in Length Units.
An optional default value to be returned by the function if the physical display height cannot be determined from the delivery context.
This function returns the physical height of the display associated with
the device as a decimal number. This value may be smaller than that returned
by the dcn:cssmq-device-height
function. Some devices, for example, have fixed areas of their display that
are unavailable to applications.
The function returns the value supplied in the
defaultargument if the physical height cannot be determined from
the delivery context. It returns 0 if the physical height cannot be
determined from the delivery context and no defaultargument is
provided.
The function returns the special value NaN if it cannot interpret the unitsargument as an appropriate unit of measure.
This section is informative.
The expression
dcn:cssmq-device-height("cm") > 2.7
returns the boolean value
true, if the display has a physical height of more than 2.7
centimeters, and falseotherwise. If the physical height cannot
be determined from the delivery context, the function returns the value
0and hence the expression evaluates to false.
The expression
dcn:cssmq-device-height("px", 250)
returns the physical height of the display in pixels as an
xs;decimalvalue or the value 250 if the height
cannot be determined from the delivery context.
This section is normative.
string dcn:cssmq-device-aspect-ratio(string default?)
An optional default value to be returned by the function if the aspect ratio cannot be determined from the delivery context.
This function returns a representation of the physical aspect ratio of the
device in the form defined in [Media
Queries]. The resulting string contains
values such as 16/9, indicating an aspect ratio of 16:9, the
ratio commonly associated with wide screen television, for example. The first
value represents the width and the second value the height of the display.
The complete value indicates the relative sizes of these dimensions. The
values within the result are always the minimuminteger values that
can represent the aspect ratio.
The function returns the value supplied in the
defaultargument if the aspect ratio cannot be determined from
the delivery context. It returns an empty string if the aspect ratio cannot
be determined from the delivery context and no defaultargument
is provided.
This section is informative.
The expression
dcn:cssmq-device-aspect-ratio() = "16/9"
returns the boolean value
true, if the display has an aspect ratio of 16:9 and
falseotherwise.
The expression
dcn:cssmq-device-aspect-ratio("4/3")
returns the string value
representing the device aspect ratio. If the aspect ratio cannot be
determined from the delivery context, the value "4/3"is
returned.
This section is normative.
number dcn:cssmq-device-aspect-ratio-width(number default?)
An optional default value to be returned by the function if the width value of the aspect ratio cannot be determined from the delivery context.
This function returns the width value of the aspect ratio of the display
associated with the device. This value is the number
representation of the firstvalue returned by the dcn:cssmq-device-aspect-ratio
function. For example, if the dcn:cssmq-device-aspect-ratio
were to return the string value
"16/9", this function would return the number value
16.
The function returns the value supplied in the
defaultargument if the width value of the aspect ratio cannot be
determined from the delivery context. It returns a value of 0 if the width
value of the aspect ratio cannot be determined from the delivery context and
no defaultargument is provided.
This section is informative.
The expression
dcn:cssmq-device-aspect-ratio-width() = 16
returns the boolean value
true, if the display has an aspect ratio width of 16 and
falseotherwise.
The expression
dcn:cssmq-device-aspect-ratio-width(12)
returns the number value
representing the width value of the aspect ratio. If the width value of the
aspect ratio cannot be determined from the delivery context, the value
12is returned.
This section is normative.
number dcn:cssmq-device-aspect-ratio-height(number default?)
An optional default value to be returned by the function if the height value of the aspect ratio cannot be determined from the delivery context.
This function returns the height value of the aspect ratio of the display
associated with the device. This value is the number
representation of the secondvalue returned by the dcn:cssmq-device-aspect-ratio
function. For example, if the dcn:cssmq-device-aspect-ratio
were to return the string value
"16/9", this function would return the number value
9.
The function returns the value supplied in the
defaultargument if the height value of the aspect ratio cannot
be determined from the delivery context. It returns a value of 0 if the
height value of the aspect ratio cannot be determined from the delivery
context and no defaultargument is provided.
This section is informative.
The expression
dcn:cssmq-device-aspect-ratio-height() = 9
dcn:cssmq-device-aspect-ratio-height() = 9
returns the boolean value
true, if the display has an aspect ratio height of 9 and
falseotherwise.
The expression
dcn:cssmq-device-aspect-ratio-height(6)
returns the number value
representing the height value of the aspect ratio. If the height value of the
aspect ratio cannot be determined from the delivery context, the value
6is returned.
This section is normative.
number dcn:cssmq-color(number default?)
An optional default value to be returned by the function if the number of bits per color cannot be determined from the delivery context.
This function returns the number of bits per color supported by the display associated with the device. The result is expressed as a positive integer.
The function returns the value supplied in the
defaultargument if the number of bits per color cannot be
determined from the delivery context. It returns 0 if the number of bits per
color cannot be determined from the delivery context and no
defaultargument is provided. The function also returns 0 if the
device does not support color.
This section is informative.
The expression
dcn:cssmq-color() > 4
returns the boolean value
true, if the display supports more than 4 bits per color, and
falseotherwise. Similarly the expression
dcn:cssmq-color(8) > 6
returns the boolean value
true, if the display supports more than 6 bits per color. It
also returns trueif the number of bits per color cannot be
determined from the delivery context. In this case, the function returns the
supplied default value of 8, which is greater than
6.
This section is normative.
number dcn:cssmq-color-index(number default?)
An optional default value to be returned by the function if the number of entries in the color look up table for the device cannot be determined from the delivery context.
This function returns the number of entries in the color look up table of the display associated with the device. The result is expressed as a positive integer.
The function returns the value supplied in the
defaultargument if the number of entries in the color look up
table cannot be determined from the delivery context. It returns 0 if the
number of entries in the color look up table cannot be determined from the
delivery context and no defaultargument is provided. The
function also returns 0 if the device does not support color or has no look
up table.
This section is informative.
The expression
dcn:cssmq-color-index() > 16
returns the boolean value
true, if the color look up table of the display has more than 16
entries, and falseotherwise. Similarly the expression
dcn:cssmq-color-index(256) > 64
returns the boolean value
true, if the the color look up table of the display has more
than 64 entries. It also returns trueif the number of entries in
the color look up table cannot be determined from the delivery context. In
this case, the function returns the supplied default value of
256, which is greater than 64.
This section is normative.
number dcn:cssmq-monochrome(number default?)
An optional default value to be returned by the function if the number of bits used to represent monochrome output cannot be determined from the delivery context.
This function returns the number of bits used to represent monochrome output by the display associated with the device. The result is expressed as a positive integer.
The function returns the value supplied in the
defaultargument if the number of bits used to represent
monochrome output cannot be determined from the delivery context. It returns
0 if the the number of bits used to represent monochrome output cannot be
determined from the delivery context and no defaultargument is
provided. The function also returns 0 if the device is not a monochrome
device.
This section is informative.
The expression
dcn:cssmq-monochrome() > 4
returns the boolean value
true, if the display uses more than 4 bits to represent
monochrome output, and falseotherwise. Similarly the
expression
dcn:cssmq-monochrome(8) > 6
returns the boolean value
true, if the display uses more than 6 bits to represent
monochrome output. It also returns trueif the number of bits
used to represent monochrome cannot be determined from the delivery context.
In this case, the function returns the supplied default value of
8, which is greater than 6.
This section is normative.
number dcn:cssmq-resolution(string units, number default?)
The units in which the value is to be returned. The possible values of this argument are described in detail in Resolution Units.
An optional default value to be returned by the function if the resolution cannot be determined from the delivery context.
This function returns the resolution of the display associated with the
device as a decimal number.
The function returns the value supplied in the
defaultargument if the resolution cannot be determined from the
delivery context. It returns 0 if the resolution cannot be determined from
the delivery context and no defaultargument is provided.
The function returns the special value NaN if it cannot interpret the unitsargument as an appropriate unit of measure.
This section is informative.
The expression
dcn:cssmq-resolution("dpi", 100) > 200
returns the boolean value
true, if the display has a resolution of more than 200 pixels
per inch, and falseotherwise. If the resolution cannot be
determined from the delivery context, the function returns the default value
100, and consequently the expression evaluates to false.
This section is normative.
string dcn:cssmq-scan(string default?)
An optional default value to be returned by the function if the scan type cannot be determined from the delivery context.
This function returns a representation of the type of scan used by the
display associated with the device. The resulting string contains
one of the following values.
The display uses a progressive scanning scheme
The display uses an interlace scanning scheme
The function returns the value supplied in the
defaultargument if the type of scan cannot be determined from
the delivery context. It returns an empty string if the type of scan cannot
be determined from the delivery context and no defaultargument
is provided.
This section is informative.
The expression
dcn:cssmq-scan() = "interlace"
returns the boolean value
true, if the display uses interlace scanning and
falseotherwise.
The expression
dcn:cssmq-scan("progressive")
returns the string value
representing the type of scanning used. If the type of scan cannot be
determined from the delivery context, the value "progressive"is
returned.
This section is normative.
boolean dcn:cssmq-grid(boolean default?)
An optional default value to be returned by the function if it is not possible to determine whether the device is grid based or bitmap based from the delivery context.
This function returns a boolean value
of trueif the device is grid based. Grid based devices support a
regular character array rather than a bitmap display. Examples of grid based
devices include teletype terminals and simple mobile phones with fixed width
fonts.
The function returns the value supplied in the
defaultargument if it is not possible to determine whether the
device is grid based or bitmap based from the delivery context. It returns
falseif it is not possible to determine whether the device is
grid based or bitmap based from the delivery context and no
defaultargument is provided.
This section is informative.
The expression
dcn:cssmq-grid()
returns the boolean value
true, if the display is grid based.
Functions which support the specification of length units
mustrecognize the following string literal
values for the associated unitargument.
the length is specified in pixels
the length is specified in inches
the length is specified in centimeters
the length is specified in millimeters
the length is specified in font points
the length is specified in picas
These units are taken from [CSS]. They are defined in that specification in the section describing lengths.
Functions which support the specification of resolution units
mustrecognize the following string literal
values for the associated unitargument.
the resolution is specified as a number dots or pixels per inch
the resolution is specified as a number dots or pixels per centimeter
the resolution is specified as a number dots or pixels per millimeter
The units specified when a function is invoked may not be the same as those in which information is represented in the delivery context.
Functions must convert values appropriately if the unit requested is not the same as that in which the delivery context information is represented. Functions mustuse the conversion factors described in [CSS] in the section describing lengths.
Reworded the titles of the main sections describing the functions themselves.
Add a section on unit conversions and refer to the appropriate section in CSS 2.1 for the conversion rules [ACTION-162].
Changed wording in cssmq-monochrome to indicate return of 0 if the device is not monochrome [ACTION-160].
Moved the reference to CSS 2.1 to the normative section and added a link to it from the length unit section [ACTION-154]
Correct typo 'from he delivery context' [ACTION-159]
Add statement about casting rules to the section "Reading the document" [ACTION-153].
Add statements, to each affected function, about behaviour when invalid unit arguments are provided [ACTION- 153]
Replaced the name 'starter set functions' with convenience functions, and adjusted the associated text appropriately.
Correct the name of the function in the prototype to dcn:cssmq-color-index. Implements action01 from 2005-06-09 f2f. (Member-only link)
Clarification of processing when required @functions are not found.
Add a reference to XSLT in our description of AVTs. AVTs are defined by XSLT not XPath.
Updated the definitions of the expr attribute on the value element and the value attribute on the variable element to make them consistent.
Updated the descriptions of events to include DOM2/XML Event information. This includes definition of the element that is the target of the event, whether or not the event can be cancelled, and whether or not it bubbles. Guidance on the particular values used was taken from the XForms specification. The default action taken by the DISelect processor was also rationalized into the tables used for this additional event information.
Added the sel:options element .
The sel:selidName attribute was introduced to overcome a possible ambiguity in the mechanism that specified both the value and the name of the unique identifier generated from the sel:selid attribute.
Clarify the use of data types for variables and make the use of XPath 1 normative in response to discussion at the 9th F2F meeting in Boston in March 2005.
Added the section describing Attribute Value Templates, as the mechanism for computing the values of host language attributes using expressions
Added the section describing the value element as the mechanism for including the values of expressions in the body content of host language elements.
Added the variable and value elements to the list of elements in the description of the selection module.
Added the mechanism for reprocessing the document in response to an event. This is based on the diselect-reprocess event.
Updated the conformance information to be closer to that in the latest QA specification guidelines
Added the mechanism for specifying the name of the attribute to be generated by the sel:selid attribute.
Added the mechanism for allowing a processor to check that extension
functions are available. This is based on the new
sel:required element.
Updated examples in the section on starter set XPath functions to use the same format as examples from earlier in the document.
Added the diselect-invalid-declaration exception. Updated the section on declaration of variables to describe the conditions under which it is raised.
Renamed the Examples sections
Corrected the reference to examples that illustrate sel:selid to point to the examples associated with content selection elements.
Reworded the description in the Overview.
Added an editorial note about whether the processing model as described is sufficient. It may not be able to handle dynamic situations in which the source infoset is repeatedly reprocessed.
Completed the processing model. Added the appropriate error events and described the conditions under which they are raised. Clarified the rules on types and variable declarations.
Added a formal syntax for the expressions used within DISelect.
Resolved comments that use of XPath 2 requires a host language to specify the types that are valid and that DISelect itself was not necessarily playing the role of the host language for XPath 2.
The changes made make XPath 1 the expression language for this version of DISelect. The changes made were:
Remove references to the use of XML schema types
Update the function prototypes to use XPath 1 types rather than XPath 2 types
Remove the definition of the use of the xs: prefix
Remove the normative reference to XPath 2
Remove the normative reference to XML Schema Part 1
Changed the prefix in the document associated with XML Schema from xsd: to xs: to reflect more common usage in W3C documents.
Changed the prefix in the document associated with delivery context from dc: to dcn: to avoid a clash with the prefix used by convention for Dublin Core.
Paul Duffin commented that the specification as written implied that a number of attributes were global. This was not the intent. The specification has been updated to reflect the author's true intent. Attributes need to be qualified only when used within elements that are not within the DISelect namespace.
All unnecessary use of explicit prefixes has been removed. A comment has been added concerning the examples and indicating that they assume that XHTML Version 2 is the host language.
The description of the use of the default namespace in this document has been updated to reflect the use of XHTML Version 2 as the host language in the examples.
At the time of publication, the participants of the Device Independence Working Group are:
The Device Independence Working Group has benefited in its work from the participation and contributions of a number of people not currently members of the Working Group, including in particular those named below. Affiliations given are those current at the time of their work with the WG.