21. 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:

Elements Attributes Minimal Content Model
object Common, archive (URIs), content-length (Number), declare ("declare") ( caption?, standby?, param*, (PCDATA | Flow)*)
param id (ID), name* (CDATA), value (CDATA), valuetype ("data"* | "ref" | "object"), type (ContentTypes) EMPTY
standby Common (PCDATA | Text)*

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

Implementation: RELAX NG

21.1. The object element


The Common collection
A collection of other attribute collections, including: Core, Events, I18N, Bi-directional, Edit, Embedding, Map, Metainformation, and Hypertext
archive = URIs
This attribute specifies a comma-separated list of URIs for archives containing classes and other resources that will be "preloaded". The classes are loaded using an instance of an AppletClassLoader with the given xml:base. Relative URIs for archives are interpreted with respect to the applet's xml:base. Preloading resources can significantly improve the performance of applets.
content-length = Number
This attribute is to be used as a hint by the object handler. The author may provide the object handler with the physical size of the object data that is to be processed. A valid value is the same as defined in section 14.13 of [RFC2616].
declare = "declare"
When present, this boolean attribute makes the current object element a declaration only - not one that is to be executed until after the document has completed loading and has been called through a user event such as selecting an anchor that references the object.

21.1.1. Defining terminology

The following terms will be 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.
Refers to the plug-in handler, and the need to create a window, modify the user interface, allocate memory, etc.

21.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 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 mime 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.

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 form controls for information about object elements in forms.

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

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.

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

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

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 type attribute specifies the mime type associated with the object data:

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

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.

    <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"/>
<style type="text/css">
#obj1 {width:150px; height:150px;}

<object id="obj1" 
    <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>


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 at the same level (this is not the recommended method), the object handler should attempt to process the embedded object first. If the nested object cannot be processed, then the alternate text should be displayed. 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.

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

<object src="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>

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.

A user agent must attempt to process the outermost object element. If the object cannot be processed, then the next level object declaration should be processed. If that object cannot be processed, then the user agent must continue to process each embedded object declaration until the innermost object declaration is reached. Once the inner most object declaration is analyzed and if the user agent cannot process it, then the alternative text of the inner most object declaration should be processed.

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

      <!-- Else, try the video -->

            <!-- Else, try the image -->

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

The outermost object element declaration specifies an applet that requires no initial values, the src attribute points to the applet class file, and the type attribute defines the mime 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 jar 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 type 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.

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

attribute function
archive For example, when defining an applet you could reference a space-separated list of jar files.
content-length This is similar to meta data, in that this can be used by the object handler as a hint to the physical size of the object data that is to be processed.
src This URI points to the object data to be processed. This can be an absolute URI (http://www.example.com/datafiles/myinstance.mpg), or a relative URI (myinstance.mpg). If you use a relative URI, then you will need to use the xml:base attribute to define the base location of the object data. This attribute should only refer to the data to be processed.
declare This is used to delay the processing of the object data until such time that it is referred to by another element that requires the object data to be processed. In other words, the object data should be downloaded but should not be processed. For example, if an a element is coded to refer to the object element and the a element is activated, then the object data would be processed.
type Defining the mime type of the object data will assist the object handler in determining whether the object data can be processed by the user agent or if an external application needs to be launched to process the object data.
xml:base Use this attribute to define the base location of the object data. For example: http://www.example.com/datafiles/. This attribute should not be used for any other purpose.

Inline vs. external data. Data to be processed may be supplied in two ways: inline and from an external resource. While the former method will generally lead to faster processing, it is not convenient when processing large quantities of data.

Here's an example that illustrates how inline data may be fed to an object handler:

    A clock.

21.2. The param element


name = CDATA
This attribute defines the name of a run-time parameter, assumed to be known by the object handler. Whether the property name is case-sensitive depends on the specific object handler implementation.
value = CDATA
This attribute specifies the value of a run-time parameter specified by name. Property values have no meaning to XHTML; their meaning is determined by the object in question.
valuetype = data|ref|object
This attribute specifies the type of the value attribute.

Possible values:

  • data: This is the default value for the attribute. It means that the value specified by value will be evaluated and passed to the object's implementation as a string.
  • ref: The value specified by value is a URI that designates a resource where run-time values are stored. This allows support tools to identify URIs given as parameters. The URI must be passed to the object as is, i.e., unresolved.
  • object: The value specified by value is an identifier that refers to an object declaration in the same document. The identifier must be the value of the id attribute set for the declared object element.
type = ContentTypes
This attribute specifies the content type of the resource designated by the src attribute. It is used to help the user agent decide whether it can process this element's contents.

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.

Could param be an attribute?

Would it be better to have param be an attribute of whatever needs it, with the attribute value syntax being something like the style attribute to permit rich values?

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.

        <param name="height" value="40" valuetype="data" />
        <param name="width" value="40" valuetype="data" />
        This user agent cannot process a java applet.

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.

        <standby>Loading Elvis...</standby>
        <param name="Init_values"
            valuetype="ref" />
        Elvis lives!

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.

    <param name="param1" value="value1" />
        <param name="param2" value="value2" />
        This user agent cannot process this application.

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

    A film showing how to open the printer to replace the cartridge.

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.

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

    This user agent cannot process this movie.

21.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:

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.

    The <strong>Earth</strong> as seen from space.
...later in the document...
<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.

21.3. The standby element


The Common collection
A collection of other attribute collections, including: Core, Events, I18N, Bi-directional, Edit, Embedding, Map, Metainformation, and Hypertext

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

21.4. Issues

Efficient param's PR #7642
State: Open
Resolution: Defer
User: None

The working group has agreed to review the param element for the next draft. BAE: f2f - it makes no difference to the actual processing. Values interpreted by handler - see discussion dated lists.w3.org/Archives/Member/w3c-html-wg/2003AprJun/0071.html item 16