Form Field List Plugin

Search, filter and format multiple data form fields from multiple topics.

This plugin offers more options than the predefined variable %FORMFIELD{"fieldname"}%.

This plugin uses Foswiki:Extensions/TopicDataHelperPlugin

Syntax Rules

• %FORMFIELDLIST{}% - default rendering of the fields of the current topic
• %FORMFIELDLIST{parameters}% - see list of parameters below

Topics to search

Parameter	Comment	Default value	Example
topic	Topic name to show form fields of. Possible values: • one topic • a comma-separated list of topic names • a wildcard * to search in all topics in the web; exclude topics using excludetopics	the current topic	topic="FormFieldListPlugin", topic="FormFieldListPlugin, WebHome", topic="*"
excludetopic	Comma-separated list of topic names to not show the form fields of	none	excludetopic="WebPreferences, WebHome"
web	Web name to show form fields of. Possible values: • one web • a comma-separated list of web names • a wildcard * to search in all webs; exclude topics using excludeweb	the current web	web="Extensions", web="Extensions, Main", web="*"
excludeweb	Comma-separated list of web names to not show the form fields of	none	web="*" excludeweb="System"

Topics to include/exclude

Parameter	Comment	Default value	Example
user	Comma-separated list of user names (that have changed the containing topic last) to be listed. To find topics where no user is specified, use UnknownUser.	none	user="ProjectContributor"
excludeuser	Comma-separated list of user names (that have changed the containing topic last) to not show.	none	excludeuser="ProjectContributor, AdminUser, WikiGuest, UnknownUser"
fromdate, todate	Date range filter: show topics between fromdate and todate (topic changed dates); dates are specified in format yyyy/mm/dd • fromdate="" todate="2007/09/01" selects all topics up to 1 Sep 2007 • fromdate="2007/12/01" todate="" selects all topics since 1 Dec 2007	no date filter	fromdate="2005/01/01" todate="2007/01/01"

Form fields to include/exclude

Parameter	Comment	Default value	Example
"" or field	The names of the form fields to show. If not specified, will retrieve all fields from the topic or topics.	The fields of the current topic.	%FORMFIELDLIST{"Author, Status"}% or %FORMFIELDLIST{field="Author, Status"}%
excludefield	The names of the form fields to exclude.	none	excludefield="Author"
includefieldpattern	Regular expression pattern to match field names to show. For example: the pattern ^[A-Z] will match fields which names start with an uppercase letter; pattern [0-9] will find fields that have a number in the name. Use prefix (?i) for case insensitivity.	none	includefieldpattern="^(?i)[A]"
excludefieldpattern	Regular expression pattern to match field names to hide.	none	excludefieldpattern="^(?i)[B]"
includevaluepattern	Regular expression pattern to match field values to show. For example: the pattern ^[A-Z] will match fields which values start with an uppercase letter; pattern [0-9] will find values that have a number. Use prefix (?i) for case insensitivity.	none	includevaluepattern="^(?i)[A]"
excludevaluepattern	Regular expression pattern to match field valus to hide.	none	excludevaluepattern="^(?i)[B]"
excludeemptyvalue	Set to on to skip fields that have no value set. Listed fields do exist. To add missing fields to your listing, use includemissingfields.	off	excludeemptyvalue="on"
includemissingfields	Set to on to add missing fields from topics. These will have an empty value, and may be substituted by param alttext. This is primarily useful if you want to achieve an even list of results.	off	includemissingfields="on"
limit	The maximum number of fields to display. Note that you should pass a multiple of the fields you are requesting: if you are requesting 2 form fields, the limit should be 2 or 4 or 6 and so on, otherwise the resulting text may be hard to understand.	no limit	limit="10"

Sort options

Parameter	Comment	Default value	Example
sort	Sorts the retrieved form fields on: name ($name) value ($value) containing topic ($topicName) date ($fieldDate) (when field has changed, this is checked against a cache) position in form definition ($fieldDefinition) topic date ($topicDate) user ($topicUser) The sort order can be specified with parameter sortorder.	$topicName	sort="$name"
sortorder	Lists sorted attachments: ascending or descending. The default sort order depends on the sort type: =descending=: default for $date (latest file first) =ascending=: default for $fieldName, $fieldValue and $topicName (alphabetically)	see left	sortorder="ascending"

Formatting parameters

