13. SMIL 3.0 State

This section is informative.

The modules defined in this chapter are all new modules which were not part of the SMIL 2.1 specification.

This section is informative.

A SMIL 2.1 presentation has a lot of state that influences how the presentation runs. Or, to rephrase that in a procedural way, state that influences decisions that the SMIL scheduler makes. All this state is either implicit in the presentation (what nodes are active and how long into their duration they are, how many iterations of a repeat we have done, which nodes in an excl are paused because a higher priority node has preempted them, etc.), or completely external to the presentation (system tests and custom tests).

This has the effect that the only control flow that the SMIL author has at his/her disposal is that which is built in to the language, unless the SMIL engine includes some scripting language component and a DOM interface to the document that the author may use to create more complex logic.

The modules in this section provide a mechanism whereby the document author may create more complex control flow than what SMIL provides through the timing and content control modules, without having to go all the way of using a scripting language. One way to provide this is to allow a document to have some explicit state (think: variables) along with ways to modify, use and save this state.

In addition, the mechanisms that the SMIL BasicContentControl and CustomTestAttributes modules provide for testing values are limited: basically one can only test for predefined conditions being true (not for them being false) and there is a limited form of testing for multiple conditions with "and" being the only boolean operator.

Application areas include things like quizzes, interactive adaptation of presentations to user preferences, computer-aided instruction and distant learning.

This section is informative.

The design of these modules was done after meeting with the W3C Backplane Group (part of the Hypertext Coordination Group) and various choices were influenced by the direction that group is taking.

These modules therefore borrow heavily from work done by other W3C working groups:

• The data model is a small XML document addressed with XPath 1.0 [XPATH10]. This follows the lead set by XForms 1.0 [XFORMS10].
• The XPath function interface to system and custom test data and the expr attribute are modelled after work by the Device Independent WG on DISelect 1.0 [DISELECT10].
• Attribute Value Templates used in StateInterpolation are lifted from XSLT 1.0 [XSLT10], [XSLT20].

The intention of these modules it to provide authors with the minimum functionality required to create compelling presentations, not to import all functionality from the standards they were lifted from, and concentrate on the timing integration issues. Applications requiring a richer set of primitives should import, for example, the XForms data model through the XML namespace mechanism.

This section is informative.

The SMIL 3.0 StateTest Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

This section is informative.

The mechanisms that the BasicContentControl and CustomTestAttributes modules provide for testing values are limited: basically one can only test for predefined conditions being true (not for them being false) and by specifying multiple system test attributes an author has a way to simulate an and operator but that is all.

This module introduces a generalized expr attribute that contains an expression. If the expression evaluates to false the element carrying the attribute is ignored. If the expression evaluates to true or if there is any error (this ranges from expression syntax errors and type errors to unavailability of the expression language engine) the element is treated normally.

This section is informative.

The SMIL 3.0 Language Profile specifies that XPath 1.0 is used as the default expression language, and the context in which the expressions are evaluated is as follows:

• The context node, context position and context size are not relevant to the functionality in the State Test module;
• The variable bindings are empty;
• The function library consists of the functions listed below (in addition to the builtin XPath functions); and
• The set of namespace declarations is not relevant to the functionality in the State Test module.

Alternative expression languages that could be used are a scaled down form of XPath as used by DI, or EcmaScript, Python, Lua or any other language suitable for the application domain of the profile.

Note that there is a slight but important semantic difference between using content control attributes and using expr: the latter is guaranteed to be dynamically evaluated at runtime and may therefore be used for more dynamic control whereas there is no such guarantee for the former.

This section is informative.

Here is a SMIL 3.0 Language Profile example of an audio element that is only played if audio descriptions are off and the internet connection is faster than 1Mbps. Think of using it for playing background music only when this will not interfere too much with the real presentation:

   <audio src="background.mp3" 
             expr="not(smil-audioDesc()) and smil-bitrate() &gt; 1000000" />

