`<object>`

The DITA <object> element corresponds to the HTML <object> element, and the attribute semantics derive from the HTML definitions. Because of this, the @type attribute on <object> differs from the @type attribute on many other DITA elements.

Usage information

The <object> element enables authors to include animated images, applets, plug-ins, video clips, and other multimedia objects in a topic.

Rendering expectations

Processors SHOULD scale the object when values are provided for the @height and @width attributes. The following expectations apply:

If a height value is specified and no width value is specified, processors SHOULD scale the width by the same factor as the height.
If a width value is specified and no height value is specified, processors SHOULD scale the height by the same factor as the width.
If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.

When an object cannot be rendered in a meaningful way, processors SHOULD present the contents of the <fallback> element, if it is present.

Content model

<desc> ?, <longdescref> ?, <fallback> ?, <param> *, <foreign> *

In order

Optional <desc>
Optional <longdescref>
Optional <fallback>
Zero or more <param>
Zero or more <foreign>

Attributes

The following attributes are available on this element: universal attributes and the attributes defined below.

@data: Contains a reference to the location of an object's data. If this attribute is a relative URL, it is specified relative to the document containing the <object> element. If this attribute is set, the @type attribute should also be set.
@datakeyref: Provides a key reference to the object. When specified and the key is resolvable, the key-provided URI is used. A key that has no associated resource, only link text, is considered to be unresolved. If @data is specified, it is used as a fallback when the key cannot be resolved to a resource.
@height: Specifies the vertical dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.
@name: Defines a unique name for the object.
@tabindex: Specifies the position of the object in tabbing order.
@type: Indicates the content type (MIME type) for the data specified by the @data or @datakeyref attribute. This attribute should be set when the @data attribute is set to avoid loading unsupported content types. Note that this differs from the @type attribute on many other DITA elements (it specifies a MIME type rather than a content type). If @type is not specified, the effective type value for the key named by the @datakeyref attribute is used as the this attribute's value.
@usemap: Indicates that a client-side image map is to be used. An image map specifies active geometric regions of an included object and assigns a link to each region. When a link is selected, a document might be retrieved or a program might run on the server.
@width: Specifies the horizontal dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

The following attributes are available on this element: universal attributes and the attributes defined below.

@data: Contains a reference to the location of an object's data. If this attribute is a relative URL, it is specified relative to the document containing the <object> element. If this attribute is set, the @type attribute should also be set.
@datakeyref: Provides a key reference to the object. When specified and the key is resolvable, the key-provided URI is used. A key that has no associated resource, only link text, is considered to be unresolved. If @data is specified, it is used as a fallback when the key cannot be resolved to a resource.
@height: Specifies the vertical dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.
@name: Defines a unique name for the object.
@tabindex: Specifies the position of the object in tabbing order.
@type: Indicates the content type (MIME type) for the data specified by the @data or @datakeyref attribute. This attribute should be set when the @data attribute is set to avoid loading unsupported content types. Note that this differs from the @type attribute on many other DITA elements (it specifies a MIME type rather than a content type). If @type is not specified, the effective type value for the key named by the @datakeyref attribute is used as the this attribute's value.
@usemap: Indicates that a client-side image map is to be used. An image map specifies active geometric regions of an included object and assigns a link to each region. When a link is selected, a document might be retrieved or a program might run on the server.
@width: Specifies the horizontal dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

Example

This section is non-normative.

This section contains examples of how the <object> element can be used.

Example 1. Referencing a web page for display in an HTML inline frame (iframe)

The following code sample shows how an <object> element can be used to render a web page in an inline frame. It assumes that the processing engine uses the outputclass="iframe" directive.

<object type="text/html"
        data="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776
              %2C0.00030577182769775396
              %2C51.478569861898606
              &layer=mapnik"
        width="800"
        height="600"
        id="map-uk-greenwich"
        outputclass="iframe">
   <desc>Greenwich, England</desc>
   <fallback><xref format="html" scope="external"
       href="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776
              %2C0.00030577182769775396
              %2C51.478569861898606
              &layer=mapnik"
    /></fallback>
</object>

The above code might generate the following HTML:

<!DOCTYPE html>
<html>
  <head>
    <title>Test of Iframe</title>
  </head>
  <body>
    <p>Iframe:</p>
    <iframe src="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776
      %2C0.00030577182769775396
      %2C51.478569861898606
      &layer=mapnik"       
      >Street map</iframe>
  </body>
</html>

Example 2. Object with reference to video using key reference on the <param> elements

The following code sample shows how key definitions can be used to reference supporting resources for an <object>:

<object id="E5123_026.mp4" width="300" height="300">
  <fallback>Media not available.</fallback>
  <param name="poster" keyref="E5123_026_poster" />
  <param name="source" keyref="E5123_026_video" />
</object>

In this scenario, the keys could be defined as follows:

<map>
  <!-- ... -->
  <keydef keys="E5123_026_poster"
      href="../images/E5123_026_poster.png"
      type="video/mp4"/>
  <keydef keys="E5123_026_video"
      href="../media/E5123_026_poster.mp4"
      type="video/mp4"/>
  <!-- ... -->
</map>

Example 3. Object with indirect reference to a flash file

The following code sample shows how key definitions can be used to reference the main content for an <object>:

<object id="cutkey370"
    datakeyref="cutkey370"
    height="280"
    width="370">
  <desc>Video illustration of how to cut a key</desc>
  <fallback>Media not available.</fallback>
  <param name="movie" keyref="cutkey370"/>
  <param name="quality" value="high"/>
  <param name="bgcolor" value="#FFFFFF"/>
</object>

In this scenario, the keys could be defined as follows:

<map>
  <!-- ... -->

  <!-- Using @scope="external" here because the referenced URL is external. -->
  <keydef keys="cutkey370"
    href="https://www.example.com/cutkey370.swf"
    type="application/x-shockwave-flash"
    format="swf"
    scope="external" />

  <!-- ... -->
</map>