FlexFormPlugin

Flexible way to render DataForms

This plugin leverages the internal capabilities to render an interface for DataForms and adds insights to the acutal DataForm definition itself as used internally. This API is part of the Foswiki::Form and Foswiki:Form::FieldDefinition classes of Foswiki now available when writing 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 https://foswiki.org/Development/MacroForRetrievingFieldDefaultValues for background.

While %RENDERFOREDIT% and %%RENDERFORDISPLAY render forms for the net data using a DataForm the %RENDERFORMDEF= macro renders information about the DataForm definition itself identpendent of any topic actually using it. This may be used to provide more defailed insights into the DataForm definition.

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
type="div/table/grid"	specify the layout to be used in case no format is specified manually (using header,format,separator and footer parameters); grid is only available when Foswiki:Extensions/GridLayoutPlugin is installed	div
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
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
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>
type="div/table/grid"	specify the layout to be used in case no format is specified manually (using header,format,separator and footer parameters); grid is only available when Foswiki:Extensions/GridLayoutPlugin is installed	table
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 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

RENDERFORMDEF

Parameter	Description	Default
"..." or form="..."	the topic holding the DataForm definition	current topic
field="..." or fields="..."	a comma separated list of fields to render information about	all fields
include="..."	regular expression a field name must match to be listed
includeattr="..."	regular expression field attributes must match to be included in the output	undefined
exclude="..."	regular expression a field name must not match to be listed
excludeattr="..."	regular expression field attributes must match to be excluded from the output	undefined
header	header string prepended to the result
format	format string for each field to be rendered in the result
separator	separator between lines when field information is rendered
footer	footer string appended to the result

The format parameter may contain the following variables:

• $name: field name
• $title: field title
• $type: field type
• $size: field size
• $attributes: field attributes
• $description: field description
• $definingtopic: topic where allowed values are defined
• $defaultvalue: default value as specified in the defaults column
• $value: value as specified in the values column, or the default value

Note that the actual results may vary depending on the formfield type of the DataForm.

Form layouts

There are three layouts that are supported by %RENDERFORDISPLAY and %RENDERFOREDIT that may be specified using the type="..." parameter:

• table
• div
• grid (only supported if GridLayoutPlugin is installed)

All of them have different advantages. A table layout aligns rows and columns nicely while using screen space quite economical. However tables don't behave responsive on mobile devices. A div based layout stacks formfields and their header from top to down thus using more screen space for the benefit of being well readable on mobile devices as well. The grid layout covers a middle ground between both: it looks like table layout on wide screens but will collaps columns into a stack as form elements fit better vertically than horizontal on mobile devices.

Examples

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

%RENDERFOREDIT{ form="Main.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. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::MultiLingualPlugin	>=3.00	Optional

Change History

12 Nov 2019:	normalize web parameter before caching topic objects
04 Jul 2018:	added type parameter to RENDERFORDISPLAY and RENDERFOREDIT
30 Aug 2016:	added includeattr, excludeattr to RENDERFORMDEF
02 Sep 2016:	improved support to translate formfields using Foswiki:Extensions.MultiLingualPlugin
08 Mar 2016:	clean up formfield title before trying to translate it; added hideempty for RENDERFOREDIT
17 Jul 2015:	fixed use of param() in list context
24 Mar 2015:	working around encoding problems with CGI >= 4.11
12 Mar 2015:	restructured code to offer a proper perl api
16 Dec 2014:	added $defaultvalue variable; catch exceptions reading a form definition not to propagate up to the page level; by default hide rows marked as hidden; read formfield description either from the tooltip or description property
29 Sep 2014:	improved cross-engine compatibility displaying formfield values
28 Aug 2014:	added new feature %RENDERFORMDEF
03 Mar 2014:	work around different styles of inconsistencies in renderForDisplay across foswiki core releases
07 Nov 2013:	properly render checkbox+buttons formfields
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