Parameter	Comment	Default value	Example
format	Format string; use the format in the table below.	the plugin setting FORMAT (==)	format="   * $name=$value"
separator	String to separate formatted results.	none	separator=","
topicheader	String to separate grouped formatted results per topic.	none	topicheader="--- $topicName"
header	A header text in case of hits.	no header	header="All fields:"
footer	A footer text in case of hits.	no footer	footer="Number of fields: $fieldCount"
alttext	Alternative text if no field is found in the topic form. Can only be used with includemissingfields="on".	none	alttext="--field not found--"
default	Alternative text if no field value is set.	none	default="(Field $name not set)"
alt	Alternative text for the entire listing if nothing is found.	none	alt="No fields found"

Formatting variables

These variables can be used in the format tag:

Format variable	Comment
$title	Field name
$name	Field name
$value	Field value
$topicName	Containing topic name
$webName	Containing web name
$topicUser	Last editor of topic
$topicDate	Last edit date of topic
$fieldDate	Edit date of topic when field has been changed last (only set when param sort="$fieldDate" is used, otherwise the same as $topicDate)

These substitution variables can be used in the format, header and footer tags:

Format variable	Comment
$n or $n()	New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar
$nop or $nop()	Is a "no operation".
$quot	Double quote (")
$percnt	Percent sign (%)
$dollar	Dollar sign ($)
$br	<br /> tag

These variables can be used in the header and footer tags:

Format variable	Comment
$fieldCount	Number of listed fields

Sorting by field changed, not by topic changed

A short motivation:

At our intranet homepage we have a list of 'client news blurbs': news oneliners to give all a quick look on what work is going on for each client. These blurbs are part of the ClientForm, and are included on every client topic. Of course, when the topic gets updated, the news blurb would be bumped on the homepage as well, even though the news itself was not updated.

For these situations it is useful to sort the list of field values on date when the field has been updated. For this you may use the sort parameter $fieldDate.

When a list with sort="$fieldDate" is found, the plugin compares the form values with a cached version, and copies the change date of the cached version if the field value was not updated.

The list will only work correctly once the cache is there. The very first view creates the cache. Subsequent views compares to the cache.

Note that sorting on dates by default lists latest on top.

Example

This example finds - from all topics in Main web - all field names with the string 'name' in it. The fields of each topic are grouped by a table header.

%FORMFIELDLIST{
web="%MAINWEB%"
topic="*"
includefieldpattern="(?i)name"
limit="10"
default="<span class='foswikiGrayText'>not set<span>"
alt="No fields found"
topicheader="| *<nop>$topicName* ||"
format="| <nop>$name | $value |"
}%

Output (if installed):

not set

Plugin Settings

You can override the default settings for the plugin by defining the following preferences in SitePreferences.
Use the notation NAMEOFPLUGIN_NAMEOFSETTING, for example: FORMFIELDLISTPLUGIN_DEBUG

Preference	Meaning	Default
DEFAULT_FORMAT	Default format of rendering form field values	$value
DEBUG	If set to 1, writes debugging info to data/debug.txt	0

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.

Plugin Info

Authors:	TWiki:Main/BerndRaichle (2004), Foswiki:Main/ArthurClemens (2008, 2009)
Copyright ©:	TWiki:Main/BerndRaichle (2004), Foswiki:Main/ArthurClemens (2008, 2009)
Release:	2.2
Version:	10259 (2010-12-10)
Change History:
03 Aug 2010:	v.2.2 Paul Harvey: Item8392 added $fieldDefinition sort attribute to sort fields by their order of appearance in the DataForm definition
20 Jun 2009:	v.2.1 Arthur Clemens: ported to Foswiki. Changed FORMAT setting to DEFAULT_FORMAT.
25 Oct 2008:	v.2.010 Arthur Clemens: Added param includemissingfields to explicitly generate field substitutes.
24 Oct 2008:	v.2.000 Arthur Clemens: Major code refactoring with the addition of numerous parameters. Created unit tests.
01 Oct 2004:	Bernd Raichle: Initial version.
Dependencies:	Name Version Description Foswiki::Plugins::TopicDataHelperPlugin Required
Perl Version:	5.005
Plugin Home:	http://foswiki.org/Extensions/FormFieldListPlugin
Support:	http://foswiki.org/Support/FormFieldListPlugin