Copyright © 2007 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 [DISelect] it 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 July 2007 publication is a Candidate Recommendation; it has been widely reviewed and satisfies the requirements defined in the charter of the Ubiquitous Web Application Working Group and also identified in the Authoring Challenges for Device Independence document; W3C publishes a Candidate Recommendation to gather implementation experience.
The first release of this document was 10 October 2006 and the Ubiquitous Web Application Working Group has made its best effort to address the comments received during the first Last Call Working Draft, and those received during the second Last Call Working Draft. No change happened since the 10 October 2006 Working Draft. The design has stabilized and the Working Group intends to advance this specification to Proposed Recommendation once the exit criteria below are met:
This specification will remain a Candidate Recommendation until at least 31 October 2007.
Comments on this document should be sent to public-diselect-editors@w3.org.This list is archived at http://lists.w3.org/Archives/Public/public-diselect-editors/.
Publication as a Candidate Recommendation 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 Ubiquitous Web Applications Activity by the Ubiquitous Web Application Working Group . As such, it was not a deliverable as defined in the Charter of that group, but originally it was part of the DISelect 1.0 Specification. Due to comments received during the first Last Call Working Draft, the Working Group decided to split the 2 specifications, each one covering part of the scope of the deliverable described in the charter under the name DISelect.
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 Conformance Information
1.1.1 Normative and Informative
Parts
1.1.2 Normative Language for
Conformance Requirements
1.1.3 Implementation
Conformance
1.1.4 XPath1.0 Compliance
1.2 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 Changes in this Version
(Non-Normative)
C Acknowledgements (Non-Normative)
This specification defines a set of functions that can be used to access and manipulate 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 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].
A conformant implementation of this specification is a set of XPath functions that can be used to access information from the delivery context. A conformant implementation mustimplement all normative parts of this specification.
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
.
The syntax used in the examples in this document is based on [XPath 1.0]. This syntax is different from that required for use within markup languages based on XML. In particular, certain special characters must be escaped when XPath expressions are used within such languages. Examples that include syntax suitable for use within XML-based markup, such as DISelect, can be found in the primer that accompanies this specification [DI Primer] and in the DISelect specification itself [DISelect].
The functions described in this section are provided to facilitate general access to any part of the Delivery Context. They require knowledge of the internal structure of the delivery context. This internal structure is implementation dependent. It is assumed that authors using these functions are creating expressions for use with a particular delivery context implementation.
Functions that can be used without knowledge of the internal structure of the delivery context are described in 3 Convenience XPath Functions for Accessing 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:delivery-context( )
This function returns a node set containing just the root element node of the delivery context. Some languages, such as DISelect [DISelect], can allow expressions to reference either the host document or the delivery context. This function allows an expression to reference the delivery context.
The nature of the node returned is dependent on the implementation of the delivery context. It is the caller's responsibility to use the returned information in an appropriate way, based on knowledge of the implementation of the delivery context.
If there is no delivery context, an empty node-set is returned.
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 and the property has an associated unit of measure, it is returned in the default units.
An optional specification of a default value that is to be returned if the specified property cannot be located.
This function returns a node set containing a single node from the delivery context. The node returned is specified by the pathargument.
The nature of the node returned is dependent on the implementation of the delivery context. It is the caller's responsibility to provide an appropriate path and to use the returned information in an appropriate way, based on knowledge of the implementation of the delivery context.
If there is no delivery context, an empty node-set is returned.
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 and the property has an associated unit of measure, it is assumed that the value is in the default units.
This function sets a value in the node in the delivery context specified by the pathargument.
The format of the string used in the valueargument is dependent on the implementation of the delivery context. It is the caller's responsibility to provide an appropriate pathand value argument based on knowledge of the implementation of the delivery context.
If there is no delivery context, the function has no effect.
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 this argument is 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.
This function returns a node set consisting of all nodes in the delivery context that meet the search criteria specified in the arguments.
The nature of the node returned is dependent on the implementation of the delivery context. It is the caller's responsibility to use the returned information in an appropriate way, based on knowledge of the implementation of the delivery context.
If there is no delivery context an empty node-set is returned.
The functions described in this section are intended to provide convenient access to the delivery context from within XPath expressions. They require no explicit knowledge of the structure of the delivery context. Authors can use these functions without regard to the way in which the underlying delivery context is implemented.
These functions are based on those described 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
default
argument 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 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-height('px') > 200
returns the boolean
value true
, if the display has a usable height of more than 200
pixels, and false
otherwise.
The expression
dcn:cssmq-height('cm', 2.54)
returns the usable height of the display in centimeters as an
xs;decimal
value 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
default
argument 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 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-device-width('px') < 640
returns the boolean
value true
, if the display has a physical width of less than 640
pixels, and false
otherwise. 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 false
otherwise.
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
default
argument 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 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-device-height('cm') > 2.7
returns the boolean
value true
, if the display has a physical height of more than
2.7 centimeters, and false
otherwise. If the physical height
cannot be determined from the delivery context, the function returns the
value 0
and 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;decimal
value 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
default
argument 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 default
argument
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
false
otherwise.
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
default
argument 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 default
argument 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
false
otherwise.
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
12
is 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
default
argument 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 default
argument is provided.
This section is informative.
The expression
dcn:cssmq-device-aspect-ratio-height() = 9
returns the boolean
value true
, if the display has an aspect ratio height of 9 and
false
otherwise.
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
6
is 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
default
argument 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
default
argument 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 false
otherwise. 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 true
if 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
default
argument 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 default
argument 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 false
otherwise. 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 true
if 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
default
argument 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 default
argument 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 false
otherwise. 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 true
if 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
default
argument 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 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-resolution('dpi', 100) > 200
returns the boolean
value true
, if the display has a resolution of more than 200
pixels per inch, and false
otherwise. 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
default
argument 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 default
argument
is provided.
This section is informative.
The expression
dcn:cssmq-scan() = 'interlace'
returns the boolean
value true
, if the display uses interlace scanning and
false
otherwise.
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 true
if 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
default
argument if it is not possible to determine whether the
device is grid based or bitmap based from the delivery context. It returns
false
if it is not possible to determine whether the device is
grid based or bitmap based from the delivery context and no
default
argument 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.
This section summarizes the changes made since the version of the document issued as the second last call.
Clarified the conformance statements for the specification
Changed the references to CSS 2.1 and Media Queries to be informative rather than normative
This document was produced with the help of the Ubiquitous Web Application Group participants:
The editors would also like to recognize the contributions of the members of the former Device Independence Working Group: