24. XHTML Object Module

This section is normative.

The Object Module provides elements for general-purpose object inclusion; this includes images and other media, as well as executable content. Specifically, the Object Module supports:

When this module is used, it adds the object element to the Text content set of the Text module.

Implementation: RELAX NG

24.1. The object element

24.1.1. Defining terminology

The following terms are used throughout this section.

object src (source)

The file that is to be processed, such as an audio file, or image file. The actual content to be processed.

object handler

The mechanism that will be used to process the object data. The mechanism could be the user agent or an external application.

object element

This refers to the actual XHTML coding, including the allowable attributes.

instantiation

Refers to the plug-in handler, and the need to create a window, modify the user interface, allocate memory, etc.

24.1.2. Basic Information for Object Handlers

Most user agents have built-in mechanisms for processing common data types such as text, and various image types. In some instances the user agent may pass the processing to an external application. Generally, a user agent will attempt to process the object declaration, otherwise it may invoke an external application, which are normally referred to as "plug-ins".

In the most general case, an author should specify three types of information:

• The location of the object data (the src attribute). The author must direct the object handler to the actual physical location of the object data, otherwise the object handler will not be able to process the request.
• The media type associated with the object data (the type attribute). For instance, if the author prefers that a particular object handler be used to process the data, they may specify a media type that is associated to a specific object handler.
• Additional values required for the appropriate processing of the object data by the object handler at run-time (via the param element). Some instances may process more appropriately if the object handler is passed initial process instructions. For example, the author can specify whether a video should automatically start or wait until the entire data file has been downloaded.

The object element allows authors to specify all three types of information, but authors may not have to specify all three at once. For example, some object element instances may not require src (e.g., a self-contained applet that performs a small animation). Others may not require media type information, i.e., the user agent itself may already know how to process that type of data. Still others may not require run-time initialization.

The object element may also appear in the content of the head element. Since user agents generally do not render elements in the head, authors should ensure that any object element in the head does not specify content that is expected to be made available to the user.

24.1.3. Rules for processing objects

A user agent must interpret an object element according to the following precedence rules:

1. The user agent MUST first try to process the object element. It should not process the embedded contents, but it must examine them for definitions of param elements (see object initialization) or elements that take advantage of the Map attribute collection.
2. If the user agent is not able to process the object for whatever reason (configured not to, lack of resources, wrong architecture, etc.), it MUST try to process its contents.

When a user agent is able to successfully process an object element it MUST not attempt to process inner elements.

If a user agent cannot process an object element or a set of nested objects, and the author did not provide alternate text, the user agent SHOULD NOT supply any additional information. It is the responsibility of the author to supply additional or alternate information. It may be the intent of the author to not provide additional information if the object cannot be processed.

The user agent SHOULD attempt to process the outer object to its fullest extent before cascading to a nested object. For example, if the author provided information that could be used to download an external application to be used to process the object, then the user agent SHOULD attempt to download and install the application. If the user selects to not install the application, the user agent SHOULD continue to process the nested object or objects, if they exist.

The following example shows a minimally coded object element. The src attribute specifies the location of the object data and the srctype attribute specifies the media type associated with the object data:

<object src="http://www.example.com/foo.mp3" srctype="audio/mpeg">
    <em>alternate text</em>
</object>

Note that the MP3 file will be processed as soon as the object handler interprets this object element declaration. It is possible to delay processing of an object through the use of additional values defined within the param element (described later). It may also be delayed by the use of the declare attribute.

The following example shows an object element coded to process an image. The src attribute specifies the location of the object data, in this case the image to be processed, and the srctype attribute specifies the media type associated with the object data:

<object src="http://www.example.com/foo.jpg" srctype="image/jpeg">
   <em>alternate text</em>
</object>

The following example shows how an applet element can be converted to an object element. The codebase attribute is replaced with the xml:base attribute. The code attribute is replaced with the src attribute. The width and the height of the applet are defined using CSS. The param elements are not modified since the values within the param elements are passed directly to the external application. If a particular version reference is required, that would be appended to the content of the type attribute. For example, type="application/x-java-applet;version=1.4.1"

