Edit online

How to Insert Custom HTML Content

You can add custom HTML content in the WebHelp Responsive output by inserting it in a well-formed XML file (or specifying it in a well-formed XHTML fragment) that will be referenced in the transformation (either from an Oxygen Publishing Template or using one of the HTML fragment placeholder 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 regarding this XML file:

Well-Formedness - If the content of the file is not XML Well-formed, the transformation will automatically convert non-well-formed HTML content to a well-formed XML equivalent (assuming the webhelp.enable.html.fragments.cleanup transformation parameter is set to true).

For example, if the HTML content includes several <script> or <link> elements, the XML fragment would have multiple root elements and to make it well-formed, it would be wrapped 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.

Note: The converted fragments are stored in a file located in the whr-html-fragments subfolder of the transformation's temporary directory.

Tip: If you do not want the transformation to automatically convert non-well-formed content into well-formed XML content, you can set the webhelp.enable.html.fragments.cleanup transformation parameter to false. This will instead cause the transformation to fail if at least one HTML fragment is not well-formed.
Referencing Resources in the XML File - You can include references to local resources (such as JavaScript or CSS files) by using the built-in ${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:
JavaScript:
```
<script type="text/javascript">
    /* Include JavaScript code here. */
 
    function myFunction() {
      return true;
    }
</script> 
```
CSS:
```
<style>
    /* Include CSS style rules here. */

    *{
      color:red
    } 
</style>
```
Note:
If you have special characters (e.g. &, <) that break the well-formedness of the XML fragment, it is important to place the content inside an XML comment.

Otherwise, the WebHelp transformation automatically wraps inline JavaScript or CSS content in an XML comment. Also, if the commented content contains constructs that are not allowed in an XML comment, those constructs are escaped.

[Important] XML comment tags (both the start and end tags) must be on lines by themselves. If they are on the same line as any of the script's content, it will likely result in a JavaScript error.
```
<script type="text/javascript">
  <!--
    /* Include JavaScript code here. */
 
    function myFunction() {
      return true;
    }
  --/>
</script> 
```

Using WebHelp Macros

The XML file can use WebHelp macros, which are variables that will be expanded when the content of the HTML fragment file will be copied in the final output.

There are two possibilities for using macros:

Directly in attribute values - For example, if you want to reference a JavaScript file from the Publishing Template directory, you can use the following construct:
```
<script type="text/javascript" src="${path(oxygen-webhelp-template-dir)}/"></script>
```
In text content - Using the <whc:macro> template component:
```
<script type="text/javascript"> 
    var outDirPath = '<whc:macro value="${path(oxygen-webhelp-output-dir)}" 
    xmlns:whc="http://www.oxygenxml.com/webhelp/components"/>';
    console.log("The output directory path is:", outDirPath);
</script>
```
Note: When using the <whc:macro> element, you should also include the xmlns:whc="http://www.oxygenxml.com/webhelp/components" namespace declaration for the whc prefix. This is necessary for the XML fragment to be well-formed.

The following macros are supported:

i18n

For localizing a string.

${i18n(string.id)}

param

Returns the value of a transformation parameter.

${param(webhelp.show.main.page.tiles)}

env

Returns the value of an environment variable.

${env(JAVA_HOME)}

system-property

Returns the value of a system property.

${system-property(os.name)}

timestamp

Can be used to format the current date and time. Accepts a string (as a parameter) that determines how the date and time will be formatted (format string or picture string as it is known in the XSLT specification). The format string must comply with the rules of the XSLT format-dateTime function specification.

${timestamp([h1]:[m01] [P] [M01]/[D01]/[Y0001])}

path

Returns the path associated with the specified path ID. The following paths IDs are supported:

oxygen-webhelp-output-dir - The path to the output directory. The path is relative to the current HTML file.
oxygen-webhelp-assets-dir - The path to the oxygen-webhelp subdirectory from the output directory. The path is relative to the current HTML file.
oxygen-webhelp-template-dir - The path to the template directory. The path is relative to the current HTML file.
```
${path(oxygen-webhelp-template-dir)}  
```

Note: New paths IDs can be added by overriding the wh-macro-custom-path template from com.oxygenxml.webhelp.responsive\xsl\template\macroExpander.xsl:

<!-- Extension template for expanding a custom path macro. -->
<xsl:template name="wh-macro-custom-path">
    <xsl:param name="pathId"/>
    <xsl:value-of select="$pathId"/>
</xsl:template>

map-xpath

Can be used to execute an XPath expression over the DITA map file from the temporary directory.

Tip: Available in all template layout HTML pages.

${map-xpath(/map/title)}

topic-xpath

Can be used to execute an XPath expression over the current topic.

Tip: Available only in the topic HTML page template (wt_topic.html).

${topic-xpath(string-join(//shortdesc//text(), ' '))}

oxygen-webhelp-build-number

Returns the current WebHelp distribution ID (build number).

${oxygen-webhelp-build-number}

Referencing the HTML fragment using a Publishing Template

If you have not already created a Publishing Template, see Working with Publishing Templates.
Insert the HTML content in a file that is XML well-formed (for example, custom-html.xml).
Using the Project view, copy your custom XML file in a folder inside publishing the template root folder (for example, in the custom_footer_template/html-fragments folder).
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.xml" 
          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.
Open the DITA Map WebHelp Responsive transformation scenario.
Click the Choose Custom Publishing Template link and select your template.
Click OK to save the changes to the transformation scenario.
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

Insert the HTML content in a well-formed XML file.
Edit the DITA Map WebHelp Responsive transformation scenario and open the Parameters tab.
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.
Click OK to save the changes to the transformation scenario.
Run the transformation scenario.

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