MoreFormfieldsPlugin

Additional formfield types for DataForms

Description

This plugin implements a set of additional special purpose formfields to be used in DataForm definitions.

To make use of these formfields use their type identifier in the Type column of a DataForm definition, such as in

Name	Type	Size	Values	Description	Attributes
Attachment	attachment	20
Bytes	bytes	10
Date2	date2	30
Icon	icon	20
Ipaddress	ipaddress	15		network address
Ipv6address	ipv6address	40		network address
Macaddress	macaddress	17		hardware-addresse
Netmask	netmask	15		netmask
Phonenumber	phonenumber	20
Select2	select2	20
Time	time	20
Topic	topic	20
User	user	20
Group	group	20
User Or Group	userorgroup	20

When defining a formfield additional parameters may be used in the Values column to further customize the behavior of the element.

Known Formfield types

autoinc

This is a formfield type that extens Foswiki's core AUTOINC mechanism to enumerate topics when they are created and brings it to formfields. A unique number is assigned to autoinc formfields whenever a topic is created will having such a DataForm attached to it. Provisions are taken that these numbers are unique among each other. This feature allow to define number ranges based on the given configuration.

A typical use case would be to have different number ranges based on another formfield, say ProjectType:

Name	Type	Size	Values	Description	Attributes
Type	radio	3	new product, experimental, enhancement	specifies the kind of project that is carried out	M
Number	autoinc	5	start="1000" query="Type='$Type'"	unique project number	h

Whenever a topic with such a DataForm definition is used will the Number property be calculated given the start and query parameters. That is, a unique number will be assigned for each type of project "new product", "experimental" and "enhancement". All "new product" projects receive unique numbers among each other, likewise all "experimental" projects and "enhancement" projects.

Numbering starts at the value given to the start parameter, 1000 in above example. The size column of an autoinc formfield specifies the number of digits the number should have similar to the id formfield. By default numbering starts at zero.

By default, number ranges are specified among topics using the same DataForm by means of a "base query" that filters for topics of the same kind. This list is then subdivided by the given query. If for some reason you'd like to implement number ranges among different DataForms you can disable this base query using the parameter basequery="off". Not however that you should definitely define a more elaborate query to prevent unexpected numbering among other content in the same web (see QuerySearch.)

autofill

A formfield that is filled automatically based on values from one or more other formfields of the same topic. During an edit-save loop, values of fields listed in the source parameter are extracted and concatenated using the specified separator. Values of an autofill formfield cannot be edited by the user.

Parameters:

Either use this approach:

• format: specify a format string to build up the autofill formfield; use $<field-name> to reference a formfield (see example below)

… or do it the old way by looping over formfields:

• header: add an optional string prefixed to the field value, but only when the source fields are not empty
• fields: comma-separated list of one or more formfields to fetch values from
• separator: separator used when concatenating all values into a new value for the autofill field
• footer: append an optional string to the field value, but only when the source fields are not empty

A typical use-case for an autofill field is the construction of a TopicTitle based on other form properties:

Name	Type	Size	Values	Description	Attributes
TopicTitle1	autofill	1	header="Project" fields="Customer, ID, Year"
TopicTitle2	autofill	1	format="Project-$ID ($Customer, $Year)"
Customer	text	80
ID	id	4
Year	text	4

bytes

This formfield displays a numeric value in a "humanized" bytes notation, using magnitutes of two: B, KB, MB, GB, TB, PB, EB and ZB.

Example:

Name	Type	Size	Values	Description	Attributes
File Size	bytes	10	max="MB" prec="4"

The FileSize formfield will display the value using a maximum magnitude of megabytes using a precision of 4.

For instance a value of 2033189908 will be displayed as 1939.0010 MB given the parameters in above example definition. Without any parameters this value value would be displayed using the simples way, 1.89 GB in this case.

date2

