# Inserting JavaScript in generated HTML

JavaScript code can be bundled in a custom plug-in and automatically inserted into the generated HTML pages to enable web analytics or dynamic content delivery.

## About this task

This scenario walks through the process of creating a very simple plug-in (`com.example.html5-javascript`) that creates a new transformation type: html5-javascript.

The html5-javascript transformation includes a custom page footer file with a JavaScript tracking snippet and sets the args.ftr parameter to integrate the script content in the HTML5 `<footer>` element of the generated pages.

Note:
This example inserts a tracking snippet for Google Analytics, but the basic approach is the same for other analytics platforms or similar use cases that require custom JavaScript.

## Procedure

1. In the plugins directory, create a directory named com.example.html5-javascript.
2. In the new com.example.html5-javascript directory, create a plug-in configuration file (plugin.xml) that declares the new html5-javascript transformation and its dependencies.
   Figure 1. Sample plugin.xml file

       <?xml version="1.0" encoding="UTF-8"?>
       <?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?>

       <plugin id="com.example.html5-javascript">
         <require plugin="org.dita.html5"/>
         <transtype name="html5-javascript" extends="html5" desc="HTML5 with embedded JavaScript"/>
         <feature extension="ant.import" file="build_html5-javascript.xml"/>
       </plugin>

   Note:
   This plug-in will extend the default HTML5 transformation, so the `<require>` element explicitly defines org.dita.html5 as a dependency.
3. In the com.example.html5-javascript directory, create a subdirectory named include.
4. In the new include subdirectory, create a file named javascript.ftr.xml with your custom JavaScript code.
   Figure 2. Sample javascript.ftr.xml file

       <div>
       <!-- Google Analytics -->
       <script>
       console.log('Adding Google Analytics tracker');

       (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
       (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
       m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
       })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

       ga('create', 'UA-XXXXX-Y', 'auto');
       ga('send', 'pageview');
       </script>
       <!-- End Google Analytics -->
       </div>

   The division wrapper will be discarded when generating HTML files, and the contents will be inserted into the `<footer>` element of each page.

   The file contents must be well-formed XML. If your JavaScript snippets include attributes without values (such as the `async` script attribute), use valid XML syntax to define the empty attribute:

   Instead of:

       <script>
         <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
       </script>

   use:

       <script>
         <script id="MathJax-script" async="" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
       </script>

5. In the com.example.html5-javascript root directory, add an Ant script (build_html5-javascript.xml) to define the transformation type and set the path to the JavaScript footer file created in the previous step.
   Figure 3. Sample build file: build_html5-javascript.xml

       <?xml version='1.0' encoding='UTF-8'?>

       <project>
         <target name="dita2html5-javascript"
              depends="dita2html5-javascript.init,
                       dita2html5"/>
         <target name="dita2html5-javascript.init">
           <property name="args.ftr"
                 location="${dita.plugin.com.example.html5-javascript.dir}/include/javascript.ftr.xml"/>
         </target>
       </project>

   Note:
   When defining the path to the footer file from the Ant script, use the plug-in directory property with the plugin-id as shown in the example above: `${dita.plugin.plugin-id.dir}`.

## Results

Tip:
The files for this sample plug-in are included in the DITA-OT installation directory under docsrc/samples/plugins/com.example.html5-javascript/ and on GitHub.

The plug-in directory has the following layout and files:

    com.example.html5-javascript
    ├── build_html5-javascript.xml
    ├── include
    │   └── javascript.ftr.xml
    └── plugin.xml

## What to do next

1. Use the dita install subcommand to install the plug-in.

   Note:
   For more information, see Installing plug-ins.
2. Build output with the new transformation type to verify that the plug-in works as intended.

       dita --input=my.ditamap --format=html5-javascript

3. Open one of the generated HTML topic files in a modern web browser and check the JavaScript Console. When the page is loaded, `Adding Google Analytics tracker` will appear on the console to verify that the sample script is loaded.
4. Remove the `console.log` debugging message from the sample JavaScript code, and replace the `'UA-XXXXX-Y'` placeholder string with the tracking ID of the Google Analytics property you wish to track.

Tip:
This example places the JavaScript code in the page footer to ensure that page display is not delayed while the script is loaded. If your JavaScript code supports pre-loading and your application targets modern browsers that recognize the `async` script attribute, you may prefer to insert the JavaScript snippet in the `<head>` element of the generated HTML files using the args.hdf parameter instead.