6. Rich media content Previous topic Parent topic Child topic Next topic

This chapter explains how to add SVG, MathML, audio, video and Flash animations to your DITA topics and how ditac processes this rich media content in the case where the output format supports rich media (e.g. XHTML 5, EPUB 3) and also in the case where the output format does not support rich media (e.g. XHTML 1, PDF, RTF).

Note
Note
XMLmind XML Editor has an "Insert media object" button in its DITA Topic tool bar which allows to easily insert any of the elements and processing-instructions described in this chapter.

Figure 4. The menu displayed by the "Insert media object" button

xxe_media_menu.png

SVG

It is possible to include SVG graphics in a DITA topic either by reference or by inclusion. Use an image element pointing to an SVG file to include it by reference. Example:
graphic.png
The XML source code corresponding to the above example is:
<p><image href="media/graphic.svg"/></p>
Embed the svg:svg element in a foreign element (or any element specializing foreign) to include it by inclusion. Example:
The XML source code corresponding to the above example is:
<p><foreign><svg:svg height="140" id="svg2" version="1.1"
  viewBox="0 0 264 120" width="320"
  xmlns:svg="http://www.w3.org/2000/svg">
  <svg:defs id="defs39"/>
  ...
  </svg:g>
</svg:svg></foreign></p>
  • It is recommended to include SVG graphics by reference as the image element has useful attributes (width, height, scale, scalefit) allowing to adjust the dimension of the image.
  • Only the following screen formats may contain SVG: XHTML 5, XHTML 5 Web Help and EPUB 3. Note that only modern web browsers support XHTML 5 and XHTML 5 Web Help. Very few EPUB readers (e.g. iBooks) support EPUB 3.
  • All XSL-FO based formats support SVG whatever the XSL-FO processor you may use.

MathML

