Abstract
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].
1 Introduction
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].
1.1 Conformance Information
1.1.1 Normative and Informative Parts
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.
1.1.2 Normative Language for Conformance
Requirements
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].
1.1.3 Implementation Conformance
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.
1.1.4 XPath1.0 Compliance
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.
1.2 Documentation Conventions
The following namespace prefixes and corresponding namespace identifiers
are used in this document:
- dcn:
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].
2 General XPath Functions for
Manipulating the Delivery Context
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].
2.1 The dcn:delivery-context function
This section is normative.
2.1.1 Prototype
node-set dcn:delivery-context( )
2.1.2 Function
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.
2.2 The dcn:getProperty function
This section is normative.
2.2.1 Prototype
node-set dcn:getProperty(string path,
string unit?, string default?)
- string path
The location path and name of the property to be retrieved
- string unit
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.
- string default
An optional specification of a default value that is to be
returned if the specified property cannot be located.
2.2.2 Function
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.
2.3 The dcn:setProperty function
This section is normative.
2.3.1 Prototype
node-set dcn:setProperty(string path,
string value, string unit?)
- string path
The location path and name of the property to be modified.
- string value
The value that is to be used to calculate the new value to be
assigned to the specified property.
- string unit
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.
2.3.2 Function
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.
2.4 The dcn:search function
This section is normative.
2.4.1 Prototype
node-set dcn:search(string propertyName,
string nameSpace?)
- string propertyName
The name of the property to be retrieved
- string nameSpace
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.
2.4.2 Function
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.
3 Convenience XPath Functions for Accessing the
Delivery Context
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.
3.1 Default Values
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.
3.2 The dcn:cssmq-width function
This section is normative.
3.2.1 Prototype
number dcn:cssmq-width(string units,
number default?)
- string units
The units in which the value is to be returned. The possible
values of this argument are described in detail in Length Units.
- number default
An optional default value to be returned by the function if the
usable display width cannot be determined from the delivery context.
3.2.2 Function
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.
3.2.3 Examples
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.
3.3 The dcn:cssmq-height function
This section is normative.
3.3.1 Prototype
number dcn:cssmq-height(string units,
number default?)
- string units
The units in which the value is to be returned. The possible
values of this argument are described in detail in Length Units.
- number default
An optional default value to be returned by the function if the
usable display height cannot be determined from the delivery
context.
3.3.2 Function
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.
3.3.3 Examples
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.
3.4 The dcn:cssmq-device-width
function
This section is normative.
3.4.1 Prototype
number dcn:cssmq-device-width(string units,
number default?)
- string units
The units in which the value is to be returned. The possible
values of this argument are described in detail in Length Units.
- number default
An optional default value to be returned by the function if the
physical display width cannot be determined from the delivery
context.
3.4.2 Function
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.
3.4.3 Examples
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.
3.5 The dcn:cssmq-device-height
function
This section is normative.
3.5.1 Prototype
number dcn:cssmq-device-height(string units,
number default?)
- string units
The units in which the value is to be returned. The possible
values of this argument are described in detail in Length Units.
- number default
An optional default value to be returned by the function if the
physical display height cannot be determined from the delivery
context.
3.5.2 Function
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.
3.5.3 Examples
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.
3.6 The
dcn:cssmq-device-aspect-ratio function
This section is normative.
3.6.1 Prototype
string dcn:cssmq-device-aspect-ratio(string
default?)
- string default
An optional default value to be returned by the function if the
aspect ratio cannot be determined from the delivery context.
3.6.2 Function
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.
3.6.3 Examples
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.
3.7 The
dcn:cssmq-device-aspect-ratio-width function
This section is normative.
3.7.1 Prototype
number
dcn:cssmq-device-aspect-ratio-width(number default?)
- numberdefault
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.
3.7.2 Function
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.
3.7.3 Examples
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.
3.8 The
dcn:cssmq-device-aspect-ratio-height function
This section is normative.
3.8.1 Prototype
number
dcn:cssmq-device-aspect-ratio-height(number default?)
- 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.
3.8.2 Function
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.
3.8.3 Examples
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
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.
3.9 The dcn:cssmq-color function
This section is normative.
3.9.1 Prototype
number dcn:cssmq-color(number default?)
- 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.
3.9.2 Function
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.
3.9.3 Examples
This section is informative.
The expression
returns the boolean
value true, if the display supports more than 4 bits per color,
and falseotherwise. Similarly the expression
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.
3.10 The dcn:cssmq-color-index
function
This section is normative.
3.10.1 Prototype
number dcn:cssmq-color-index(number
default?)
- 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.
3.10.2 Function
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.
3.10.3 Examples
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.
3.11 The dcn:cssmq-monochrome function
This section is normative.
3.11.1 Prototype
number dcn:cssmq-monochrome(number default?)
- 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.
3.11.2 Function
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.
3.11.3 Examples
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.
3.12 The dcn:cssmq-resolution function
This section is normative.
3.12.1 Prototype
number dcn:cssmq-resolution(string units,
number default?)
- string units
The units in which the value is to be returned. The possible
values of this argument are described in detail in Resolution Units.
- number default
An optional default value to be returned by the function if the
resolution cannot be determined from the delivery context.
3.12.2 Function
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.
3.12.3 Examples
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.
3.13 The dcn:cssmq-scan function
This section is normative.
3.13.1 Prototype
string dcn:cssmq-scan(string default?)
- string default
An optional default value to be returned by the function if the
scan type cannot be determined from the delivery context.
3.13.2 Function
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.
- progressive
The display uses a progressive scanning scheme
- interlace
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.
3.13.3 Examples
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.
3.14 The dcn:cssmq-grid function
This section is normative.
3.14.1 Prototype
boolean dcn:cssmq-grid(boolean default?)
- 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.
3.14.2 Function
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.
3.14.3 Examples
This section is informative.
The expression
returns the boolean
value true, if the display is grid based.
4 Units
4.1 Length Units
Functions which support the specification of length units
mustrecognize the following string
literal values for the associated unitargument.
- px
the length is specified in pixels
- in
the length is specified in inches
- cm
the length is specified in centimeters
- mm
the length is specified in millimeters
- pt
the length is specified in font points
- pc
the length is specified in picas
These units are taken from [CSS]. They are defined
in that specification in the section describing lengths.
4.2 Resolution Units
Functions which support the specification of resolution units
mustrecognize the following string
literal values for the associated unitargument.
- dpi
the resolution is specified as a number dots or pixels per inch
- dpcm
the resolution is specified as a number dots or pixels per
centimeter
- dpmm
the resolution is specified as a number dots or pixels per
millimeter
4.3 Unit Conversion
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.