Powered by Foswiki, The Free and Open Source Wiki

You are here: DAMASK>System>Category>AdminDocumentationCategory>Plugins>TwistyPlugin

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:

Show button
Hide button
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:

my twisty content

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

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

Will generate:

my twisty content

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

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:

my twisty content

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%

my twisty content

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%

my twisty content

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%

my twisty content

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%

Hide

my twisty content

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

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

Show...

my twisty content

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%

Hide

my twisty content

Other use: hide interface parts in case of no JavaScript

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

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:

my twisty content

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:

my twisty content

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:

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:

Incorrect	Correct	Example
* L1 * L2 %TWISTY{}% Some content %ENDTWISTY{}% * L3	* L1 * L2 %TWISTY{}% Some content %ENDTWISTY{} * L3	L1 L2 More...Close Some content L3
	* L1 * L2 %TWISTY{mode="span"}% Some content %ENDTWISTY{} * L3	L1 L2 More...Close Some content 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:

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:

link="%Y%"

but use format tokens:

link="$percntY$percnt"

... to get:

my twisty content

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`	`"div"` or `"span"` 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 `div` as well to create valid HTML markup.	`<div>`
`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 div or span
`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 div

Examples

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

Expands as:
moremore
content

TWISTYSHOW - Show/open link

Parameters

Parameter	Description	Default
`id`	Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE	required
`link`	Show link label
`mode`	`"div"` or `"span"` Specify if the Twisty Show link will use a `<div>` or a `<span>` tag. Note that if the contents contains block elements such as `div`, `mode` should be `div` as well to create valid HTML markup.	`<div>`
`img`	Specify the url of an image that will be displayed 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.
`imgleft`	Specify the url of an image that will be displayed 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.
`imgright`	Specify the url of an image that will be displayed 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`).

Examples

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

TWISTYHIDE - Hide/close link

Parameters

Parameter	Description	Default
`id`	Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE	required
`link`	Hide link label
`mode`	`"div"` or `"span"` Specify if the Twisty Hide link will use a `<div>` or a `<span>` tag. Note that if the contents contains block elements such as `div`, `mode` should be `div` as well to create valid HTML markup.	`<div>`
`img`	Specify the url of an image that will be displayed 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`).

Examples

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

TWISTYTOGGLE -- Twisty Toggle contents section

Parameters

Parameter	Description	Default
`id`	Used to link TWISTYSHOW, TWISTYHIDE and TWISTYTOGGLE.	required
`mode`	`"div"` or `"span"` 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 `div` as well to create valid HTML markup.	`<div>`
`class`	CSS class name for content div or span
`linkclass`	CSS class name for link
`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`	`hide` to make content hidden in case use does not have JavaScript on

Examples

%TWISTYTOGGLE{id="demo" mode="div" 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

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

Plugin Settings

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

Preference	Meaning	Default
`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_TWISTYSHOWLINK`	For example: `More...`	More...
`TWISTYPLUGIN_TWISTYHIDELINK`	For example: `Close`	Close
`TWISTYPLUGIN_TWISTYANIMATIONSPEED`	Speed of animation: 'fast', 'slow', or integer milliseconds	`0` (no animation)

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. Use "Find More Extensions" to get a list of available extensions. Select "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 http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Change History:
25 Apr 2016	1.63 Bump version due to minor documentation updates. Released with Foswiki 2.1.1
17 Jun 2014	1.62 Foswikitask:Item12597: Expand/Collapse all is acting as a toggle. Foswikitask:Item12694 Default to fast animation speed. Foswikitask:Item12583: Change to simple decimal version, Foswikitask:Item10986: Better documentation for twisties in lists.
15 Oct 2013	1.6.18 Foswikitask:Item12597: fixed collapse/expand all
28 Nov 2012	1.6.17 Foswikitask:Item12079: Scripts added to the wrong zone Foswikitask:Item11267: Convert to perl version strings.
18 Sep 2012	1.6.16 Foswikitask:Item11983: fixed script being added to the wrong zone
05 Dec 2011	1.6.15 Released with Foswiki 1.1.4 - minor changes
07 Jul 2011	1.6.14 Foswikitask:Item10946: fixed requesting of defunct/missing jquery.twisty.css
02 Jun 2011	1.6.13 Foswikitask:Item10827: clear pref completely when using `remember="off"`. Effective from Foswiki 1.1.4 and higher.
10 Apr 2011	1.6.12 Foswikitask:Item10618: parenthesis (or other Regex characters) in topic name crashes Foswiki Foswikitask:Item10264: Change template-js-css logic from foswikiJs to foswikiNoJs Foswikitask:Item10506: Add noci to avoid checkin of files during installation.
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 `$percent` back to `$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 Foswikitask:Item9422: Implement as JQueryPlugin::Plugin; emit `display: none` style on hidden twisties to avoid relying on CSS/JS Foswikitask:Item9415: Documentation changes
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

PackageForm edit

Author	Foswiki:Main.RafaelAlvarez, Foswiki:Main.MichaelDaum, Foswiki:Main.ArthurClemens
Version	1.63
Release	1.63
Repository	https://github.com/foswiki/distro
Copyright	Copyright (C) Rafael Alvarez; Michael Daum, Arthur Clemens, Foswiki Contributors 2008-2014
License	GPL
Home	http://foswiki.org/Extensions/TwistyPlugin
Support	http://foswiki.org/Support/TwistyPlugin

Topic revision: r1 - 01 May 2016, UnknownUser

Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding DAMASK? Send feedback

TwistyPlugin

Usage examples

Triad

Shorthand

Block or inline

Twisty with icons

Make it remember

Make it obey

Make it obey only the first time

Other use: hide interface parts in case of no JavaScript

Styling the Twisty

Styling the Twisty link or button

All on, all off

Twisties inside other elements

Special syntax: format tokens

Generation of the twisty ID

Syntax

TWISTY -- generate content block with interactive visibility controls

Parameters

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

TWISTYBUTTON -- Shorthand version for TWISTYSHOW & TWISTYHIDE

Parameters

Examples

Related

TWISTYSHOW - Show/open link

Parameters

Examples

TWISTYHIDE - Hide/close link

Parameters

Examples

TWISTYTOGGLE -- Twisty Toggle contents section

Parameters

Examples

ENDTWISTYTOGGLE -- Twisty closure

Examples

Notes for developers

CSS classes

Plugin Settings

Plugin Installation Instructions

Plugin Info

PackageForm edit