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.

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%

Shorthand

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

%TWISTY{}%
my twisty content
%ENDTWISTY%

Will generate:

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.

Block or inline

The default display mode of Twisty is block, that is, the contents is displayed using a <div> element, displayed on the next line.

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

%TWISTY{mode="inline"}%
my twisty content
%ENDTWISTY%

Will generate:

More ...Less ... my twisty content

Twisty with icons

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

It will look like this:

To put icons at the right side, write

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

Make it remember

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

WARNING: If you really want it to be remembered, best to provide an id with it, otherwise it might not work.

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

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

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    remember="off"
}%
my twisty content
%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.

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

Note that id sets a site wide cookie. To create a unique id, add topic or web macros:

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%

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

%TWISTY{
    showlink="Show..."
    hidelink="Hide"
    start="hide"
}%
my twisty content
%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.

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

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="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:

%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:

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

Generates:

Styling the Twisty link or button

Use parameter linkclass to style the twisty links:

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

Generates:

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 foswikiButton">Expand all</button>
<button class="twistyCollapseAll foswikiButton">Collapse all</button>

Creates these controls:

Expand allCollapse 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

Twisties inside other elements

Twisties generate a <div> or a <span> so it's important to not divide the Twisty element across other elements such as lists. In order to use a twisty within a list, be sure that the twisty is closed before moving to the next list entry:

   * L1
   * L2 %TWISTY{}% Some content
%ENDTWISTY{}%
   * L3

   * L1
   * L2 %TWISTY{}% Some content %ENDTWISTY{}
   * L3

   * L1
   * L2 %TWISTY{mode="inline"}% Some content %ENDTWISTY{}
   * L3

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 FormattedSearch:

For example, to show an icon inside the link, do not write:

link="%Y%"

but use format tokens:

link="$percntY$percnt"

... to get:

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

link="Count: (%CALC{"$GET(infoCount)"}%)"

but use format tokens:

link="Count: ($percntCALC{$quot$dollarGET(infoCount)$quot}$percnt)"

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

TWISTY -- generate content block with interactive visibility controls

This renders the button as well as the toggled content section contained within this and the closing ENDTWISTY tag.

Parameters

Parameter	Description	Default
id	Used to link TWISTYBUTTON and TWISTYTOGGLE
link	Link label for both show and hide links
hidelink	Hide link label
showlink	Show link label
mode	"block" or "inline" Specify if the Twisty Toggle section will use a <div> or a <span> tag. Note that if the contents contains block elements such as div, mode should be block as well to create valid HTML markup.	<block>
showimgleft	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 DocumentGraphics icons. Alternatively use an image attached to the topic.
hideimgleft	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 DocumentGraphics icons. Alternatively use an image attached to the topic.
showimgright	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 DocumentGraphics icons. Alternatively use an image attached to the topic.
hideimgright	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 DocumentGraphics icons. Alternatively use an image attached to the topic.
remember	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.
start	"hide" or "show" Initial state of the Twisty; this will override any setting stored in a cookie (see remember).
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).
noscript	Make content hidden in case use does not have JavaScript on. Default content is shown in case JavaScript if off
class	CSS class name for Twisty element
linkclass	CSS class name for link
prefix	Text to display before the show/hide links
suffix	Text to display after the show/hide links

Additional parameters img, imgleft, imgright, hideimg, showimg are deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.

ENDTWISTY -- complements an opening TWISTY tag to close a twisty

Closes an open twisty

TWISTYBUTTON -- Shorthand version for TWISTYSHOW & TWISTYHIDE

This is useful if both the show and the hide button take the same arguments.

Parameters

All parameters supported by TWISTY, except for

• noscript and class (only used for 'toggle' content)
• mode button mode defaults to "block"

Examples

%TWISTYBUTTON{
    id="myid"
    link="more"
  }%%TWISTYTOGGLE{
    id="myid"
  }%content%ENDTWISTYTOGGLE%

• Expands as:

  moremore

  content

Related

• ENDTWISTY -- complements an opening TWISTY tag to close a twisty
• ENDTWISTYTOGGLE -- Twisty closure
• TWISTY -- generate content block with interactive visibility controls
• TWISTYHIDE - Hide/close link
• TWISTYSHOW - Show/open link
• TWISTYTOGGLE -- Twisty Toggle contents section

TWISTYSHOW - Show/open link

Parameters

Examples

%TWISTYSHOW{id="demo" link=" Click to Unfold " imgleft="%ICONURLPATH{toggleopen}%"}%

TWISTYHIDE - Hide/close link

Parameters

Examples

%TWISTYHIDE{id="demo" link=" Click to Fold " imgleft="%ICONURLPATH{toggleclose}%"}%

TWISTYTOGGLE -- Twisty Toggle contents section

Parameters

Examples

%TWISTYTOGGLE{id="demo" mode="block" remember="on"}%My content%ENDTWISTYTOGGLE%

ENDTWISTYTOGGLE -- Twisty closure

Will end the most inner unclosed Twisty Toggle section, using the proper tag

Examples

%ENDTWISTYTOGGLE%

Notes for developers

CSS classes

Plugin Settings

You can override some default settings in the plugin by setting the following preferences.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Change History