PUC Smart Templates

This document describes the Smart Templates recognized by personal universal controllers (PUCs). Smart Templates are used in the specification of appliances for the PUC as a way of indicating where higher-level relationships exist beyond those that are describable in the current specification language.

As a general rule, interface generators are not required to understand any of the Smart Templates described in this document. This is why state and command information is an integral part of the Smart Templates description. If an interface generator does not know about a given template, then it can easily fallback to the states and commands that make up the template.

The states and commands also allow Smart Templates to be flexible. One template can be made up of a number of different combinations of states and commands, which reflects the different ways that an appliance might implement the functionality of a Smart Template. For example, a media playback control on a tape player will have play, stop, pause, fast-forward, and rewind modes. On a CD player, the same control would have play, stop, and pause, but have next track and previous track instead of fast-forward and rewind. The states and commands underlying a Smart Template allow such differentiation without requiring a number of different templates for playback controls. The interface generator that handles such a template must examine the states and commands that make up the template in order to create a control that matches the appliance and yet matches other instances of the same template.

The next section of this document shows how Smart Templates are specified within the existing specification language. A list of proposed templates is presented, and then detailed descriptions of those Smart Templates are shown.

Using Smart Templates in the PUC Specification Language

Smart Templates may be assigned by specifying the name of the template in the group's is-a attribute. To help interface generators recognize the components of the template, each state and command within a Smart Template is labeled with a particular name that is defined in advance for that template. Here are three examples of Smart Templates in a PUC specification:

Example #1

<group name="CountdownTimer" is-a="time-duration">
  <state name="Time">
    <type>
      <integer/>
    </type>

    <labels>
      <label>Countdown Timer</labels>
      <label>Timer</labels>
    </labels>
  </state>
</group>

Example #2

<state name="Time" is-a="time-duration">
  <type>
    <string/>
  </type>

  <labels>
    <label>Countdown Timer</labels>
    <label>Timer</labels>
  </labels>
</state>

Example #3

<group name="CountdownTimer" is-a="time-duration">
  <labels>
    <label>Countdown Timer</label>
    <label>Timer</label>
  </labels>

  <state name="Minutes">
    <type>
      <integer/>
    </type>

    <labels>
      <label>Minutes</labels>
      <label>Mins</labels>
    </labels>
  </state>

  <state name="Seconds">
    <type>
      <integer>
	<min>0</min>
	<max>60</max>
      </integer>
    </type>

    <labels>
      <label>Seconds</label>
      <label>Secs</label>
    </labels>
  </state>
</group>

These examples are based on the time-duration Smart Template. Note that in the first and third examples the group is labeled with the Smart Template being applied. In the second case, a state is labeled with a Smart Template directly (thus eliminating the need for an extra group). In the first and third examples, the state variables have particular names that are defined in advance by the detailed Smart Template description.

If a state is defined with a Smart Template group that an interface generator does not recognize (for example, perhaps the Smart Template was updated since the interface generator was built), then the interface generator is expected to render that state as it would normally.

Proposed Smart Templates

The following list of templates are those considered for inclusion in a PUC. Those that are linked have been defined in more detail, and may have been implemented in some interface generators.

address
date
date-time
four-way-dpad
four-way-dpad-with-enter
image
image-list
list-commands
media-controls
mute-mic
mute-speaker
power
telephone-dialpad
time-absolute
time-duration
volume
zoom-controls


Template Descriptions

These templates are currently defined:

• address
• date
• date-time
• four-way-dpad
• four-way-dpad-with-enter
• image
• image-list
• list-commands
• media-controls
• time-absolute
• time-duration
• zoom-controls

See the implementation notes for a particular type to check if it has been implemented in any interface generators.

address

Overview

Represents an address, like might be entered into a navigation system.

Revision History

Contents

This template only supports the Multi-State form. In the future, it might make sense to support a single state string form that contains a parsable address, but this is not required now.

There are no required states in this template. This allows the template to be used in a number of situations where a partial piece of an address is needed, such as zip code by itself. The different states in this template are:

StreetName

This state represents the name of the street. It may have a string or enumerated type. It must support the use of completions and server-side error correction, if either of those features are available.

ApartmentNumber

This state represents the number of an apartment or suite at this address. This state may have a string or integer type. When the integer is used, it may have type restrictions such as bounds or an increment. The labels of this state must be taken into account in order to know whether the number is for a suite, apartment, etc.

StreetNumber

This state represents the street number of the address. It must have an integer type, but restrictions such as bounding are optional. It must support the use of completions and server-side error correction, if either of those features are available.

City

This state represents the city of the address. It must have a string or enumerated state. It must support the use of completions and server-side error correction, if either of those features are available.

State

This state represents the state or province in which the address is located. It may have a string or enumerated type.

ZipCode

This state represents a zip code in the address. It may have a string, integer, or enumerated type. It must support the use of completions and server-side error correction, if either of those features are available.

Country

This state represents the country of the address. It may have a string or enumerated type. It must support the use of completions or server-side error correction, if either of those features are available.

Implementations

PocketPC

date

Overview

This template describes data that stores a date. This might be used by an appliance to store and display the current date, or to record a date in the future when some pre-defined action will be taken. This template currently supports both single state and multiple state instantiations.

Revision History

Contents

The contents of this Smart templkate may be represented in several different ways. One state with the string type may be used, or multiple states may be used. For the single state variable case there are the following type restrictions:

String

The state variable must have a string type. The value of the state variable must be a parseable date string in one of the ISO 8601 international date formats.

If multiple states are used to represent the date, they must have the following form:

Month

This state may have an integer type with bounds from 1-12, or an enumerated type with 12 items.

Day

This state must have an integer type ranging between 1 and 31. The maximum bound may also be linked to a state variable that gives the proper maximum for the given month. If the maximum is set to a constant value of 31, then the user interface will enforce the proper maximum for the given month and year.

Year

This state must have an integer type. Bounds on this variable are optional. Negative values in this state variable will be interpreted as years BC, and positive years as AD. Increments may also be specified for this state.

Implementations

In progress on PocketPC.

date-time

Overview

This template combines a date template with a time-absolute template to form a complete representation for dates and times together.

Revision History

Contents

The contents of this Smart template may be represented in several different ways. One state with the string type may be used, or the template may contain two groups that separately instantiate the date and time-aboslute smart templates. If one state variable is used, it has the following restrictions:

String

The state variable must have a string type. The value of the state variable must be a parseable date-time string in one of the ISO 8601 international date formats.

If two groups are used, then one of those groups must be tagged with date and the other must be tagged with time-absolute. These groups must conform to the restictions for these other Smart Templates.

Implementations

In progress on PocketPC.

four-way-dpad

Overview

This template represents a four-way directional control.

Revision History

Contents

This template may only be applied to a group that includes four commands. The commands must be:

Left

The command for the left button in the directional control.

Right

The command for the right button in the directional control.

Top

The command for the top button in the directional control.

Bottom

The command for the bottom button in the directional control.

Implementations

PocketPC.

four-way-dpad-with-enter

Overview

This template represents a four-way directional pad with an enter function.

Revision History

Contents

This template must include the four-way-dpad smart template and one extra command:

Enter

The enter command

Implementations

PocketPC.

image

Overview

This Smart Template represents any kind of image data, regardless of the underlying format.

Revision History

Contents

This Smart Template may be applied to a state or a group. If the template is applied to a group, then that group must contain one state with the name Image. The state must have the binary primitive type. This template should support the following parameters for the binary type:

arbitrary-scaling

This parameter indicates that the server can provide the image scaled to any size. If this parameter is defined, then the Smart Template should request the appropriate image size to fit in its allocated space.

fixed-height

The image will have a fixed height. The value of this parameter should be provided to the layout engine.

fixed-width

The image will have a fixed width. The value of this parameter should be provided to the layout engine.

minimum-height

The image may have any height larger than the value of this parameter.

minimum-width

The image may have any width larger than the value of this parameter.

Implementations

Complete for PocketPC and Smartphone.

image-list

Overview

This Smart Template represents a one-dimensional list of images, regardless of the underlying format of the images or the other variables in the list. It is expected that this template will use a conventional layout for showing a list of images (e.g. thumbnails) and pass any remaining variables in the list to interface generator for normal rendering.

Revision History

Contents

This Smart Template must be applied to a list group. That list group may contain any number of variables and commands, but one state variable must have a binary type and be named Image.

Implementations

Complete for PocketPC and Desktop.

