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

Parameter	Description	Default
"..." (or topic="..."	name of a topic to render the edit form for	the base topic of the current url
revision="..."	topic revision which to use the data from while populating the edit form
excludeattr="..."	regular expression field attributes must match to be excluded from the output	undefined
exclude="..."	regular expression fieldnames must match to be excluded from the output	undefined
fields="<fieldname1>, <fieldname2>, ..."	list of formfields to render the interface for	all known formfields
prefix="..."	adds a prefix string to the name while rendering the editor for a formfield
footer="..."	footer string to apped to the output	<empty string>
format="..."	format string to render each formfield with, more info below	$edit$mandatory
form="..."	topic name containing the DataForm definition	form found at the base topic
header="..."	header string to be put in front of the output	<empty string>
hidden="..."	those fields that match this regular expression will be rendered hidden	undefined
includeattr="..."	regular expression field attributes must match to be included in the output	undefined
include="..."	regular expression fieldnames must match to be included in the output	undefined
mandatory="..."	string to be inserted when a field is mandatory	**
map="<fieldname1>=<title1>, <fieldname2>=<title2>, ..."	allows to map a fieldname to a different title string in the edit interface	original fieldnames are used as title string
separator="..."	string to be put between each formatted output per formfield	<empty string>
sort="on/off"	sort values of multi-valued formfields	on
valueseparator="..."	string to be put between each allowed value as defined in the form schema	,
value="..."	value to be inserted into the edit interface; makes sense for single-field calls only	stored value in the base topic
<fieldname>_attributes="..." <fieldname>_default="..." <fieldname>_description="..." <fieldname>_format="..." <fieldname>_name="..." <fieldname>_size="..." <fieldname>_title="..." <fieldname>_type="..." <fieldname>_values="..."	these parameters allow to override the formfield properties as specified in the DataForm definition; for example a Teaser_type="text" , Teaser_size="30" will override a definition of a Teaser formfield that otherwise is a textarea of size 80x25; <fieldname>_values redefines the list of allowed values for that field	values as defined in the DataForm definition and the current topic
<fieldname>_value="..."	value to be inserted into the edit interface of the named field	looks for urlparam <fieldname>, defaults to stored value
<fieldname>_sort="..."	on/off/asc/desc/rev - sort allowed values before displaying them	as defined in the DataForm

RENDERFORDISPLAY

Parameter	Description	Default
"..." or topic="..."	name of a topic to display the form for	the base topic of the current url
revision="..."	topic revision to display
autolink="on/off"	enable/disable WikiWord autolinking when rendering a formfield; setting autolink sets the default for all fields specific settings of =<fieldname>_autolink=which can, that is you can disable autolinking globally and switch it back on per field	on
excludeattr="..."	regular expression field attributes must match to be excluded from the output	undefined
exclude="..."	regular expression fieldnames must match to be excluded from the output	undefined
fields="<fieldname1>, <fieldname2>, ..."	list of formfields to be displayed	all known formfields
footer="..."	footer string to apped to the output	<empty string>
format="..."	format string to render each formfield with, more info below	$edit$mandatory
form="..."	topic name containing the DataForm definition	form found at the base topic
header="..."	header string to be put in front of the output	<empty string>
hideempty="on/off"	hide empty formfields	off
includeattr="..."	regular expression field attributes must match to be included in the output	undefined
include="..."	regular expression fieldnames must match to be included in the output	undefined
labelformat="..."	format string used for labels exclusively; labels aren't real input fields; they are part of the form definition but carry read-only values only if at all	same as format
map="<fieldname1>=<title1>, <fieldname2>=<title2>, ..."	allows to map a fieldname to a different title string (deprecated: please use <fieldname>_title to redefine the title)	original fieldnames are used as title string
separator="..."	string to be put between each formatted output per formfield	<empty string>
sort="on/off"	sort values of multi-valued formfields	on
valueseparator="..."	string to be put between each allowed value as defined in the form schema	,
<fieldname>_attributes="..." <fieldname>_autolink="..." <fieldname>_default="..." <fieldname>_description="..." <fieldname>_format="..." <fieldname>_size="..." <fieldname>_sort="..." <fieldname>_title="..." <fieldname>_type="..." <fieldname>_value="..." <fieldname>_values="..."	see above	defaults as defined in the DataForm definition and the current topic

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

Author(s):	Foswiki:MichaelDaum
Copyright:	© 2009-2013 Michael Daum http://michaeldaumconsulting.com
License:	GPL (Gnu General Public License)
Release:	13 Jul 2013
Version:	v2.8.0
Change History:
13 Jul 2013:	added revision parameter to access non-top revisions; improved compatibility with foswiki-1.2.x
20 Mar 2013:	added <fieldname>_name to temporarily override the input field name
17 Oct 2012:	rationalized include and exclude; adding $mandatory to the default format
24 Feb 2012:	added $origvalues to display unmapped values of +values formfields; added prefix parameter; protecting the editor of a formfield by surrounding it with <literal> tags
25 Aug 2011:	fixed rendering +value formields yet again; added $origvalue
18 Mar 2011:	added autolink param; fixed getting default values; added global sort param; added fieldname_format param; protecting %MACROs in value attr of an input field
13 Aug 2010:	added fieldname_sort param to sort allowed field values before displaying them
10 Aug 2010:	added hideempty to RENDERFORDISPLAY
23 Jul 2010:	fixed rendering hidden fields when creating a new topic (Foswiki:Main/PasiHaekkinen)
22 Jul 2010:	fixed not try to load a non-existing form definition; providing fallback method for retrieving default values from form definition for those formfield types that can't do that by themselves; fixed expanding field title before the formfield does; fixed expanding standard escapes at the very end of the rendering process; added better default format for RENDERFOREDIT
07 Jun 2010:	added includeattr, excludeattr to filter formfields by their attributes
24 Mar 2010:	fixed error where topic values were not inserted into the edit form properly
12 Mar 2010:	cleaned up $value and $values variable in both RENDERFOREDIT and RENDERFORIDPLSAY; added $default
11 Mar 2010:	Foswiki:Main.MartinCleaver - added ability to extract allowed values of a field Foswiki:Tasks.Item8671
10 Mar 2010:	added fine-grained control over each formfield, i.e. remapping of the formfield type
08 Mar 2010:	initial release
Dependencies:	None
Home page:	Foswiki:Extensions/FlexFormPlugin
Support:	Foswiki:Support/FlexFormPlugin