This is an alternative for the core date formfield type using the jQuery-ui datepicker widget instead of using the Mishoo JSCalendar widget. It will launch a calendar when clicking into a date2 formfield to select a date from, as well as restricts allowed keys to be entered into the formfield. The format of a date2 formfield value will always be of a YYYY-MM-DD pattern and thus not be depending on any locale settings. This is quite important to get consistant data rather than differences based on the user's current browser language. While the value stored into a date2 formfield is locale-independent will it display according to the settings of $Foswiki::cfg{DefaultDateFormat} settings.

icon

A select box to chose an icon supported by Foswiki (famfamfam and fontawesome).

Parameters:

• cat: list of icon categories to be included in the selection
• include: regular expression of icons to include in the selection
• exclude: regular expression of icons to be excluded from the selection

An icon category can be either a topic on the icon search path as defined in $Foswiki::cfg{JQueryPlugin}{IconSearchPath}:

• famfamfam … to select famfamfam icons only
• silkicons … to selec from a silk icon only,
• flagicons … to select a flag
• …

Or an icon category as defined in the fontawesome definition:

• Brand Icons
• Chart Icons
• Currency Icons
• Directional Icons
• File Type Icons
• Form Control Icons
• Medical Icons
• Payment Icons
• Spinner Icons
• Text Editor Icons
• Video Player Icons
• Web Application Icons

Examples:

Name	Type	Size	Values	Description	Attributes	Default
FamFamFamIcon	icon	20	cat="famfamfam"
SilkIcon	icon	20	cat="silkicon"
MintIcon	icon	20	cat="minticons"
FlagIcon	icon	20	cat="flagicons"
WebApp	icon	20	cat="Web App"

id

Extract the numeric identifier from the topic name. This is most usefull for topics created using the AUTOINC feature (see TemplateTopics). The AUTOINC feature adds a numeric unique identifier when the topic is created. This identifier can be extracted using an id formfield type and stored into a DataForm and be available for formatted searches.

The value in the Size column will be used to add leading zeros to the id. For example, given a topic FooBar1 has a DataForm

Name	Type	Size	Values	Description	Attributes
ID	id	4

Then upon save the id formfield will have a value of 0001.

Parameters: none

ipaddress

A general purpose IPv4 address, consisting of 4 octets, e.g. 10.0.0.1

Parameters: none

ipv6address

A general purpose IPv6 address,e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7348

Parameters: none

macaddress

A hardware address given in 6 hex values, e.g. 00:1a:10:6f:ba:12

Parameters: none

natedit

This renders a textarea using the NatEditPlugin. The size of the imput fields is specified similar to the standard textarea formfield type. Any additional parameters specific to natedit may be specified in the "Values" column.

netmask

A special IP address used for routing, consisting of 4 octets, e.g. 255.255.255.0

phonenumber

A standard telephone number. This formfield uses JQueryValidate to make sure the formfield value is a valid phone number.

Parameters: none

select2

A drop-in replacement for the standard select formfield. See JQSelect2Contrib.

Parameters: none

smartbox

A somewhat "smarter" checkbox formfield type. It allows to select one of the values as a placeholder representing "any" value in the selection.

So given this DataForm definition …

Name	Type	Size	Values	Description	Attributes	Default
Business Area	smartbox	5	Energy, Maritime, Oil & Gas, Software, Across all Business Areas*

… then selecting "Accross all Business Areas" will select all other areas with it. Likewise, selecting all business areas indivudually will automatically select "Accross all Business Areas" as well.

Note that the "any value" selection is the one indicated by the "*" asterisk, or if not present the first in the list.

time

A time formfield using the clockpicker widget from http://weareoutman.github.io/clockpicker/

topic

A topic reference using JQSelect2Contrib for autocompletion.

Parameters:

• web: the web the user can choose topics from; defaults to current web
• default: the default value to use if no value exists yet
• url: url for autocompletion, default: %SCRIPTURL{"rest"}%/RenderPlugin/template?expand=select2::topic;contenttype=application/json
• TopicType: name of a TopicType to be selected
• include: regular expression topics must match to be included in the selection
• exclude: regular expression topics must not match to be included