Here is an example that will show the image colour.jpg to most english-speaking people. However, people preferring American English over other variants of english will see color.jpg. Non-english speaking people will see couleur.jpg.

    <switch>
      <img src="color.jpg" expr="smil-systemLanguage('en-us') &gt;= smil-systemLanguage('en')" />
      <img src="colour.jpg" expr="smil-systemLanguage('en')" />
      <img src="couleur.jpg" />
    </switch>

This section is informative.

The SMIL 3.0 UserState Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

This section is informative.

This section introduces a data model that document authors may refer to in the context of the expr attribute, allowing elements to be rendered depending on author-defined values. A mechanism to change values in the data model is also included.

The actual choice of the expression language is made in the language profile. The SMIL 3.0 Language Profile requires support for the XPath 1.0 expression language (but allows use of other languages as well).

This section is informative.

Here is a SMIL 3.0 Language Profile example of a sequence of audio clips that remembers the last audio clip played, omitting the state declaration in the head for brevity:

   <seq>
       <audio src="chapter1.mp3" />
       <setvalue ref="lastPlayed" value="1" />
       <audio src="chapter2.mp3" />
       <setvalue ref="lastPlayed" value="2" />
       <audio src="chapter3.mp3" />
       <setvalue ref="lastPlayed" value="3" />
   </seq>

Here is an extension of the previous example: not only is the last clip remembered but if this sequence is played again, later during the presentation, any audio clips played previously are skipped:

   <seq>
       <seq expr="lastPlayed &lt; 1">
           <audio src="chapter1.mp3" />
           <setvalue ref="lastPlayed" value="1" />
       </seq>
       <seq expr="lastPlayed &lt; 2">
           <audio src="chapter2.mp3" />
           <setvalue ref="lastPlayed" value="2" />
       </seq>
       <seq expr="lastPlayed &lt; 3">
           <audio src="chapter3.mp3" />
           <setvalue ref="lastPlayed" value="3" />
       </seq>
   </seq>

This section is informative.

As stated before, the normative choice of an expression language and data model is made in the profile that includes this module, but for ease of reading this section informatively describes the choices in the SMIL 3.0 Language Profile: XPath 1.0 operating on a simple XML document contained in the state element.

It is important to note that the data model is an XML document. This is not to be confused with the variable bindings in the expression context, another namespace that XPath has. These variable bindings are not supported through SMIL State. Therefore references to state elements are node-set expressions, not $name-style variable references. This usage allows for nested variables and more complex data structures than the flat namespace of the variable bindings provides. SMIL follows the lead of XForms here.

The state element, of which at most one may occur, in the head section, should either be empty or contain a well-formed XML document.

The XPath context in which the expressions are evaluated is as follows:

• The context node is the root of the XML document specified with the state element;
• context position and context size refer to that same element;
• The variable bindings are empty;
• The function library consists of the functions defined in the StateTest module and those defined in the XPath Core Function Library; and
• The set of namespace declarations is defined by the xmlns attribute on the context node.

This context means that an expression of the form count has the same meaning as one of the form /data/count. Moreover, the XPath type conversion rules result in count + 1 in meaning the exact same things as number(/data/count) + 1.

Data Model Examples

Here is the minimal state section that corresponds to the audio clip example above:

    <smil>
     <head>
      <state>
         <data xmlns="">
          <lastPlayed>0</lastPlayed>
         </data>
      </state>
      ...

Expression Constraints

The UserState module does not constrain the data model and expressions of the underlying language, unless specifically done so in a profile. For ease of reading most examples in this document use simple variable-style names, but richer constructs, such as setting attribute values with XPath or using compound values in Python, are allowed.

This section is informative.

Supported events for event-based timing are normatively specified in the profile. For ease of reading we include the relevant event defined in the SMIL 3.0 Language Profile here as well. The purpose of these events is to allow document authors to create documents (or sections of documents) that restart and re-evaluate conditional expressions whenever the values underlying the expressions have changed.

