NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Twisty Made Easy

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!"

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.

Well, here you are.

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. All you need to do is to enable TWiki:Plugins.TwistyPlugin - or in newer installs, just keep it enabled (because it is, per default).

Since some time (in which I missed to update this topic), TWiki:Plugins.TwistyPlugin is installed at twiki.org, and per default in every fresh TWiki installation. So let me drop the example I gave in a previous revision for use without that plugin (inasmuch as it didn't work recently anyway)

All text samples in the following demo have been taken from Damian Conway's book "Perl Best Practices" (O'Reilly, 2005).

You'll find here:

What You Write

In your Main.TWikiPreferences write:

   * Set FLIP = %TWISTY{id="%CALC{$SETM(twisty_id, + 1)$GET(twisty_id)}%" showlink="more..." hidelink="close"}%
   * Set FLOP = %ENDTWISTY%

What Your Users Write

   * *Brace and parenthesize in K&R style* 
     %FLIP% 
     When setting out a code block, use the K&R style of bracketing.  
     That is, place the opening brace at the end of the construct that controls the block. ... 
     %FLOP%
   * *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%
   * *Don't separate subroutine or variable names from the following opening bracket.* 
     %FLIP% 
     In order for the previous rule to work properly, it's important that subroutines and
     variables _not_ have a space between their name and any following brackets. ...
     %FLOP%
   * *Don't use unnecessary parentheses for builtins and "honorary" builtins* 
     %FLIP% 
     Perl's many built-in functions are effectively keywords of the language,
     so they can legitimately be called without parentheses, except when it's
     necessary to enforce precedence. ...
     %FLOP%

What You See

• Brace and parenthesize in K&R style more... close When setting out a code block, use the K&R style of bracketing. That is, place the opening brace at the end of the construct that controls the block. ... </>
• Separate your control keywords from the following opening bracket more... close Control structures regulate the dynamic behaviour of a program, so the keywords of control structures are the most critical components of a program. ... </>
• Don't separate subroutine or variable names from the following opening bracket. more... close In order for the previous rule to work properly, it's important that subroutines and variables not have a space between their name and any following brackets. ... </>
• Don't use unnecessary parentheses for builtins and "honorary" builtins more... close Perl's many built-in functions are effectively keywords of the language, so they can legitimately be called without parentheses, except when it's necessary to enforce precedence. ... </>

Final Remarks

• On twiki.org, I can not edit the site preferences topic, but I hope %FLIP% and %FLOP% to be available soon.
• Of course, you are a serious person, and you will select better variable names than I have done here.
• However you call the variables, make sure to write the appropriate VarFLIP and VarFLOP topics in your documentation web so that users can look it up either in these topics, or in TWikiVariables.

-- HaraldJoerg - 05 Jul 2006

Comments & Questions about this Supplemental Document Topic

Thanks Harald for contributing this doc. The FLIP and FLOP settings are very useful. I suggest to take this into the release.

-- PeterThoeny - 06 Jul 2006

For now I enabled it on TWiki.org in the Main.TWikiPreferences. I had to put the settings in a verbatim block since the divs messed up the page layout (leftbar showed up on the right)

-- PeterThoeny - 06 Jul 2006

If taken into the release, this also asks for a new TWikiTipsOfTheDay entry.

-- PeterThoeny - 06 Jul 2006

By separating the initialization from the marking of the text to be hidden, I can avoid having to enter the first line of a paragraph twice, and can put the twisty icon at the beginning of a header instead of after:

      * Set INITFOLD = <span id="twid_%CALC{$SETM(twisty_id, + 1)$GET(twisty_id)}%show" class="twistyMakeVisible"><a href="#" class="twistyTrigger">%ICON{toggleopen}%</a></span><span id="twid_%CALC{$GET(twisty_id)}%hide" class="twistyHidden"><a href="#" class="twistyTrigger">%ICON{toggleclose}%</a></span>
      * Set FOLD = <div id="twid_%CALC{$GET(twisty_id)}%toggle" class="twistyMakeHidden">
      * Set ENDFOLD = </div>

Test Header

-- RichardInman - 10 Sep 2006

Thanks for the inspiration. I have made TwistyPlugin a bit easier to use (version 1.2). And I have included above examples to the TwistyContrib info page.

-- ArthurClemens - 25 Oct 2006

sadly this does not work with topics which contain Chars outside ASCII! Because the generated url contains other Chars eg. %FC = ü is mapped to %C3%BC

-- NorbertZacharias - 18 Jul 2007

Could you explain what doesn't work, and how it fails? The settings here do not generate URLs, and Twisty sections work with a combination of Javascript and CSS.

Better still: Open a question in the Support web, and include the relevant portions of your topics as well as the generated HTML (either in a <verbatim>...</verbatim> section or as attachment). The form in that web gives an opportunity to enter details (TWiki version, client software,...) which can be helpful for diagnosis.

-- HaraldJoerg - 19 Jul 2007