How to Insert HTML Content in WebHelp Responsive Output
Edit online

You can add custom HTML content in the WebHelp Responsive output by inserting it in a well-formed XML file that will be referenced in the transformation (either from a Oxygen Publishing Template or using one of the HTML fragment parameters). This content may include references to additional JavaScript, CSS, and other types of resources, or such resources can be inserted inline within the HTML content that is inserted in the XML file.

The XML File

There are several things to consider in regards to this XML file:
  • Well-Formedness - If the file is not a Well-formed XML document (or fragments are not well-formed), the transformation will fail.

    A common use case is if you want to include several script or link elements. In this case, the XML fragment has multiple root elements and to make it well-formed, you can wrap it in an html element. This element tag will be filtered out and only its children will be copied to the output documents. Similarly, you can wrap your content in head, body, html/head, or html/body elements.

  • Referencing Resources in the XML File - You can include references to local resources (such as JavaScript or CSS files) by using the predefined ${oxygen-webhelp-output-dir} macro to specify their paths relative to the output directory:
    <html>
  <script type="text/javascript" src="${oxygen-webhelp-output-dir}/js/test.js"/>
  <link rel="stylesheet" type="text/css" 
        href="${oxygen-webhelp-output-dir}/css/test.css" />
</html>

    If you want that the path of your resource to be relative to the templates directory, you can use the ${oxygen-webhelp-template-dir} macro.

    To copy the referenced resources to the output directory, follow the procedure in: How to Copy Additional Resources to Output Directory.
  • Inline JavaScript or CSS Content - If you want to include inline JavaScript or CSS content in the XML file, it is important to place this content inside an XML comment, as in the following examples:

    JavaScript:

    <script type="text/javascript">
  <!--
    /* Include JavaScript code here. */
 
    function myFunction() {
      return true;
    }
  -->
</script>

    CSS:

    <style>
  <!-- 
    /* Include CSS style rules here. */

    *{
      color:red
    } 
  -->
</style>

Referencing the HTML fragment using a Publishing Template

  1. If you haven't already created a Publishing Template, see Working with Publishing Templates.
  2. Insert the HTML content in a well-formed XML file (for example, custom-html.html).
  3. Using the Project view, copy your custom HTML fragment in a folder inside publishing the template root folder (for example, in the custom_footer_template/html-fragments folder).
  4. Open the template descriptor file associated with your publishing template and add a reference to the custom HTML fragment in the html-fragments section.
    <publishing-template>
    ...    
    <webhelp>
      ...
      <html-fragments>
        <fragment 
          file="html-fragments/custom-html.html" 
          placeholder="webhelp.fragment.head"/>
    Note: If you want to insert the content in another location within the output document, you can reference the XML file from any other HTML Fragment extension points.
  5. Open the DITA Map WebHelp Responsive transformation scenario.
  6. Click the Choose Custom Publishing Template link and select your template.
  7. Click OK to save the changes to the transformation scenario.
  8. Run the transformation scenario.

Results: Your additional content will be included at the end of the head element of your output document.

Referencing the HTML Fragment using a Transformation Parameter

  1. Insert the HTML content in a well-formed XML file.
  2. Edit the DITA Map WebHelp Responsive transformation scenario and open the Parameters tab.
  3. Edit the value of the webhelp.fragment.head parameter and set it to the absolute path of your XML file.
    Note: If you want to insert the content in another location within the output document, you can reference the XML file from any other HTML Fragment extension points.
  4. Click OK to save the changes to the transformation scenario.
  5. Run the transformation scenario.

Results: Your additional content will be included at the end of the head element of your output document.