FlexFormPlugin

Flexible way to render DataForms

This plugin leverages the internal capabilities to render an interface for DataForms. This API is part of the Form class of Foswiki and is called renderForEdit(). It takes a form definition and creates an appropriate edit interface for the given DataFrom. This feature is actually very handy to write custom EDIT_TEMPLATEs and VIEW_TEMPLATEs in wiki applications.

The %RENDEFFOREDIT and %RENDERFORDISPLAY macros allows wiki application authors to customize interfaces to DataForms while not losing the flexibility of defining a DataForm in one place.

Imagine you created an EDIT_TEMPLATE without %RENDERFOREDIT by creating an HTML input form manually. When you decide to extend or modify a form definition later you will always have to maintain these HTML forms in an EDIT_TEMPLATE as well. This redundancy can be avoided by using a %RENDERFOREDIT macro that loops over all formfields in your DataForm to render the input form in a more dynamic way while still customizing the overall output.

In addition, FlexFormPlugin facilitates the extraction of field default values (such as valid schema options) from DataForm. See http://foswiki.org/Development/MacroForRetrievingFieldDefaultValues for background.

Usage

RENDERFOREDIT

RENDERFORDISPLAY

If all three format, header and footer are undefined a foswikiFormSteps block will be rendered as illustrated in the example below.

The format parameter may contain the following pseudo-variables:

• $attrs: attribute string as given in the DataForm definition
• $description: formfield description in DataForm
• $edit: the HTML form element as specified by the DataForm definition, that is a input field, a textarea, a select box, whatever
• $extra: the "extra" return value of the Foswiki::Form::renderForEdit() call
• $mandatory: placeholder to display the mandatory flag when a formfield is mandatory; the format of the mandatroy flag can be defined in the mandatory parameter to RENDERFOREDIT
• $name: the original fieldname
• $size: size parameter of the formfield as given in the DataForm definition
• $title: the fieldtitle derived from the fieldname and remapped as specified in the map parameter
• $tooltip: formfield description in DataForm (deprecated: use $description instead)
• $type: type of formfield as given in the DataForm definition
• $value: current value of the formfield; for +value formfields this is the mapped value use $origvalue to get the original one
• $origvalue: current value of the formfield; for +value formfields this is the original unmapped value of the formfield
• $values: list of all allowed values for the formfield as defined in the DataForm definition
• $origvalues: list of all allowed values; for +value formfields this is the original unmapped value of the formfield
• $default: this is the default value if no value is specified in the topic itself

Examples

%RENDERFOREDIT{
  form="%USERSWEB%.UserForm"
  topic="Sandbox.TestTopic1"
  exclude="Email|Comment|State"
  FirstName_value="Horst"
  LastName_value="Buchholz"
  map="VoIP=Skype"
}%

Display the allowed values of one field and its default

%RENDERFORDISPLAY{
  form="ValueTransactionForm" 
  field="FromRole" 
  format="allowed values for $title are $values, default is '$default'"
}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info