If the archive attribute is used, the object handler should process the search order by interpreting the archive attribute value first and then the xml:base attribute value.

<applet
  codebase="http://www.example.com/applets/classes"
  code="Clock.class"
  width="150"
  height="150">
    <param name="bgcolor" value="ffffff"/>
    <param name="border" value="5"/>
    <param name="ccolor" value="dddddd"/>
    <param name="cfont" value="TimesRoman|BOLD|18"/>
    <param name="delay" value="100"/>
    <param name="hhcolor" value="0000ff"/>
    <param name="link" value="http://www.example.com/"/>
    <param name="mhcolor" value="00ff00"/>
    <param name="ncolor" value="000000"/>
    <param name="nradius" value="80"/>
    <param name="shcolor" value="ff0000"/>
</applet>

<style type="text/css">
#obj1 {width:150px; height:150px;}
</style>
...

<object id="obj1"
  xml:base="http://www.example.com/applets/classes"
  srctype="application/x-java-applet"
  src="Clock.class">
    <param  name="delay"   value="100"/>
    <param  name="link"    value="http://www.example.com/"/>
    <param  name="border"  value="5"/>
    <param  name="nradius" value="80"/>
    <param  name="cfont"   value="TimesRoman|BOLD|18"/>
    <param  name="bgcolor" value="ddddff"/>
    <param  name="shcolor" value="ff0000"/>
    <param  name="mhcolor" value="00ff00"/>
    <param  name="hhcolor" value="0000ff"/>
    <param  name="ccolor"  value="dddddd"/>
    <param  name="ncolor"  value="000000"/>
    <em>alternate text</em>

</object>

Authors should always include alternate text as the content of the object element declaration when an embedded object is not defined.

The following example demonstrates how alternate text may be used within an object element.

<object src="http://www.example.com/foo.mp3" srctype="audio/mpeg">
   A really cool audio file. If you want to download and install
   a plug-in to listen to this file, please go to
   <a href="http://www.example.com">www.example.com</a>
</object>

In the following example, we embed several object element declarations to illustrate how alternate processing works. In the following order: (1) an Earth applet, (2) an animation of the Earth, (3) an image of the Earth, (4) alternate text.

<!-- First, try the applet -->
<object
    src="http://www.example.com/applets/classes/TheEarth.class"
    srctype="application/x-java-applet">

      <!-- Else, try the video -->
      <object
          src="TheEarth.mpeg"
          srctype="video/mpeg"
          xml:base="http://www.example.com/videos/">

            <!-- Else, try the image -->
            <object
                src="TheEarth.png"
                srctype="image/png"
                xml:base="http://www.example.com/images/">

                <!-- Else process the alternate text -->
                The <strong>Earth</strong> as seen from space.
            </object>
      </object>
</object>

The outermost object element declaration specifies an applet that requires no initial values, the src attribute points to the applet class file, and the srctype attribute defines the media type. An xml:base attribute could have been used to point to the base location to access the class file. In this example, however, the src attribute value contains an absolute URL so the xml:base attribute was not required. An archive attribute could have been used if the author needed to include any associated files. The second object element declaration specifies an MPEG animation, and the xml:base attribute defines the location of the object data defined in the src attribute. We also set the srctype attribute so that a user agent can determine if it has the capability to process the object data or to invoke an external application to process the MPEG. The third object element declaration specifies a PNG file and furnishes alternate text in case all other mechanisms fail.

24.2. The param element

param elements specify a set of values that may be required to process the object data by an object handler at run-time. Any number of param elements may appear in the content of an object element, in any order, but must be placed at the start of the content of the enclosing object element, with the exception of optional caption and standby elements.

The syntax of names and values is assumed to be understood by the user agent or the external application that will process the object data. This document does not specify how object handlers should retrieve name/value pairs nor how they should interpret parameter names that appear twice.

The user agent or the external application can utilize the param element name/value pairs to pass unique datapoints to trigger specific functions or actions. For example, the user agent may wish to trigger an external application download if the user does not have an appropriate application installed on their system.

We return to the clock example to illustrate the use of the param element. For example, suppose that the applet is able to handle two run-time parameters that define its initial height and width. We can set the initial dimensions to 40x40 pixels with two param elements.

