Controls Plugin

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

Example

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

If this plugins is installed, the variable

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

will expand as follows:

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 preselecting 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.

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

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

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

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 dependant 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 = This plugin renders a control (typically used in an HTML form) based on values defined in a 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 server where TWiki is running.

• Download the ZIP file from the Plugin web (see below)
• Unzip ControlsPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/ControlsPlugin.txt	Plugin topic
  pub/TWiki/ControlsPlugin/cascade_select.js	Java script supporting hierarchical menus
  lib/TWiki/Plugins/ControlsPlugin.pm	Plugin Perl module
  lib/TWiki/Plugins/ControlsPlugin/menuexample.zip	Demo example

• Test if the installation was successful:
  • See if above example rendered correctly
  • Unzip lib/TWiki/Plugins/ControlsPlugin/menuexample.zip in a web and view topic CitiesMenu.

Plugin Info

Related Topics: TWikiForms

-- TWiki:Main/ThomasWeigert - 04 Aug 2021