Content Selection for Device Independence (DISelect) 1.0

1.1 Conformance Information for DISelect

1.2 Documentation Conventions

The XML representations of various elements within DISelect are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization]

The following namespace prefixes and corresponding namespace identifiers are used in this document:

sel:

The DISelect namespace described in section 2.1 The Namespaces.

dcn:

The Delivery Context namespace described in section 2.1 The Namespaces.

In the examples, the default namespace, with no prefix, is used to indicate the host language within which the content selection markup is being used. The examples assume that the host language is XHTML Version 2 [XHTML 2]. The examples also assume that the integration with the host language makes the assumption that where the expr attribute is not explicitly referenced, its value is assumed to be true. In other words, host language elements carrying no expr attribute are unaffected by the presence of DISelect. The same assumption applies to select elements that do not explicitly carry an expr attribute.

Expressions in the examples used in this document are based on [XPath 1.0]. This syntax requires that certain special characters be escaped appropriately for use within XML processors. This quoting is used explicitly throughout the document.

2.1 The Namespaces

DISelect is not a stand-alone document type. It is intended to be integrated into other host languages such as XHTML. Such integration could result in the elements and attributes described in this specification being subsumed into the host language namespace. Alternatively, it might result in the elements and attributes being added to a host language, but in a separate namespace. The DISelect namespace is provided for this purpose.

The DISelect namespace has the URI: http://www.w3.org/2005/sel.

The Delivery Context namespace has the URI: http://www.w3.org/2005/dcn.

2.2 The Selection Module

The selection module consists of a set of elements and associated attributes that allow authors to specify how content will be selected for use in different delivery contexts.

The if and select elements provide mechanisms for choosing whether or not to use particular parts of the content. Their associated attributes and sub-elements provide the means to control how the alternatives are defined and how the decisions are made.

Section 4 Attributes for Conditional Processing describes how the attributes are used within a host markup language. Section 5 Elements for Conditional Processing describes the markup elements themselves. Section 6 Variables describes variables that can be used to simplify expressions. Section 7 Attribute Value Templates describes how DISelect supports the use of attribute value templates in host language elements. Finally, section 8 XPath Expressions describes the expressions used within DISelect to control the decisions about which content is used.

3.1 Events Overview

DISelect uses the events system defined in [DOM2 Events] and [XML Events]. These event models specify an event capture flow that includes:

Capture Phase

Processing where the event flows down the DOM tree towards its target element. In this phase, appropriately registered event handlers are notified of the event and may perform processing based on it.

Arrival at Target

When the event arrives at its target element, event handlers registered there are notified of the event and may perform processing based on it.

Bubbling Phase

Processing in which the event flows back up the DOM tree towards its root. In this phase, appropriately registered event handlers are notified of the event an may perform processing based on it.

The following sections define specific events associated with DISelect. In each case, the target element is defined together with information about whether the event bubbles and whether or not the default action can be cancelled.

3.2 Events in Response to Errors

During transformation, certain situations may occur that cause events to be raised. These situations represent errors that have been detected by the DISelect processor. DISelect does not contain any facilities by which events can be detected and processed other than by the processor.

Error indications happen as a result of unusual conditions in the DISelect Processor. There are two types of error indication.

Exception

Exceptions cause the DISelect processor to halt. The names bear the suffix exception.

Error

Errors are raised for notification. They do not cause the DISelect processor to halt. They bear the suffix error. It is permissible for the DISelect Processor to perform default handling for any of the events of this type. For example, a DISelect processor might choose to log error messages to a file.

4.1 Overview

DISelect provides three attributes that can be used with elements of the host language. This section describes those attributes. One attribute, expr, simplifies the specification of selection under certain circumstances. The other attributes, selid and selidname, provide a mechanism for avoiding problems associated with duplication of values of host language attributes that represent unique identifiers.

When used within a host language element, the DISelect attributes need to be appropriately qualified to indicate that they are within the content selection namespace.

4.2 The expr Attribute in Host Language Elements

The expr attribute is useful for simple decisions that affect small amounts of content. It is used within elements of the host language. It defines an expression used to determine whether or not the host language element appears in the result infoset. It can be added to any element of the host language.

The DISelect processor evaluates the expression defined by the exprattribute. If the result is a boolean value of true, the element that contains the attribute and all its descendants appear in the result infoset. The expr attribute itself does not appear in the result infoset. If the expression has a value of false, the element and all its descendents are omitted from the result infoset.

The expressions used with this attribute are described in section 8 XPath Expressions.

Section 4.5 Using the Attributes illustrates the use of the expr attribute.

If the decision to include or exclude material applies to a significant amount of content or if a number of different versions of the content are available, it is usually simpler to use the elements which are also part of this module. These are described in section 5 Elements for Conditional Processing.

