TwistyPlugin.txt

%META:TOPICINFO{author="ProjectContributor" date="1195487956" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="Plugins"}%
---+!! <nop>%TOPIC%

*A "twisty" is an interface toggle control to show and hide content.*

!TwistyPlugin gives you several options to control the appearance of a twisty:
   * use link text or buttons
   * position an icon left or right
   * remember the state at the next visit of the page
   * start the Twisty open or closed
   * start the Twisty open or closed for the first visit
   * use a span or div for the content
   * set a class for the content span or div

Twisty has a fallback mechanism in case !JavaScript is not available: all content is displayed and the control buttons are hidden.

%TOC{title="On this page:"}%

---++ Usage examples
---+++ Triad
A Twisty consists of 3 elements:
   1 Show button
   1 Hide button
   1 Collapsing content ('Toggle')
   
The typical !TwistyPlugin triad will look like this (pseudo code):

<verbatim class="tml">
%TWISTYSHOW{}% %TWISTYHIDE{}%
(there may be other things between buttons and content)
%TWISTYTOGGLE{}% my content %ENDTWISTYTOGGLE%
</verbatim>

---+++ Shorthand

The Twisty triad is conveniently packed into shorthand =%<nop>TWISTY{some parameters}% Collapsing content %<nop>ENDTWISTY%=:

<verbatim class="tml">
%TWISTY{}%
my twisty content
%ENDTWISTY%
</verbatim>

Will generate:

%TWISTY{}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

