FlexFormPlugin

Flexible way to render DataForms

Description

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.

%DISPLAYFIELD% is supposed to be a shortcut for %RENDERFORDISPLAY% for a single formfield, similar to %FORMFIELD%. Contrary to %FORMFIELD% it renders a proper display value based on the type of the formfield, whereas %FORMFIELD% returns the raw data as stored in the topic.

Similarly, %EDITFIELD% is a shortcut for % rendering an editor for a single field.

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="..." or rev="..."	topic revision which to use the data from while populating the edit form	"rev" url parameter
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
ignoreerror="on/off"	ignore any inline error	off
includeattr="..."	regular expression field attributes must match to be included in the output	undefined
excludeattr="..."	regular expression field attributes must match to be excluded from the output	undefined
include="..."	regular expression fieldnames must match to be included in the output	undefined
exclude="..."	regular expression fieldnames must match to be excluded from 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="..." <fieldname>_params="..." <fieldname>_definition="..."	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; <fieldname>_definition redefinies a value defining topic	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="..." or rev="..."	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
editable="on/off"	enable/disable inline editing, given the current user has got access rights on the target topic	off
editicon="..."	font-awesome class of the icon displayed when hovering over an inline editor	fa-pencil
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
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
ignoreerror="on/off"	ignore any inline error	off
includeattr="..."	regular expression field attributes must match to be included in the output	undefined
excludeattr="..."	regular expression field attributes must match to be excluded from the output	undefined
includevalue="..."	regular expression field value must match to be included in the output	undefined
excludevalue="..."	regular expression field value must match to be excluded in the output	undefined
include="..."	regular expression fieldnames must match to be included in the output	undefined
exclude="..."	regular expression fieldnames must match to be excluded from the output	undefined
limit="..."	specifies the maximum number of formfields to be included in the output
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="..." <fieldname>_params="..."	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
• $inlineEditor: expands to =inlineEditor if the current user has got access rights on the target topic
• $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

DISPLAYFIELD

Parameter	Description	Default
"..." or field="..."	name of the field to display
topic="..."	topic to display the field for	current topic
form="..."	topic name containing the DataForm definition	form found at topic
default="..."	default value if the field isn't defined	empty string
editable="on/off"	enable/disable inline editing	off
format="..."	format for the field (see RENDERFORDISPLAY)	$value
revision="..." or rev="..."	topic revision to display

EDITFIELD

Parameter	Description	Default
"..." or field="..."	name of the field to render an editor for
topic="..."	topic to render the editor for	current topic
form="..."	topic name containing the DataForm definition	form found at topic
default="..."	default value if the field isn't defined	empty string
format="..."	format for the field (see RENDERFOREDIT)	$edit
revision="..." or rev="..."	topic revision to display

RENDERFORMDEF

Parameter	Description	Default
"..." or form="..."	the topic holding the DataForm definition	current topic
topic="..."	the topic with a DataForm attached to it	current topic
field="..." or fields="..."	a comma separated list of fields to render information about	all fields
ignoreerror="on/off"	ignore any inline error	off
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
includetype="..."	regular expression field type 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
excludetype="..."	regular expression field type must match to be excluded from the output	undefined
header	header string prepended to the result
sort="on/off"	sort formfields by title; by default they are processed in the order given by the DataForm definition	off
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.

Inline editor

The %RENDERFORDISPLAY macro allows to activate inline editing of individual formfields using the editable switch given the current user has got change access rights. The inline editor is activated by clicking on the edit icon being displayed while hovering over a formfield being rendered, or by double-clicking it. This will swap in the formfield's editor. Once finished the formfield view will be rendered again.

Technically speaking, an edit widget for the formfield will be fetched from a jsonrpc template backend (using RenderPlugin) thus bringing in not only the required html markup but also any js and css to properly intialize the editor. The actuall rendering process is performed by the inlineedit.tmpl template using a %RENDERFOREDIT. Once the edit has been finished, the original view is reestablished likewise. Note that an edit lock is acquired and released the same way a normal non-inline edit would do.

Inline editing will be enabled automatically per formfield unless output is customized using the header, footer, separator and format parameters. There are a few things to consider to bring in inline editing to a custom output. The following example illustrates the required markup to provide the required hints to the inline editor:

%RENDERFORDISPLAY{
  editable="on"
  header="<table class='inlineEditor'>"
  format="<tr>
            <th>$title:</th>
            <td class='inlineEditValue' data-formfield='$name'>$value $editicon</td>
          </tr>"
  separator="$n"
  footer="</table>"
}%

1. the inline editor is activated on the container elemenent using the inlineEditor css class
2. the container of the actual formfield value must be identified using the inlineEditvalue css class
3. the formfield container requires an HTML5 data property data-formfield holding the name of the formfield to be editable
4. an $editicon variable indicates the position where the edit icon is supposed to be located

Note that multiple instances of %RENDERFORDISPLAY can be covered by a single inline editor:

<div class='foswikiPageForm inlineEditor'>
...
%RENDERFORDISPLAY{
  editable="on"
  topic="JohnDoe"
  fields="FirstName, MiddleName, LastName"
  header="<table>"
  format="<tr>
            <th>$title:</th>
            <td class='inlineEditValue' data-formfield='$name' data-topic='$web.$topic'>$value $editicon</td>
          </tr>"
  separator="$n"
  footer="</table>"
}%
...
%RENDERFORDISPLAY{
  editable="on"
  topic="JohnDoesAddress"
  fields="Address, PostalCode, Cirty, Country"
  header="<table>"
  format="<tr>
            <th>$title:</th>
            <td class='inlineEditValue' data-formfield='$name' data-topic='$web.$topic'>$value $editicon</td>
          </tr>"
  separator="$n"
  footer="</table>"
}%
...
</div>

This also illustrates how to edit formfields of different topics in one inline editor interface.

1. the macro uses a topic="..." parameter
2. the formfield value container has got an extra HTML5 property data-topic to provide the actual target topic being edited

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. "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::Contrib::JQAjaxFormContrib	>=1.20	Required
Foswiki::Plugins::MoreFormfieldsPlugin	>=8.00	Optional
Foswiki::Plugins::MultiLingualPlugin	>=3.00	Optional
Foswiki::Plugins::RenderPlugin	>=7.00	Required

Change History

22 Jan 2024:	added EDITFIELD; added _definition to RENDERFOREDIT; added _params as a synonym for _values as this column is used form formfield parameters more often than for listing allowed values; rationalized the way format strings are collected and defaulted; read rev url parameter by default; added limit parameter for RENDERFORDISPLAY
29 Apr 2022:	added includevalue and excludevalue to RENDERFORDISPLAY
22 Feb 2022:	added inline editor feature to RENDERFORDISPLAY
25 Jan 2022:	fixed $description in RENDERFORMDEF
25 Aug 2021:	added DISPLAYFIELD
27 Oct 2020:	render tml from formfields properly
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