How to Insert JavaScript AMD Modules in WebHelp Responsive Output
Edit online

In the WebHelp Responsive output, you may want to include a JavaScript module that uses the Asynchronous Module Definition (AMD) format. Unlike the traditional JavaScript resources that are loaded using <script> tags, these modules are loaded using the RequireJS library. For the traditional JavaScript libraries, the standard procedure to contribute your script to the output would be to use an HTML fragment file as described here.

Although following the procedure that uses HTML fragments would result in having your JS file included in the output, loading the JS code in the browser will result in an error. Since your JS module uses the AMD API, it cannot be loaded using a <script> element. For example, because many jQuery plugins use the AMD format, it will be difficult for you to use those libraries in your custom WebHelp output.

Normally, a JavaScript AMD module can be loaded in one of the following ways:

  • As a top-level script, using the data-main attribute of the <script> element used to load the RequireJS library. 
    <script data-main="js/template-main.js" src="js/require.js"></script>

    However, since WebHelp already loads its internal JS modules using RequireJS, a top level script is already specified and you cannot specify another top level script in the same page. Therefore, this approach can not be used to load your custom JS module in Oxygen XML WebHelp, leaving you with only the following option.

  • As a dependency module, using a require() call from the top level (main) script or from one of its dependency modules. This means that you would have to alter one of the WebHelp core JS libraries and inject a require() call to load your custom module: 
    require(['js/template-main.js']);
    Note: Altering the WebHelp core libraries is not recommended because when you will upgrade the WebHelp plugin to a newer version, those modifications will be lost.

Contributing JavaScript AMD Modules Using a Publishing Template

Oxygen XML WebHelp provides the ability to contribute a custom JavaScript Asynchronous Module Definition (AMD) resource in the output by referencing it in the Publishing Template descriptor file. This module is automatically copied to the output directory and it is automatically loaded in the output HTML pages using a require() call. Thus, you can include your scripts in the output without altering WebHelp's core JavaScript libraries.

This module may contain all of your custom functionality or can be used to load other AMD JavaScript modules. The additional sub-modules can be stored either locally in your custom Publishing Template or on a remote web server.
Important: To enable loading of a JS module you should set the webhelp.enable.template.js.module.loading parameter to yes (the default value is no) in the Publishing Template descriptor file or in the transformation scenario.

The JavaScript Modules

The JS Modules sample template contains a main JavaScript module (template-main.js) that loads other modules stored in the template package or in a remote location on the Internet.
define(['require'], function (require) {
    require(['./red', './italic', './tables']);
});
Besides the main JavaScript example, the template contains 3 other sub-modules:
  • red.js - Changes the font color of the publication title.
    define(["jquery"], function ($) {
    $(document).ready(function () {
        // Make the title red
        $('.wh_publication_title a').attr('style', 'color:red');
    });
});
  • italic.js - Changes the font style of your publication title.
    define(["jquery"], function ($) {
    $(document).ready(function () {
        // Make the title italic
        $('.wh_publication_title a').wrapInner('<i></i>');
    });
});
  • tables.js - Loads the DataTables jQuery plugin from a CDN.
    define(["jquery", 
    "https://cdn.datatables.net/1.10.16/js/jquery.dataTables.min.js"], function ($) {

    $(document).ready(function () {
        $('.table').DataTable();
    });
});
The JavaScript modules are stored in the Publishing Template package as follows:
[template-dir]
    [js]
        template-main.js
        italic.js
        red.js
        tables.js
Note:
  • The main module should be referenced in the Publishing Template descriptor file by specifying its path relative to the base directory of the template. 
    <js-amd-module file="js/template-main.js"/>
  • The main JS module is copied automatically to the output directory, but the sub-modules are not. To instruct the Publishing Template engine to copy those modules to the output directory you should include a <fileset> section in the Publishing Template descriptor file.
    <fileset>
    <include name="js/*.js"/>
</fileset>
  • The main module can reference other modules bundled in the publishing template package as follows:
    • Relative to template directory - Prefix their paths with the ID of the template directory: template-base-dir (for example: template-base-dir/js/italic).
    • Relative to the name of the current JS module - Use ./ to prefix the paths of the referenced modules.
    • The .js extension should be omitted for local modules, because the RequireJS library will add it automatically.