create new tag
view all tags

Controls Plugin

Render HTML form controls based on values defined in TWiki Forms topics


This plugin creates controls that can be used to define HTML forms from possible values defined in a topic.

TWikiForms allow possible values for a form field to be defined in a topic (see Section "Defining a Form with Multiple Topics"). The same set of values are often used as the values of HTML form controls (e.g., when defining a search where these values are selectable parameters). Using this plugin, these lists of values can be kept synchronized by having the form controls generated based on the topic that defined the values in the first place.

Background: I often found myself defining the possible values for a field of a TWikiForms in a TWiki:Codev.TWikiApplication, and then had to manually define the same possible values for a drop down selection or similar in an HTML form. Keeping these consistent was a nuisance. This plugin automates that process.

Syntax Rules

  • Syntax: %CONTROL{"name" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "name" The name of the control to be generated, i.e. %CONTROL{"address"}% required
    topic="..." The topic defining the field values Current topic
    web="..." The web from which the topic is taken Current web
    type="..." The control to be rendered. Possible values are select, radio, or checkbox select
    size="..." The size parameter for the control. 1
    urlparam="..." Generates a select option to be passed as URL parameter (valid only with type="select" ). Possible values are on, off off


Below is the definition of the field values for TopicClassifications from TWikiForms:

Name Type Tooltip message
NoDisclosure option blah blah...
PublicSupported option blah blah...
PublicFAQ option blah blah...

If this plugins is installed, the variable

%<nop>CONTROL{"firstInput" type="checkbox" size="1"}%

will expand as follows:

Output Expected

Hierarchical Select

This plugin also supports the dynamic selection of hierarchical (cascaded) menus, albeit only for select type controls. A selection in the first menu will configure the second menu with only those options relevant to the selection made in the first menu. A selection in the second menu will in turn configure the options in the third menu, and so on.

The dynamic aspects of hierarchical menus requires Javascript to be available. Where Javascript is not enabled, this plugin degrades gracefully and provides all options in the dependent menus. (The ability to degrade gracefully explains the rather large amount of Javascript to be included. Unfortunately, a side effect is that pre-selecting a choice via URL parameters is not supported.)

  • The following additional parameters are supported in the CONTROL tag and are useful for hierarchical menus:
    Parameter: Description: Default:
    form="..." The name of the form the hierarchical control will be used in. This form must be given a name attribute. required
    separator="..." A string inserted between the controls generated for each level of the hierarchy. single space
    initmessage="..." A string that will be shown in a dependent menubefore a selection in the parent menu is made Select previous level first
    nextmessage="..." A string that will be shown in a dependent once a selection in the parent menu has been made  

The options for each menu are given in a topic as described above. If a menu is hierarchical, its field value must point to another topic where the options for the dependent menu are defined. See TWikiForms for detail of how to define option tables. As a reminder, when a field is defined with the syntax [[XXX][YYY]], where XXX is a topic name, and YYY is some text, then while YYY is chosen as the displayed text, the topic XXX will be consulted for the dependent menu.

For hierarchical menus, the name of the controls generated are given by the name parameter, with the depth of the control suffixed, starting at 0 for the first level.

ALERT! Note that this plugin assumes that menu hierarchy is fully defined, that is, that all branches of the menu tree have the same depth.

ALERT! Note that the urlparam parameter does not apply to hierarchical menus.

Acknowledgement: The Javascript for the hierarchical menus was written by Richard Comford.

Dependent Select

This plugin also supports the generation of a select dependent of a selection made, e.g., in a URL parameter. One sets up a hierarchical menu as for hierarchical selects, but one of the options at the top level will be selected. In this way, one can pass in a parameter to the topic, and configure a menu (or hierarchy of menus) dependent on this parameter.

If the resultant control is hierarchical, it is treated as a hierarchical menu. Otherwise, the control functions as a standard control.

  • The following additional parameters are supported in the CONTROL tag to support dependent select:
    Parameter: Description: Default:
    selection="..." The name of the option that is selected from the options defined in the topic parameter. If empty, all dependent options are selected. If the selected option is not among those specified, no control is generated. required

Note: If the selection parameter is left empty, all options possible are concatenated. This could be enhanced by (i) sorting all options and/or (ii) removing duplicates.

Plugin Settings

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Render HTML form controls based on values defined in TWiki Forms topics

  • 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 server where TWiki is running.

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

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip ControlsPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/ControlsPlugin.txt Plugin topic
      data/Sandbox/ControlsPluginExampleArgentinaCities.txt Example topic
      data/Sandbox/ControlsPluginExampleCitiesMenu.txt Example topic
      data/Sandbox/ControlsPluginExampleBrasilCities.txt Example topic
      data/Sandbox/ControlsPluginExampleUruquayCities.txt Example topic
      lib/TWiki/Plugins/ControlsPlugin.pm Plugin Perl module
      pub/TWiki/ControlsPlugin/cascade_select.js Java script supporting hierarchical menus
    • Set the ownership of the extracted directories and files to the webserver user.

Plugin Info

Plugin Author: TWiki:Main.ThomasWeigert
Copyright: © 2005-2006 TWiki:Main.ThomasWeigert
© 2008-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2011-05-03
Change History:  
2011-05-03: TWikibug:Item6701: Fix plugin to use only published API so that it runs on TWiki-4.0 through TWiki-5.0; doc improvements; moving menuexample.zip to Sandbox web for easy access -- TWiki:Main.PeterThoeny
04 Aug 2006: Fixed erroneous hierarchy presentation when selections were links.
19 Jul 2006: Added dependent select and example.
17 Jul 2006: Added hierarchical menu support
07 Jul 2006: Ported to Dakar
20 Feb 2005: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.024
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
TWiki:Plugins/Benchmark: GoodStyle nn%, FormattedSearch nn%, ControlsPlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ControlsPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ControlsPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ControlsPluginAppraisal

Related Topics: ControlsPluginExampleArgentinaCities, ControlsPluginExampleCitiesMenu, ControlsPluginExampleBrasilCities, ControlsPluginExampleUruquayCities, TWikiPlugins, TWikiForms, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
JavaScriptjs cascade_select.js r1 manage 8.2 K 2011-05-04 - 03:24 TWikiAdminUser Saved by install script
Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | More topic actions
Topic revision: r3 - 2015-06-17 - TWikiAdminUser
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.ControlsPlugin.