Skip to content

JavaScript AMD Modules

Jump to bottom
Alin Balasa edited this page Jun 14, 2018 · 9 revisions

Demonstrates how to include JavaScript AMD modules in a Publishing Template.

Use case

Let's assume that you want to include in the WebHelp Responsive output 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 in the User Manual.

<html>
  <script type="text/javascript" src="${oxygen-webhelp-output-dir}/js/template-main.js"/>
</html>

Problem

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

Usually, a JavaScript AMD module should 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>

    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. In conclusion, this approach can not be used to load your custom JS module, 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.

Solution

Oxygen XML WebHelp comes with a feature that lets you specify a JavaScript AMD module in the Publishing Template descriptor. This module is automatically copied in the output directory and it is automatically loaded in the output HTML pages using a require() call. This way, you can include your scripts in the output without altering WebHelp's core JavaScript libraries. This module may contain all 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.

📓 Note: 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

This 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 module, the template contains 3 other submodules:

  • 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

📓 Notes:

  • The main module should be referenced in the Publishing Template descriptor file 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 submodules are not. In order to instruct the Publishing Template engine to copy those modules to the output directory you should include in the Publishing Template descriptor file a <fileset> section. 
    <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 (e.g: 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.

Template resources

  • dita/flowers/ - Contains the DITA map sample that can be published using this template.
  • templates/generation-time/ - The JS Modules Publishing Template package (read more about the package contents here):
    • js/ - Contains the JavaScript module files.
    • js-modules.css - The base CSS that defines the styles of the WebHelp output.
    • js-modules.png - Preview image.
    • js-modules.opt - The Publishing Template descriptor file.

How to use this template

  1. Open the dita/flowers/flowers.ditamap DITA map in the DITA Maps Manager view.
  2. Open the Configure Transformation Scenario(s) dialog.
  3. Duplicate the DITA Map WebHelp Responsive built-in transformation scenario.
  4. Select the JS Modules template.
  5. Click OK to save the scenario.
  6. Apply the transformation scenario to publish the DITA map to WebHelp Responsive format.

Publishing Templates:

Clone this wiki locally