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

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

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.

Example

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

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

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

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