Custom parameters may be added. These will be appended to the autocompletion url.

There are a couple of parameters that further customize the behavior of the select2 widget. Some of the most useful ones are:

• minimumInputLength: number of characters that have to be entered before the autocompletion url is called to fetch matching selections from the backend; default 0
• quietMillis: number of milliseconds to wait for input before the backend is called for autocompletion
• limit: maximum number of values fetched from the autocompletion backend, default 10

These are also available for the user and icon formfield types.

user

A user reference using JQSelect2Contrib for autocompletion.

Parameters:

• url: url for autocompletion, default: %SCRIPTURL{"rest"}%/MoreFormfieldsPlugin/users
• group: groups that users must be a member of to be included in the selection
• include: regular expression a user must match to be included in the selection
• exclude: regular expression a user must not match to be included

group

A group reference using JQSelect2Contrib for autocompletion.

Parameters:

• url: url for autocompletion, default: %SCRIPTURL{"rest"}%/MoreFormfieldsPlugin/users
• include: regular expression a group must match to be included in the selection
• exclude: regular expression a group must not match to be included

userorgroup

This formfield type combines user and group formfields providing the same parameters.

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::Plugins::DBCachePlugin	>=9.00	Required
Foswiki::Plugins::JQueryPlugin	>=9.00	Required
Foswiki::Plugins::RenderPlugin	>=4.00	Required
Foswiki::Plugins::TopicInteractionPlugin	>=6.00	Required
Foswiki::Plugins::ImagePlugin	>=8.00	Required
Foswiki::Contrib::JQSelect2Contrib	>1.00	Required
JSON	>=2.59	Required
Scalar::Util	>=0	Required
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required for Foswiki < 2.2

Change History

10 Jan 2019:	new formfields group and userorgroup; added include and exclude params to topic formfield; added group, include and exclude params to user formfield; multiple improvements to date2 formfield, i.e. convert format strings to jQuery ui; using core's datetime parser now instead of a local one, which in turn brings in DateManipPlugin's capabilities if installed; make use of JQueryPlugin's new icon service for the icon formfield; added protocol param to phonenumber formfield which was hard-coded to sip before; added saveMetaDataHandler integrating into MetaDataPlugin
23 Nov 2018:	added new formfields group and userorgroup
28 May 2018:	new formfields bytes and autoinc
12 Jan 2018:	fixed thumbnails in topic, user and attachment formfields
13 Sep 2017:	added attachment formfield
27 Jan 2017:	render empty date2 formfields as an empty string, not 01 Jan 1970
25 Jan 2017:	fixed topic formfield to properly store web dot topic values
16 Jan 2017:	replace MoreFormfieldsAjaxHelper with a template solution to be able to override it when required; fixes in id and autofill formfields; defaulting to YYYY/MM/DD in date2 formfield now to prevent browsers from interpreting date formfields using their own idea of locales; added an afterSaveHandler for formfield classes; add register of latest fontawesome icons for the icon formfield
29 Jun 2016:	replaced MoreformfieldAjaxHelper topic with a template approach for higher flexibility
31 May 2016:	added formfield types date2, ipv6address and natedit; removed dependency on YAML; added a format parameter to the autofill formfield type; added beforeSaveHandlers to network address formfield types to normalize their store format on save
01 Mar 2016:	fixed select2 in jquery-ui modal not allowing focus
09 Jan 2016:	added ipv6, fixed validation of all network addresses by properly integrating it into jquery.validate
09 Apr 2015:	documentation; final bugfixing before release; updated to latest clockpicker
26 Mar 2015:	updated list of all fontawesom icons; fixed rendering of Topic formfields values
16 Dec 2014:	fixed thumbnails in user autocompletion; don't inherit from ListFieldDefinition for performance reasons
22 Aug 2014:	added smarbox formfield
04 Apr 2014:	fixed compatibility with foswiki >= 1.2.0
23 Sep 2010:	initial release