%META:TOPICINFO{author="TWikiContributor" date="1354433342" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="TWikiPreferences"}%
---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/HierarchicalSelectPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/HierarchicalSelectPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

<img src="%PUBURLPATH%/%WEB%/%TOPIC%/select-screenshot.png" alt="Screenshot" width="536" height="132" />

---++ Syntax Rules

Write =%<nop>HIERARCHICALSELECT{topic="<i>TopicName</i>" <i>[other optional attributes]</i>}%= 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.

|*Name*|*Description*|*Default*|
|topic|topic from which to read the menu definition|_required_|
|web|web from which to read the menu definition|current web|
|key|string to use as the basis for naming of HTML form elements|derived from menu topic|
|level|if specified, select a menu level (integer starting from 0) to display|all levels|
|parse_keywords|flag: nonzero sets parsing mode where first word of menu line is return-value keyword, remainder is text to display|entire line used as both return value and display text|

#UsageExample
---++ 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.

<div style="padding: 10px; background-color: #f0f0f4">
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>
</div>

It is from the following HTML and TML markup:

<verbatim>
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>
</verbatim>

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>HIERARCHICALSELECTPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %SYSTEMWEB%.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 [[%SCRIPTURL{configure}%][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 ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/%TOPIC%Example.txt== | Example topic |
        | ==data/TWiki/VarHIERARCHICALSELECT.txt== | Variable documentation topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==pub/TWiki/Plugins/%TOPIC%/twiki-hierarchicalselect.js== | !JavaScript code |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][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 [[http://www.twiki.net/][Twiki Inc]]
|  Plugin Author: | TWiki:Main.IanKluft |
|  Copyright: | &copy; 2010 Twiki Inc <br /> &copy; 2010 TWiki:Main.IanKluft <br /> &copy; 2010-2011 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2012-12-01 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %TOPIC%Example, VarHIERARCHICALSELECT, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="select-screenshot.png" attachment="select-screenshot.png" attr="h" comment="" date="1354433257" path="select-screenshot.png" size="23107" user="TWikiContributor" version="1"}%