4.3 The selid and selidname Attributes

The notion of unique identifiers that can be associated with particular elements in markup languages is common, if not universal. Using them allows particular instances to be identified so that, for example, links can be created or particular styling can be specified. Often, markup languages use an attribute named id for this identifier. Markup languages based on XML often use the attribute xml:id for this purpose.

The uniqueness of these identifiers usually forms part of the validity constraints associated with the host language. The presence of multiple elements with the same identifier violates the constraints and makes the associated document invalid. This is a potential issue when the host language is combined with a selection mechanism, such as the one detailed here. An author may wish to provide alternative versions of particular elements to be used under different circumstances. Both versions may need to carry the same identifier. Consequently, although the document resulting from processing the selection markup will be valid, the document containing the selection markup is not.

The selid and selidname attributes provide a solution for this problem. Rather than specify the host language unique identifier attribute directly, authors can use the DISelect selid and selidname attributes instead. The selid attribute defines the value of a host language identifier while the selidname attribute defines its name.

4.4 The functions Attribute

This attribute defines the names of additional XPath functions that are required to enable processing of material that contains DISelect elements and attributes. It allows authors to verify that the materials they have provided can be processed by the DISelect processor. The names in the list reference functions that are required by the content in addition to the set provided by the DISelect processor itself. Facilities that must be provided by the DISelect processor are described in section 8 XPath Expressions.

The value of the functionsattribute is a space-separated list of the XPath extension functions that are required for processing. Each extension function is represented by a QName.

The DISelect processor verifies that any functions specified using this element are available. If they are not, the processor causes an invalid computation exception to be raised (see 3.2.4 The diselect-compute-exception Event).

A DISelect processor mustverify the availability of the resources defined by this attribute no later than the point during processing at which it encounters the functionsattribute in the source infoset. A DISelect processor mayverify resource availability before it encounters the attribute. For example, the processor may verify the availability of resources at the time the infoset containing the attribute is loaded. This provides an optimization by avoiding unnecessary processing that would be rendered invalid by subsequent discovery of missing resources.

The functions attribute can occur any number of times within a source infoset. The set of resources required by the source infoset is considered to be the union of those defined by all of the functions attributes that are processed by the DISelect processor.

4.5 Using the Attributes

The examples in this section are informative. They have been chosen for clarity and simplicity. They are not intended to represent best practice. The companion primer [DI Primer] discusses a variety of ways to use DISelect under different circumstances.

The following example illustrates suppression of the display of an image if the usable width of the display on a device is too small. The first and third paragraphs containing the text are always presented. However, the second paragraph containing the image is shown only if the dcn:cssmq-width function indicates that the usable width of the device display is more than 200 pixels. If the second paragraph is shown, the object element will carry a generated xml:id attribute with a value of artimg42.

<p>The flooding was quite extensive.</p>
<p sel:expr="dcn:cssmq-width('px') > 200">
  <object src="image1" sel:selid="artimg42"/>
</p>
<p>Many people were evacuated from their homes.</p>

The conditional expressions used within the expr attribute can contain multiple terms that relate to different characteristics from the delivery context. So, for example, if the image should only be shown on devices with color displays wider than 200 pixels, the following markup might be used.

<p>The flooding was quite extensive.</p>
<p sel:expr="dcn:cssmq-width('px') > 200 and dcn:cssmq-color() > 0">
  <object src="image1" sel:selid="artimg42" sel:selidname="myns:myid"/>
</p>
<p>Many people were evacuated from their homes.</p>

In this version of the example, the value of the expr attribute is true only if the dcn:cssmq-width function indicates that the usable width of the device is more than 200 pixels and that the dcn:cssmq-color function indicates that the display supports color.

In addition, in this second example, if the second paragraph is shown, the object element will carry a generated myns:myid attribute with a value of artimg42. In this case, the selid attribute specifies the value of the generated attribute and the selidname attribute specifies its name.

<div selidname="myns:myid">
  <p>The flooding was quite extensive.</p>
  <p sel:expr="dcn:cssmq-width('px') > 200 and dcn:cssmq-color() > 0">
    <object src="image1" sel:selid="artimg42"/>
  </p>
  <p>Many people were evacuated from their homes.</p>
</div>

This version of the example is the same as the previous one, except that the selidname attribute is used to specify the name of the attribute to be generated from any sel:selid attributes in the markup contained within the div element.

Notice that in these examples, the attributes relating to conditional selection are qualified to indicate that they are from the DISelect namespace.

5.1 Overview

DISelect defines several elements used for controlling whether or not material appears in the result infoset as a result of processing.

5.2 Conditional Processing

5.3 Using the Elements

The examples in this section are informative. They have been chosen for clarity and simplicity. They are not intended to represent best practice. The companion primer [DI Primer] discusses a variety of ways to use DISelect under different circumstances.

