JQueryTwistyPlugin

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/JQueryTwistyPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/JQueryTwistyPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

About a jQuery rework

This is a fork of the famous TWiki:Plugins/TwistyPlugin by Rafael Alvarez and Arthur Clemens. Instead of being build on top of Behaviour and TWiki's own homebrewed JavaScript framework, this rework is solely based on jQuery, a lean and simple 3rd party framework which easily superseeds Behaviour and makes most of TWiki's own JavaScript framework superfluous. In addition, the JQueryTwistyPlugin adds open/close animations to twisties making them even more userfriendly.

The other motivation to patch the original TwistyPlugin/Contrib was to remove the Behaviour contrib all together. It really was only used in twisties in TWiki and wasn't up to being used much in any other place. So this way you will only have to deal with one instead of two JavaScript frameworks, reducing download time and adding all the merrits of jQuery along the way.

In general this is a drop-in replacement for the TwistyPlugin and the TwistyContrib. You don't need both when you are using the JQueryTwistyPlugin.

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

JQueryTwistyPlugin 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.

Usage examples

Triad

A Twisty consists of 3 elements:

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

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

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

Shorthand

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

%TWISTY{}%
my twisty content
%ENDTWISTY%

Will generate:

More... Close

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

You may have noticed that no parameters are passed to %TWISTY{}% but the show and hide links do have text! The default values are fetched from plugin settings TWISTYSHOWLINK and TWISTYHIDELINK, see Plugin Settings below.

Twisty with icons

We will use mode="div" to put the collapsing content below the button (the default mode is "span").

%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

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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 

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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%

Note that id sets a sitewide cookie. To create a unique id, add topic or web variables:

id="%WEB%_%TOPIC%_currentCustomerList"

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

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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

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

Show... Hide

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

Hide interface parts if 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%

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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 might have !JavaScript" />
%ENDTWISTY%

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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:

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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>!!" mode="div" link="Header"
showimgleft="%ICONURLPATH{toggleopen}%"
hideimgleft="%ICONURLPATH{toggleclose}%" suffix="</h4>"}%
my twisty content
%ENDTWISTY%

Add the !! to prevent the twisty header appear in the table of contents when you use %TOC%.

Will create:

!! Header Header

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

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> &nbsp; <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> &nbsp; 
<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%

• Related TWISTYBUTTON and TWISTYTOGGLE

ENDTWISTY

Twisty closure, complements the opening TWISTY tag.

• Syntax: %ENDTWISTY%

See ENDTWISTYTOGGLE.

Twisty components syntax

The Fine Print

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 JQueryTwistyPlugin.zip in your root ($TWIKI_ROOT) directory. Content:

  File:	Description:
  data/TWiki/JQueryTwistyPlugin.txt
  lib/TWiki/Plugins/JQueryTwistyPlugin.pm
  pub/TWiki/JQueryTwistyPlugin/twist.css
  pub/TWiki/JQueryTwistyPlugin/twist.js

• Optionally, if it exists, run JQueryTwistyPlugin_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::Plugins::JQueryPlugin	>=0.5	Required.

• 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-2007 Arthur Clemens; © 2007-2008 Michael Daum; © 2005-2010 TWiki:TWiki/TWikiContributor
License:	GPL
Dependencies:	Name Version Description TWiki::Plugins::JQueryPlugin >=0.5 Required.
Plugin Version:	2010-07-25
Change History:	<-- versions below in reverse order -->
2010-07-25	TWikibug:Item6530 - doc fixes
28 Apr 2008	warn on wrong ordering of TWISTY ... ENDTWISTY
13 Feb 2008	minor fixes for jquery-1.2.3
15 Nov 2007	first version forking TwistyPlugin/TwistyContrib
Home:	http://TWiki.org/cgi-bin/view/Plugins/JQueryTwistyPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/JQueryTwistyPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/JQueryTwistyPluginAppraisal