stateChange(ref)

Raised by the state element. The parameter is a reference to an item (or multiple items) in the data model. Whenever any of the data model items referenced by the parameter is changed this event is raised. The event does not bubble.

contentControlChange(attrname)

Raised by the root of the SMIL document when the named Content Control test values has changed. The list of allowed values for attrname is taken from the Content Control Module attribute names. The event does not bubble.

contentControlChange

Raised by the root of the SMIL document when any Content Control test value has changed. The event does not bubble.

Raising the stateChange event on the state element instead of on the data model element itself allows for external data models (which have a distinct xmlid-space) and on non-XML data models (depending on the expression language).

If any of the Content Control test values changes both the specific event and the general event are raised. This is because for some documents the author will want to react to a change in a specific parameter (bandwidth, screensize) only, whereas for other use cases the author may want to reconfigure the whole presentation on any change.

This section is informative.

The SMIL 3.0 StateSubmission Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

This section is informative.

This section introduces a method to save author defined state or to transmit it to an external server.

This section is informative.

The SMIL 3.0 Language Profile includes the StateSubmission module, and it defines that the submission element must occur in the head section.

This section is informative.

Here is an example of asynchronous submission: whenever the lastPlayed item changes because another clip has been played this fact is communicated to some server.

      <smil>
       <head>
        <state xml:id="stateid">
           <data xmlns="">
            <lastPlayed>0</lastPlayed>
           </data>
        </state>
        <submission xml:id="subid" action="http://www.example.com/savexmldoc" method="put" />
       </head>
       <body>
        <par>
         <send submission="subid" begin="stateid.stateChange(lastPlayed)" restart="always" />
         ...
         <seq end="... some interactive end condition ..." >
          <seq expr="lastPlayed &lt; 1">
           <audio src="chapter1.mp3" />
           <setvalue ref="lastPlayed" value="1" />
          </seq>
          <seq expr="lastPlayed &lt; 2">
           <audio src="chapter2.mp3" />
           <setvalue ref="lastPlayed" value="2" />
          </seq>
          <seq expr="lastPlayed &lt; 3">
           <audio src="chapter3.mp3" />
           <setvalue ref="lastPlayed" value="3" />
          </seq>
         </seq>
        </par>

In another presentation we could pick this value up again synchronously and use it.

    <smil>
     <head>
      <state>
      </state>
      <submission xml:id="subid" action="http://www.example.com/loadxmldoc" replace="instance" method="get" />
     </head>
       <body>
      <par>
       ...
       <seq >
        <send submission="subid" />
        <seq expr="lastPlayed &lt; 1">
         <audio src="chapter1.mp3" />
         <setvalue ref="lastPlayed" value="1" />
        </seq>
        <seq expr="lastPlayed &lt; 2">
         <audio src="chapter2.mp3" />
         <setvalue ref="lastPlayed" value="2" />
        </seq>
        <seq expr="lastPlayed &lt; 3">
         <audio src="chapter3.mp3" />
         <setvalue ref="lastPlayed" value="3" />
        </seq>
       </seq>
      </par>

That last example is actually a procedural roundabout way to get the same effect as using <state src="http://www.example.com/loadxmldoc" /> without submissions.

This section is informative.

The SMIL 3.0 StateInterpolation Module defined in this document is a new module which was not part of the SMIL 2.1 specification.

This section is informative

The SMIL 3.0 Language Profile includes the StateInterpolation module. It allows its use in the same set of attributes for which SMIL animation is allowed plus the src, href, clipBegin and clipEnd attributes. It disallows its use on the Timing and Synchronization attributes. Its use on other attributes is implementation-dependent.

This section is informative.

This SMIL 3.0 Language Profile example shows an icon corresponding to the current CPU on which the user views the presentation, or a default icon for an unknown CPU:

   <switch>
    <img src="cpu-icons/{smil-CPU()}.png" />
    <img src="cpu-icons/unknown.png" />
   </switch>