Adding Rich Contents to LibreOffice Help Pages

    From The Document Foundation Wiki
    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).

    ExampleVideoHelp.png

    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:

    ExampleFileIcon.png

    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.