HierarchicalSelectPlugin

Syntax Rules

Write %HIERARCHICALSELECT{topic="TopicName" [other optional attributes]}% anywhere in a TWiki topic or template.

• Displays a multi-level drop down menu built from a nested bullet list in another TWiki topic.
• More than one drop down menu may be used on the same topic. However, a menu (or specific levels from a menu) defined by a specific topic may not be displayed more than once on the same topic - unpredictable things may happen if you try because that is not supported by the software architecture.

Usage Example

This is a multi-level dropdown menu using data from HierarchicalSelectPluginExample. It includes English-speaking countries and state/provincial and regional subdivisions (generally not including levels where municipalities are, though including independent cities), where applicable. Not all have the same levels of depth, even within the same country. The varying depth is really the point of the demo.

It is from the following HTML and TML markup:

The HierarchicalSelectPlugin %IF{"context HierarchicalSelectPluginEnabled" then="is" else="is not"}% enabled on this TWiki system

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#UsageExample">
<table cellpadding="5">
<tr><th>
Field:
</th><th>
Country
</th><th>
State/Province/Subdivision
</th><th>
County/Region
</th></tr>
<tr><td>
Entry:
</td><td>
%HIERARCHICALSELECT{web="TWiki" topic="HierarchicalSelectPluginExample" level="0" names="country,subdivision,region"}%
</td><td>
%HIERARCHICALSELECT{web="TWiki" topic="HierarchicalSelectPluginExample" level="1"}%
</td><td>
%HIERARCHICALSELECT{web="TWiki" topic="HierarchicalSelectPluginExample" level="2"}%
</td></tr>
<tr><td>
Values by level name:
</td><td>
%URLPARAM{"country"}%
</td><td>
%URLPARAM{"subdivision"}%
</td><td>
%URLPARAM{"region"}%
</td></tr>
<tr><td>
Values by menu name:
</td><td>
%URLPARAM{"root"}%
</td><td>
%URLPARAM{"%URLPARAM{"root"}%"}%
</td><td>
%URLPARAM{"%URLPARAM{"%URLPARAM{"root"}%"}%"}%
</td></tr>
</table>
<input type="submit" class="twikiSubmit">
</form>

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %HIERARCHICALSELECTPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Display hierarchical multi-level JavaScript drop-down menus from contents of a TWiki topic

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

• Or, follow these manual installation steps:
  • Download the ZIP file from the Plugins home (see below).
  • Unzip HierarchicalSelectPlugin.zip in your twiki installation directory. Content:

    File:	Description:
    data/TWiki/HierarchicalSelectPlugin.txt	Plugin topic
    data/TWiki/HierarchicalSelectPluginExample.txt	Example topic
    data/TWiki/VarHIERARCHICALSELECT.txt	Variable documentation topic
    lib/TWiki/Plugins/HierarchicalSelectPlugin.pm	Plugin Perl module
    pub/TWiki/Plugins/HierarchicalSelectPlugin/twiki-hierarchicalselect.js	JavaScript code

  • Set the ownership of the extracted directories and files to the webserver user.

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.
  • Test if the installation was successful: See Usage Example above

Plugin Info

• This plugin is sponsored by Twiki Inc

Plugin Author:	TWiki:Main.IanKluft
Copyright:	© 2010 Twiki Inc © 2010 TWiki:Main.IanKluft © 2010-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2012-12-01
Change History:
2012-12-01:	TWikibug:Item7020: Add category to VarHIERARCHICALSELECT; add screenshot -- TWiki:Main.PeterThoeny
2011-05-01:	TWikibug:Item6701: Doc improvements -- TWiki:Main.PeterThoeny
2010-02-20:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005
Benchmarks:	GoodStyle nn%, FormattedSearch nn%, HierarchicalSelectPlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/HierarchicalSelectPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/HierarchicalSelectPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/HierarchicalSelectPluginAppraisal

Related Topics: HierarchicalSelectPluginExample, VarHIERARCHICALSELECT, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences