Send comments to Tom Kuo (tom@harmonia.com)
Author: Tom Kuo
revised 9 May 2001

Abstract

UIML can be used with a variety of vocabularies defining class and property names for parts in the user interface. It is desirable to label every UIML document to identify which vocabulary is used in that document. We recommend a convention in writing UIML documents that achieves this labeling.

In addition, a renderer for UIML documents will recognize some set of vocabularies (e.g., vocabularies for HTML 3.2 and HTML 4.0 but not a vocabulary for Java 1.3). UIML authors are free to extend these vocabularies with new UI widgets. There must be a way for a renderer to quickly tell if it can render the vocabulary specified in the UIML document. We propose a new attribute for <presentation>, named base, to accomplish this.

Motivation

Every UIML document uses a vocabulary. The vocabulary defines the legal class and property names that can be used for parts in a UIML document. The formal definition of a vocabulary is through a <presentation> element containing <d-class> elements. Each <d-class> defines a legal class name. Children of <d-class> define legal properties for that class.

There are two categories of vocabularies:

• Well known vocabularies with very widespread use, whose definition is posted on uiml.org, in uiml.org/toolkits. Examples are vocabularies for Java 1.3 AWT and Swing, HTML 3.2, WML, and VoiceXML. We will call these base vocabularies.
• Custom vocabularies that individuals, companies, or other organizations define. These may or may not be not posted on uiml.org. Probably they are posted on web sites around the world of interest to specific communities, or posted in a company's internal network, or not posted at all. We will call these custom vocabularies.
  • Typically a custom vocabulary extends a base vocabulary (e.g., a company creates custom Java UI classes that extend Swing classes). In this case the <presentation> element in a UIML document either contains a source attribute naming a base vocabulary, or contains a source attribute naming a <template> that in turn contains a <presentation> with a source attribute naming a base vocabulary, etc.
  • The highly unusual but possible exception is when someone creates a custom vocabulary from scratch that does not rely on any base vocabulary, but yet a renderer for some base vocabulary can render the custom vocabulary. For example, someone might create UI widget classes for Java from scratch that does not use AWT or Swing, but design the classes so that a renderer for UIML using the Java 1.3 or Swing base vocabulary can still render the custom classes.

This proposal addresses two problems in UIML.

Problem 1:

A renderer for UIML will recognize a base vocabulary. For example, a renderer could be created to display UIs using the Java 1.3 Swing and AWT toolkits. The renderer could also render custom classes that a UIML author creates that extend Swing classes. There should be some way to label the base vocabulary (e.g., java 1.3 Swing/AWT) that is used in a UIML document.

For example, when a renderer that translates UIML to HTML is given a UIML document, that renderer could use the base vocabulary label to quickly tell if the document uses the HTML vocabulary. If the document does not, then a clear error message can be printed. As a second example, an authoring tool for UIML needs to quickly identify which vocabulary is used, perhaps to display an appropriate pallete of user interface widgets for further editing of the document (e.g., a pallete of Java Swing objects if the file uses the Java 1.3 vocabulary).

Problem 2:

As custom UIML vocabularies are created, it is desirable to label each UIML document with the name and version of the custom vocabulary the document uses. So a convention is needed to label the actual vocabulary used.

Summary

So to summarize, two labels are needed:

• The base vocabulary, which is generally one that is well known and whose <presentation> must be posted on uiml.org.
• The actual vocabulary that is used, which is usually a base vocabulary or an extension of a base vocabulary.

Proposal to Solve Problem 1:
Adding "base" attribute to <presentation>

To easily determine the base language used within the UIML document, we propose addition of a new attribute to <presentation>, named base, to identify the base target language of the UIML document.

The proposed modification to the UIML DTD is the following according to the table below: (Yellow highlighted text denotes changes from UIML2_Od.dtd.)

          <!ELEMENT presentation (d-class*)
>
          <!ATTLIST presentation
                    id     NMTOKEN                    #IMPLIED
                    source CDATA                      #IMPLIED
                    base   CDATA                      #REQUIRED
                    how    (append|cascade|replace)   "replace"
                    export (hidden|optional|required) "optional">

