14. 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 Inline content set of the Inline Text module.

Implementation: RELAX NG

14.1. The object element

14.1.1. Defining terminology

The following terms will be used throughout this section.

object data

The file that is to be processed, such as an mp3, or a .gif 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.

14.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 (gif, jpg and png for example) 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 data 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 mime 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 mime 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 data (e.g., a self-contained applet that performs a small animation). Others may not require mime type information, i.e., the user agent itself may already know how to process that type of data (e.g., GIF images). Still others may not require run-time initialization.

Authors specify an object's mime type and the location of the data to be processed via the object element. To specify run-time values, however, authors use the param element, which is discussed in the section on object initialization.

The object element may also appear in the content of the head element. Since user agents generally do not process elements in the head, authors should ensure that any object element in the head does not specify content that may be processed. Please consult the section on sharing frame data for an example of including the object element in the head element.

Please consult the section on form controls for information about object elements in forms.

14.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 in case there are param elements (see object initialization) or elements that take advantage of the Map attribute collection defined.
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.

Authors should not include content in object elements that appear in the head element.

When a user agent is able to successfully process an object element it MUST not attempt to process inner elements. For example, if the following code is encountered:

<object ... pointing to objectdataA>
<object ... pointing to objectdataB>
<p>alternate text</p>
</object>
</object>

When the user agent encounters objectdataA and is able to process that object element, then all nested elements (except for applicable param elements) MUST be ignored.

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 dropping 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.

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

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

<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" 
  type="application/x-java-applet" 
  data="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. If an author includes alternate text and an embedded object, the object handler may process both the text and the embedded object. The alternate text will provide the user a hint in cases where the object handler cannot process the object data. The author should also consider supplying a link to the location where the external application may be downloaded in case the user does not have the external application installed.

<object data="http://www.example.com/foo.mp3" type="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>

One significant consequence of the object element's design is that it offers a mechanism for specifying alternate object processing; each embedded object element declaration may specify alternate content types. If the object handler cannot process the outermost object, it must then process the embedded contents, which may be another object element, etc. In this case, the innermost object element declaration should contain alternative text, the outer object element declarations should not contain alternative text since an embedded object element declaration is present.

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

      <!-- Else, try the MPEG video -->
      <object 
          data="TheEarth.mpeg"
          type="video/mpeg"
          xml:base="http://www.example.com/">

            <!-- Else, try the GIF image -->
            <object
                data="TheEarth.gif"
                type="image/gif"
                xml:base="http://www.example.com/">

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

Another way to approach the usage of the object element attributes is this way:

<object 
    id="clock1"
    type="application/x-java-applet">
    A clock.
</object>

14.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.

    
<object 
    data="http://www.example.com/myclock.class"
    type="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>

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

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.

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

14.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.

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

By setting the type 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.

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

14.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 delaring 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.).

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

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

14.3. The standby element

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