Chapter 8. Rich media content

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).

SVG

It is possible to include SVG graphics in a DITA document either by reference or by inclusion. Use an <svg-container>/<svgref> element pointing to an SVG file to include it by reference. Example:
The XML source code corresponding to the above example is:
<p><svg-container><svgref href="media/graphic.svg"/></svg-container></p>
It's also possible to use an <image> element pointing to an SVG file to include it by reference. Example:
<p><image href="media/graphic.svg"/></p>
Embedding SVG graphics in a DITA document can be achieved using the same <svg-container> element. Example:
The XML source code corresponding to the above example is:
<p><svg-container>
  <svg:svg height="64.710144" version="1.1"
    viewBox="0 0 104.28986 51.768115" width="130.36232"
    xmlns:svg="http://www.w3.org/2000/svg">
  ...
  </svg:svg>
</svg-container></p>
Notes:
  • It is still recommended to include SVG graphics by reference using the <image> element rather then <svg-container>/<svgref>. The <image> element has useful attributes (@width, @height, @scale, @scalefit) allowing to adjust the dimension of the image. Moreover this elements permits on the fly conversion between image formats.
  • It is not recommended to embed SVG graphics in a DITA document as this is likely to cause many validation problems.
  • 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 (PDF, RTF, DOCX, etc) support SVG whatever the XSL-FO processor you may use.

MathML

It is possible to include math in a DITA document either by reference or by inclusion. Use an <mathml>/<mathmlref> element pointing to a MathML file to include it by reference. Example:
E = ρ ε 0
The XML source code corresponding to the above example is:
<p><mathml><mathmlref href="media/math.mml"/></mathml></p>
Embedding MathML in a DITA document can be achieved using the same <mathml> element. Example:
{ ∇× E = - B t ∇× B = μ 0 J + μ 0 ε 0 E t
The XML source code corresponding to the above example is:
<p><mathml>
  <m:math display="block" 
    xmlns:m="http://www.w3.org/1998/Math/MathML">
    <m:row>
    ...
    </m:mrow>
  </m:math>
</mathml></p>
Notes:
  • For clarity, it is recommended to wrap <mathml> into the following equation elements: <equation-inline>, <equation-block>, <equation-figure>.
  • There is an option to number <equation-figure> elements having a <title>. Example:

    Equation 8-1. Gauss's law in its differential form

    E = ρ ε 0
    <equation-block> elements containing a empty <equation-number> are automatically numbered. Example:
    E = ρ ε 0 (8-1)
    The counter used to number to <equation-figure> elements having a <title> and the counter used to number <equation-block> elements containing an empty <equation-number> are different. Therefore mixing numbered <equation-figure>s and numbered <equation-block>s in the same DITA document may result in a hard to understand equation numbering.
  • 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(PDF, RTF, DOCX, etc) support MathML depending 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" value="media/audio.ogg"
            valuetype="ref" type="audio/ogg"/>

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

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

     <param name="controls" value="true"/>
</object></p>
Notes:
  • 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 <param> child elements to the <object> element. Such <param> elements must have a name="source" attribute, a valuetype="ref" attribute, a @value attribute referencing an audio file and preferably, a @type attribute specifying the media type of the 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 output 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" value="media/video.ogv"
            valuetype="ref" type='video/ogg; codecs="theora, vorbis"'/>

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

     <param name="width" value="320"/>
     <param name="controls" value="yes"/>
     <param name="poster" value="media/video_poster.jpg"
            valuetype="ref"/>
</object></p>
Notes:
  • 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 <param> child elements to the <object> element. Such <param> elements must have a name="source" attribute, a valuetype="ref" attribute, a @value attribute referencing a video file and preferably, a @type attribute specifying the media type of the 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 output 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"
           valuetype="ref" type="application/x-shockwave-flash"/>

    <param name="menu" value="true"/>
    <param name="quality" value="low"/>
</object></p>
Notes:
  • 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 output file.

Other uses of the <object> element

We have seen in previous sections how the <object> DITA element may be used to add audio, video and Adobe® Flash® animations to your DITA topics. In any case other than those described in previous sections, the <object> DITA element is converted to the equivalent <object> XHTML element. For example, if you want to add a YouTube video to your DITA topics, simply do it in DITA as you would do it in XHTML using the <object> element.
youtube_icon.png Watch this test video Opens in new window on YouTube.
The XML source code corresponding to the above example is:
<p><object data="https://www.youtube.com/embed/C0DPdy98e4c"
           width="640" height="360">
     <desc><image href="media/youtube_icon.png"/> Watch this <xref format="html"
     href="https://youtu.be/C0DPdy98e4c" scope="external">test video</xref> on
     YouTube.</desc>
</object></p>
Notes:
  • If the <object> element has a <desc> child element, then this <desc> element is used to generate fallback content in case the media object 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 media file.
  • When ditac is used to generate an XSL-FO based format (PDF, RTF, etc), only the fallback content appears in the output 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 8-1. 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>