You may have noticed that no parameters are passed to =%<nop>TWISTY{}%= but the show and hide links _do_ have text! The default values are fetched from plugin settings =TWISTYSHOWLINK= and =TWISTYHIDELINK=, see [[#PluginSettings][Plugin Settings]] below.

---+++ Block or inline
The default display mode of Twisty is =div=, that is, the contents is displayed as block element, displayed on the next line.

If you want to show the Twisty contents on the same line - inline - use =mode="span"=:

<verbatim class="tml">
%TWISTY{
mode="span"
}%
my twisty content
%ENDTWISTY%
</verbatim>

Will generate:

%TWISTY{
mode="span"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

Note that if animations are on (using =TWISTYPLUGIN_TWISTYANIMATIONSPEED=), you won't see animations with inline mode. 


---+++ Twisty with icons
<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    showimgleft="%ICONURLPATH{toggleopen-small}%"
    hideimgleft="%ICONURLPATH{toggleclose-small}%"
}%
my twisty content
%ENDTWISTY%
</verbatim>

It will look like this:

%TWISTY{
showlink="Show..."
hidelink="Hide"
showimgleft="%ICONURLPATH{toggleopen-small}%"
hideimgleft="%ICONURLPATH{toggleclose-small}%"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

To put icons at the right side, write
<verbatim class="tml">
%TWISTY{
    showlink="Show"
    hidelink="Hide"
    showimgright="%ICONURLPATH{toggleopen-small}%"
    hideimgright="%ICONURLPATH{toggleclose-small}%"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
showlink="Show"
hidelink="Hide"
showimgright="%ICONURLPATH{toggleopen-small}%"
hideimgright="%ICONURLPATH{toggleclose-small}%"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%



---+++ Make it remember
To store the last state in a FOSWIKIPREF cookie, add the parameter =remember="on"=.%BR%
To test this, reload the page after toggling.

%X% WARNING: If you really want it to be remembered, best to provide an id with
it, otherwise it might not work.
<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    remember="on"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
showlink="Show..."
hidelink="Hide"
remember="on"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

If a Twisty state has been stored in a FOSWIKIPREF cookie before, it can be cleared by using =remember="off"=:

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    remember="off"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    remember="off"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

*Note:* Unless specified, Twisty ids are generated automatically based on web
and topic names. If remember option is set, a counter that increments for each
twisty is appended, otherwise a random value is, so AJAX calls will not kill
JS, as IDs have to be unique.


<verbatim class="tml">
%TWISTY{
    id="currentCustomerList"
    showlink="Show..."
    hidelink="Hide"
    remember="on"
}%
my customer list
%ENDTWISTY%
</verbatim>

Note that =id= sets a site wide cookie. To create a unique id, add topic or web macros:
<verbatim class="tml">
id="%WEB%_%TOPIC%_currentCustomerList"
</verbatim>



---+++ Make it obey
To let the Twisty start with its content folded open, add parameter =start="show"=. 

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    start="show"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    start="show"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%

Likewise use =start="hide"= to start with hidden content.

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    start="hide"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    start="hide"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%



---+++ Make it obey only the first time
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.

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    firststart="show"
}%
my twisty content
%ENDTWISTY%
</verbatim>

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    firststart="show"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%


---+++ Other use: hide interface parts in case of no !JavaScript

<div class="foswikiHelp">
*Foswiki 1.1 and higher* uses the CSS class =foswikiJs= to indicate the availability of !JavaScript (the class is set to the =html= tag if !JavaScript is available).
</div>

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.

Put the "JavaScript content" in an almost bare bones Twisty. Write =showlink="" hidelink=""= to not display any default link texts.

<verbatim class="tml">
%TWISTY{
    link=""
    noscript="hide"
    start="show"
}%
<input type="submit" class="foswikiButton" value="You surely have !JavaScript" />
%ENDTWISTY%
</verbatim>

%TWISTY{
    link=""
    noscript="hide"
    start="show"
}%
<input type="submit" class="foswikiButton" value="You surely have !JavaScript" />
%ENDTWISTY%

Do not forget to set =start="show"= to show the Twisty content at all. 

When !JavaScript is off, the button should be invisible.

This code will show the button when !JavaScript is off:

<verbatim class="tml">
%TWISTY{
    link=""
    start="show"
}%
<input type="submit" class="foswikiButton" value="You might have !JavaScript" />
%ENDTWISTY%
</verbatim>

%TWISTY{
    link=""
    start="show"
}%
<input type="submit" class="foswikiButton" value="You might have !JavaScript" />
%ENDTWISTY%



---+++ Styling the Twisty
Use parameter =class= to style the content div or class:

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    class="foswikiHelp"
}%
my twisty content
%ENDTWISTY%
</verbatim>

Generates: %BR%
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    class="foswikiHelp"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%


---+++ Styling the Twisty link or button
Use parameter =linkclass= to style the twisty links:

<verbatim class="tml">
%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    linkclass="foswikiButton"
}%
my twisty content
%ENDTWISTY%
</verbatim>

Generates: %BR%
%TWISTY{
showlink="Show..."
hidelink="Hide"
linkclass="foswikiButton"
}%
%GREEN% my twisty content %ENDCOLOR%
%ENDTWISTY%


---+++ All on, all off

You can toggle all Twisties on or off at once by putting a link or button on the page with class =twistyExpandAll= or =twistyCollapseAll=.

<verbatim class="tml">
<button class="twistyExpandAll foswikiButton">Expand all</button>
<button class="twistyCollapseAll foswikiButton">Collapse all</button>
</verbatim>

Creates these controls:

<button class="twistyExpandAll foswikiButton">Expand all</button>  
<button class="twistyCollapseAll foswikiButton">Collapse all</button>

When you want to use links, write:

<verbatim class="tml">
#VarTOGGLE

<a href="#TOGGLE" class="twistyExpandAll">Expand all</a>  
<a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>
</verbatim>


#VarTOGGLE

<a href="#TOGGLE" class="twistyExpandAll">Expand all</a>  
<a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>


---++ Special syntax: format tokens
If you use other macros inside TWISTY parameters chances are it will mess up the macro, or the rendered html. Use format tokens to 'delay' rendering of these variables until the Twisty parameters are parsed.

The format tokens are the same as with %SYSTEMWEB%.FormattedSearch:

| *Escape:* | *Expands To:* |
| =$n= or =$n()= | New line. Use =$n()= if followed by alphanumeric character, e.g. write =Foo$n()Bar= instead of =Foo$nBar= |
| =$nop= or =$nop()= | Is a "no operation". |
| =$quot= | Double quote (="=) |
| =$percnt= | Percent sign (=%=) |
| =$dollar= | Dollar sign (=$=) |


For example, to show an icon inside the link, do not write:
<verbatim class="tml">
link="%Y%"
</verbatim>

but use format tokens:

<verbatim class="tml">
link="$percntY$percnt"
</verbatim>

... to get:

%TWISTY{
link="$percntY$percnt"
showimgleft="%ICONURLPATH{toggleopen-small}%"
hideimgleft="%ICONURLPATH{toggleclose-small}%"
}%
my twisty content
%ENDTWISTY%

Or a more complex example using %SYSTEMWEB%.SpreadSheetPlugin; do not write:

<verbatim class="tml">
link="Count: (%CALC{"$GET(infoCount)"}%)"
</verbatim>

but use format tokens:

<verbatim class="tml">
link="Count: ($percntCALC{$quot$dollarGET(infoCount)$quot}$percnt)"
</verbatim>

---++ Generation of the twisty ID

If you do not define an =id=, the plugin autogenerates an ID based on web and
topic names.

ID is then appended with either a counter that counts from 1 for each
twisty if remember option is set, or a random number (useful for AJAX calls).

---++ Syntax
%INCLUDE{VarTWISTY}%
%INCLUDE{VarENDTWISTY}%
%INCLUDE{VarTWISTYBUTTON}%
%INCLUDE{VarTWISTYSHOW}%
%INCLUDE{VarTWISTYHIDE}%
%INCLUDE{VarTWISTYTOGGLE}%
%INCLUDE{VarENDTWISTYTOGGLE}%


---++ Notes for developers
---+++ CSS classes

| *Class name* | *Note* |
| =.twistyTrigger= | |
| =.twistyContent= | |
| =.twistyPlaceholder= | |
| =.twistyRememberSetting= | behavior class |
| =.twistyForgetSetting= | behavior class |
| =.twistyStartHide= | behavior class |
| =.twistyStartShow= | behavior class |
| =.twistyInited1= | behavior class: state is set to shown |
| =.twistyInited0= | behavior class: state is set to hidden |



#PluginSettings
---++ Plugin Settings

You can override some default settings in the plugin by setting the following [[%SYSTEMWEB%.PreferenceSettings][preferences]].
| *Preference* | *Meaning* | *Default* |
| =TWISTYPLUGIN_TWISTYSHOWLINK= | For example: =More...= | %MAKETEXT{"More..."}% |
| =TWISTYPLUGIN_TWISTYHIDELINK= | For example: =Close= | %MAKETEXT{"Close"}% |
| =TWISTYPLUGIN_TWISTYMODE= | Either =div= or =span= | =span= |
| =TWISTYPLUGIN_TWISTYREMEMBER= | Either =on= or =off=. If set to =on= all Twisty states will be stored in a FOSWIKIPREF cookie; if set to =off= the FOSWIKIPREF cookie will be cleared | not specified |
| =TWISTYPLUGIN_TWISTYANIMATIONSPEED= | Speed of animation: 'fast', 'slow', or integer milliseconds | =0= (no animation) |

<!--
   * Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
-->
   
---++ Plugin Installation Instructions
%$INSTALL_INSTRUCTIONS%

---++ Plugin Info

|  Authors: | Foswiki:Main.RafaelAlvarez, Foswiki:Main.MichaelDaum, Foswiki:Main.ArthurClemens |
|  Copyright  | Copyright (C) Rafael Alvarez; Michael Daum, Arthur Clemens |
|  License: | [[http://www.gnu.org/copyleft/gpl.html][GPL]] |
|  Version: | %$VERSION% |
|  Release: | %$RELEASE% |
|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
|  10 Apr 2011 | Foswikitask:Item10618: parenthesis (or other Regex characters) in topic name crashes Foswiki |
|  15 Dec 2010 | 1.6.11 Foswikitask:Item10161: improved compatibility with jquery-1.4.3/4 |
|  06 Nov 2010 | 1.6.10 Foswikitask:Item9963: Revert usage of =$<nop>percent= back to =$<nop>percnt= |
|  29 Oct 2010 | 1.6.9 Foswikitask:Item9918: fixed twisty animation on jquery-1.4.3 |
|  27 Oct 2010 | 1.6.8 Foswikitask:Item9904: fixed compatibility with IE |
|  24 Oct 2010 | 1.6.7 Foswikitask:Item9815: Changed random IDs back to predictable IDs if remember option is set |
|  11 Sep 2010 | 1.6.6 Foswikitask:Item9499: Recoded show/hide animation code for smooth twisties. |
|  10 Sep 2010 | 1.6.5 Foswikitask:Item9515: Simplified code that shows/hides twisties. |
|  05 Sep 2010 | 1.6.4 Foswikitask:Item9626: Put link class around link and image. |
|  24 Aug 2010 | 1.6.3 Foswikitask:Item8573: Fix new dependency on JQueryPlugin |
|  25 Aug 2010 | 1.6.2 Foswikitask:Item9515: Fix compatibility with browsers running without js (content should always be shown) |
|  20 Aug 2010 | 1.6.1 Foswikitask:Item9499: Added preference variable to set show/hide transition animation speed (default to none) |
|  15 Aug 2010 | 1.6.0<br/>\
 Foswikitask:Item9422: Implement as JQueryPlugin::Plugin; emit =display: none= style on hidden twisties to avoid relying on CSS/JS<br/>\
 Foswikitask:Item9415: Documentation changes<br/> |
|  27 Jul 2010 | 1.5.6 Foswiki:Tasks.Item9387: Fixed jQuery JS |
|  13 Mar 2010 | 1.5.5 Fixed id generated in subwebs. |
|  12 Feb 2010 | 1.5.4 Fixed jquery twisties, improved templates structure |
|  02 Sep 2009 | 1.5.3 Add sequential number to the =TWISTY= =id= to allow more than one instance with that id on the page. |
|  26 Aug 2009 | 1.5.2 Fix dependencies - jqueryPlugin and !DojoToolkit were ported to foswiki a while ago. |
|  03 Dec 2008 | 1.5.1 Added parameter =linkclass=. Foswiki version. |
|  27 Nov 2008 | 1.5 Foswiki release; added option to use other Javascript libraries. |
|  08 Oct 2008 | 1.4.11, 1.4.12 It is now possible to have a twisty on the same line without a linebreak. |
|  03 Aug 2008 | 1.4.10 TWiki 4.2.1 release version. |
|  13 Dec 2007 | 1.4.9 fix to the loading order of javascript files in head. |
|  24 Nov 2007 | 1.4.6 - 1.4.8 Arthur Clemens - Added format tokens. |
|  07 Oct 2007 | 1.4.5 Arthur Clemens - Fix html tag with show/hide controls. |
|  25 Sep 2007 | 1.4.4 Arthur Clemens - Fix rendering of headers when =prefix= is used. |
|  11 Jul 2007 | 1.4.3 Arthur Clemens - Fix invalid html when =prefix= and =suffix= is used. |
|  23 Jun 2007 | 1.4.2 Arthur Clemens - Fixed bugs with parameters =firststart= and =noscript= (since version 1.4). |
|  20 Jun 2007 | 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. |
|  19 Jun 2006 | 1.3 Arthur Clemens - Updated with TWiki 4 !JavaScript files. |
|  25 Oct 2006 | 1.2 New variables to set default values: =TWISTYSHOWLINK=, =TWISTYHIDELINK=, =TWISTYMODE=, =TWISTYREMEMBER=; property =id= is no longer required as this is automatically set (still recommended in some cases with =remember="on"=); property value =remember="off"= will clear a previously stored cookie; new properties =prefix= and =suffix=; !JavaScript to collapse or expand all Twisties on the page.  |
|  27 Sep 2006 | 1.101 Fixes !JavaScript handling when !AllowInlineScript in configure is not set |
|  11 Jun 2006 | 1.100 Added parameters =start=, =firststart=, =noscript= and =class=; complete !JavaScript rewrite for speed |
|  12 Sep 2005 | 1.000 First Version |
|  Dependencies: | None |
|  Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |
<!-- %JQREQUIRE{"chili"}% -->