Adding Rich Contents to LibreOffice Help Pages

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

Other languages:

LibreOffice new Help Online pages can display and link to rich contents such as videos or true example files. The offline Help (local help) does not have this feature by design.

The intent of adding multimedia and other objects files is complimentary to the precise but often cumbersome textual description. Both are important in a help page. The textual description is a way to describe how a feature does work and the object file is the implementation of the description. When there is a discrepancy, then either the software has a bug, or the page needs a description update.

External videos

To insert a video just add an <object> tag inside a <paragraph> in the help file with the proper settings

<paragraph role="paragraph" id="par_id1234567" xml-lang="en-US">
<object data="https://www.youtube-nocookie.com/embed/3KC0ZdcA6s8?rel=0" 
id="vid_id61521568603544" 
type="video/youtube" 
width="560" 
height="315" />
</paragraph>

Where

data is the URL of the file in the help system
type is the type of the file and must be video/youtube
id is a unique identifier
width is the width of the video
height is the height.

The type specified here (video/youtube) does not force to use You Tube services. The video can he hosted in an external server such as You Tube (tested) or any other (not tested).

Technical description

The HTML rendered by this type is defined in the stylesheet transform is an <iframe> tag:

<xsl:when test="starts-with(@type,'video/youtube')">
  <xsl:if test="$online">
      <div id="mediadiv">
         <iframe id="{@id}" src="{@data}" width="{$width}" height="{$height}" frameborder="0" allowfullscreen="true"></iframe>
      </div>
   </xsl:if>
</xsl:when>

which means that when the type is video/youtube and help is online, an <iframe> will contain the video and will be wrapped in a <div> with style .mediadiv

ODF files in help pages

The OpenDocuments inserted in the help system work in either offline and online version of the new Help pages.

Help authors can now add <object> elements with type="application/vnd.oasis.opendocument.*" such as

application/vnd.oasis.opendocument.text
application/vnd.oasis.opendocument.spreadsheet
application/vnd.oasis.opendocument.drawing
application/vnd.oasis.opendocument.presentation
application/vnd.oasis.opendocument.formula
application/vnd.oasis.opendocument.database

Since our help pages are mostly textual, it is not the best way to show how a given feature works. By having a real opendocument file available to download directly from the Help is a step to see a real example working.

The implementation of a OpenDocument object is simple. Just insert an <object> tag specifying the file location in the data attribute, the right type as a valid OpenDocument MIME type and an id that is a random string.

<object data="media/files/scalc/imtrigon.ods"
id="ods_id61521568603544" 
type="application/vnd.oasis.opendocument.spreadsheet" />

Where

data is the URL of the file in the help system
type is the MIME type of the file, as above
id is a unique identifier

The result in the rendered page is an icon with a link to download the page:

Technical description

The transformation of the ODF files object to HTML5 is made by this template:

<xsl:when test="@type='application/vnd.oasis.opendocument.spreadsheet'">
       <a class="objectfiles" href="{concat($target,@data)}"><img src="{concat($target,'media/navigation/libo-calc.svg')}" width="25px" height="30px"></img></a>
</xsl:when>

which means an icon of the MIME type is inserted with a link to the file in the repository.

What to add in help pages

Adding rich contents in our help pages is a topic for Help Authors.