list-commands

Overview

This template is for commands that manipulate list data, such as adding, deleting, or moving list items. This is the first example of a nested template, which means that the template must contains other templates. In this case, there is a list-commands template which may only contain list-add, list-remove, list-clear, list-move-after, or list-move-before templates.

One tricky aspect of the list-commands template is linking each template instance to the list that it manipulates. This is done by requiring that the template be at the same level and immediately precede the list group that it manipulates. We suggest that each pair of commands and list group be placed in their own group, but this is not required.

Revision History

Contents

The list-commands template only supports the multi-state form. The constituent templates list-add, list-remove, list-clear, list-move-after, and list-move-before must be single commands. Constituent templates may be used outside of the list-commands template.

As mentioned above, any instance of the list-commands template must be placed at the same level of the specification tree immediately preceding the list-group that the command modify. This requirement is also true of any of the consituent templates when used outside of the list-commands template.

The following are descriptions of the constituent templates:

list-add

Commands with this template should add a new item to the list. The server upon receiving the command should insert an item into the list at the appropriate location in the list. The template implementation can automatically display a dialog box in this case, or it may rely on the required-if infrastructure to determine whether an editing dialog box should be displayed.

list-remove

Commands with this template should delete an item from the list, preferably the currently selected item(s).

list-clear

Commands with this template should remove all items from the list.

list-move-after

Commands with this template should move the currently selected item(s) to the next higher index.

list-move-before

Commands with this template should move the currently selected item(s) to the next lower index.

Implementations

PocketPC

media-controls

Overview

This template represents the interactions that control the playback of any audio/visual media, such as a CD, MP3, or VHS tape. This template supports either state- or command-based representations of the controls, and also handles related functions such as Next Track and Previous Track.

Revision History

Contents

This Smart Template may represent the controls as a single state variable and/or several commands. The state-based representation must have an enumerated type with standardized labels mapped to each value in the type in the valueLabels section. The state must have the name Mode. The labels are described below. Other labels may be included in addition to the standardized ones for the benefit of interface generators that don't recognize this Smart Template.

Stop

This label identifies the state when the media is stopped.

Play

This label identifies the state when the media is playing.

Pause

This label identifies the state when the media is paused.

Rewind

This label identifies the state when the media is rewinding.

Fast-Forward

This label identifies the state when the media is fast-forwarding.

Record

This label identifies the state when media is being recorded.

If no state information is available from the appliance, a command-based description may be used instead. Such a representation must include one or more of the following commands. These commands should not be included if the Mode state is included in the description. Allowable commands are:

Play

When this command is activated, the appliance should begin playing.

Stop

When this command is activated, the appliance should stop playing.

Pause

When this command is activated, the appliance should pause playback.

Rewind

When this command is activated, the appliance should begin rewinding.

FastFwd

When this command is activated, the appliance should begin fast-forwarding.

Record

When this command is activated, the appliance should begin recording.

In addition to having either the state or a set of commands, additional states and commands may be specified that will be integrated with the rest of the playback controls.

Commands

NextTrack

When this command is activated, the next track should be selected.

PrevTrack

When this command is activated, the previous track should be selected.

NOTE: Other playback modes may be possible and should probably be considered. These include:

• Reverse Play
• Fast-Forward while Playing vs. while Stopped
• Rewind (same thing)
• Different speeds of fast-forward and rewind
• Play New (for answering machines)

Implementations

Complete for PocketPC, Smartphone and Desktop. Smartphone implementation is limited and should probably be re-visited.

time-absolute

Overview

This template specifies absolute time, i.e. time-of-day. This includes the time value along with parameters of the time such as the time zone, 12/24 hour mode, etc.

Revision History

Contents

This template supports both the single and multi-state specification methods. The single state method may only represent an absolute time value in 24-hour units. This value may be rendered as a 12-hour time value with AM/PM depending on the configuration of the user's device. The multi-state method may also include parameters for the time value, as described below.

The single state form may have one of four primitive types:

Integer

The value of the state variable should contain the number of seconds since midnight. No increment is allowed.

String

The value of the state variable must be of the form: hh:mm:ss or hh:mm, where h = hours, m = minutes, and s = seconds. Note that unlike the time-duration template, digits may be omitted if they are not significant. In other words, 1:45:56 has the same meaning as 01:45:56. An arbitrary number of digits may be used for representing the fractions of a second.

