TWiki/TwistyContrib.mdwn

   1 # <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
   2
   3 **This contrib packages in a convenient way the JavaScript library and the CSS file needed to implement Twisty sections.**
   4
   5 TwistyContrib is installed by default in TWiki 4 and used by [[Twisty Plugin|TWiki:Plugins/TwistyPlugin]].
   6
   7 It is recommended to use the TwistyPlugin as it eases the deployment and use of this contrib.
   8
   9 This Contrib should work with [[TWiki 4|TWiki:Codev/DakarRelease]] and newer.
  10
  11 <div><span>On this page:</span><ul>
  12     <li><a href="#Usage examples"> Usage examples</a><ul>
  13         <li><a href="#Basic Twisty"> Basic Twisty</a></li>
  14         <li><a href="#Twisty with placeholder text"> Twisty with placeholder text</a></li>
  15       </ul>
  16     </li>
  17     <li><a href="#Twisty made easy"> Twisty made easy</a><ul>
  18         <li><a href="#You Write"> You Write </a></li>
  19         <li><a href="#Your Users Write"> Your Users Write</a></li>
  20         <li><a href="#You See"> You See</a></li>
  21         <li><a href="#All on, all off"> All on, all off</a></li>
  22       </ul>
  23     </li>
  24     <li><a href="#Settings"> Settings</a></li>
  25     <li><a href="#Installation Instructions"> Installation Instructions</a></li>
  26     <li><a href="#Contrib Info"> Contrib Info</a></li>
  27   </ul>
  28 </div>
  29
  30 ## <a name="Usage examples"></a> Usage examples
  31
  32 If the contrib is properly installed (and JavaScript is enabled in your browser) you should see two folding sections below.
  33
  34 ### <a name="Basic Twisty"></a> Basic Twisty
  35
  36     <span id="demo1show" class="twistyTrigger twistyMakeVisible"><button class="twikiButton"> Unfold </button></span>
  37     <span id="demo1hide" class="twistyTrigger twistyHidden"><button class="twikiButton"> Fold </button></span>
  38     <span id="demo1toggle" class="twistyContent twistyMakeHidden">
  39     my twisty content
  40     </span>
  41
  42 Generates:
  43
  44 <span></span>
  45
  46 <button> Unfold </button>
  47
  48 <span></span>
  49
  50 <button> Fold </button>
  51
  52 <span> my twisty content </span>
  53
  54 ### <a name="Twisty with placeholder text"></a> Twisty with placeholder text
  55
  56     <span id="demo2show" class="twistyTrigger twistyMakeVisible"><a href="#">Expand...</a> <span class="twistyPlaceholder">Hamlet is without question the most famous play in the English language...</span></span>
  57     <span id="demo2hide" class="twistyTrigger twistyHidden"><a href="#">Collapse...</a></span>
  58     <span id="demo2toggle" class="twistyContent twistyMakeHidden">
  59     Hamlet is without question the most famous play in the English language. Probably written in 1601 or 1602, the tragedy is a milestone in Shakespeare's dramatic development.
  60     </span>
  61
  62 Generates:
  63
  64 <span>[Expand...](#) <span>Hamlet is without question the most famous play in the English language...</span></span> <span>[Collapse...](#)</span> <span> Hamlet is without question the most famous play in the English language. Probably written in 1601 or 1602, the tragedy is a milestone in Shakespeare's dramatic development. </span>
  65
  66 Skins can customize the color of the twisty placeholder by modifiying the `.twistyPlaceholder` style.
  67
  68 ## <a name="Twisty made easy"></a> Twisty made easy
  69
  70 Manual written by [[Harald Joerg|TWiki:Main/HaraldJoerg]]. Examples require [[Spreadsheet Plugin|TWiki:Plugins/SpreadsheetPlugin]] to work (installed by default).
  71
  72 > Some of my TWiki users are impressed by the optical effect of what can be done with TWiki:Plugins.TwistyPlugin - and they keep asking me: "How do I do that? I don't understand the documentation, and I don't understand the raw text of your topics!"
  73 >
  74 > They indeed have a point here. The docs aren't easily understood. It isn't easy to pick all the variables needed from a single example, and just copypasting sometimes fails in embarrassing ways if non-unique `id` attributes are present in a topic. Maybe it is easy for a power user, but it surely isn't easy _enough_. There _ought_ to be a way to make it easier.
  75 >
  76 > Well, here you are.
  77 >
  78 > Just set a couple of site preferences, and your users will immediately understand your examples and start writing their own twisties. And what's more: They'll do so in a _consistent_ way, across all your topics in all webs.
  79
  80 ### <a name="You Write"></a> You Write
  81
  82 In your Main.TWikiPreferences write:
  83
  84        * Set FLIP = <span id="twid_%CALC{$SETM(twisty_id, + 1)$GET(twisty_id)}%show" class="twistyTrigger twistyMakeVisible">
  85            <a href="#">more...</a>
  86          </span>
  87          <span id="twid_%CALC{$GET(twisty_id)}%hide" class="twistyTrigger twistyHidden">
  88            <a href="#">close</a>
  89          </span>
  90          <div id="twid_%CALC{$GET(twisty_id)}%toggle" class="twistyContent twistyMakeHidden">
  91        * Set FLOP = </div>
  92
  93 %T% You can include the text in a verbatim block if you want (like I have done here). Additionally I've added plenty of newlines and spaces to make it readable. This works, and you don't have to care for invalid HTML!
  94
  95 ### <a name="Your Users Write"></a> Your Users Write
  96
  97 In any topic, your users can now write things like this:
  98
  99        * *Brace and parenthesize in K&R style*
 100          %FLIP%
 101          When setting out a code block, use the K&R style of bracketing.
 102          That is, place the opening brace at the end of the construct that controls the block. ...
 103          %FLOP%
 104        * *Separate your control keywords from the following opening bracket*
 105          %FLIP%
 106          Control structures regulate the dynamic behaviour of a program, so the keywords
 107          of control structures are the most critical components of a program. ...
 108          %FLOP%
 109
 110 ### <a name="You See"></a> You See
 111
 112 - **Brace and parenthesize in K&amp;R style** %FLIP% When setting out a code block, use the K&amp;R style of bracketing. That is, place the opening brace at the end of the construct that controls the block. ... %FLOP%
 113 - **Separate your control keywords from the following opening bracket** %FLIP% Control structures regulate the dynamic behaviour of a program, so the keywords of control structures are the most critical components of a program. ... %FLOP%
 114
 115 ### <a name="All on, all off"></a> All on, all off
 116
 117 You can toggle all Twisties on or off at once by putting a link or button on the page with class `twistyExpandAll` or `twistyCollapseAll`.
 118
 119     <button class="twistyExpandAll twikiButton">Expand all</button>
 120     <button class="twistyCollapseAll twikiButton">Collapse all</button>
 121
 122 Creates these controls:
 123
 124 <button>Expand all</button>
 125 <button>Collapse all</button>
 126
 127 When you want to use links, write:
 128
 129     #VarTOGGLE
 130
 131     <a href="#TOGGLE" class="twistyExpandAll">Expand all</a>
 132     <a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>
 133
 134 <a name="VarTOGGLE"></a>
 135
 136 [Expand all](#TOGGLE) [Collapse all](#TOGGLE)
 137
 138 ## <a name="Settings"></a> Settings
 139
 140 - Set SHORTDESCRIPTION = Twisty section javascript library to open/close content dynamically
 141
 142 You can also set the global TWiki variable TWISTYCONTRIB\_DEBUG to 1 to make the contrib use uncompressed javascript sources, in the event of problems.
 143
 144 ## <a name="Installation Instructions"></a> Installation Instructions
 145
 146 %\*INSTALL\_INSTRUCTIONS%
 147
 148 - TwistyContrib uses these header includes:
 149     <style type="text/css" media="all">
 150     @import url("%PUBURL%/%TWIKIWEB%/TwistyContrib/twist.css");
 151     </style>
 152     <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikilib.js"></script>
 153     <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikiPref.js"></script>
 154     <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikiCSS.js"></script>
 155     <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.js"></script>
 156     <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TwistyContrib/twist.js"></script>
 157
 158 ## <a name="Contrib Info"></a> Contrib Info
 159
 160 <table border="1" cellpadding="0" cellspacing="0">
 161   <tr>
 162     <td align="right"> Authors: </td>
 163     <td> JavaScript written by TWiki:Main.ArthurClemens; Contrib packaged by TWiki:Main.RafaelAlvarez; original JavaScript written by TWiki:Main.SamHasler. </td>
 164   </tr>
 165   <tr>
 166     <td align="right"> Copyright ©: </td>
 167     <td> 2005 Sam Hasler and Rafael Alvarez; 2006,2007 Arthur Clemens </td>
 168   </tr>
 169   <tr>
 170     <td align="right"> License: </td>
 171     <td><a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GPL</a></td>
 172   </tr>
 173   <tr>
 174     <td align="right"> Dependencies: </td>
 175     <td>
 176       <table border="1">
 177         <tr>
 178           <th>Name</th>
 179           <th>Version</th>
 180           <th>Description</th>
 181         </tr>
 182         <tr>
 183           <td align="left">TWiki::Plugins::BehaviourContrib</td>
 184           <td align="left">&gt;=1.000</td>
 185           <td align="left">Required</td>
 186         </tr>
 187       </table>
 188     </td>
 189   </tr>
 190   <tr>
 191     <td align="right"> Plugin Version: </td>
 192     <td> 20 Jun 2007 (version 1.4.1) </td>
 193   </tr>
 194   <tr>
 195     <td align="right"> Version: </td>
 196     <td> 17595 (30 Mar 2009) </td>
 197   </tr>
 198   <tr>
 199     <td align="right"> Change History: </td>
 200     <td>  </td>
 201   </tr>
 202   <tr>
 203     <td align="right"> 20 Jun 2007 </td>
 204     <td> 1.4 Arthur Clemens - Updated script so [[Main/TwistyPlugin]] can work without extra javascript 'init' calls. </td>
 205   </tr>
 206   <tr>
 207     <td align="right"> 18 Jun 2007 </td>
 208     <td> 1.3 Arthur Clemens - Updated with TWiki 4 JavaScript files. </td>
 209   </tr>
 210   <tr>
 211     <td align="right"> 25 Oct 2006 </td>
 212     <td> 1.2 Arthur Clemens - Updated JavaScript to support TwistyPlugin version 1.2 </td>
 213   </tr>
 214   <tr>
 215     <td align="right"> 26 Sep 2006 </td>
 216     <td> 1.010 Arthur Clemens - Complete JavaScript rewrite </td>
 217   </tr>
 218   <tr>
 219     <td align="right"> 12 Sep 2005 </td>
 220     <td> 1.000 First Version </td>
 221   </tr>
 222   <tr>
 223     <td align="right"> Home: </td>
 224     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
 225   </tr>
 226   <tr>
 227     <td align="right"> Feedback: </td>
 228     <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>
 229   </tr>
 230   <tr>
 231     <td align="right"> Appraisal: </td>
 232     <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>
 233   </tr>
 234 </table>
 235
 236 **_Related Topics:_** [[TWikiPreferences]]