SeeSaw

Contents

SeeSaw

Purpose

To enable sections of a page to be see-sawed (toggled) between hidden and shown, or unconditionally placed in either state.

Description

SeeSaw creates a control (link or button) for performing its actions. It has two parts: at any time one is shown and the other hidden. SeeSaw uses the CSS display attribute to switch between the two parts, and to hide and show sections. Every page element that SeeSaw affects is normally identified with the CSS class name seesaw, so that it is impossible for it to accidentally affect unrelated elements.

The control is created by a call of the following form:

<<SeeSaw(section="section", toshow="toshow", tohide="tohide",
         show=True|False, bg="background", inline="inline",
         image="arrow|plumin|attachment|file",
         speed="slow|normal|fast"|integer,
         seesaw=True|False, addclass="list", type="link|button",
         effect="slide|fade")>>

section: in basic usage - extended usage is described below - section specifies the name of a section that the control will toggle; the name is also attached to the parts of the control as a CSS class name, and needs to be attached to sections that the control is to affect;
the default is section
toshow: specifies the text or image to display for showing the section;
the default is Show, except for inline sections where it is »»
tohide: specifies the text or image to display for hiding the section;
the default is Hide, except for inline sections where it is ««
show: specifies whether the section is to be shown initially;
the default is False
bg: specifies a background colour to be applied to the section;
the default is None
inline: specifies the text of an inline section; SeeSaw creates inline sections itself, immediately after the controls;
the default is None
image: specifies the source of a pair of images to be used by the control;
the default is None
speed: specifies the rate at which the section should appear or disappear, or provides a number of milliseconds for an animation to last;
the default is None
seesaw: SeeSaw will, by default, only toggle sections created for it, i.e. bearing the CSS class name seesaw; this option, when set to False, enables non-SeeSaw elements to be toggled from a SeeSaw control;
the default is True
addclass: specifies a space-separated list of additional CSS class names to be associated with the control, and inline section, if any, to enable them to be manipulated using those names in other SeeSaw calls;
the default is None
type: specifies the type of HTML element to create for the control;
the default is link
effect: specifies an alternative style of animation for showing and hiding the section;
the default is None

The (leading) arguments can also be given positionally, in the order of the keyword arguments above, e.g.

<<SeeSaw(section1, Show, Hide, True)>>

is equivalent to

<<SeeSaw(section=section1, toshow=Show, tohide=Hide, show=True)>>

Requirements

SeeSaw uses JavaScript and requires jQuery. The version of jQuery current at the time of release is included in the download.

Examples

<<SeeSaw(example3, toshow=See-Saw, show=True, bg="#FFFFDD")>> example 3
{{{#!wiki seesaw example3 show
This is part 1 of example 3; it is displayed initially.<<BR>>
It is hidden and part 2 displayed when See-Saw is clicked
}}}
{{{#!wiki seesaw example3 example3-bg
This is part 2 of example 3; it has a different background colour and is
displayed when part 1 is hidden.<<BR>>
It is hidden and part 1 displayed again when See-Saw is clicked.
}}}

Further examples, bundled as a set of wiki pages, can be downloaded below. Unpack into .../data/pages in your wiki and access SeeSawExamples.

Changes

1.5

Allow free use of attachments and files as images

1.4

Added macro_MacroName interface. A consequence (for MoinMoin 1.7+) is that there is no need to quote arguments that used to need quoting, e.g. the quotes in section="one -all", bg="#FFFFDD" can be dispensed with.
Improved installation procedure: can be run with just the macro needing to be installed

1.3

Can be applied to all HTML element types, and thus now to MoinMoin tables using tableclass, rowclass and class
Treats additional plain names in section argument as additional classes, i.e. as if added by addclass argument

There are no substantive differences in functionality between versions 1.3 and 1.4

Download

Version	MoinMoin	Comment
SeeSaw-1.5.tgz	1.6 - 1.9	SeeSaw.py changed Provides jQuery 1.10.1. Released 9 Jun 2013.
SeeSaw-1.4.tgz		SeeSaw.py changed Provides jQuery 1.9.1. Released 28 Apr 2013.
SeeSaw-1.3.tgz		SeeSaw.py and seesaw.js both changed. Provides jQuery 1.9.1. Released 31 Mar 2013.
seesawexamples.tgz		Unpack into .../data/pages in your wiki and access SeeSawExamples Updated 9 Jun 2013 for SeeSaw 1.5

Copyright

2008,2009,2011,2013 Jim Wight

Extended Description

section and addclass

Sections are typically set up as follows:

{{{#!wiki seesaw section   or   {{{#!wiki seesaw/section
}}}                             }}}

