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. Unless parameter `noscript="hide"` is used to specifically set the content to hide.
  16
  17 <div><strong>What's new in version 1.2:</strong><ul>
  18     <li> New variables to set default values: <code>TWISTYSHOWLINK</code>, <code>TWISTYHIDELINK</code>, <code>TWISTYMODE</code>, <code>TWISTYREMEMBER</code></li>
  19     <li> Property <code>id</code> is no longer required as this is automatically set (still recommended in some cases with <code>remember="on"</code>) </li>
  20     <li> Property value <code>remember="off"</code> will clear a previously stored setting </li>
  21     <li> New properties <code>prefix</code> and <code>suffix</code></li>
  22     <li> JavaScript to collapse or expand all Twisties on the page </li>
  23   </ul>
  24 </div>
  25
  26 <div><span>On this page:</span><ul>
  27     <li><a href="#Usage examples"> Usage examples</a><ul>
  28         <li><a href="#Triad"> Triad</a></li>
  29         <li><a href="#Working Twisty"> Working Twisty</a></li>
  30         <li><a href="#Twisty with icons"> Twisty with icons</a></li>
  31         <li><a href="#Make it remember"> Make it remember</a></li>
  32         <li><a href="#Make it obey"> Make it obey</a></li>
  33         <li><a href="#Make it obey only the first time"> Make it obey only the first time</a></li>
  34         <li><a href="#Other use: hide interface parts"> Other use: hide interface parts in case of no JavaScript</a></li>
  35         <li><a href="#Styling the Twisty"> Styling the Twisty</a></li>
  36         <li><a href="#Twisty headers"> Twisty headers</a></li>
  37         <li><a href="#All on, all off"> All on, all off</a></li>
  38       </ul>
  39     </li>
  40     <li><a href="#Syntax"> Syntax</a><ul>
  41         <li><a href="#TWISTY"> TWISTY</a></li>
  42         <li><a href="#ENDTWISTY"> ENDTWISTY</a></li>
  43       </ul>
  44     </li>
  45     <li><a href="#Twisty components syntax"> Twisty components syntax</a><ul>
  46         <li><a href="#TWISTYBUTTON"> TWISTYBUTTON</a></li>
  47         <li><a href="#TWISTYSHOW"> TWISTYSHOW</a></li>
  48         <li><a href="#TWISTYHIDE"> TWISTYHIDE</a></li>
  49         <li><a href="#TWISTYTOGGLE"> TWISTYTOGGLE</a></li>
  50         <li><a href="#ENDTWISTYTOGGLE"> ENDTWISTYTOGGLE</a></li>
  51       </ul>
  52     </li>
  53     <li><a href="#The Fine Print"> The Fine Print</a></li>
  54     <li><a href="#Plugin Settings"> Plugin Settings</a></li>
  55     <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
  56     <li><a href="#Plugin Info"> Plugin Info</a></li>
  57   </ul>
  58 </div>
  59
  60 ## <a name="Usage examples"></a> Usage examples
  61
  62 ### <a name="Triad"></a> Triad
  63
  64 A Twisty consists of 3 elements:
  65
  66 1. Show button
  67 2. Hide button
  68 3. Collapsing content ('Toggle')
  69
  70 The typical TwistyPlugin triad will look like this (pseudo code):
  71
  72     %TWISTYSHOW{}% %TWISTYHIDE{}%
  73     (there may be other things between buttons and content)
  74     %TWISTYTOGGLE{}% my content %ENDTWISTYTOGGLE%
  75
  76 ### <a name="Working Twisty"></a> Working Twisty
  77
  78 The Twisty triad is conveniently packed into shorthand `%TWISTY{some parameters}% Collapsing content %ENDTWISTY%`:
  79
  80     %TWISTY{showlink="Show..." hidelink="Hide"}%
  81     my twisty content
  82     %ENDTWISTY%
  83
  84 It will look like this:
  85
  86 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
  87
  88 <div style="display: inline"><span id="twistyId1toggle"> my twisty content </span></div>
  89
  90 ### <a name="Twisty with icons"></a> Twisty with icons
  91
  92 We will use `mode="div"` to put the collapsing content below the button.
  93
  94     %TWISTY{mode="div" showlink="Show..." hidelink="Hide"
  95     showimgleft="%ICONURLPATH{toggleopen-small}%"
  96     hideimgleft="%ICONURLPATH{toggleclose-small}%"}%
  97     my twisty content
  98     %ENDTWISTY%
  99
 100 It will look like this:
 101
 102 <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>
 103
 104 <div style="display: inline">
 105   <div id="twistyId2toggle"> my twisty content </div>
 106 </div>
 107
 108 To put icons at the right side, write
 109
 110     %TWISTY{mode="div" showlink="Show&nbsp;" hidelink="Hide&nbsp;"
 111     showimgright="%ICONURLPATH{toggleopen-small}%"
 112     hideimgright="%ICONURLPATH{toggleclose-small}%"}%
 113     my twisty content
 114     %ENDTWISTY%
 115
 116 <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>
 117
 118 <div style="display: inline">
 119   <div id="twistyId3toggle"> my twisty content </div>
 120 </div>
 121
 122 ### <a name="Make it remember"></a> Make it remember
 123
 124 To store the last state in a TWIKIPREF cookie, add the parameter `remember="on"`.%BR% To test this, reload the page after toggling.
 125
 126     %TWISTY{showlink="Show..." hidelink="Hide" remember="on"}%
 127     my twisty content
 128     %ENDTWISTY%
 129
 130 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 131
 132 <div style="display: inline"><span id="twistyId4toggle"> my twisty content </span></div>
 133
 134 If a Twisty state has been stored in a TWIKIPREF cookie before, it can be cleared by using `remember="off"`:
 135
 136     %TWISTY{showlink="Show..." hidelink="Hide" remember="off"}%
 137     my twisty content
 138     %ENDTWISTY%
 139
 140 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 141
 142 <div style="display: inline"><span id="twistyId5toggle"> my twisty content </span></div>
 143
 144 **NOTE:** Twisty ids are generated automatically. If you need control over exactly _which_ Twisty should be remembered, add the parameter `id`:
 145
 146     %TWISTY{id="currentCustomerList" showlink="Show..." hidelink="Hide" remember="on"}%
 147     my customer list
 148     %ENDTWISTY%
 149
 150 ### <a name="Make it obey"></a> Make it obey
 151
 152 To let the Twisty start with its content folded open, add parameter `start="show"`.
 153
 154     %TWISTY{showlink="Show..." hidelink="Hide" start="show"}%
 155     my twisty content
 156     %ENDTWISTY%
 157
 158 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 159
 160 <div style="display: inline"><span id="twistyId6toggle"> my twisty content </span></div>
 161
 162 Likewise use `start="hide"` to start with hidden content.
 163
 164     %TWISTY{showlink="Show..." hidelink="Hide" start="hide"}%
 165     my twisty content
 166     %ENDTWISTY%
 167
 168 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 169
 170 <div style="display: inline"><span id="twistyId7toggle"> my twisty content </span></div>
 171
 172 ### <a name="Make it obey only the first time"></a> Make it obey only the first time
 173
 174 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.
 175
 176     %TWISTY{showlink="Show..." hidelink="Hide" firststart="show"}%
 177     my twisty content
 178     %ENDTWISTY%
 179
 180 <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 181
 182 <div style="display: inline"><span id="twistyId8toggle"> my twisty content </span></div>
 183
 184 ### <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
 185
 186 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.
 187
 188 Put the "JavaScript content" in an almost bare bones Twisty. Write `showlink="" hidelink=""` to not display any default link texts.
 189
 190     %TWISTY{link="" noscript="hide" start="show"}%
 191     <input type="submit" class="twikiButton" value="You surely have !JavaScript" />
 192     %ENDTWISTY%
 193
 194 <span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
 195
 196 <div style="display: inline"><span id="twistyId9toggle"><input type="submit" value="You surely have JavaScript" /> </span></div>
 197
 198 Do not forget to set `start="show"` to show the Twisty content at all.
 199
 200 When JavaScript is off, the button should be invisible.
 201
 202 This code will show the button when JavaScript is off:
 203
 204     %TWISTY{link="" start="show"}%
 205     <input type="submit" class="twikiButton" value="You surely have !JavaScript" />
 206     %ENDTWISTY%
 207
 208 <span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
 209
 210 <div style="display: inline"><span id="twistyId10toggle"><input type="submit" value="You surely have JavaScript" /> </span></div>
 211
 212 ### <a name="Styling the Twisty"></a> Styling the Twisty
 213
 214 Use parameter `class` to style the content div or class:
 215
 216     %TWISTY{mode="div" showlink="Show..." hidelink="Hide" class="twikiHelp"}%
 217     my twisty content
 218     %ENDTWISTY%
 219
 220 Generates: %BR% <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
 221
 222 <div style="display: inline">
 223   <div id="twistyId11toggle"> my twisty content </div>
 224 </div>
 225
 226 ### <a name="Twisty headers"></a> Twisty headers
 227
 228 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`.
 229
 230     %TWISTY{prefix="<h4>!!" link="Header"
 231     showimgleft="%ICONURLPATH{toggleopen}%"
 232     hideimgleft="%ICONURLPATH{toggleclose}%" suffix="</h4>"}%
 233     my twisty content
 234     %ENDTWISTY%
 235
 236 Will create:
 237
 238 #### <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>
 239
 240 <div style="display: inline"><span id="twistyId12toggle"> my twisty content </span></div>
 241
 242 ### <a name="All on, all off"></a> All on, all off
 243
 244 You can toggle all Twisties on or off at once by putting a link or button on the page with class `twistyExpandAll` or `twistyCollapseAll`.
 245
 246     <button class="twistyExpandAll twikiButton">Expand all</button>
 247     <button class="twistyCollapseAll twikiButton">Collapse all</button>
 248
 249 Creates these controls:
 250
 251 <button>Expand all</button>
 252 <button>Collapse all</button>
 253
 254 When you want to use links, write:
 255
 256     #VarTOGGLE
 257
 258     <a href="#TOGGLE" class="twistyExpandAll">Expand all</a>
 259     <a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>
 260
 261 <a name="VarTOGGLE"></a>
 262
 263 [Expand all](#TOGGLE) [Collapse all](#TOGGLE)
 264
 265 ## <a name="Syntax"></a> Syntax
 266
 267 <a name="VarTWISTY"></a>
 268
 269 ### <a name="TWISTY"></a> TWISTY
 270
 271 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%`
 272
 273 <table border="1" cellpadding="0" cellspacing="0">
 274   <tr>
 275     <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
 276     <th bgcolor="#99CCCC"><strong> Value </strong></th>
 277     <th bgcolor="#99CCCC"><strong> Description </strong></th>
 278     <th bgcolor="#99CCCC"><strong> Remark </strong></th>
 279   </tr>
 280   <tr>
 281     <td><code>id</code></td>
 282     <td> Unique identifier </td>
 283     <td> Used to link [[Main/WebHome#VarTWISTYBUTTON]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
 284     <td> optional </td>
 285   </tr>
 286   <tr>
 287     <td><code>link</code></td>
 288     <td> Link label </td>
 289     <td> Link label for both show and hide links </td>
 290     <td> optional </td>
 291   </tr>
 292   <tr>
 293     <td><code>hidelink</code></td>
 294     <td> Link label </td>
 295     <td> Hide link label </td>
 296     <td> optional </td>
 297   </tr>
 298   <tr>
 299     <td><code>showlink</code></td>
 300     <td> Link label </td>
 301     <td> Show link label </td>
 302     <td> optional </td>
 303   </tr>
 304   <tr>
 305     <td><code>mode</code></td>
 306     <td><code>"div"</code> or <code>"span"</code></td>
 307     <td> Specify if the Twisty Toggle section will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. </td>
 308     <td> optional, defaults to <code>&lt;span&gt;</code></td>
 309   </tr>
 310   <tr>
 311     <td><code>showimgleft</code></td>
 312     <td> Image url </td>
 313     <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>
 314     <td> optional, defaults to no image </td>
 315   </tr>
 316   <tr>
 317     <td><code>hideimgleft</code></td>
 318     <td> Image url </td>
 319     <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>
 320     <td> optional, defaults to no image </td>
 321   </tr>
 322   <tr>
 323     <td><code>showimgright</code></td>
 324     <td> Image url </td>
 325     <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>
 326     <td> optional, defaults to no image </td>
 327   </tr>
 328   <tr>
 329     <td><code>hideimgright</code></td>
 330     <td> Image url </td>
 331     <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>
 332     <td> optional, defaults to no image </td>
 333   </tr>
 334   <tr>
 335     <td><code>remember</code></td>
 336     <td><code>"on"</code>, <code>"off"</code></td>
 337     <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>
 338     <td> optional, no default </td>
 339   </tr>
 340   <tr>
 341     <td><code>start</code></td>
 342     <td><code>"hide"</code> or <code>"show"</code></td>
 343     <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
 344     <td> optional, default no initial state </td>
 345   </tr>
 346   <tr>
 347     <td><code>firststart</code></td>
 348     <td><code>"hide"</code> or <code>"show"</code></td>
 349     <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>
 350     <td> optional, default no initial state </td>
 351   </tr>
 352   <tr>
 353     <td><code>noscript</code></td>
 354     <td><code>"hide"</code></td>
 355     <td> Make content hidden in case use does not have JavaScript on </td>
 356     <td> optional, default content is shown in case JavaScript if off </td>
 357   </tr>
 358   <tr>
 359     <td><code>class</code></td>
 360     <td> CSS class name </td>
 361     <td> Class for Twisty div or span </td>
 362     <td> optional, default none </td>
 363   </tr>
 364   <tr>
 365     <td><code>prefix</code></td>
 366     <td> Text </td>
 367     <td> Text to display before the show/hide links </td>
 368     <td> optional, default none </td>
 369   </tr>
 370   <tr>
 371     <td><code>suffix</code></td>
 372     <td> Text </td>
 373     <td> Text to display after the show/hide links </td>
 374     <td> optional, default none </td>
 375   </tr>
 376   <tr>
 377     <td><code>img</code></td>
 378     <td> Image url </td>
 379     <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
 380     <td> optional, defaults to no image </td>
 381   </tr>
 382   <tr>
 383     <td><code>imgleft</code></td>
 384     <td> Image url </td>
 385     <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
 386     <td> optional, defaults to no image </td>
 387   </tr>
 388   <tr>
 389     <td><code>imgright</code></td>
 390     <td> Image url </td>
 391     <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
 392     <td> optional, defaults to no image </td>
 393   </tr>
 394   <tr>
 395     <td><code>hideimg</code></td>
 396     <td> Image url </td>
 397     <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
 398     <td> optional, defaults to no image </td>
 399   </tr>
 400   <tr>
 401     <td><code>showimg</code></td>
 402     <td> Image url </td>
 403     <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
 404     <td> optional, defaults to no image </td>
 405   </tr>
 406 </table>
 407
 408 - Related [[TWISTYBUTTON|Main/WebHome#VarTWISTYSHOW]] and [[TWISTYTOGGLE|Main/WebHome#VarTWISTYTOGGLE]]
 409
 410 <a name="VarENDTWISTY"></a>
 411
 412 ### <a name="ENDTWISTY"></a> ENDTWISTY
 413
 414 **Twisty closure, complements the opening TWISTY tag.**
 415
 416 - Syntax: `%ENDTWISTY%`
 417
 418 See [[ENDTWISTYTOGGLE|Main/WebHome#VarENDTWISTYTOGGLE]].
 419
 420 ## <a name="Twisty components syntax"></a> Twisty components syntax
 421
 422 <div style="background-color: #eee; padding: .5em; margin: -.5em">
 423   <p> Ocassionally you might need to create a custom set of individual Twisty components: </p>
 424   <p><a name="VarTWISTYBUTTON"></a></p>
 425   <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>
 426     <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>
 427     <li> Parameter differences: <ul>
 428         <li><code>mode</code>: button mode defaults to span </li>
 429       </ul>
 430     </li>
 431     <li> Syntax: <code>%TWISTYBUTTON{id="myid" ... }%</code></li>
 432     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
 433         <tr>
 434           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
 435           <th bgcolor="#99CCCC"><strong> Value </strong></th>
 436           <th bgcolor="#99CCCC"><strong> Description </strong></th>
 437           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
 438         </tr>
 439         <tr>
 440           <td><code>mode</code></td>
 441           <td><code>"div"</code> or <code>"span"</code></td>
 442           <td> Specify if the <strong>Twisty button</strong> will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag </td>
 443           <td> optional, defaults to <code>&lt;span&gt;</code></td>
 444         </tr>
 445       </table>
 446     </li>
 447     <li> Related: [[Main/WebHome#VarTWISTYSHOW]] and [[Main/WebHome#VarTWISTYHIDE]]</li>
 448   </ul>
 449   <p><a name="VarTWISTYSHOW"></a></p>
 450   <h3><a name="TWISTYSHOW"></a> TWISTYSHOW </h3><strong>Show/open link</strong><ul>
 451     <li> Syntax: <code>%TWISTYSHOW{id="myid" ... }%</code></li>
 452     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
 453         <tr>
 454           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
 455           <th bgcolor="#99CCCC"><strong> Value </strong></th>
 456           <th bgcolor="#99CCCC"><strong> Description </strong></th>
 457           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
 458         </tr>
 459         <tr>
 460           <td><code>id</code></td>
 461           <td> Unique identifier </td>
 462           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
 463           <td> required </td>
 464         </tr>
 465         <tr>
 466           <td><code>link</code></td>
 467           <td> Link label </td>
 468           <td> Show link label </td>
 469           <td> optional </td>
 470         </tr>
 471         <tr>
 472           <td><code>mode</code></td>
 473           <td><code>"div"</code> or <code>"span"</code></td>
 474           <td> Specify if the Twisty Show link will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag </td>
 475           <td> optional, defaults to <code>&lt;span&gt;</code></td>
 476         </tr>
 477         <tr>
 478           <td><code>img</code></td>
 479           <td> Image url </td>
 480           <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>
 481           <td> optional, defaults to no image </td>
 482         </tr>
 483         <tr>
 484           <td><code>imgleft</code></td>
 485           <td> Image url </td>
 486           <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>
 487           <td> optional, defaults to no image </td>
 488         </tr>
 489         <tr>
 490           <td><code>imgright</code></td>
 491           <td> Image url </td>
 492           <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>
 493           <td> optional, defaults to no image </td>
 494         </tr>
 495         <tr>
 496           <td><code>remember</code></td>
 497           <td><code>"on"</code>, <code>"off"</code></td>
 498           <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>
 499           <td> optional, no default </td>
 500         </tr>
 501         <tr>
 502           <td><code>start</code></td>
 503           <td><code>"hide"</code> or <code>"show"</code></td>
 504           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
 505           <td> optional, default no initial state </td>
 506         </tr>
 507         <tr>
 508           <td><code>firststart</code></td>
 509           <td><code>"hide"</code> or <code>"show"</code></td>
 510           <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>
 511           <td> optional, default no initial state </td>
 512         </tr>
 513       </table>
 514     </li>
 515     <li> Example: <code>%TWISTYSHOW{id="demo" link=" Click to Unfold " imgleft="%ICONURLPATH{toggleopen}%"}%</code></li>
 516     <li> Related: [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</li>
 517   </ul>
 518   <p><a name="VarTWISTYHIDE"></a></p>
 519   <h3><a name="TWISTYHIDE"></a> TWISTYHIDE </h3><strong>Hide/close link</strong><ul>
 520     <li> Syntax: <code>%TWISTYHIDE{id="myid" ... }%</code></li>
 521     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
 522         <tr>
 523           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
 524           <th bgcolor="#99CCCC"><strong> Value </strong></th>
 525           <th bgcolor="#99CCCC"><strong> Description </strong></th>
 526           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
 527         </tr>
 528         <tr>
 529           <td><code>id</code></td>
 530           <td> Unique identifier </td>
 531           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]</td>
 532           <td> required </td>
 533         </tr>
 534         <tr>
 535           <td><code>link</code></td>
 536           <td> Link label </td>
 537           <td> Hide link label </td>
 538           <td> optional </td>
 539         </tr>
 540         <tr>
 541           <td><code>mode</code></td>
 542           <td><code>"div"</code> or <code>"span"</code></td>
 543           <td> Specify if the Twisty Hide link will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag </td>
 544           <td> optional, defaults to <code>&lt;span&gt;</code></td>
 545         </tr>
 546         <tr>
 547           <td><code>img</code></td>
 548           <td> Image url </td>
 549           <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>
 550           <td> optional, defaults to no image </td>
 551         </tr>
 552         <tr>
 553           <td><code>remember</code></td>
 554           <td><code>"on"</code>, <code>"off"</code></td>
 555           <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>
 556           <td> optional, no default </td>
 557         </tr>
 558         <tr>
 559           <td><code>start</code></td>
 560           <td><code>"hide"</code> or <code>"show"</code></td>
 561           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
 562           <td> optional, default no initial state </td>
 563         </tr>
 564         <tr>
 565           <td><code>firststart</code></td>
 566           <td><code>"hide"</code> or <code>"show"</code></td>
 567           <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>
 568           <td> optional, default no initial state </td>
 569         </tr>
 570       </table>
 571     </li>
 572     <li> Example: <code>%TWISTYHIDE{id="demo" link=" Click to Fold " imgleft="%ICONURLPATH{toggleclose}%"}%</code></li>
 573     <li> Related: [[Main/WebHome#VarTWISTYSHOW]] and [[Main/WebHome#VarTWISTYTOGGLE]]</li>
 574   </ul>
 575   <p><a name="VarTWISTYTOGGLE"></a></p>
 576   <h3><a name="TWISTYTOGGLE"></a> TWISTYTOGGLE </h3><strong>Twisty Toggle contents section</strong><ul>
 577     <li> Syntax: <code>%TWISTYTOGGLE{id="myid"}%</code></li>
 578     <li> Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
 579         <tr>
 580           <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
 581           <th bgcolor="#99CCCC"><strong> Value </strong></th>
 582           <th bgcolor="#99CCCC"><strong> Description </strong></th>
 583           <th bgcolor="#99CCCC"><strong> Remark </strong></th>
 584         </tr>
 585         <tr>
 586           <td><code>id</code></td>
 587           <td> Unique identifier </td>
 588           <td> Used to link [[Main/WebHome#VarTWISTYSHOW]], [[Main/WebHome#VarTWISTYHIDE]] and [[Main/WebHome#VarTWISTYTOGGLE]]. </td>
 589           <td> required </td>
 590         </tr>
 591         <tr>
 592           <td><code>mode</code></td>
 593           <td><code>"div"</code> or <code>"span"</code></td>
 594           <td> Specify if the Twisty Toggle section will use a <code>&lt;div&gt;</code> or a <code>&lt;span&gt;</code> tag. </td>
 595           <td> optional, defaults to <code>&lt;span&gt;</code></td>
 596         </tr>
 597         <tr>
 598           <td><code>class</code></td>
 599           <td> CSS class name </td>
 600           <td> Class for content div or span </td>
 601           <td> optional, default none </td>
 602         </tr>
 603         <tr>
 604           <td><code>remember</code></td>
 605           <td><code>"on"</code>, <code>"off"</code></td>
 606           <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>
 607           <td> optional, no default </td>
 608         </tr>
 609         <tr>
 610           <td><code>start</code></td>
 611           <td><code>"hide"</code> or <code>"show"</code></td>
 612           <td> Initial state of the Twisty; this will override any setting stored in a cookie (see <code>remember</code>). </td>
 613           <td> optional, default no initial state </td>
 614         </tr>
 615         <tr>
 616           <td><code>firststart</code></td>
 617           <td><code>"hide"</code> or <code>"show"</code></td>
 618           <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>
 619           <td> optional, default no initial state </td>
 620         </tr>
 621         <tr>
 622           <td><code>noscript</code></td>
 623           <td><code>"hide"</code></td>
 624           <td> Make content hidden in case use does not have JavaScript on </td>
 625           <td> optional, default content is shown with no JavaScript </td>
 626         </tr>
 627       </table>
 628     </li>
 629     <li> Example: <code>%TWISTYTOGGLE{id="demo" mode="div" remember="on"}%My content%ENDTWISTYTOGGLE%</code></li>
 630     <li> Related: [[Main/WebHome#VarTWISTYHIDE]], [[Main/WebHome#VarTWISTYHIDE]] an [[Main/WebHome#VarENDTWISTYTOGGLE]]</li>
 631   </ul>
 632   <p><a name="VarENDTWISTYTOGGLE"></a></p>
 633   <h3><a name="ENDTWISTYTOGGLE"></a> ENDTWISTYTOGGLE </h3><strong>The Twisty closure</strong><ul>
 634     <li> Syntax: <code>%ENDTWISTYTOGGLE%</code><ul>
 635         <li> Will end the most inner unclosed Twisty Toggle section, using the proper tag </li>
 636       </ul>
 637     </li>
 638     <li> Example: <code>%ENDTWISTYTOGGLE%</code></li>
 639     <li> Related: [[Main/WebHome#VarTWISTYTOGGLE]]</li>
 640   </ul>
 641 </div>
 642
 643 ## <a name="The Fine Print"></a> The Fine Print
 644
 645 TwistyPlugin is a convenience plugin for TWiki:Plugins.TwistyContrib.
 646
 647 Major features are:
 648
 649 - When active, the Twisty JavaScript library is included in every topic
 650 - Provides a convenience syntax to define Twisty areas
 651 - Automatically generates ids
 652 - Automatically fills in default values
 653 - Global preference settings can be set in this topic or locally in individual topics
 654
 655 ## <a name="Plugin Settings"></a> Plugin Settings
 656
 657 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>
 658
 659 - Set TWISTYSHOWLINK = More...
 660   - For example: `More...`
 661 - Set TWISTYHIDELINK = Close
 662   - For example: `Close`
 663 - Set TWISTYMODE =
 664   - Either `div` or `span`; `span` if nothing set
 665 - Set TWISTYREMEMBER =
 666   - 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
 667
 668 - Set SHORTDESCRIPTION = Twisty section JavaScript library to open/close content dynamically
 669 - Set DEBUG = 0
 670
 671 ## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
 672
 673 - Download the ZIP file from the Plugin web (see below)
 674 - Unzip <code>**%TOPIC%.zip**</code> in your root ($TWIKI\_ROOT) directory. Content: <table border="1" cellpadding="0" cellspacing="0">
 675   <tr>
 676     <th bgcolor="#99CCCC"><strong> File: </strong></th>
 677     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
 678   </tr>
 679   <tr>
 680     <td><code><b>data/TWiki/TwistyPlugin.txt</b></code></td>
 681     <td>   </td>
 682   </tr>
 683   <tr>
 684     <td><code><b>lib/TWiki/Plugins/TwistyPlugin.pm</b></code></td>
 685     <td>   </td>
 686   </tr>
 687 </table>
 688
 689 - 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.
 690 - Alternatively, manually make sure the dependencies listed in the table below are resolved. <table border="1">
 691   <tr>
 692     <th>Name</th>
 693     <th>Version</th>
 694     <th>Description</th>
 695   </tr>
 696   <tr>
 697     <td align="left">TWiki::Contrib::TwistyContrib</td>
 698     <td align="left">&gt;=1.200</td>
 699     <td align="left">Required. Twisty javascript library</td>
 700   </tr>
 701 </table>
 702 - Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
 703
 704 ## <a name="Plugin Info"></a> Plugin Info
 705
 706 <table border="1" cellpadding="0" cellspacing="0">
 707   <tr>
 708     <td> Authors: </td>
 709     <td> TWiki:Main.RafaelAlvarez, TWiki:Main.ArthurClemens </td>
 710   </tr>
 711   <tr>
 712     <td> Copyright ©: </td>
 713     <td> 2005 Rafael Alvarez, 2006 Arthur Clemens </td>
 714   </tr>
 715   <tr>
 716     <td> License: </td>
 717     <td><a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GPL</a></td>
 718   </tr>
 719   <tr>
 720     <td> Dependencies: </td>
 721     <td>
 722       <table border="1">
 723         <tr>
 724           <th>Name</th>
 725           <th>Version</th>
 726           <th>Description</th>
 727         </tr>
 728         <tr>
 729           <td align="left">TWiki::Contrib::TwistyContrib</td>
 730           <td align="left">&gt;=1.200</td>
 731           <td align="left">Required. Twisty javascript library</td>
 732         </tr>
 733       </table>
 734     </td>
 735   </tr>
 736   <tr>
 737     <td> 25 Oct 2006 </td>
 738     <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>
 739   </tr>
 740   <tr>
 741     <td> 27 Sep 2006 </td>
 742     <td> 1.101 Fixes JavaScript handling when AllowInlineScript in configure is not set </td>
 743   </tr>
 744   <tr>
 745     <td> 11 June 2006 </td>
 746     <td> 1.100 Added parameters <code>start</code>, <code>firststart</code>, <code>noscript</code> and <code>class</code>; complete JavaScript rewrite for speed </td>
 747   </tr>
 748   <tr>
 749     <td> 12 Sep 2005 </td>
 750     <td> 1.000 First Version </td>
 751   </tr>
 752   <tr>
 753     <td> Home: </td>
 754     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
 755   </tr>
 756   <tr>
 757     <td> Feedback: </td>
 758     <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>
 759   </tr>
 760   <tr>
 761     <td> Appraisal: </td>
 762     <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>
 763   </tr>
 764 </table>