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.
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 |
Parameter![]() |
Description | Default |
---|---|---|
"..." or topic="..." | name of a topic to display the form for | the base topic of the current url |
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 |
exclude="..." | regular expression fieldnames must match to be excluded from the output | undefined |
excludeattr="..." | regular expression field attributes 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> |
form="..." | topic name containing the DataForm definition | form found at the base topic |
format="..." | format string to render each formfield with, more info below | $edit$mandatory |
header="..." | header string to be put in front of the output | <empty string> |
hideempty="on/off" | hide empty formfields | off |
include="..." | regular expression fieldnames must match to be included in the output | undefined |
includeattr="..." | regular expression field attributes 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 |
<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 |
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 |
revision="..." | topic revision to display | |
separator="..." | string to be put between each formatted output per formfield | <empty string> |
sort="on/off" | sort values of multi-valued formfields | on |
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 |
valueseparator="..." | string to be put between each allowed value as defined in the form schema | , |
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
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 |
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
%RENDERFORDISPLAY
and %RENDERFOREDIT
that may be specified using the type="..."
parameter:
table
div
grid
(only supported if GridLayoutPlugin is installed)
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.
%RENDERFOREDIT{ form="%USERSWEB%.UserForm" topic="Sandbox.TestTopic1" exclude="Email|Comment|State" FirstName_value="Horst" LastName_value="Buchholz" map="VoIP=Skype" }%
%RENDERFORDISPLAY{ form="ValueTransactionForm" field="FromRole" format="allowed values for $title are $values, default is '$default'" }%
cd /path/to/foswiki perl tools/extension_installer <NameOfExtension> installIf 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.
Name | Version | Description |
---|---|---|
Foswiki::Plugins::MultiLingualPlugin | >=3.00 | Optional |
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 |