TIP FormFieldListPlugin is not installed on Foswiki.org.

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

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:
NameVersionDescription
Foswiki::Plugins::TopicDataHelperPluginRequired
Perl Version: 5.005
Plugin Home: http://foswiki.org/Extensions/FormFieldListPlugin
Support: http://foswiki.org/Support/FormFieldListPlugin
Topic revision: r4 - 22 Dec 2012, GauravRishi - This page was cached on 30 Jun 2016 - 11:38.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License