TwistyPlugin

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. Unless parameter noscript="hide" is used to specifically set the content to hide.

Usage examples

Triad

A Twisty consists of 3 elements:

1. Show button
2. Hide button
3. Collapsing content ('Toggle')

The typical TwistyPlugin triad will look like this (pseudo code):

%TWISTYSHOW{}% %TWISTYHIDE{}%
(there may be other things between buttons and content)
%TWISTYTOGGLE{}% my content %ENDTWISTYTOGGLE%

Working Twisty

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

%TWISTY{showlink="Show..." hidelink="Hide"}%
my twisty content
%ENDTWISTY%

It will look like this:

Show...Hide

Twisty with icons

We will use mode="div" to put the collapsing content below the button.

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

It will look like this:

Show...Hide

To put icons at the right side, write

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

Show Hide 

Make it remember

To store the last state in a TWIKIPREF cookie, add the parameter remember="on".
To test this, reload the page after toggling.

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

Show...Hide

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

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

Show...Hide

NOTE: Twisty ids are generated automatically. If you need control over exactly which Twisty should be remembered, add the parameter id:

%TWISTY{id="currentCustomerList" showlink="Show..." hidelink="Hide" remember="on"}%
my customer list
%ENDTWISTY%

Make it obey

To let the Twisty start with its content folded open, add parameter start="show".

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

Show...Hide

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

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

Show...Hide

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.

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

Show...Hide

Other use: hide interface parts in case of no JavaScript

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.

%TWISTY{link="" noscript="hide" start="show"}%
<input type="submit" class="twikiButton" 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:

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

Styling the Twisty

Use parameter class to style the content div or class:

%TWISTY{mode="div" showlink="Show..." hidelink="Hide" class="twikiHelp"}%
my twisty content
%ENDTWISTY%

Generates:
Show...Hide

Twisty headers

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.

%TWISTY{prefix="<h4>!!" link="Header"
showimgleft="%ICONURLPATH{toggleopen}%"
hideimgleft="%ICONURLPATH{toggleclose}%" suffix="</h4>"}%
my twisty content
%ENDTWISTY%

Will create:

HeaderHeader

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.

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

Creates these controls:

Expand all Collapse all

When you want to use links, write:

#VarTOGGLE

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

Expand all Collapse all

Syntax

TWISTY

This renders the button as well as the toggled content section contained within this and the closing ENDTWISTY tag.
Usage: %TWISTY{ ... }% Toggable contents %ENDTWISTY%

Parameter	Value	Description	Remark
id	Unique identifier	Used to link TWISTYBUTTON and TWISTYTOGGLE	optional
link	Link label	Link label for both show and hide links	optional
hidelink	Link label	Hide link label	optional
showlink	Link label	Show link label	optional
mode	"div" or "span"	Specify if the Twisty Toggle section will use a <div> or a <span> tag.	optional, defaults to <span>
showimgleft	Image url	Specify the url of an image that will be displayed with the show link at the left side of the link. You may use ICONURLPATH to display one of the TWikiDocGraphics icons. Alternatively use an image attached to the topic.	optional, defaults to no image
hideimgleft	Image url	Specify the url of an image that will be displayed with the hide link at the left side of the link. You may use ICONURLPATH to display one of the TWikiDocGraphics icons. Alternatively use an image attached to the topic.	optional, defaults to no image
showimgright	Image url	Specify the url of an image that will be displayed with the show link at the right side of the link. You may use ICONURLPATH to display one of the TWikiDocGraphics icons. Alternatively use an image attached to the topic.	optional, defaults to no image
hideimgright	Image url	Specify the url of an image that will be displayed with the hide link at the right side of the link. You may use ICONURLPATH to display one of the TWikiDocGraphics icons. Alternatively use an image attached to the topic.	optional, defaults to no image
remember	"on", "off"	If "on", the Twisty state is remembered the next time the page is shown. If "off", the stored setting will be cleared. Note: 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.	optional, no default
start	"hide" or "show"	Initial state of the Twisty; this will override any setting stored in a cookie (see remember).	optional, default no initial state
firststart	"hide" or "show"	Initial state of the Twisty the first time the visitor gets to see the Twisty; this will NOT override cookie settings (see remember).	optional, default no initial state
noscript	"hide"	Make content hidden in case use does not have JavaScript on	optional, default content is shown in case JavaScript if off
class	CSS class name	Class for Twisty div or span	optional, default none
prefix	Text	Text to display before the show/hide links	optional, default none
suffix	Text	Text to display after the show/hide links	optional, default none
img	Image url	Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.	optional, defaults to no image
imgleft	Image url	Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.	optional, defaults to no image
imgright	Image url	Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.	optional, defaults to no image
hideimg	Image url	Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.	optional, defaults to no image
showimg	Image url	Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.	optional, defaults to no image

• Related TWISTYBUTTON and TWISTYTOGGLE

ENDTWISTY

Twisty closure, complements the opening TWISTY tag.

• Syntax: %ENDTWISTY%

See ENDTWISTYTOGGLE.

Twisty components syntax

The Fine Print

TwistyPlugin is a convenience plugin for TWiki:Plugins.TwistyContrib.

Major features are:

• When active, the Twisty JavaScript library is included in every topic
• Provides a convenience syntax to define Twisty areas
• Automatically generates ids
• Automatically fills in default values
• Global preference settings can be set in this topic or locally in individual topics

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %TWISTYPLUGIN_SHORTDESCRIPTION%

• Set TWISTYSHOWLINK = More...
  • For example: More...
• Set TWISTYHIDELINK = Close
  • For example: Close
• Set TWISTYMODE =
  • Either div or span; span if nothing set
• Set TWISTYREMEMBER =
  • 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

• Set SHORTDESCRIPTION = Twisty section JavaScript library to open/close content dynamically
• Set DEBUG = 0

Plugin Installation Instructions

• Download the ZIP file from the Plugin web (see below)
• Unzip TwistyPlugin.zip in your root ($TWIKI_ROOT) directory. Content:

  File:	Description:
  data/TWiki/TwistyPlugin.txt
  lib/TWiki/Plugins/TwistyPlugin.pm

• Optionally, if it exists, run TwistyPlugin_installer to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
• Alternatively, manually make sure the dependencies listed in the table below are resolved.

  Name	Version	Description
  TWiki::Contrib::TwistyContrib	>=1.200	Required. Twisty javascript library

• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Plugin Info

Authors:	TWiki:Main.RafaelAlvarez, TWiki:Main.ArthurClemens
Copyright ©:	2005 Rafael Alvarez, 2006 Arthur Clemens
License:	GPL
Dependencies:	Name Version Description TWiki::Contrib::TwistyContrib >=1.200 Required. Twisty javascript library
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 June 2006	1.100 Added parameters start, firststart, noscript and class; complete JavaScript rewrite for speed
12 Sep 2005	1.000 First Version
Home:	http://TWiki.org/cgi-bin/view/Plugins/TwistyPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/TwistyPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/TwistyPluginAppraisal