The synatx of values for the "base" attribute must follow this convention:

<vocab-name>_<vocab-version>_<author-of-vocab>_<author's-version-of-vocab>

Several rules apply to base:

• The value of base is case insensitive.
• If the value of base is x, then the following URL must define x:uiml.org/toolkits/x.uiml. (Requests to post a new file should be sent to info@uiml.org.) This URL must contain a <presentation> element defining the classes and properties constituting vocabulary x.
• If a UIML document contains <presentation base="x"> (with or without the source attribute) then that document can be rendered by any renderer that implements vocabulary "uiml.org/toolkits/x.uiml". Therefore a renderer that implements vocabulary uiml.org/toolkits/Java_1.3_Harmonia_1.0.uiml can render a UIML document containing the following element, even though the renderer was written without knowledge of what is in vocabulary PrettySwing_1.0_AbleProgrammer_0.1.uiml:

  <presentation
      source="PrettySwing_1.0_AbleProgrammer_0.1.uiml#vocab"
      base="Java_1.3_Harmonia_1.0"/>
  

  (It is the responsibility of the UIML author to insure consistency between the values of the source and base attributes. For exmaple, the UIML author should not define class names mapped to HTML tags in PrettySwing_1.0_AbleProgrammer_0.1.uiml and then set base to a vocabulary for Java [e.g., Java_1.3_Harmonia_1.0].)
  
  A rendering engine is free to implement multiple vocabularies, and hence recognize multiple values of the base attribute.

• The vocabulary that a renderer actually uses to render a UIML document is given by the following table. The table assumes that the <presentation> element contains base="x" (recall that attribute base is mandatory).
  
  

Example usage of "base"

1. <presentation base="Java_1.3_Harmonia_1.0"/>
2. <presentation base="HTML_3.2_Harmonia_1.0"/>
3. <presentation base="GenericHJ_1.0_Harmonia_1.0"/>
4. <presentation base="Java_1.3_Harmonia_0.8"
                 source="PrettySwing_1.0_AbleProgrammer_0.1#vocab"/>

5. <presentation base="Java_1.3_Harmonia_0.8">
      <d-class>
         .
         .
      </d-class>
   </presentation>   

Proposal to Solve Problem 2:
Labeling Custom Vocabulary via source attribute in <presentation>

If a UIML document does not use a custom vocabulary, then skip this section.

Normally, when one creates a custom vocabulary, they create a .uiml file containing a <template> element, whose body is a <presentation> element. The body of the <presentation> contains <d-class> elements defining legal class names for the custom vocabulary. (We say "normally", because if this is not done, then the <presentation> element cannot be reused in multiple UIML documents.) In this case, the name of the UIML document should use the following syntax:

<custom-vocab-name>_<custom-vocab-version>_<your-organization's-name>_<your-version-of-vocab>.uiml#vocab

The line above requires that the <template> element in the UIML file contain id="vocab".

For example, if you developed a libary of classes that extend Java 1.3 Swing and called the library "PrettySwing", and the current version of PrettySwing was 1.0, and your name was AbleProgrammer, and this was the first UIML file you wrote to define the vocabulary (version 0.1) then you might name the custom vocabulary file PrettySwing_1.0_AbleProgrammer_0.1.uiml.

Any UIML documents that use this custom vocabulary should then contain the following line:

<presentation 
    source="PrettySwing_1.0_AbleProgrammer_0.1.uiml#vocab"
    base="Java_1.3_Harmonia_1.0"/>

Final Notes

Note that the value of the id attribute, if present in the <presentation> element, is not used in this proposal. Therefore a UIML author is free to set it to whatever value is convenient. It is typically used when a UIML document contains multiple <presentation> elements, and one them is selected by the renderer based on information outside the UIML document (e.g., as a command line option to the renderer).

© 2001 Harmonia, Inc. (all rights reserved)

© 1999-2001 UIML.org (all rights reserved)