Timesheets: XML Timing Language

3.1 Timesheet element

An XML document may contain one or more Timesheets. The elements under these Timesheets are referred to as Timesheet elements. A timesheet element may be a time container, which has other timesheet elements as its children, or an item element, which references to one or more Media elements (cf. Section 3.2 Media element). Timesheet elements are said to be active when the they have a resolved activation time, otherwise they are inactive.

3.2 Media element

Media element is an element that takes part in the layout of the XML document. They usually represent visual or audible content that is shown when the document is presented. Also, elements that control the structure of the document (div element in XHTML, for example) are media elements. Media element is said to be visible when the contents of the element is either visible or audible.

Media elements can be divided into two separate groups according to the type of content they represent.

Static elements

Static media elements represent content that has no implicit duration. These elements include the document structure elements and elements defining textual content and images.

Dynamic elements

Dynamic media elements represent content that may have an implicitely defined duration. This type of content include video and audio. In some cases, the duration of dynamic media may also be indefinite (streaming content, for example).

From the timesheet's point of view, the static and dynamic elements are treated differently. For the static elements, the author has to explicitely define the duration, otherwise the element will be shown an indefinitely long time. The duration of the dynamic elements is defined, so the author doesn't need to explicitely define it for them. Dynamic elements stop and become inactive when their content stops.

4.1 The begin attribute

The begin defines the start time of the element, relative to the scheduled activation of the element. Under a parallel time container the time is relative to the beginning of the parent container. Under sequential and exclusive containers the time is relative to the time when the parent container activated the element. The attribute is not mandatory, omitting it equals the attribute value "0s".

4.2 The dur attribute

The dur defines the duration of the element. The duration is relative to the start time of the element. If this attribute is omitted, the duration depends on the type of the element. For time containers, this means that the duration is unspecified and the container will stop after all it's children have stopped. For the item element, the interpretation of an unspecified duration depends on the type of the media element the item is referencing to. For static elements the duration is indefinite and the element will stay active unless the parent element inactivates it. For dynamic content the duration will be the duration of the content itself. An item referencing to multiple media elements has a duration of the longest lasting dynamic element, or indefinite, if any of the referenced elements are static. The duration is always overridden with the duration of the parent container.

4.3 Syntax of the time related attributes

The begin and dur attributes specify points on the time-line when some action should happen, either activating or inactivating an element and it's children. These points can be specified as an offset from some other point or an offset from a certain document event, or as a combination of both. The values can also be set to "indefinite". The syntax for the different cases are explained below.

Time offset

Denoted with a numerical value followed by the unit of time, which can be either s for seconds or ms for milliseconds. The numerical value must be positive.

Event offset

An offset from an event from the DOM that can, for example, be triggered by user action or some other timesheet element. The syntax for an event offset is built from the event's target id, event's type and optionally the time offset from the catching of the event. The target and the type of the event are separated by a dot (.) and the time offset is added with a plus (+) sign. For example, to wait for a DOMActivate event of an element that has an id link1 and specifying that the action is committed two seconds after the event, the value of the attribute would be "link1.DOMActivate+2s". The time offset part of the syntax is optional, omitting it is equal to setting the offset to zero seconds. To specify a non-existing target is an error.

Multiple values

The values are separated with comma (,). There can be multiple event offset values, but only one time offset value. If multiple time offset values are specified, only the first is taken into account while the rest are ignored.

4.4 The repeat attribute

The repeat defines the repeat count for the element. When the element stops and the current repeat count is positive, the element is activated again and actions of the element are repeated. The repeat attribute only has meaning with time containers and items that reference to dynamic content, since repeating static content has no effect. The dur attribute specifies the total duration of the element, repetitions included. This means that, for example, if the duration is set to one and half times the original duration of the element and the repeat value is more than one, the element is shown one and a half times, since the dur attribute overrides the actual duration of the element.

The repeat attribute can also have value "indefinite", which means that the element will be repeated until it is stopped by the time container or the value of dur attribute.

5.1 The timesheet element

The timesheet element is the parent element for all the other elements of the timing language. The children of timesheet are scheduled similarily to par element. The common attributes, defined in the attributes section have no meaning when used with the timesheet element. Instead, two optional attributes are defined for the element.

src

The value of src tells the location of an external timesheet, which will be appended to the end of the local timesheet. With this attribute a common timesheet can be reused in multiple documents without the need to rewrite it every time.

media

The media attribute is used for selecting the most suitable timesheet for current media device. It works similarily to the @media rule in the CSS stylesheets [CSS 2.1].

5.2 The par element

Parallel time container. All the children of the par are activated simultaneously and the duration of the container, if not specified with the dur attribute will be the same as with the child that has the longest duration of all the children of the container. This element is similar to the par element specified in the SMIL 2.0 Timing and Synchronization Module [SMIL 2.0 Timing].

