AddToggle

Summary: Add a toggle link

Version: 20150723

Prerequisites: $EnableGUIButtons, Cookbook:Toggle

Status: Beta

Maintainer: RandyB

License: GPL2+

Users: +1 (view / edit)

Discussion: AddToggle-Talk ?

Questions answered by this recipe

Q. What's an easy way to create a toggle link if I don't know how toggle link markup works?
Q. How can I reduce the page source clutter created by toggle link markup?
Q. What is an easy way to keep in sync the show and hide versions of a toggle link's text?
Q. How do I put a toggle within another toggle?
Q. What's an easy way to create a list of questions with each answer hidden until clicked?

Like most toggle recipes, this recipe answers:
Q. How do I hide a section of a page until the user wants to see it?
Q. How do I make available info such as help and options without visually cluttering the page for the end reader?

Description

A GUIEdit button to convert selected text to a toggle link

The Cookbook:Toggle recipe allows markup to create a toggle link that shows or hides a div section. AddToggle provides a simple way for editors to convert selected text into a toggle's link text.

Installation

Make sure the Cookbook:Toggle recipe is working on your site, and that you have set $EnableGUIButtons = 1; in your configuration file (you will see guiedit buttons at the top of your edit form)
Copy addtoggle.php Δ to your cookbook directory. (Note: the file should not end immediately after the final semi-colon - append a blank line if necessary.)
Copy the button picture file Δ to your pmwiki/pub/guiedit directory.

Add to your configuration file lines such as:

# Define toggle icons for {$Show} and {$Hide} 
$FmtPV['$Show'] = "'&#9657;'";  # triangle pointing down
$FmtPV['$Hide'] = "'&#9663;'";  # triangle pointing right
include_once("$FarmD/cookbook/addtoggle.php");

Configuration

You can change the characters assigned to the page variables $Show and $Hide to whatever you want, or delete those lines if you don't want an icon to appear in front of your link text.

Usage

Select in your markup the text that you want to be your link. For example:

My link text

Then click the guiedit button: . The selected text will be transformed in the page's source into:

{(toggle 5615 "My link text")}
Hidden
(:div5615end:)

The page will show:

▹ My link text

when the contents are hidden, and

▿ My link text
Hidden

when the contents are showing.

Notes

If nothing is selected, the button adds sample markup wherever the cursor is.
Replace the "Hidden" text with whatever you want to show or hide.
You can use the page variables {$Show} and {$Hide} in other toggle directives as well, for a consistent look.
You can repeat the process inside the hidden area, to put toggles within toggles.
Wikistyles should work, e.g. %rfloat% {(toggle 5615 "Help")} puts a Help link on the right

How this recipe works

Since Toggle requires that each div on a page be unique, AddToggle generates a random number for the toggle. This allows multiple toggles to co-exist on the page. To simplify the markup (and to facilitate future updates), the AddToggle recipe converts the selected text into a markup expression, which in turn will bring into the page the required markup upon page rendering. It's as if you had put in your page source:

(:toggle id=toggle5615 hide nojs=2 show="{$Show} My link text" hide="{$Hide} My link text":)
(:div5615 id=toggle5615 :)
Hidden
(:div5615end:)

Change log / Release notes

20150723 - first public release, ready to be tested.

Contributors

Recipe written and maintained by RandyB.

Comments

See discussion at AddToggle-Talk ?

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.