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 | Minimal Content Model |
---|---|---|
object | Common, archive (URIs), content-length (Number), data (URI), declare ("declare"), standby (Text) | ( caption?,(PCDATA | Flow | param)*) |
param | id (ID), name* (CDATA), value (CDATA), valuetype ("data"* | "ref" | "object") | EMPTY |
When this module is used, it adds the object
element to the Inline content set of the Text module.
Implementation: DTD
Attributes
The following terms will be used throughout this section.
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 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.
A user agent must interpret an object element according to the following precedence rules:
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.
The following example, shows a minimally coded object element. The data attribute specifies the location of the object data and the type attribute specifies the mime type associated with the object data:
<object data="http://www.example.com/foo.mp3" type="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 data 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 data="http://www.example.com/foo.jpg" type="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 data 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.
<object 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"/> </object>
<style type="text/css"> #obj1 {width:150; height:150;} </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.
The following example demonstrates how alternate text may be used within an object element.
<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">here</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.
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 inner most 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 MPEG animation of the Earth, (3) a GIF image of the Earth, (4) alternate text.
<!-- 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>
The outermost object element declaration specifies an applet that requires no initial values, the data 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 data 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 data 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 GIF 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. |
data | 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. |
standby | The author can provide a text string that should be displayed while the object data is being downloaded and 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:
<object id="clock1" type="application/x-java-applet"> A clock. </object>
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.
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 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>
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 data="http://www.example.com/gifappli" type="image/gif" standby="Loading Elvis..."> <param name="Init_values" value="./images/elvis.gif" valuetype="ref" /> Elvis lives! </object>
Note that we have also set the standby attribute 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 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>
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 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.
The following example specifies a base location via the xml:base attribute. The data attribute defines the data to process.
<object xml:base="http://www.example.com/" data="mymovie.mpg" type="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 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.).
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" 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>
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.