5.3 The seq element

Sequential time controller. The children of seq are displayed sequentially so, that next child is activated as soon as the previous child finishes. The first child is activated when the parent container starts. Only one child of seq can be shown simultaneously. Total duration of the seq is either specified by the dur attribute, or if it is omitted, by the sum of durations of all the children of the element. If a child of the container has an indefinite duration, the following children will never be activated and the duration of the container will be indefinite. This element is similar to the seq element specified in the SMIL 2.0 Timing and Synchronization Module [SMIL 2.0 Timing].

5.4 The excl element

The exclusive time container can have only one child active at a certain moment, similarly to the sequential time container. The excl doesn't provide any other synchronization or scheduling to its children, it only assures that no multiple children are active simultaneously. When a child starts according to its begin attribute, the container deactivates any other child that may be active.

Unlike the other time containers, excl has implicitely indefinite duration, since there is no defined situation when the container should end. The par ends when all the children has stopped, and the seq when the last child finishes. Neither approach is applicable to the excl, since the temporal order of the children is unknown.

The excl is a special case of the seq where the container's duration is set to indefinite and all the children have indefinite or interactive begin times. It is also a simplified version of the excl element defined in the SMIL 2.0 Timing and Synchronization Module [SMIL 2.0 Timing].

5.5 The item element

The item element implements the actual connection between the timesheet and the document. It can reference a media element or a set of elements by the element's tag, id or class; the syntax and processing is similar to the CSS selector syntax. The item element has three attributes, in addition to the common attributes. The select attribute gives the references to the media elements, the prefetch attribute controls the loading of the referenced elements and the class can be used to change the properties of the referenced elements.

The select attribute

The select attribute links the timesheet to the document. The attribute follows the same syntax and processing as the CSS selectors, so that the elements can be referenced by their name, id or class, or a more complex combination of the selectors. If the attribute targets multiple elements in the document, item controls all of them. The attribute value can also specify a comma separated list of selectors.

The prefetch attribute

The prefetch controls the loading of the resources needed by the elements referenced by the item element. Some resources, like audio, video and big images, can be quite big in size and fetching them on the fly while the timesheet is already running could skew the timing of the whole timesheet. With the prefetch attribute the author can mark certain elements and their resources to be prefetched to the memory before the timesheet is started. This way the resources can be shown precisely at the specified moment of time. If the attribute is omitted or set to false, the resources are loaded just before the item is activated. When the attribute is set to true the resources are loaded into the memory before the timesheet and the timeline is started.

7.1 Internal events

Internal events are dispatched from within the timesheets. They can be used by other elements in the timesheet to create relations between different parts of the timeline. The events specified are begin event, which is dispatched when an element starts and end event, which is dispatched when element stops.

7.2 User events

User events are triggered by the actions that user makes. A typical example is that the user clicks on a link in the document, and thus a DOMActivate event is dispatched [DOM Events].

7.3 Event semantics

A timesheet element is set to listen to a certain event by specifying the event's target and type by either begin or dur attribute. When specified by the begin attribute, an inactive or active but not yet started element will be started when it receives the specified event. This may involve the activation and starting of the parent elements as well, which can require some special scheduling to be done on the upper level of the DOM tree. Consider Figure 2 as an example. At a certain time, the item with the id "1" is active. This means that the second child of the seq (i.e., the par element) can't be active. Next, the item number "3" gets an event, which it is set to listen to by the begin attribute. To activate itself, the element must first inform its parent that it is going to start. The parent (i.e., the par element) is also inactive, so it informs its parent of the activation. The parent seq element then stops the excl element and its children to allow the par element to start, and par element then activates its children according to the definition.

Figure 2: the affect of event on a timesheet.

When the element is specified to stop according to an event, it doesn't cause that much processing in the timesheet. The element informs its parent that it has stopped and parent then decides what should happen next. Of course, some other element could be waiting to start according to the end event from the particular element.

7.4 Additional events

There are also four additional events that are specified for the seq element. They are select-next, select-prev, select-first and select-last. These are used to select a certain child of the seq element, which facilitates the creation of presentations where the user can have control of the progression of the timeline, for example, a slide show. It should be possible to add later more additional events to any other elements of the timesheet.

8.1 Simple without events

This example shows a document that could be a single slide in a slide show. A new bullet is shown every two seconds.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:time="http://www.x-smiles.org/2004/timesheet">

<head>
  <style type="text/css">
  ...
  </style>

  <time:timesheet>
    <time:par>
      <time:item select="#bullet1" begin="2s"/>
      <time:item select="#bullet2" begin="4s"/>
      <time:item select="#bullet3" begin="6s"/>
      <time:item select="#bullet4" begin="8s"/>
    </time:par>
  </time:timesheet>
