This week I’ve been doing some research on how to make JS scripts work with DITA-based topics in the XML documentation plug-in for Adobe Experience Manager.
While defining the scope of my research, I identified three possible approaches:
- Directly embed the script (and eventually, the accompanying CSS styles) into a DITA topic
- Insert the script in the generated HTML
- Create a separate HTML (not XML-based) with the embedded JS + CSS styles and link it from a DITA topic via a file reference link (dirty fix)
My goal was to add interactive decision trees to the content generated with AEM. For more information, see: Adding Interactivity to your Content
As I found out, at least two of the aforementioned options should work, with some caveats.
Option 1: Embed the Script Directly into a DITA Topic
This option is not supported by DITA, as the <script> tag can not be used in .dita files 😦
DITA does not integrate with JavaScript libraries. In theory, there is some workaround you can use if you have an Oxygen license. However, this option has some limitations, as its web help “strips out a lot of the elements (such as product, audience, platform, etc.) that would normally be coded as data elements to allow JavaScript listeners to trigger. You can make a lot of these JavaScript libraries work in DITA, but it’s a major hassle”
For more information see: https://idratherbewriting.com/2015/01/28/10-reasons-for-moving-away-from-dita/
Option 2: Insert the Script in the Generated HTML
This is one of the options that could (potentially) work. To implement it, we have to bundle the JS code in a custom plug-in that creates a new transformation type: html5-javascript. The plug-in extends the default HTML5 transformation, so that the <require> element explicitly defines org.dita.html5 as a dependency.
In one of the plug-in subfolders, we’d create a file named javascript.ftr.xml which contains the JavaScript code. In this case, the <script> wrapping is supported.
The code would be then automatically inserted in the generated html. For more information, see: https://www.dita-ot.org/dev/topics/html-customization-plugin-javascript.html
We’d still have to figure out how to deal with the styles used to build the decision tree in html in the first place (legend and fieldset) and convert them to DITA attributes.
Option 3: Create a Separate HTML and Link it from a DITA topic Via a Reference Link
This should be used as a last resort, as it would mean to mingle different file types for creating the output. It should only be used in case option 2 cannot be implemented.
What we would do here is to customise an HTML file to make it look like a DITA-based file. The html file would be linked from a DITA topic via a reference link:
“File Reference
Opens a dialog box that allows you to insert a link to a target non-DITA file resource at the current location within a document. The target resource can be the location of a file or a key that is already defined in your DITA map structure. It inserts an <xref> element with either an @href attribute or a @keyref attribute. If you select Location for the target, the link is expressed in an @href attribute. If you select Key for the target, keys will be used to express the link in a @keyref attribute. You can select a key from the drop-down list or click the Choose Key Reference button to use the Choose Key dialog box.”
This solution is a “dirty fix” because it requires some manual effort as the xrefs contained in the html are not updated dynamically, which is certainly error-prone…
As you see, there is not an optimal solution to combine JS and DITA. However, with some workarounds you can make the two of them work together.
Marina Hernandez 