In this first example, the expr attribute on the if element controls the selection. If the display on the device is more than 200 pixels wide, both the image and the paragraph will be included in the result infoset. If the display is not more than 200 pixels wide, they will be omitted.

<sel:if expr="dcn:cssmq-width('px') > 200">
  <object src="image1"/>
  <p>Many people had to be evacuated.</p>
</sel:if>  

In the second example, the expr attributes on the when elements control the selection.

<sel:select>
  <sel:when expr="dcn:cssmq-width('px') > 200">
    <object sel:selid="pic42" src="image1"/>
  </sel:when>
  <sel:when expr="dcn:cssmq-color() > 4">
    <object sel:selid="pic42" src="image2"/>
  </sel:when>
  <sel:otherwise>
    <p sel:selid="pic42">Many people had to be evacuated.</p>
  </sel:otherwise>
</sel:select>  

Each when element carries an expression in its expr attribute. The select element does not have a precept attribute. As a result, the precept defaults to matchfirst. Consequently, the descendents of the first when element whose expr attribute evaluates to true will be included in the result infoset. Based on the expressions in the example, if the usable width of the device, as reported by the dcn:cssmq-width function, is greater than 200 pixels, image1 will be included. If it is not, but if the device supports more than 4 bits per color, as reported by the dcn:cssmq-color function, image2 will be included. If neither of these conditions is true the paragraph of text is included.

This example also illustrates use of the selid attribute. The image elements and the paragraph element all carry the same value of pic42 for this attribute. After processing, whichever of the elements appears in the result infoset will carry an id attribute with this value.

<sel:select precept="matchevery">
  <sel:when expr="dcn:cssmq-width('px') > 200">
    <object src="image1"/>
  </sel:when>
  <sel:when expr="dcn:cssmq-color() > 4">
    <object src="image2"/>
  </sel:when>
  <sel:otherwise>
    <p>Many people had to be evacuated.</p>
  </sel:otherwise>
</sel:select>  

The third example is a slightly modified version of the second example. The select element carries a precept attribute with a value of matchevery. This change means that the descendents of every when element whose expr attribute evaluates to true are included in the result infoset. In this version of the example, if the usable width of the device is greater than 200 pixels and the device supports more than 4 bits per color, both images will be included. With a precept of matchfirst, only image1 would have been included. If neither of the conditions is true, the paragraph be included instead of the images.

<div sel:selidname="myns:myid" sel:functions="myfns:specialFunction1 mynfs:specialFunction2">
  ...
  <sel:select precept="matchfirst">
    <sel:when expr="dcn:cssmq-width('px') &lt; 200 and dcn:cssmq-color() > 4">
      <object src="smallimage"/>
    </sel:when>
    <sel:when expr="dcn:cssmq-color() > 4">
      <object src="biggerimage"/>
    </sel:when>
    <sel:otherwise>
      <p>Many people had to be evacuated.</p>
    </sel:otherwise>
  </sel:select> 
  ...
</div>

The final example illustrates the use of slightly more complex expressions within the expr attribute on the when elements. In this case, the content of the first when element will be selected if the usable width of the device is less than 200 pixels and the device supports more than 4 bits per color. Notice the need to use the entity < to specify the comparison "less than". The "<" character is special and needs to be escaped this way in XPath expressions used within XML documents.

In addition, this example illustrates use of the selidname attribute on the containing host language div element. This attribute defines the name of the generated unique identifiers as myns:myid. The same div element also includes a functions attribute that defines two additional functions needed within this particular source infoset.

6.1 The variable Element

The variable element is used to declare a variable and to set its value.

As described in 3 Processing Model, neither the element itself nor any of its attributes appears in the result infoset.

6.2 The value Element

The value element is used to include the value of an expression in the content. The DISelect processor evaluates the expression specified in the element. It places the value of that expression in the result infoset in place of the value element.

As described in 3 Processing Model, neither the element itself nor any of its attributes appears in the result infoset.

6.3 Using Variables

The examples in this section are informative. They have been chosen for clarity and simplicity. They are not intended to represent best practice. The companion primer [DI Primer] discusses a variety of ways to use DISelect under different circumstances.

<sel:variable name="nColors" value="dcn:cssmq-color(0)"/>
<sel:if expr="$nColors > 0">
  <p>Your device can display <sel:value expr="$nColors"/> different colors.</p>
</sel:if>

In this example, variable nColors is set by a call to the function dcn:cssmq-color. This function returns the number of colors supported by the device. The variable is referenced within the expression in the exprattribute of the ifelement. If the value of the variable is greater than zero, indicating that the device supports color, the paragraph is included in the result infoset. The value of the nColors variable appears in place of the sel:value element within the paragraph.

