/wiki/JsPlate.wiki

  1#summary Creating JavaScript templates used by JsDoc Toolkit
  2= !JsPlate Introduction =
  3
  4!JsPlate is a !JavaScript-based templating system. This system is used by !JsDoc Toolkit to format the documentation information it parses out of your source files into published output, such as HTML web pages or XML documents.
  5
  6= Overview =
  7
  8As !JsDoc Toolkit uses them, a "template" is a directory containing the following files:
  9
 10  * publish.js
 11  * <!JsPlate template file/s>
 12  * <any other file/s>
 13
 14=== publish.js ===
 15The publish.js file is required. It defines and controls the process of publishing a collection of input and output files. Using !JsDoc Toolkit you may have many input files, and these may be combined or split in various ways into a complete package of output files.
 16
 17=== !JsPlate Files ===
 18A template file defines how to format some data into a particular kind of output file. It contains formatting instructions written in the !JsPlate microlanguage, a very simple template language that will be demonstrated below.
 19
 20=== Other Files ===
 21Other files you might include could be static resources like images, stylesheets, or whatever else you want to be part of your final published output.
 22
 23The expectation is that all output files will be saved to or copied over to a single output directory. By convention, the default name of this directory is "js_docs_out" but you can provide any name you prefer using the {{{-d=some/other/dir/}}} command line option.
 24
 25= publish.js In Detail =
 26
 27To create a !JsPlate template you first create a folder. The name of that folder is the name of the template. For example, if you wanted to create a template called "mytmp" you would start with an empty folder named "mytmp". Within your new template folder you must now create a file named `publish.js`. A very minimal publish.js file might look like this:
 28
 29{{{
 30function publish(fileGroup, context) {
 31}
 32}}}
 33
 34As you can see, there is one function defined in the `publish.js` file: In the `publish` function you can add any code you like to handle the main publishing work. !JsDoc Toolkit will pass in a fileGroup object along with the commandline options you provided when you invoked the application.
 35
 36A fileGroup has a property called `files` that contains information about every file the parser scanned. You can iterate over that to get information about each file.
 37
 38{{{
 39function publish(fileGroup, context) {
 40	var file_template = new JsPlate(context.t+"file.tmpl");
 41
 42	for (var i = 0; i < fileGroup.files.length; i++) {
 43		var output = template.process(fileGroup.files[i]);
 44	}
 45}
 46}}}
 47
 48
 49= !JsPlate In Detail =
 50
 51The !JsPlate micro-language really is "micro" -- it has exactly four syntax constructs. The first two are tags:
 52
 53  * `<for>...</for>` - loops over objects in an array or named in an object.
 54  * `<if>...</if>` - conditionally renders some content based on a test.
 55
 56Additionally there are two field specifiers.
 57
 58  * `{+foo+}` - inserts the value in the foo variable into the template output.
 59  * `{!doSomething();!}` - evaluates the !JavaScript code.
 60
 61The content of a `{+ ... +}` doesn't have to be static, for example you can insert the current date into the output like so: `{+ new Date() +}`. Similarly, notice that  `{+ foo +}` is really just a nicer way of saying: `{! output += foo; !}` -- you can manipulate `output` directly from within `{! ... !}` if you want. Comments can be added using the `{# this is ignored #}` syntax.
 62
 63== for Loops ==
 64
 65The `for` mark-up tag lets you loop over all the items stored in an array or stored in an object as properties. For example, assume that `data.things` is an array. To render a list of the things in your output, you could do the following:
 66
 67{{{
 68<ul>
 69<for each="thing" in="data.things">
 70	<li>{+thing+}</li>
 71</for>
 72</ul>
 73}}}
 74
 75
 76This would work exactly the same if you were accessing all the _values_ stored in an object: if `data.things` were set to {Sue: "red", Bob: "blue"} the above code would print the values like so:
 77
 78{{{
 79<ul>
 80
 81	<li>red</li>
 82	<li>blue</li>
 83
 84</ul>
 85}}}
 86
 87If you were only interested in outputting the keys, not the values, you could use the built-in `keys` function like so:
 88
 89{{{
 90<ul>
 91<for each="thing" in="keys(data.things)">
 92	<li>{+thing+}</li>
 93</for>
 94</ul>
 95}}}
 96
 97Which would yield:
 98{{{
 99<ul>
100
101	<li>Sue</li>
102	<li>Bob</li>
103
104</ul>
105}}}
106
107And, since the `in` attribute can take any !JavaScript as it's value you can get sorted keys like so.
108
109{{{
110<ul>
111<for each="thing" in="keys(data.things).sort()">
112	<li>{+thing+}</li>
113</for>
114</ul>
115}}}
116
117Which would yield:
118{{{
119<ul>
120
121	<li>Bob</li>
122	<li>Sue</li>
123
124</ul>
125}}}
126
127If you wanted both the keys and values you can use the special key varaible that exists within each `for` loop. If the value is assigned to "foo" the key would be available as "$foo_key" like so:
128
129{{{
130<ul>
131<for each="thing" in="data.things">
132	<li>{+$thing_key+": "+thing+}</li>
133</for>
134</ul>
135}}}
136
137Resulting in:
138
139{{{
140<ul>
141
142	<li>Bob: blue</li>
143	<li>Sue: red</li>
144
145</ul>
146}}}
147
148Using another special variable you can get the numeric index of a `for` loop. If the value is assigned to "foo" the numeric key would be available as "$foo_i" like so:
149
150{{{
151<ul>
152<for each="thing" in="data.things">
153	<li>{+$thing_i+": "+thing+}</li>
154</for>
155</ul>
156}}}
157
158Resulting in:
159
160{{{
161<ul>
162
163	<li>0: blue</li>
164	<li>1: red</li>
165
166</ul>
167}}}
168
169Finally, within a `for` loop there is a way to detect if you are on the last iteration. If the value is assigned to "foo" the boolean that indicates the last loop will be available as "$foo_last" like so:
170
171{{{
172<ul>
173<for each="thing" in="data.things">
174	<li>{+thing+}</li>
175	<if test="!$thing_last">...</if>
176</for>
177</ul>
178}}}
179
180Resulting in:
181
182{{{
183<ul>
184
185	<li>blue</li>
186	...
187	<li>red</li>
188
189</ul>
190}}}
191== if Blocks ==
192
193The `if` mark-up allows you conditionally output some text or field based on a test.
194
195{{{
196<if test="thing=='Bob'">
197	<em>The Best</em>
198</if>
199}}}
200
201Would only add "The Best" to the output when the `thing` was "Bob." You can of course nest `for` and `if` as much as you need, perhaps only looping in certain conditions, or only doing certain things for certain loop iterations.
202
203{{{
204<if test="thing=='Bob'">
205	<em>The Best</em>
206<else />
207	<em>meh!</em>
208</if>
209}}}
210
211= Creating Output Files =
212
213== Saving Generated Output To Files ==
214
215From within your `publish.js` file you can save the your template output to files using the `IO.saveFile` function.
216
217{{{
218function publish(fileGroup, context) {
219	var file_template = new JsPlate(context.t+"file.tmpl");
220
221	for (var i = 0; i < fileGroup.files.length; i++) {
222		var output = template.process(fileGroup.files[i]);
223		IO.saveFile(context.d, "docs"+i+".htm", output);
224	}
225}
226}}}
227
228The `IO.saveFile` function takes an output directory as it's first argument, and this will automatically be set on the `context` based on what output directory you specified on the command line when you executed !JsDoc Toolkit.
229
230== Copying Static Files To The Output Directory==
231
232From within your `publish.js` file you can copy files from the template directory into the output directory using the `IO.copyFile` function. For example if you had a static css file that you wanted copied into the output directory, you could do this:
233
234{{{
235	IO.copyFile(context.t+"mystyle.css", context.d);
236}}}
237