Contents
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 | 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"), @paramtype (ContentType) | EMPTY |
standby | Common | (PCDATA | Text)* |
Implementations: RELAX NG, XML Schema
Attributes
The following terms are used throughout this section.
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 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.
A user agent must interpret an object element according to the following precedence rules:
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:
Example
<object src="http://www.example.com/foo.mp3"> <em>alternate text</em> </object>
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:
Example
<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.
Example
<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>
Example
<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.
Example
<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.
Example
<!-- 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.
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.
Attributes
Possible values:
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.
Example
<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.
Example
<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.
Example
<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>
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.
Example
<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.
Example
<object xml:base="http://www.example.com/" src="mymovie.mpg" srctype="video/mpeg"> This user agent cannot process this movie. </object>
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.
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.
Attributes
The standby element specifies a message that a user agent may render while loading the object's implementation and data.