</head>

<body>
  <div id="content">
    <p id="title">Introduction</p>
    <p id="bullet1">o Some intro to WLAN</p>
    <p id="bullet2">o Some intro to WLAN</p>
    <p id="bullet3">- Subbullet</p>
    <p id="bullet4">- Subbullet</p>
    <p id="pagenum">2</p>
  </div>
</body>
</html>

8.2 With internal events

Next example is a picture show with captions for each image shown simultaneously. The new image is shown every five seconds, which dispatches a begin event that is listened by the corresponding item under the exclusive time container. The exclusive time container takes care that there can be only one caption active at a certain time. If the selection of an image is changed later, there is no need to touch the selection of captions.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:time="http://www.x-smiles.org/2004/timesheet">

<head>
  <style type="text/css">
  ...
  </style>

  <time:timesheet>
    <time:par>
      <time:seq>
        <time:item select="image1" id="img1" dur="5s"/>
        <time:item select="image2" id="img2" dur="5s"/>
        <time:item select="image3" id="img3" dur="5s"/>
	...
      </time:seq>
      <time:excl>
        <time:item select="text1" begin="img1.begin"/>
        <time:item select="text2" begin="img2.begin"/>
        <time:item select="text3" begin="img3.begin"/>
	...
      </time:excl>
    </time:par>
  </time:timesheet>
</head>

<body>
  <div>
    <img src="image1.jpg" id="image1"/>
    <img src="image2.jpg" id="image2"/>
    <img src="image3.jpg" id="image3"/>
    ...
    <p id="text1">Text 1</p>
    <p id="text2">Text 1</p>
    <p id="text3">Text 1</p>
    ...
  </div>
</body>
</html>

8.3 With user events

This is an extended version of the previous example. In this version, the user has full control of progression of the show. When document is loaded, there's a welcome page that suggest the user to click on a link to start the show. Showing the pictures is not done automatically this time, instead the user must click on links "Next" or "Previous" to navigate through the show. At any time, the user can also jump to the beginning or the end of the presentation.

The start and end pages listen to DOMActivate event, which is dispatched when a user clicks a link. The forward/backward navigation can't use the same event, the seq element listens to events select-next and select-prev instead (cf. Section 7.4 Additional events). In this example, the XForms [XForms] is used to dispatch the events.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:time="http://www.x-smiles.org/2004/timesheet"
      xmlns:ev="http://www.w3.org/2001/xml-events"
      xmlns:xforms="http://www.w3.org/2002/xforms">

<head>
  <style type="text/css">
  ...
  </style>

  <time:timesheet>
    <time:seq>
      <time:item select="#start-div" begin="0s,home.DOMActivate"/>
      <time:par begin="show.DOMActivate">
        <time:seq id="imageshow">
          <time:item select="#image1" id="img1"/>
          <time:item select="#image2" id="img2"/>
          <time:item select="#image3" id="img3"/>
  	  ...
        </time:seq>
        <time:excl>
          <time:item select="#text1" begin="img1.begin"/>
          <time:item select="#text2" begin="img2.begin"/>
          <time:item select="#text3" begin="img3.begin"/>
	  ...
        </time:excl>
	<time:item select="#linkdiv"/>
      </time:par>
      <time:item select="#end-div" begin="end.DOMActivate"/>
    </time:seq>
  </time:timesheet>
</head>

<body>
  <div id="start-div">
    <a href="" id="show" ev:event="DOMActivate" 
    ev:defaultAction="cancel">Start show</a>
  </div/>

  <div>
    <img src="image1.jpg" id="image1"/>
    <img src="image2.jpg" id="image2"/>
    <img src="image3.jpg" id="image3"/>
    ...
    <p id="text1">Text 1</p>
    <p id="text2">Text 1</p>
    <p id="text3">Text 1</p>
    ...
    <div id="linkdiv">
      <a href="">
        Previous
        <xforms:dispatch name="select-prev" target="imageshow" 
        ev:event="DOMActivate" ev:defaultAction="cancel"/>
      </a>
      <a href="">
        Next
        <xforms:dispatch name="select-next" target="imageshow" 
        ev:event="DOMActivate" ev:defaultAction="cancel"/>
      </a>
      <a href="" id="home" ev:event="DOMActivate" 
      ev:defaultAction="cancel">Home</a>
      <a href="" id="end" ev:event="DOMActivate" 
      ev:defaultAction="cancel">End show</a>
    </div>
  </div>

  <div id="end-div">
    <h1>Thanks for watching</h1>
    <a href="" id="home" ev:event="DOMActivate" 
    ev:defaultAction="cancel">Watch again</a>
  </div/>
</body>
</html>