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 😦
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
<require> element explicitly defines org.dita.html5 as a dependency.
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:
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.