Embed the mml:math element in a foreign element (or any element specializing foreign) to add math to your DITA topics. Example:
{ ∇× E = - B t ∇× B = μ 0 J + μ 0 ε 0 E t
The XML source code corresponding to the above example is:
<p><foreign><mml:math display="block" 
  xmlns:mml="http://www.w3.org/1998/Math/MathML">
  <mml:mrow>
    <mml:mo>{</mml:mo>
    <mml:mtable>
      <mml:mtr>
        <mml:mtd>
        ...
        </mml:mtd>
      </mml:mtr>
    </mml:mtable>
  </mml:mrow>
</mml:math></foreign></p>
  • Only the following screen formats may contain MathML: XHTML 5, XHTML 5 Web Help and EPUB 3. Most modern web browsers (Firefox, Chrome) support XHTML 5 and XHTML 5 Web Help containing MathML. Very few EPUB readers (e.g. iBooks) support EPUB 3.
  • XSL-FO based formats support MathML dependin g on the XSL-FO processor you use:

Audio

Use the object DITA element to add audio to your DITA topics. Example:
The XML source code corresponding to the above example is:
<p><object data="media/audio.mp3" type="audio/mpeg">
     <param name="source.src" value="media/audio.ogg"/>
     <param name="source.type" value="audio/ogg"/>

     <param name="source.src" value="media/audio.m4a"/>
     <param name="source.type" value="audio/mp4"/>

     <param name="source.src" value="media/audio.wav"/>
     <param name="source.type" value="audio/wav"/>

     <param name="controls" value="true"/>
</object></p>
  • The data and type attributes are required. The value of the type attribute must start with "audio/".
  • It is strongly recommended to specify alternate audio files as modern web browsers, while all supporting the HTML 5 audio element, vary in their support of audio formats. This is done by adding pairs of param child elements to the object element. The first param of a pair must have name="source.src" attribute and its value attribute must reference an audio file. The second param of a pair must have name="source.type" attribute and its value attribute must contain the media type of the preceding audio file.
  • It is possible to add param elements corresponding to the attributes supported by the HTML 5 audio element (crossorigin, preload, autoplay, mediagroup, loop, muted, controls). In the above example, we have added a param element corresponding to the controls HTML 5 attribute. Note that in the case of HTML 5 boolean attributes (autoplay, loop, muted, controls), the value attribute of a param is not significant. For example, in the case of the above example, you could have specified "yes", "on", "1", etc, instead of "true".
  • If the object element has a desc child element, then this desc element is used to generate fallback content in case audio is not supported. If the object element has no desc child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the audio file.
  • When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

Video

Use the object DITA element to add video to your DITA topics. Example:
The XML source code corresponding to the above example is:
<p><object data="media/video.mp4" type="video/mp4">
     <param name="source.src" value="media/video.ogv"/>
     <param name="source.type" value='video/ogg; codecs="theora, vorbis"'/>

     <param name="source.src" value="media/video.webm"/>
     <param name="source.type" value="video/webm"/>

     <param name="width" value="320"/>
     <param name="controls" value="yes"/>
     <param name="poster" value="media/video_poster.jpg"/>
</object></p>
  • The data and type attributes are required. The value of the type attribute must start with "video/".
  • It is strongly recommended to specify alternate video files as modern web browsers, while all supporting the HTML 5 video element, vary in their support of video formats. This is done by adding pairs of param child elements to the object element. The first param of a pair must have name="source.src" attribute and its value attribute must reference an video file. The second param of a pair must have name="source.type" attribute and its value attribute must contain the media type of the preceding video file.
  • It is possible to add param elements corresponding to the attributes supported by the HTML 5 video element (crossorigin, poster, preload, autoplay, mediagroup, loop, muted, controls, width, height). In the above example, we have added a param element corresponding to the width, controls and poster HTML 5 attributes. Note that in the case of HTML 5 boolean attributes (autoplay, loop, muted, controls), the value attribute of a param is not significant. For example, in the case of the above example, you could have specified "true", "on", "1", etc, instead of "yes".
  • If the object element has a desc child element, then this desc element is used to generate fallback content in case video is not supported. If the object element has no desc child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the video file. The param element corresponding to the poster HTML 5 attribute, if present, is used to generate a nicer automatic fallback content.
  • When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

Flash animation

Use the object DITA element to add Adobe® Flash® animations to your DITA topics. Example:
(You may have to right-click on the above screenshot and select Play from the Flash popup menu to replay the animation.)
The XML source code corresponding to the above example is:
<p><object data="animation.swf" 
           type="application/x-shockwave-flash" 
           width="431" height="123">
    <param name="movie" value="animation.swf"/>

    <param name="menu" value="true"/>
    <param name="quality" value="low"/>
</object></p>
  • The data, type, width and height attributes are required. The param name=movie child element having the same value as attribute data is required too.
  • You may add any other param child element supported by the Flash object. In the above example, you'll find menu and quality in addition to required movie.
  • If the object element has a desc child element, then this desc element is used to generate fallback content in case Flash is not supported. If the object element has no desc child element, then a simple fallback content is automatically generated by ditac. This automatic fallback content basically consists in a link allowing to download the .swf file.
  • When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the ouput file.

Actions

Unless you add param name="controls" (see above), you'll not be able to play audio or video. Even worse, without the controls param, an audio object is not rendered on screen (that is, it is invisible).
A simple solution for this problem is to insert a <?onclick?> processing-instruction in a DITA element (typically an inline element such as xref or ph). The <?onclick?> processing-instruction allows to specify an number of actions:
play
Play the associated resource from the beginning. Only applicable to video or audio targets.
pause
Pause playing . Only applicable to video or audio targets.
resume
Resume playing . Only applicable to video or audio targets.
mute
Mute sound . Only applicable to video or audio targets.
unmute
Unmute sound . Only applicable to video or audio targets.
show
Set the visibility property of the target element to visible.
hide
Set the visibility property of the target element to hidden.
The above actions are exactly those supported by EPUB 3's epub:trigger.
The <?onclick?> processing-instruction is processed by ditac for the following output formats: XHTML 5, XHTML 5 Web Help and EPUB 3. It is discarded for any other output format.
The syntax for the content of <?onclick?> is:
onclick_data -> action (S action)*
action -> op '(' target_id? ')'
op -> 'play'|'pause'|'resume'|'mute'|'unmute'
      'show'|'hide'
When target_id is not specified, it is taken from the href attribute of the element containing the <?onclick?> processing-instruction. For example, <xref href="#media/target_audio"><?onclick play()?> is equivalent to: <xref href="#media/target_audio"><?onclick play(media/target_audio)?>.
Example 1: Say: "Viens Hubble!", which, in French, means: "Come here Hubble!".
no_audio.png No audio. Say: "Viens Hubble!", which, in French, means: "Come here Hubble!".
The XML source code corresponding to the above example is:
<p>Example 1: <xref href="#media/target_audio"><?onclick play()?>
Say "<ph xml:lang="fr">Viens Hubble!</ph>"</xref> 
... 
<object data="media/audio.wav" id="audio_sample" type="audio/wav">
  <desc> ... </desc>
</object></p>
Example 2: Hide Hubble. Show Hubble.

Figure 5. My name is Hubble. I'm a 7-month old Golden Retriever.

video_poster.jpg
The XML source code corresponding to the above example is:
<p>Example 2: 
<xref href="#media/target_image"><?onclick hide()?>Hide Hubble</xref>.
<xref href="#media/target_image"><?onclick show()?>Show Hubble</xref>.</p>