7.1 Using Attribute Value Templates

The examples in this section are informative. They have been chosen for clarity and simplicity. They are not intended to represent best practice. The companion primer [DI Primer] discusses a variety of ways to use DISelect under different circumstances.

This example illustrates the use of a variable within an attribute of the host language. Two variables are defined in the example. Variable isColor is set by a call to the function dcn:cssmq-color. This function returns a value of zero if the device does not support color. The value of isColor is used to control the value of variable presClass. The value of variable presClass is used, in an AVT, to specify the value of the class attributes on various elements in the host markup. The DISelect processor replaces the expressions in each AVT with the appropriate value, and this is subsequently used by the host language element. The different values of the class attribute select different CSS styles appropriate for monochrome and color devices.

<sel:variable name="isColor" value="dcn:cssmq-color(0)"/>
<sel:variable name="presClass" value="'colorDisplay'"/>
<sel:if expr="$isColor = 0">
  <sel:variable ref="presClass" value="'monochromeDisplay'"/>
</sel:if>
...
<h3 class="{$presClass}">Latest Cricket News</h3>
<dl class="{$presClass}">
  <dt>South Africa win latest one day international</dt>
  <dd>In a thrilling run chase, England yesterday just failed to overtake
      South Africa's mammoth score of 311.....</dd>
  <dt>Flintoff layoff will last four months</dt>
  <dd>Following recent surgery to correct a recurring injury problem, .......</dd>
</dl>

In this example, the two different values of the class attribute reference entries in the associated CSS style sheet that contain definitions appropriate for use on devices with color and monochrome displays respectively. The example is intended primarily to illustrate the syntax of the use of AVTs and is not necessarily realistic. Note the quoting required around the string literal values colorDisplay and monochromeDisplay.

8.1 Identifying Profiles and Versions

The two functions described in this section are useful for a content author to determine which profile and which version of DISelect are supported. Both functions must be supported by DISelect processors. Both are defined in the DISelect namespace, bound to the prefix "sel" in the prototypes below.

8.2 DISelect Basic XPath Support

The subset of XPath 1.0 defined in this section must be supported by all DISelect processors. The subset is sufficient to construct conditional expressions and expressions that return values. It also includes the ability to invoke XPath functions. It specifically omits the ability to construct expressions that contain paths.

8.3 DISelect Full XPath Support

DISelect Full processors must provide support for full XPath 1.0 expressions. This support includes a complete implementation of XPath 1.0 [XPath 1.0] in addition to providing implementations of all of the XPath functions described the companion specification Delivery Context: XPath Access Functions 1.0 [DCN XAF]. In addition to the convenience functions, that specification defines additional functions that provide path-based access. These can be used with the delivery context and the host document.

dcn:delivery-context()/beverage/coffee[3]

<variable name="city" value="dcn:delivery-context()/geo:location/geo:city-name"/>

<body>
  <p>Here is a paragraph.</p>
  <p id="important">Here is a paragraph which carries an id.</p>
  <p expr="//body/p[@id='important']">Here is a paragraph which is 
     included if there is also a paragraph carrying an id value of important
     present within the body.</p>
</body>

8.4 Extension Functions

Both DISelect Basic and DISelect Full processors mayoptionallysupport additional, implementation-specific, XPath functions. These functions might, for example, provide additional information from the delivery context. Such functions are known as extension functions.

Extension functions must not be placed in the DISelect namespace nor in the Delivery Context namespace. These namespaces are described in 2.1 The Namespaces. This is important because it is anticipated that additional sets of XPath functions will be defined in future versions of specifications related to DISelect. The DISelect and Delivery Context namespaces are reserved for such use.

The provision of the ability to provide extension functions recognizes that there is a need for capabilities beyond those described within this specification. The current diversity in representations of delivery context makes it difficult to define a standard yet comprehensive set of access functions. Instead, this specification defines a core set of such functions but allows for implementation-specific extensions. In future, it is anticipated that a wider range of types of access to the delivery context will become standardized.

Both DISelect Basic and DISelect Full processors may support additional functions over and above those defined in section 8.2 DISelect Basic XPath Support. These functions are known as extension functions.

Extension functions must notbe placed in the DISelect namespace nor in the Delivery Context namespace. These namespaces are described in section 2.1 The Namespaces. This is important because it is anticipated that, in future, additional sets of functions will be defined, in future versions of specifications related to DISelect, to provide more comprehensive access to the delivery context. These functions will be defined within the Delivery Context namespace

The delivery context is essentially a set of metadata. Some representations of delivery context, such as [CC/PP], use technologies such as RDF [RDF Primer] to provide semantically rich definitions. It is expected that additional sets of functions will be developed in future specifications to provide access to the delivery context in ways that reflect its role as metadata.