If multiple states are used to represent the time-absolute template, then they must have the following form:

Time

This state specifies the time. It may have any of the types listed above for the single-state format. Either this state, or some combination of the hour/minute/etc. states below may be included, but not both.

Hours

This state must have an integer type. The minimum and maximum must be 0-23. This state is required if the Time state is not specified, and may not be included if the Time state is defined.

Minutes

This state must have an integer type ranging from 0 to 59. This state must be specified if the Time state is specified, and may not be included if the Time state is defined.

Seconds

This state must have an integer type ranging from 0 to 59. This state must not be included if the Time state, but is otherwise optional.

TimeZone

This state optionally specified the time zone. It must have an enumerated type where each value has at least one label of the form GMT-X or GMT+X, where X specifies the number of hours from Greenwich Mean Time. The labels should also include common names for each time zone (such as "Eastern" for GMT-5) to ensure that generators not equipped with this Smart Template can still render an understandable interface.

DaylightSavings

This state optionally specifies whether it is currently daylight savings time. This state must have a boolean type.

HourMode

This state optionally specifies whether the time is specified in 24 or 12 hour mode. The state must have a boolean type with labels for each value. One value must be labeled as "12Hr" and the other as "24Hr". If this state exists, it should be linked to the rendering for the time value (if included).

Increments may be specified only for the least significant unit. For example, if a particular template defines an hours state and a minutes state then an increment may be specified only for the minutes state. Another template that defines all four of the possible states may only have an increment specified for the fraction state.

Implementations

PocketPC

time-duration

Overview

This template describes data that stores a duration of time. This could be used by media player devices to describe the length of a song or the current playback point in a song, or by microwaves to display the amount of cooking time that remains. This template supports resolutions in the fractions of a second, seconds, minutes and hours. The fractions of a second resolution is purposely left ambiguous and may be defined by the specification designer by defining a range for the state. Milliseconds might be the fraction used for a timer application, whereas frame number might be used by a VCR or other video application.

Revision History

Contents

The contents of this Smart Template may be represented in several different ways. One state with one of four primitive types may be used, or multiple states with an integer type may be used. If one state is used, the Smart Template must be applied directly to that state (see Example #2 above). The allowable types are:

Integer

The value of the state variable should contain the number of seconds in the time duration.

Fixed Point

The pointpos may be set as necessary. The value of the state variable should contain the number of seconds in the time duration. The decimal component represents the fractions of a second that have elapsed.

Floating Point

The value of the state variable should contain the number of seconds in the time duration, with the decimal component representing the fractions of seconds in the duration.

String

The value of the state variable must be of the form: hh:mm:ss:fff, mm:ss:fff, hh:mm:ss, or mm:ss, where h = hours, m = minutes, s = seconds, and f = fractions of a second. Note that it is not optional to omit digits if they are not significant. In other words, 1:45:56 is not valid, but both 01:45:56 and 01:45:560 are. Also note that three digits are required for fractions of second component, if it is used.

If multiple states are used to represent the time-duration, they must have the following form:

Hours

This state must have an integer type. A minimum and maximum may be optionally specified.

Minutes

This state must have an integer type ranging between 0 and 60 if the Hours state is specified. Minimum and maximum are optional if Hours is not specified. This state must be included if both the Hours and Seconds states are specified.

Seconds

This state must have an integer type ranging between 0 and 60 if the Minutes state is specified. Minimum and maximum are optional if Minutes is not specified. This state must be included if both the Minutes and Fraction states are specified.

Fraction

This state must have an integer type. The ranges may be specified to fit the type of fraction being used.

Increments may be specified only for the least significant unit. For example, if a particular template defines an hours state and a minutes state then an increment may be specified only for the minutes state. Another template that defines all four of the possible states may only have an increment specified for the fraction state.

Implementations

Complete for PocketPC, Desktop and Smartphone.

A specification for testing time-duration Smart Template handlers is available in the repository at specs/time-duration.xml.

zoom-controls

Overview

This template represents controls for zooming something on the appliance.

Revision History

Contents

This template may include two commands, only one of which must be included:

In

The zoom in command.

Out

The zoom out command.

Implementations

PocketPC