where the word section matches the value section in the corresponding SeeSaw call. This creates an HTML div with the classes seesaw and section applied. In general, a section can be any HTML element to which CSS classes can be applied via MoinMoin markup, e.g. divs as just described, tables via tableclass (for whole tables), rowclass (for rows) and class (for cells), or others via {{{#!html. See also inline below.

In extended usage, section is a space- or slash-separated list of plain or modified section or CSS class names specifying actions to be carried out when the control is clicked. The items can have any of the following forms:

section  - for toggling itself and other controls and sections identified by "section"
%section - for toggling controls and sections identified by "section"
+section - for unconditionally putting controls and sections identified by "section" into their shown state
-section - for unconditionally putting controls and sections identified by "section" into their hidden state

If there is more than one plain name, the second and subsequent are treated as additional CSS class names (as if added by 'addclass') to be associated with the control, and inline section, if any, to enable them to be manipulated using those names in other SeeSaw calls. For example,

<<SeeSaw("s1 s2 all")>>

would toggle sections identified by s1 and its control parts would also be toggled by calls toggling sections identified by either s2 or all. It is equivalent to

<<SeeSaw(s1,addclass="s2 all")>> and <<SeeSaw("s1 s2",addclass=all)>>

The order of priority, from highest to lowest, is toggles, shows and hides, so it is possible, for example, to show a section that is also hidden by virtue of a classification in the same sequence, e.g "+s1 -all" would result in s1 being shown even if also covered by all.

If the section argument doesn't contain a plain name, then the control has a single state and always displays the toshow part (or equivalent for images); the show argument is not relevant.

If you want a section to be manipulated by extra class names, i.e. additional plain section names or names appearing in addclass arguments, then those names should also be added to to the sections, e.g. given

<<SeeSaw("a both")>> <<SeeSaw(b, addclass=both)>> <<SeeSaw("%both")>>

{{{#!wiki seesaw a both   and   {{{#!wiki seesaw b both

the first SeeSaw call would create a control toggling its own parts and the first section, the second call would do the same for the second section, and the third would toggle both sections and the parts of both controls (keeping them in sync with the states of the sections).

toshow, tohide and show

By default, sections are hidden initially, but can be shown by adding show to the relevant markup. show should be set to True in the matching SeeSaw call if its tohide and toshow arguments are different (so that the correct one can be shown initially).

The toshow and tohide defaults only apply if both options are not set. If only one is set the other is given its value.

toshow and tohide can accommodate text surrounding the control, to allow it to be different in the two cases. The three parts are distinguished by enclosing the text of the control between << and >>, e.g.

toshow="<<Open>> me up", tohide="Now <<close>> me down"

(The middle parts of) toshow and tohide can be set independently to be images using the following notation:

<<SeeSaw(s, "attachment:show.png", Hide)>>

to use an image from the page's attachments directory, and

<<SeeSaw(s, Show, "file:/path/to/hide.png")>>

where /path/to/hide.png is a server path for loading the image from the filesystem.

bg

If a background colour is specified for a section, "section"-bg needs to be added to the corresponding markup to have the colour applied to the section, e.g.

<<SeeSaw(section1, bg="#FFFFDD")>>

||<class="seesaw section1 section1-bg">Data||

If there are multiple SeeSaw calls for the same section name, it is sufficient to use bg in just one of them, with the last taking precedence if multiple, but different, values are given.

inline

The text of inline sections is embedded in SeeSaw calls. By default, inline sections are hidden initially, and the effects of show and bg, and the addition of the section and addclass classes are handled directly by SeeSaw. Inline sections are created as HTML spans. Spans not adjacent to controls can be created by using the 3rd-party span macro, available at http://moinmo.in/MacroMarket/span.

image

Additional image sets can be made available as embedded data or from files. Instructions are in the Configuration section of the source file. When image specifies one of the provided sets, or one added by the installer, the middle parts of toshow and tohide are ignored.

When image has the value attachment, toshow and tohide (strictly the middle parts) are interpreted as the names of images in the page's attachments directory, e.g.

<<SeeSaws(s, "show.png", "hide.png", image=attachment)>>

Similarly, when image has the value file, toshow and tohide are interpreted as server paths for directly loading user-specified images from the filesystem, e.g.

<<SeeSaw(s, image=file, toshow="/img/show.png", tohide="/img/hide.png")>>

Note that if image= is used out of order, toshow= and tohide= must be used.

seesaw

By setting the option seesaw to False it is possible to apply SeeSaw to non-SeeSaw sections, e.g. the div created by the TableOfContents macro. In such a case, the section name in the SeeSaw call should be a class already attached to the div, or the class can be added as an extra name or by use of the addclass argument. If the section is shown initially (more than likely), show=True should be set in order to get the control's text right - or the values of toshow and tohide can be reversed.

When seesaw is True (the default), the control affects only sections with seesaw and any of the names in the section argument attached as class names. When seesaw is False, the control affects all sections with any names in the section argument attached as class names. In this case, sections will be shown initially.

It is the presence of seesaw on a section that causes it to be hidden initially. Thus, treating user-created sections as non-SeeSaw sections (without the addition of seesaw) is an option if most are to be shown initially.

speed

By default, sections are shown and hidden instantaneously. However, if a speed is specified, they are gradually revealed and withdrawn via an animation which adjusts their width, height and opacity simultaneously. The speed is applied to all sections specified in the section argument and is independent of the speeds applied to those sections in other calls, e.g. given

<<SeeSaw(s1)>>   <<SeeSaw(s2, speed=fast)>>  <<SeeSaw("s3 %s1 %s2", speed=slow)>>

both s1 and s2, as well as s3, will be animated slowly by the third call.

effect

By default, sections are shown and hidden instantaneously. The effect option provides animations which are smoother in operation. The effect is applied to all sections specified in the section argument and is independent of the effects applied to those sections in other calls, as above for speed.

MoinMoin: MacroMarket/SeeSaw