(r1) FlexFormPlugin < System

You are here: Foswiki>System Web>FlexFormPlugin~~EditAttach~~
---+!! %TOPIC%
Flexible way to render <nop>DataForms 

%TOC%

This plugin leverages the internal capabilities to render an interface for %SYSTEMWEB%.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 %<nop>RENDEFFOREDIT and %<nop>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_ %<nop>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 %<nop>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="&lt;fieldname1>, &lt;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 | &lt;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 | &lt;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 | <span class='foswikiAlert'>**</span> |
| map="&lt;fieldname1>=&lt;title1>, &lt;fieldname2>=&lt;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 | &lt;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 |
| &lt;fieldname>_attributes="..." %BR% \
  &lt;fieldname>_default="..." %BR% \
  &lt;fieldname>_description="..." %BR% \
  &lt;fieldname>_format="..." %BR% \
  &lt;fieldname>_name="..." %BR% \
  &lt;fieldname>_size="..." %BR% \
  &lt;fieldname>_title="..." %BR% \
  &lt;fieldname>_type="..." %BR% \
  &lt;fieldname>_values="..." %BR% \
  | 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=; &lt;fieldname>_values redefines the list of allowed values for that field | values as defined in the !DataForm definition and the current topic |
| &lt;fieldname>_value="..." | value to be inserted into the edit interface of the named field | looks for urlparam &lt;fieldname>, defaults to stored value |
| &lt;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 =&lt;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="&lt;fieldname1>, &lt;fieldname2>, ..." | list of formfields to be displayed | all known formfields |
| footer="..." | footer string to apped to the output | &lt;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 | &lt;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="&lt;fieldname1>=&lt;title1>, &lt;fieldname2>=&lt;title2>, ..." | allows to map a fieldname to a different title string (*deprecated*: please use &lt;fieldname>_title to redefine the title) | original fieldnames are used as title string |
| separator="..." | string to be put between each formatted output per formfield | &lt;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 | , |
| &lt;fieldname>_attributes="..." %BR% \
  &lt;fieldname>_autolink="..." %BR% \
  &lt;fieldname>_default="..." %BR% \
  &lt;fieldname>_description="..." %BR% \
  &lt;fieldname>_format="..." %BR% \
  &lt;fieldname>_size="..." %BR% \
  &lt;fieldname>_sort="..." %BR% \
  &lt;fieldname>_title="..." %BR% \
  &lt;fieldname>_type="..." %BR% \
  &lt;fieldname>_value="..." %BR% \
  &lt;fieldname>_values="..." %BR% \
  | 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

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

%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

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

---++ 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

<!--
   * Set SHORTDESCRIPTION = Flexible way to render <nop>DataForms
-->

|  Author(s): | Foswiki:MichaelDaum|
|  Copyright: | &copy; 2009-2013 Michael Daum http://michaeldaumconsulting.com |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Release: | 13 Jul 2013 |
|  Version: | v2.8.0 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  13 Jul 2013: | added =revision= parameter to access non-top revisions; \
                  improved compatibility with foswiki-1.2.x |
|  20 Mar 2013: | added =&lt;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 &lt;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/%TOPIC% |
|  Support: | Foswiki:Support/%TOPIC% |

<!-- Do _not_ attempt to edit this topic; it is auto-generated. -->
Topic revision: r1 - 23 Dec 2012, UnknownUser
System
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback