none
[openafs-wiki.git] / TWiki / TwistyPlugin.mdwn
1 # <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
2
3 **A "twisty" is an interface toggle control to show and hide content.**
4
5 TwistyPlugin gives you several options to control the appearance of a twisty:
6
7 - use link text or buttons
8 - position an icon left or right
9 - remember the state at the next visit of the page
10 - start the Twisty open or closed
11 - start the Twisty open or closed for the first visit
12 - use a span or div for the content
13 - set a class for the content span or div
14
15 Twisty has a fallback mechanism in case JavaScript is not available: all content is displayed and the control buttons are hidden.
16
17 <div><span>On this page:</span><ul>
18     <li><a href="#Usage examples"> Usage examples</a><ul>
19         <li><a href="#Triad"> Triad</a></li>
20         <li><a href="#Shorthand"> Shorthand</a></li>
21         <li><a href="#Twisty with icons"> Twisty with icons</a></li>
22         <li><a href="#Make it remember"> Make it remember</a></li>
23         <li><a href="#Make it obey"> Make it obey</a></li>
24         <li><a href="#Make it obey only the first time"> Make it obey only the first time</a></li>
25         <li><a href="#Other use: hide interface parts"> Other use: hide interface parts in case of no JavaScript</a></li>
26         <li><a href="#Styling the Twisty"> Styling the Twisty</a></li>
27         <li><a href="#Twisty headers"> Twisty headers</a></li>
28         <li><a href="#All on, all off"> All on, all off</a></li>
29       </ul>
30     </li>
31     <li><a href="#Special syntax: format tokens"> Special syntax: format tokens</a></li>
32     <li><a href="#Syntax"> Syntax</a><ul>
33         <li><a href="#TWISTY"> TWISTY</a></li>
34         <li><a href="#ENDTWISTY"> ENDTWISTY</a></li>
35       </ul>
36     </li>
37     <li><a href="#Twisty components syntax"> Twisty components syntax</a><ul>
38         <li><a href="#TWISTYBUTTON"> TWISTYBUTTON</a></li>
39         <li><a href="#TWISTYSHOW"> TWISTYSHOW</a></li>
40         <li><a href="#TWISTYHIDE"> TWISTYHIDE</a></li>
41         <li><a href="#TWISTYTOGGLE"> TWISTYTOGGLE</a></li>
42         <li><a href="#ENDTWISTYTOGGLE"> ENDTWISTYTOGGLE</a></li>
43       </ul>
44     </li>
45     <li><a href="#The Fine Print"> The Fine Print</a></li>
46     <li><a href="#Plugin Settings"> Plugin Settings</a></li>
47     <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
48     <li><a href="#Plugin Info"> Plugin Info</a></li>
49   </ul>
50 </div>
51
52 ## <a name="Usage examples"></a> Usage examples
53
54 ### <a name="Triad"></a> Triad
55
56 A Twisty consists of 3 elements:
57
58 1. Show button
59 2. Hide button
60 3. Collapsing content ('Toggle')
61
62 The typical TwistyPlugin triad will look like this (pseudo code):
63
64     %TWISTYSHOW{}% %TWISTYHIDE{}%
65     (there may be other things between buttons and content)
66     %TWISTYTOGGLE{}% my content %ENDTWISTYTOGGLE%
67
68 ### <a name="Shorthand"></a> Shorthand
69
70 The Twisty triad is conveniently packed into shorthand `%TWISTY{some parameters}% Collapsing content %ENDTWISTY%`:
71
72     %TWISTY{}%
73     my twisty content
74     %ENDTWISTY%
75
76 Will generate:
77
78 <span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
79
80 <div style="display: inline"><span id="twistyId1toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
81
82 You may have noticed that no parameters are passed to `%TWISTY{}%` but the show and hide links _do_ have text! The default values are fetched from plugin settings `TWISTYSHOWLINK` and `TWISTYHIDELINK`, see [[Plugin Settings|Main/WebHome#PluginSettings]] below.
83
84 ### <a name="Twisty with icons"></a> Twisty with icons
85
86 We will use `mode="div"` to put the collapsing content below the button (the default mode is `"span"`).
87
88     %TWISTY{
89     mode="div"
90     showlink="Show..."
91     hidelink="Hide"
92     showimgleft="%ICONURLPATH{toggleopen-small}%"
93     hideimgleft="%ICONURLPATH{toggleclose-small}%"
94     }%
95     my twisty content
96     %ENDTWISTY%
97
98 It will look like this:
99
100 <span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleopen-small.gif)<span>Show...</span>](#)</span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleclose-small.gif)<span>Hide</span>](#)</span></span>
101
102 <div style="display: inline">
103   <div id="twistyId2toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
104 </div>
105
106 To put icons at the right side, write
107
108     %TWISTY{
109     mode="div"
110     showlink="Show&nbsp;"
111     hidelink="Hide&nbsp;"
112     showimgright="%ICONURLPATH{toggleopen-small}%"
113     hideimgright="%ICONURLPATH{toggleclose-small}%"
114     }%
115     my twisty content
116     %ENDTWISTY%
117
118 <span><span>[<span>Show </span>![](http://www.dementia.org/twiki//view/Main/WebHome/toggleopen-small.gif)](#)</span><span>[<span>Hide </span>![](http://www.dementia.org/twiki//view/Main/WebHome/toggleclose-small.gif)](#)</span></span>
119
120 <div style="display: inline">
121   <div id="twistyId3toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
122 </div>
123
124 ### <a name="Make it remember"></a> Make it remember
125
126 To store the last state in a TWIKIPREF cookie, add the parameter `remember="on"`.%BR% To test this, reload the page after toggling.
127
128     %TWISTY{
129     showlink="Show..."
130     hidelink="Hide"
131     remember="on"
132     }%
133     my twisty content
134     %ENDTWISTY%
135
136 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
137
138 <div style="display: inline"><span id="twistyId4toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
139
140 If a Twisty state has been stored in a TWIKIPREF cookie before, it can be cleared by using `remember="off"`:
141
142     %TWISTY{
143     showlink="Show..."
144     hidelink="Hide"
145     remember="off"
146     }%
147     my twisty content
148     %ENDTWISTY%
149
150 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
151
152 <div style="display: inline"><span id="twistyId5toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
153
154 **NOTE:** Twisty ids are generated automatically. If you need control over exactly _which_ Twisty should be remembered, add the parameter `id`:
155
156     %TWISTY{
157     id="currentCustomerList"
158     showlink="Show..."
159     hidelink="Hide"
160     remember="on"
161     }%
162     my customer list
163     %ENDTWISTY%
164
165 Note that `id` sets a sitewide cookie. To create a unique id, add topic or web variables:
166
167     id="%WEB%_%TOPIC%_currentCustomerList"
168
169 ### <a name="Make it obey"></a> Make it obey
170
171 To let the Twisty start with its content folded open, add parameter `start="show"`.
172
173     %TWISTY{
174     showlink="Show..."
175     hidelink="Hide"
176     start="show"
177     }%
178     my twisty content
179     %ENDTWISTY%
180
181 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
182
183 <div style="display: inline"><span id="twistyId6toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
184
185 Likewise use `start="hide"` to start with hidden content.
186
187     %TWISTY{
188     showlink="Show..."
189     hidelink="Hide"
190     start="hide"
191     }%
192     my twisty content
193     %ENDTWISTY%
194
195 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
196
197 <div style="display: inline"><span id="twistyId7toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
198
199 ### <a name="Make it obey only the first time"></a> Make it obey only the first time
200
201 To let the Twisty start with its content folded open the first time the visitor sees the Twisty, add the parameter `firststart="show"`. If `remember="on"` is used, subsequential visits to the page will display the Twisty according the cookie setting.
202
203     %TWISTY{
204     showlink="Show..."
205     hidelink="Hide"
206     firststart="show"
207     }%
208     my twisty content
209     %ENDTWISTY%
210
211 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
212
213 <div style="display: inline"><span id="twistyId8toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
214
215 ### <a name="Other use: hide interface parts"></a><a name="Other use: hide interface parts "></a> Other use: hide interface parts in case of no JavaScript
216
217 You can use Twisty to show interface elements that should only be visible with JavaScript enabled. For instance the textbox control buttons in the edit screen need JavaScript to work. If a visitor does not have JavaScript on it would not make sense to show these buttons.
218
219 Put the "JavaScript content" in an almost bare bones Twisty. Write `showlink="" hidelink=""` to not display any default link texts.
220
221     %TWISTY{
222     link=""
223     noscript="hide"
224     start="show"
225     }%
226     <input type="submit" class="twikiButton" value="You surely have !JavaScript" />
227     %ENDTWISTY%
228
229 <span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
230
231 <div style="display: inline"><span id="twistyId9toggle"><input type="submit" value="You surely have JavaScript" /> </span></div>
232
233 Do not forget to set `start="show"` to show the Twisty content at all.
234
235 When JavaScript is off, the button should be invisible.
236
237 This code will show the button when JavaScript is off:
238
239     %TWISTY{
240     link=""
241     start="show"
242     }%
243     <input type="submit" class="twikiButton" value="You might have !JavaScript" />
244     %ENDTWISTY%
245
246 <span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
247
248 <div style="display: inline"><span id="twistyId10toggle"><input type="submit" value="You might have JavaScript" /> </span></div>
249
250 ### <a name="Styling the Twisty"></a> Styling the Twisty
251
252 Use parameter `class` to style the content div or class:
253
254     %TWISTY{
255     mode="div"
256     showlink="Show..."
257     hidelink="Hide"
258     class="twikiHelp"
259     }%
260     my twisty content
261     %ENDTWISTY%
262
263 Generates: %BR% <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
264
265 <div style="display: inline">
266   <div id="twistyId11toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
267 </div>
268
269 ### <a name="Twisty headers"></a> Twisty headers
270
271 To be able to use header tags like `<h2>`, use the properties `prefix` and `suffix`. Because we have identical show and hide links we can use the shorthand property `link`.
272
273     %TWISTY{
274     prefix="<h4>!!"
275     mode="div"
276     link="Header"
277     showimgleft="%ICONURLPATH{toggleopen}%"
278     hideimgleft="%ICONURLPATH{toggleclose}%"
279     suffix="</h4>"
280     }%
281     my twisty content
282     %ENDTWISTY%
283
284 Add the `!!` to prevent the twisty header appear in the table of contents when you use `%TOC%`.
285
286 Will create:
287
288 #### <a name="Header%_TWISTYSCRIPT{&quot;TWiki._Twi"></a> <span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleopen.gif)<span>Header</span>](#)</span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleclose.gif)<span>Header</span>](#)</span></span>
289
290 <div style="display: inline">
291   <div id="twistyId12toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
292 </div>
293
294 ### <a name="All on, all off"></a> All on, all off
295
296 You can toggle all Twisties on or off at once by putting a link or button on the page with class `twistyExpandAll` or `twistyCollapseAll`.
297
298     <button class="twistyExpandAll twikiButton">Expand all</button> &nbsp; <button class="twistyCollapseAll twikiButton">Collapse all</button>
299
300 Creates these controls:
301
302 <button>Expand all</button>
303
304 <button>Collapse all</button>
305
306 When you want to use links, write:
307
308     #VarTOGGLE
309
310     <a href="#TOGGLE" class="twistyExpandAll">Expand all</a> &nbsp;
311     <a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>
312
313 <a name="VarTOGGLE"></a>
314
315 [Expand all](#TOGGLE)   [Collapse all](#TOGGLE)
316
317 ## <a name="Special syntax: format tokens"></a> Special syntax: format tokens
318
319 If you use TWiki variables inside TWISTY parameters chances are it will mess up the variable, or the rendered html. Use format tokens to 'delay' rendering of these variables until the Twisty parameters are parsed.
320
321 The format tokens are the same as with [[FormattedSearch]]:
322
323 <table border="1" cellpadding="0" cellspacing="0">
324   <tr>
325     <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
326     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
327   </tr>
328   <tr>
329     <td><code>$n</code> or <code>$n()</code></td>
330     <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
331   </tr>
332   <tr>
333     <td><code>$nop</code> or <code>$nop()</code></td>
334     <td> Is a "no operation". </td>
335   </tr>
336   <tr>
337     <td><code>$quot</code></td>
338     <td> Double quote (<code>"</code>) </td>
339   </tr>
340   <tr>
341     <td><code>$percnt</code></td>
342     <td> Percent sign (<code>%</code>) </td>
343   </tr>
344   <tr>
345     <td><code>$dollar</code></td>
346     <td> Dollar sign (<code>$</code>) </td>
347   </tr>
348 </table>
349
350 For example, to show an icon inside the link, do not write:
351
352     link="%Y%"
353
354 but use format tokens:
355
356     link="$percntY$percnt"
357
358 ... to get:
359
360 <span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleopen-small.gif)<span>$percntY$percnt</span>](#)</span><span>[![](http://www.dementia.org/twiki//view/Main/WebHome/toggleclose-small.gif)<span>$percntY$percnt</span>](#)</span></span>
361
362 <div style="display: inline">
363   <div id="twistyId13toggle"> my twisty content </div>
364 </div>
365
366 Or a more complex example using [[SpreadsheetPlugin]]; do not write:
367
368     link="Count: (%CALC{"$GET(infoCount)"}%)"
369
370 but use format tokens:
371
372     link="Count: ($percntCALC{$quot$dollarGET(infoCount)$quot}$percnt)"
373
374 ## <a name="Syntax"></a> Syntax
375
376 <a name="VarTWISTY"></a>
377
378 ### <a name="TWISTY"></a> TWISTY
379
380 This renders the button as well as the toggled content section contained within this and the closing ENDTWISTY tag. %BR% Usage: `%TWISTY{ ... }% Toggable contents %ENDTWISTY%`
381
382 <table border="1" cellpadding="0" cellspacing="0">
383   <tr>
384     <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
385     <th bgcolor="#99CCCC"><strong> Value </strong></th>
386     <th bgcolor="#99CCCC"><strong> Description </strong></th>
387     <th bgcolor="#99CCCC"><strong> Remark </strong></th>
388   </tr>
389   <tr>
390     <td><code>id</code></td>
391     <td> Unique identifier </td>
392     <td> Used to link [[Main/WebHome#VarTWISTYBUTTON]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
393     <td> optional </td>
394   </tr>
395   <tr>
396     <td><code>link</code></td>
397     <td> Link label </td>
398     <td> Link label for both show and hide links </td>
399     <td> optional </td>
400   </tr>
401   <tr>
402     <td><code>hidelink</code></td>
403     <td> Link label </td>
404     <td> Hide link label </td>
405     <td> optional </td>
406   </tr>
407   <tr>
408     <td><code>showlink</code></td>
409     <td> Link label </td>
410     <td> Show link label </td>
411     <td> optional </td>
412   </tr>
413   <tr>
414     <td><code>mode</code></td>
415     <td><code>"div"</code> or <code>"span"</code></td>
416     <td> Specify if the Twisty Toggle section will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. Note that if the contents contains block elements such as <code>div</code>, <code>mode</code> should be <code>div</code> as well to create valid HTML markup. </td>
417     <td> optional, defaults to <code>&lt;span&gt;</code></td>
418   </tr>
419   <tr>
420     <td><code>showimgleft</code></td>
421     <td> Image url </td>
422     <td> Specify the url of an image that will be displayed with the show link at the left side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
423     <td> optional, defaults to no image </td>
424   </tr>
425   <tr>
426     <td><code>hideimgleft</code></td>
427     <td> Image url </td>
428     <td> Specify the url of an image that will be displayed with the hide link at the left side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
429     <td> optional, defaults to no image </td>
430   </tr>
431   <tr>
432     <td><code>showimgright</code></td>
433     <td> Image url </td>
434     <td> Specify the url of an image that will be displayed with the show link at the right side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
435     <td> optional, defaults to no image </td>
436   </tr>
437   <tr>
438     <td><code>hideimgright</code></td>
439     <td> Image url </td>
440     <td> Specify the url of an image that will be displayed with the hide link at the right side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
441     <td> optional, defaults to no image </td>
442   </tr>
443   <tr>
444     <td><code>remember</code></td>
445     <td><code>"on"</code>, <code>"off"</code></td>
446     <td> If <code>"on"</code>, the Twisty state is remembered the next time the page is shown. If <code>"off"</code>, the stored setting will be cleared.<br /><strong>Note:</strong> when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked. </td>
447     <td> optional, no default </td>
448   </tr>
449   <tr>
450     <td><code>start</code></td>
451     <td><code>"hide"</code> or <code>"show"</code></td>
452     <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
453     <td> optional, default no initial state </td>
454   </tr>
455   <tr>
456     <td><code>firststart</code></td>
457     <td><code>"hide"</code> or <code>"show"</code></td>
458     <td> Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see <code>remember</code>). </td>
459     <td> optional, default no initial state </td>
460   </tr>
461   <tr>
462     <td><code>noscript</code></td>
463     <td><code>"hide"</code></td>
464     <td> Make content hidden in case use does not have JavaScript on </td>
465     <td> optional, default content is shown in case JavaScript if off </td>
466   </tr>
467   <tr>
468     <td><code>class</code></td>
469     <td> CSS class name </td>
470     <td> Class for Twisty div or span </td>
471     <td> optional, default none </td>
472   </tr>
473   <tr>
474     <td><code>prefix</code></td>
475     <td> Text </td>
476     <td> Text to display before the show/hide links </td>
477     <td> optional, default none </td>
478   </tr>
479   <tr>
480     <td><code>suffix</code></td>
481     <td> Text </td>
482     <td> Text to display after the show/hide links </td>
483     <td> optional, default none </td>
484   </tr>
485   <tr>
486     <td><code>img</code></td>
487     <td> Image url </td>
488     <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
489     <td> optional, defaults to no image </td>
490   </tr>
491   <tr>
492     <td><code>imgleft</code></td>
493     <td> Image url </td>
494     <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
495     <td> optional, defaults to no image </td>
496   </tr>
497   <tr>
498     <td><code>imgright</code></td>
499     <td> Image url </td>
500     <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
501     <td> optional, defaults to no image </td>
502   </tr>
503   <tr>
504     <td><code>hideimg</code></td>
505     <td> Image url </td>
506     <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
507     <td> optional, defaults to no image </td>
508   </tr>
509   <tr>
510     <td><code>showimg</code></td>
511     <td> Image url </td>
512     <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
513     <td> optional, defaults to no image </td>
514   </tr>
515 </table>
516
517 - Related [[TWISTYBUTTON|Main/WebHome#VarTWISTYSHOW]] and [[TWISTYTOGGLE|Main/WebHome#VarTWISTYTOGGLE]]
518
519 <a name="VarENDTWISTY"></a>
520
521 ### <a name="ENDTWISTY"></a> ENDTWISTY
522
523 **Twisty closure, complements the opening TWISTY tag.**
524
525 - Syntax: `%ENDTWISTY%`
526
527 See [[ENDTWISTYTOGGLE|Main/WebHome#VarENDTWISTYTOGGLE]].
528
529 ## <a name="Twisty components syntax"></a> Twisty components syntax
530
531 <div style="background-color: #eee; padding: .5em; margin: -.5em">
532   <p> Ocassionally you might need to create a custom set of individual Twisty components: </p>
533   <p><a name="VarTWISTYBUTTON"></a></p>
534   <h3><a name="TWISTYBUTTON"></a> TWISTYBUTTON </h3><strong>Shorthand version for TWISTYSHOW &amp; TWISTYHIDE</strong> This is useful if both the show and the hide button take the same arguments. <ul>
535     <li> Supported parameters: all parameters supported by [[Main/WebHome#VarTWISTYSHOW]], except for <code>noscript</code> and <code>class</code> (only used for 'toggle' content) </li>
536     <li> Parameter differences: <ul>
537         <li><code>mode</code>: button mode defaults to span </li>
538       </ul>
539     </li>
540     <li> Syntax: <code>%TWISTYBUTTON{id="myid" ... }%</code></li>
541     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
542         <tr>
543           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
544           <th bgcolor="#99CCCC"><strong> Value </strong></th>
545           <th bgcolor="#99CCCC"><strong> Description </strong></th>
546           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
547         </tr>
548         <tr>
549           <td><code>mode</code></td>
550           <td><code>"div"</code> or <code>"span"</code></td>
551           <td> Specify if the <strong>Twisty button</strong> will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. Note that if the contents contains block elements such as <code>div</code>, <code>mode</code> should be <code>div</code> as well to create valid HTML markup. </td>
552           <td> optional, defaults to <code>&lt;span&gt;</code></td>
553         </tr>
554       </table>
555     </li>
556     <li> Example: <code>%TWISTYBUTTON{id="myid" link="more"}%%TWISTYTOGGLE{id="myid"}%content%ENDTWISTYTOGGLE%</code></li>
557     <li> Related: [[Main/WebHome#VarTWISTYSHOW]] and [[Main/WebHome#VarTWISTYHIDE]]</li>
558   </ul>
559   <p><a name="VarTWISTYSHOW"></a></p>
560   <h3><a name="TWISTYSHOW"></a> TWISTYSHOW </h3><strong>Show/open link</strong><ul>
561     <li> Syntax: <code>%TWISTYSHOW{id="myid" ... }%</code></li>
562     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
563         <tr>
564           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
565           <th bgcolor="#99CCCC"><strong> Value </strong></th>
566           <th bgcolor="#99CCCC"><strong> Description </strong></th>
567           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
568         </tr>
569         <tr>
570           <td><code>id</code></td>
571           <td> Unique identifier </td>
572           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
573           <td> required </td>
574         </tr>
575         <tr>
576           <td><code>link</code></td>
577           <td> Link label </td>
578           <td> Show link label </td>
579           <td> optional </td>
580         </tr>
581         <tr>
582           <td><code>mode</code></td>
583           <td><code>"div"</code> or <code>"span"</code></td>
584           <td> Specify if the Twisty Show link will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. Note that if the contents contains block elements such as <code>div</code>, <code>mode</code> should be <code>div</code> as well to create valid HTML markup. </td>
585           <td> optional, defaults to <code>&lt;span&gt;</code></td>
586         </tr>
587         <tr>
588           <td><code>img</code></td>
589           <td> Image url </td>
590           <td> Specify the url of an image that will be displayed at the <strong>right side</strong> of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
591           <td> optional, defaults to no image </td>
592         </tr>
593         <tr>
594           <td><code>imgleft</code></td>
595           <td> Image url </td>
596           <td> Specify the url of an image that will be displayed at the left side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
597           <td> optional, defaults to no image </td>
598         </tr>
599         <tr>
600           <td><code>imgright</code></td>
601           <td> Image url </td>
602           <td> Specify the url of an image that will be displayed at the right side of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
603           <td> optional, defaults to no image </td>
604         </tr>
605         <tr>
606           <td><code>remember</code></td>
607           <td><code>"on"</code>, <code>"off"</code></td>
608           <td> If <code>"on"</code>, the Twisty state is remembered the next time the page is shown. If <code>"off"</code>, the stored setting will be cleared.<br /><strong>Note:</strong> when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked. </td>
609           <td> optional, no default </td>
610         </tr>
611         <tr>
612           <td><code>start</code></td>
613           <td><code>"hide"</code> or <code>"show"</code></td>
614           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
615           <td> optional, default no initial state </td>
616         </tr>
617         <tr>
618           <td><code>firststart</code></td>
619           <td><code>"hide"</code> or <code>"show"</code></td>
620           <td> Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see <code>remember</code>). </td>
621           <td> optional, default no initial state </td>
622         </tr>
623       </table>
624     </li>
625     <li> Example: <code>%TWISTYSHOW{id="demo" link=" Click to Unfold " imgleft="%ICONURLPATH{toggleopen}%"}%</code></li>
626     <li> Related: [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</li>
627   </ul>
628   <p><a name="VarTWISTYHIDE"></a></p>
629   <h3><a name="TWISTYHIDE"></a> TWISTYHIDE </h3><strong>Hide/close link</strong><ul>
630     <li> Syntax: <code>%TWISTYHIDE{id="myid" ... }%</code></li>
631     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
632         <tr>
633           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
634           <th bgcolor="#99CCCC"><strong> Value </strong></th>
635           <th bgcolor="#99CCCC"><strong> Description </strong></th>
636           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
637         </tr>
638         <tr>
639           <td><code>id</code></td>
640           <td> Unique identifier </td>
641           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
642           <td> required </td>
643         </tr>
644         <tr>
645           <td><code>link</code></td>
646           <td> Link label </td>
647           <td> Hide link label </td>
648           <td> optional </td>
649         </tr>
650         <tr>
651           <td><code>mode</code></td>
652           <td><code>"div"</code> or <code>"span"</code></td>
653           <td> Specify if the Twisty Hide link will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. Note that if the contents contains block elements such as <code>div</code>, <code>mode</code> should be <code>div</code> as well to create valid HTML markup. </td>
654           <td> optional, defaults to <code>&lt;span&gt;</code></td>
655         </tr>
656         <tr>
657           <td><code>img</code></td>
658           <td> Image url </td>
659           <td> Specify the url of an image that will be displayed at the <strong>right side</strong> of the link. <br />You may use [[TWiki/TWikiVariables#VarICONURLPATH]] to display one of the [[TWiki/TWikiDocGraphics]] icons. Alternatively use an image attached to the topic. </td>
660           <td> optional, defaults to no image </td>
661         </tr>
662         <tr>
663           <td><code>remember</code></td>
664           <td><code>"on"</code>, <code>"off"</code></td>
665           <td> If <code>"on"</code>, the Twisty state is remembered the next time the page is shown. If <code>"off"</code>, the stored setting will be cleared.<br /><strong>Note:</strong> when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked. </td>
666           <td> optional, no default </td>
667         </tr>
668         <tr>
669           <td><code>start</code></td>
670           <td><code>"hide"</code> or <code>"show"</code></td>
671           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
672           <td> optional, default no initial state </td>
673         </tr>
674         <tr>
675           <td><code>firststart</code></td>
676           <td><code>"hide"</code> or <code>"show"</code></td>
677           <td> Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see <code>remember</code>). </td>
678           <td> optional, default no initial state </td>
679         </tr>
680       </table>
681     </li>
682     <li> Example: <code>%TWISTYHIDE{id="demo" link=" Click to Fold " imgleft="%ICONURLPATH{toggleclose}%"}%</code></li>
683     <li> Related: [[Main/WebHome#VarTWISTYSHOW]] and [[Main/WebHome#VarTWISTYTOGGLE]]</li>
684   </ul>
685   <p><a name="VarTWISTYTOGGLE"></a></p>
686   <h3><a name="TWISTYTOGGLE"></a> TWISTYTOGGLE </h3><strong>Twisty Toggle contents section</strong><ul>
687     <li> Syntax: <code>%TWISTYTOGGLE{id="myid"}%</code></li>
688     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
689         <tr>
690           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
691           <th bgcolor="#99CCCC"><strong> Value </strong></th>
692           <th bgcolor="#99CCCC"><strong> Description </strong></th>
693           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
694         </tr>
695         <tr>
696           <td><code>id</code></td>
697           <td> Unique identifier </td>
698           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]. </td>
699           <td> required </td>
700         </tr>
701         <tr>
702           <td><code>mode</code></td>
703           <td><code>"div"</code> or <code>"span"</code></td>
704           <td> Specify if the Twisty Toggle section will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. Note that if the contents contains block elements such as <code>div</code>, <code>mode</code> should be <code>div</code> as well to create valid HTML markup. </td>
705           <td> optional, defaults to <code>&lt;span&gt;</code></td>
706         </tr>
707         <tr>
708           <td><code>class</code></td>
709           <td> CSS class name </td>
710           <td> Class for content div or span </td>
711           <td> optional, default none </td>
712         </tr>
713         <tr>
714           <td><code>remember</code></td>
715           <td><code>"on"</code>, <code>"off"</code></td>
716           <td> If <code>"on"</code>, the Twisty state is remembered the next time the page is shown. If <code>"off"</code>, the stored setting will be cleared.<br /><strong>Note:</strong> when used, think carefully about a unique name (id) for the Twisty, otherwise the cookie that is set might affect other Twisties with the same name. Also note that only interaction is stored, not the state of the Twisty when left unclicked. </td>
717           <td> optional, no default </td>
718         </tr>
719         <tr>
720           <td><code>start</code></td>
721           <td><code>"hide"</code> or <code>"show"</code></td>
722           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
723           <td> optional, default no initial state </td>
724         </tr>
725         <tr>
726           <td><code>firststart</code></td>
727           <td><code>"hide"</code> or <code>"show"</code></td>
728           <td> Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see <code>remember</code>). </td>
729           <td> optional, default no initial state </td>
730         </tr>
731         <tr>
732           <td><code>noscript</code></td>
733           <td><code>"hide"</code></td>
734           <td> Make content hidden in case use does not have JavaScript on </td>
735           <td> optional, default content is shown with no JavaScript </td>
736         </tr>
737       </table>
738     </li>
739     <li> Example: <code>%TWISTYTOGGLE{id="demo" mode="div" remember="on"}%My content%ENDTWISTYTOGGLE%</code></li>
740     <li> Related: [[Main/WebHome#VarTWISTYHIDE]], [[Main/WebHome#VarTWISTYHIDE]] an [[Main/WebHome#VarENDTWISTYTOGGLE]]</li>
741   </ul>
742   <p><a name="VarENDTWISTYTOGGLE"></a></p>
743   <h3><a name="ENDTWISTYTOGGLE"></a> ENDTWISTYTOGGLE </h3><strong>The Twisty closure</strong><ul>
744     <li> Syntax: <code>%ENDTWISTYTOGGLE%</code><ul>
745         <li> Will end the most inner unclosed Twisty Toggle section, using the proper tag </li>
746       </ul>
747     </li>
748     <li> Example: <code>%ENDTWISTYTOGGLE%</code></li>
749     <li> Related: [[Main/WebHome#VarTWISTYTOGGLE]]</li>
750   </ul>
751 </div>
752
753 ## <a name="The Fine Print"></a> The Fine Print
754
755 TwistyPlugin is a convenience plugin for TWiki:Plugins.TwistyContrib.
756
757 Major features are:
758
759 - When active, the Twisty JavaScript library is included in every topic
760 - Provides a convenience syntax to define Twisty areas
761 - Automatically generates ids
762 - Automatically fills in default values
763 - Global preference settings can be set in this topic or locally in individual topics
764
765 <a name="PluginSettings"></a>
766
767 ## <a name="Plugin Settings"></a> Plugin Settings
768
769 Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%&lt;plugin&gt;\_&lt;setting&gt;%**</code>, i.e. <code>**%TWISTYPLUGIN\_SHORTDESCRIPTION%**</code>
770
771 - Set TWISTYSHOWLINK = More...
772   - For example: `More...`
773 - Set TWISTYHIDELINK = Close
774   - For example: `Close`
775 - Set TWISTYMODE =
776   - Either `div` or `span`; `span` if nothing set
777 - Set TWISTYREMEMBER =
778   - Either `on` or `off`; default is not specified. If set to `on` all Twisty states will be stored in a TWIKIPREF cookie; if set to `off` the TWIKIPREF cookie will be cleared
779
780 - Set SHORTDESCRIPTION = Twisty section JavaScript library to open/close content dynamically
781 - Set DEBUG = 0
782
783 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
784
785 - Download the ZIP file from the Plugin web (see below)
786 - Unzip <code>**%TOPIC%.zip**</code> in your root ($TWIKI\_ROOT) directory. Content: <table border="1" cellpadding="0" cellspacing="0">
787   <tr>
788     <th bgcolor="#99CCCC"><strong> File: </strong></th>
789     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
790   </tr>
791   <tr>
792     <td><code><b>TwistyBundleTWiki04x02_installer</b></code></td>
793     <td>   </td>
794   </tr>
795   <tr>
796     <td><code><b>TwistyBundleTWiki04x02_installer.pl</b></code></td>
797     <td>   </td>
798   </tr>
799   <tr>
800     <td><code><b>data/TWiki/TwistyBundleTWiki04x02.txt</b></code></td>
801     <td>   </td>
802   </tr>
803   <tr>
804     <td><code><b>data/TWiki/BehaviourContrib.txt</b></code></td>
805     <td>   </td>
806   </tr>
807   <tr>
808     <td><code><b>data/TWiki/TwistyContrib.txt</b></code></td>
809     <td>   </td>
810   </tr>
811   <tr>
812     <td><code><b>data/TWiki/TwistyPlugin.txt</b></code></td>
813     <td>   </td>
814   </tr>
815   <tr>
816     <td><code><b>lib/TWiki/Contrib/BehaviourContrib.pm</b></code></td>
817     <td>   </td>
818   </tr>
819   <tr>
820     <td><code><b>lib/TWiki/Contrib/TwistyBundleTWiki04x02.pm</b></code></td>
821     <td>   </td>
822   </tr>
823   <tr>
824     <td><code><b>lib/TWiki/Contrib/TwistyContrib.pm</b></code></td>
825     <td>   </td>
826   </tr>
827   <tr>
828     <td><code><b>lib/TWiki/Plugins/TwistyPlugin.pm</b></code></td>
829     <td>   </td>
830   </tr>
831   <tr>
832     <td><code><b>pub/TWiki/BehaviourContrib/behaviour.compressed.js</b></code></td>
833     <td>   </td>
834   </tr>
835   <tr>
836     <td><code><b>pub/TWiki/BehaviourContrib/behaviour.compressed_src.js</b></code></td>
837     <td>   </td>
838   </tr>
839   <tr>
840     <td><code><b>pub/TWiki/BehaviourContrib/behaviour.js</b></code></td>
841     <td>   </td>
842   </tr>
843   <tr>
844     <td><code><b>pub/TWiki/BehaviourContrib/behaviour_src.js</b></code></td>
845     <td>   </td>
846   </tr>
847   <tr>
848     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/cssQuery-p.js</b></code></td>
849     <td>   </td>
850   </tr>
851   <tr>
852     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-level2.js</b></code></td>
853     <td>   </td>
854   </tr>
855   <tr>
856     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-level3.js</b></code></td>
857     <td>   </td>
858   </tr>
859   <tr>
860     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-standard.js</b></code></td>
861     <td>   </td>
862   </tr>
863   <tr>
864     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery.js</b></code></td>
865     <td>   </td>
866   </tr>
867   <tr>
868     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/test.html</b></code></td>
869     <td>   </td>
870   </tr>
871   <tr>
872     <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/test.html</b></code></td>
873     <td>   </td>
874   </tr>
875   <tr>
876     <td><code><b>pub/TWiki/TwistyContrib/twist.compressed.js</b></code></td>
877     <td>   </td>
878   </tr>
879   <tr>
880     <td><code><b>pub/TWiki/TwistyContrib/twist.compressed_src.js</b></code></td>
881     <td>   </td>
882   </tr>
883   <tr>
884     <td><code><b>pub/TWiki/TwistyContrib/twist.css</b></code></td>
885     <td>   </td>
886   </tr>
887   <tr>
888     <td><code><b>pub/TWiki/TwistyContrib/twist.js</b></code></td>
889     <td>   </td>
890   </tr>
891   <tr>
892     <td><code><b>pub/TWiki/TwistyContrib/twist_src.js</b></code></td>
893     <td>   </td>
894   </tr>
895 </table>
896
897 - Optionally, if it exists, run <code>**%TOPIC%\_installer**</code> to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
898 - Alternatively, manually make sure the dependencies listed in the table below are resolved. None
899 - Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
900
901 ## <a name="Plugin Info"></a> Plugin Info
902
903 <table border="1" cellpadding="0" cellspacing="0">
904   <tr>
905     <td align="right"> Authors: </td>
906     <td> TWiki:Main.RafaelAlvarez, TWiki:Main.ArthurClemens </td>
907   </tr>
908   <tr>
909     <td align="right"> Copyright ©: </td>
910     <td> 2005 Rafael Alvarez; 2006-2008 Arthur Clemens </td>
911   </tr>
912   <tr>
913     <td align="right"> License: </td>
914     <td><a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GPL</a></td>
915   </tr>
916   <tr>
917     <td align="right"> Dependencies: </td>
918     <td> None </td>
919   </tr>
920   <tr>
921     <td align="right"> Plugin Version: </td>
922     <td> 10 Oct 2008 (version 1.4.12) </td>
923   </tr>
924   <tr>
925     <td align="right"> Change History: </td>
926     <td>  </td>
927   </tr>
928   <tr>
929     <td align="right"> 08 Oct 2008 </td>
930     <td> 1.4.11, 1.4.12 It is now possible to have a twisty on the same line without a linebreak. </td>
931   </tr>
932   <tr>
933     <td align="right"> 03 Aug 2008 </td>
934     <td> 1.4.10 TWiki 4.2.1 release version </td>
935   </tr>
936   <tr>
937     <td align="right"> 13 Dec 2007 </td>
938     <td> 1.4.9 fix to the loading order of javascript files in head </td>
939   </tr>
940   <tr>
941     <td align="right"> 24 Nov 2007 </td>
942     <td> 1.4.6 - 1.4.8 Arthur Clemens - Added format tokens. </td>
943   </tr>
944   <tr>
945     <td align="right"> 07 Oct 2007 </td>
946     <td> 1.4.5 Arthur Clemens - Fix html tag with show/hide controls. </td>
947   </tr>
948   <tr>
949     <td align="right"> 25 Sep 2007 </td>
950     <td> 1.4.4 Arthur Clemens - Fix rendering of headers when <code>prefix</code> is used. </td>
951   </tr>
952   <tr>
953     <td align="right"> 11 Jul 2007 </td>
954     <td> 1.4.3 Arthur Clemens - Fix invalid html when <code>prefix</code> and <code>suffix</code> is used. </td>
955   </tr>
956   <tr>
957     <td align="right"> 23 Jun 2007 </td>
958     <td> 1.4.2 Arthur Clemens - Fixed bugs with parameters <code>firststart</code> and <code>noscript</code> (since version 1.4). </td>
959   </tr>
960   <tr>
961     <td align="right"> 20 Jun 2007 </td>
962     <td> 1.4 Arthur Clemens - Updated to work without ugly inserted javascript 'init' calls. This will change nothing to the functionality, but it will produce cleaner HTML, while at the same time the twisty is still set immediately (not at page onload) and graceful fallback in case of no javascript is maintained. </td>
963   </tr>
964   <tr>
965     <td align="right"> 19 Jun 2006 </td>
966     <td> 1.3 Arthur Clemens - Updated with TWiki 4 JavaScript files. </td>
967   </tr>
968   <tr>
969     <td align="right"> 25 Oct 2006 </td>
970     <td> 1.2 New variables to set default values: <code>TWISTYSHOWLINK</code>, <code>TWISTYHIDELINK</code>, <code>TWISTYMODE</code>, <code>TWISTYREMEMBER</code>; property <code>id</code> is no longer required as this is automatically set (still recommended in some cases with <code>remember="on"</code>); property value <code>remember="off"</code> will clear a previously stored cookie; new properties <code>prefix</code> and <code>suffix</code>; JavaScript to collapse or expand all Twisties on the page. </td>
971   </tr>
972   <tr>
973     <td align="right"> 27 Sep 2006 </td>
974     <td> 1.101 Fixes JavaScript handling when AllowInlineScript in configure is not set </td>
975   </tr>
976   <tr>
977     <td align="right"> 11 June 2006 </td>
978     <td> 1.100 Added parameters <code>start</code>, <code>firststart</code>, <code>noscript</code> and <code>class</code>; complete JavaScript rewrite for speed </td>
979   </tr>
980   <tr>
981     <td align="right"> 12 Sep 2005 </td>
982     <td> 1.000 First Version </td>
983   </tr>
984   <tr>
985     <td align="right"> Home: </td>
986     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
987   </tr>
988   <tr>
989     <td align="right"> Feedback: </td>
990     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
991   </tr>
992   <tr>
993     <td align="right"> Appraisal: </td>
994     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
995   </tr>
996 </table>