/
html-customization-plugin-javascript.dita
139 lines (139 loc) · 7.77 KB
/
html-customization-plugin-javascript.dita
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-plugin-webfont">
<title>Inserting JavaScript in generated HTML</title>
<titlealts>
<navtitle>Inserting JavaScript</navtitle>
</titlealts>
<shortdesc>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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>footer</xmlelement></indexterm>
<indexterm><xmlelement>require</xmlelement></indexterm>
<indexterm><xmlelement>head</xmlelement></indexterm>
<indexterm>HTML5
<indexterm>JavaScript, adding</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>This scenario walks through the process of creating a very simple plug-in
(<codeph>com.example.html5-javascript</codeph>) that creates a new transformation type:
<option>html5-javascript</option>. </p>
<p>The <option>html5-javascript</option> transformation includes a custom page footer file with a JavaScript
tracking snippet and sets the <parmname>args.ftr</parmname> parameter to integrate the script content in the
HTML5 <xmlelement>footer</xmlelement> element of the generated pages.</p>
<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.</note>
</context>
<steps>
<step>
<cmd>In the <filepath>plugins</filepath> directory, create a directory named
<filepath>com.example.html5-javascript</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>com.example.html5-javascript</filepath> directory, create a plug-in configuration file
(<filepath>plugin.xml</filepath>) that declares the new <option>html5-javascript</option> transformation and
its dependencies.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>plugin.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/plugin.xml"
/></codeblock>
</fig>
<note>This plug-in will extend the default HTML5 transformation, so the <xmlelement>require</xmlelement>
element explicitly defines <filepath>org.dita.html5</filepath> as a dependency.</note>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-javascript</filepath> directory, create a subdirectory named
<filepath>include</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>include</filepath> subdirectory, create a file named
<filepath>javascript.ftr.xml</filepath> with your custom JavaScript code.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>javascript.ftr.xml</filepath> file</title>
<codeblock outputclass="language-javascript normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/include/javascript.ftr.xml"
/></codeblock>
</fig>
<p>The division wrapper will be discarded when generating HTML files, and the contents will be inserted into
the <xmlelement>footer</xmlelement> element of each page.</p>
<p>The file contents must be well-formed XML. If your JavaScript snippets include attributes without values
(such as the <codeph>async</codeph> script attribute), use valid XML syntax to define the empty
attribute:</p>
<p>Instead of:
<codeblock outputclass="language-javascript normalize-space show-line-numbers show-whitespace"><script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
</script></codeblock>
</p>
<p>use:
<codeblock outputclass="language-javascript normalize-space show-line-numbers show-whitespace"><script>
<script id="MathJax-script" <b
>async=""</b> src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
</script></codeblock>
</p>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-javascript</filepath> root directory, add an Ant script
(<filepath>build_html5-javascript.xml</filepath>) to define the transformation type and set the path to the
JavaScript footer file created in the previous step.</cmd>
<stepxmp>
<fig>
<title>Sample build file: <filepath>build_html5-javascript.xml</filepath></title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/build_html5-javascript.xml"
/></codeblock>
</fig>
</stepxmp>
<info>
<note>When defining the path to the footer file from the Ant script, use the plug-in directory property with
the <varname>plugin-id</varname> as shown in the example above:
<codeph>${dita.plugin.<varname>plugin-id</varname>.dir}</codeph>.</note>
</info>
</step>
</steps>
<result>
<note type="tip">The files for this sample plug-in are included in the DITA-OT installation directory under
<filepath>docsrc/samples/plugins/com.example.html5-javascript/</filepath> and on
<xref
href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-javascript"
format="html"
scope="external"
>GitHub</xref>.</note>
<p>The plug-in directory has the following layout and files:</p>
<codeblock>com.example.html5-javascript
├── build_html5-javascript.xml
├── include
│ └── javascript.ftr.xml
└── plugin.xml</codeblock>
</result>
<postreq>
<ol>
<li conkeyref="conref-task/install-plugin-postreq-li"/>
<li>Build output with the new transformation type to verify that the plug-in works as intended.
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>html5-javascript</option></codeblock></li>
<li>Open one of the generated HTML topic files in a modern web browser and check the JavaScript
<uicontrol>Console</uicontrol>. When the page is loaded, <msgph>Adding Google Analytics tracker</msgph> will
appear on the console to verify that the sample script is loaded.</li>
<li>Remove the <codeph>console.log</codeph> debugging message from the sample JavaScript code, and replace the
<codeph>'UA-XXXXX-Y'</codeph> placeholder string with the tracking ID of the Google Analytics property you
wish to track.</li>
</ol>
<note type="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 <codeph>async</codeph> script attribute, you may prefer to insert the
JavaScript snippet in the <xmlelement>head</xmlelement> element of the generated HTML files using the
<parmname>args.hdf</parmname> parameter instead.</note>
</postreq>
</taskbody>
</task>