Edit online

How to Add Custom HTML Content in WebHelp Classic Output

You can add custom HTML content in the WebHelp Classic output by inserting it in a well-formed XML file that will be referenced in the transformation. 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.

Using Oxygen XML Editor/Author

To include custom HTML content in the WebHelp Classic output using a transformation scenario from within Oxygen XML Editor/Author, follow this procedure:

Insert the HTML content in a well-formed XML file considering the following notes:
- Well-Formedness - If the content of the file is not XML Well-formed, (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 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>
```
  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 (for example, &, <) that break the well-formedness of the XML fragment, it is important to place the content inside an XML comment.
  
  [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> 
```
Edit the WebHelp Classic transformation scenario.
Go to the Parameters tab.
Edit the value of the webhelp.head.script parameter and set it to reference the URL of the XML file created in step 1. Your additional content will be included at the end of the head element of your output document.
Note: If you want to include the content in the body element, use the webhelp.body.script parameter instead.
Click OK to save the changes and run the transformation scenario.

Using a Script Outside of Oxygen XML Editor/Author

Important: Running WebHelp transformations from a script outside of Oxygen XML Editor/Author requires an additional license and some additional setup:

You must have a valid license for the Oxygen XML WebHelp Plugin (https://www.oxygenxml.com/buy_webhelp.html).
The Oxygen XML WebHelp Plugin must be installed and integrated.

To include custom HTML content in the WebHelp Classic output using a script outside of Oxygen XML Editor/Author, follow this procedure:

Insert the HTML content in a well-formed XML file considering the following notes:
- Well-Formedness - If the content of the file is not XML Well-formed, (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 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>
```
  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 (for example, &, <) that break the well-formedness of the XML fragment, it is important to place the content inside an XML comment.
  
  [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> 
```
Use the webhelp.head.script parameter in your transformation script and set its value to reference the URL of the XML file created in step 1. Your additional content will be included at the end of the head element of your output document.
Note: If you want to include the content in the body element, use the webhelp.body.script parameter instead.
Execute the transformation script.