<object 
    src="http://www.example.com/myclock.class"
    srctype="application/x-java-applet">
        <param name="height" value="40" valuetype="data" />
        <param name="width" value="40" valuetype="data" />
        This user agent cannot process a java applet.
</object>

In the following example, run-time data for the object's "Init_values" parameter is specified as an external resource (a GIF file). The value of the valuetype attribute is thus set to "ref" and the value is a URI designating the resource.

<object
    src="http://www.example.com/gifappli"
    srctype="image/gif">
        <standby>Loading Elvis...</standby>
        <param name="Init_values"
            value="./images/elvis.gif"
            valuetype="ref" />
        Elvis lives!
</object>

Note that we have also set the standby element so that the object handler may display a message while the object data is downloading.

When an object element is processed, the user agent must search the content for only those param elements that are direct children and "feed" them to the object handler.

Thus, in the following example, if "obj1" is processed, then the name/value content of "param1" applies to "obj1" (and not "obj2"). If "obj1" is not processed and "obj2" is, "param1" is ignored, and the name/value content of "param2" applies to "obj2". If neither object element is processed, neither param name/value content applies.

<object
    src="obj1"
    srctype="application/x-something">
    <param name="param1" value="value1" />
    <object
        src="obj2"
        srctype="application/x-something">
        <param name="param2" value="value2" />
        This user agent cannot process this application.
    </object>
</object>

24.2.1. Referencing object data

The location of an object's data is given by a URI. The URI may be either an absolute URI or a relative URI. If the URI is relative, it may be based from the referring document location or from the xml:base attribute location.

In the following example, we insert a video clip into an XHTML document.

<object
    src="mymovie.mpg"
    srctype="video/mpeg">
    A film showing how to open the printer to replace the cartridge.
</object>

By setting the srctype attribute, a user agent can determine whether to retrieve the external application based on its ability to do so. The location of the object data is relative to the referencing document, in this example the object data would need to exist within the same directory.

The following example specifies a base location via the xml:base attribute. The src attribute defines the data to process.

<object
    xml:base="http://www.example.com/"
    src="mymovie.mpg"
    srctype="video/mpeg">
    This user agent cannot process this movie.
</object>

24.2.2. Object element declarations and instantiations

The following example is for illustrative purposes only. When a document is designed to contain more than one instance of the same object data, it is possible to separate the declaration of the object from the references to the object data. Doing so has several advantages:

• The object data may be retrieved from the network by the object handler one time (during the declaration) and reused for each additional reference to that object data.
• It is possible to reference the object data from a location other than the object element in which it was defined, for example, from a link.
• It is possible to specify an object data as run-time data for other object element declarations.

To declare an object element so that it is not executed when read by the object handler, set the boolean declare attribute in the object element. At the same time, authors must identify the object declaration by setting the id attribute in the object element to a unique value. Later processing of the object data will refer to this identifier.

A declared object element must appear in a document before the first time the object data is referenced. For example, the declaring object element must appear before a link referencing the object data.

When an object element is defined with the declare attribute, the object handler is instantiated every time an element refers to that object data later in the document. The references will require the object data to be processed (e.g., a link that refers to it is activated, an object element that refers to it is activated, etc.).

In the following example, we declare an object element and cause the object handler to be instantiated by referring to it from a link. Thus, the object data can be activated by clicking on some highlighted text, for example.

<object
    declare="declare"
    id="earth.declaration" 
    src="TheEarth.mpg" 
    srctype="video/mpeg">
    The <strong>Earth</strong> as seen from space.
</object>
<em>...later in the document...</em>
<p>A neat <a href="#earth.declaration">animation of The Earth!</a></p>

In the previous example, when the document is initially loaded the object data should not be processed. If this was to be processed within a visual user agent, the object data would not be displayed. When the user selects the anchor data, the object data would then be initialized and displayed. This would also be the case for an audio file, where the file would be instantiated but would not be processed. Selecting the anchor data would then trigger the audio file to be processed.

User agents that do not support the declare attribute must process the contents of the object element.

24.3. The standby element

The standby element specifies a message that a user agent may render while loading the object's implementation and data.