MetaDataPlugin

Bring custom meta data to wiki apps

This plugin allows to store data sets to Foswiki topics. Foswiki itself is a structured wiki already using DataForms which are attached a topic. This in essence makes each topic a database record. MetaDataPlugin goes one step further by making each Foswiki topic a full database. That way each topic can serve as a container for multiple data records, even of different kind.

Technically, MetaDataPlugin combines technologies in a new way that are already part of Foswiki:

1. MetaData types are defined using DataForms (like normal forms).
2. MetaData types are registered to the Foswiki store using Foswiki::Meta::registerMETA()
3. Records are stored as %META:MYDATA{...}% hashes.
4. Records are rendered using the renderForEdit() and renderForDisplay() API of Foswiki::Form leveraged to wiki application programming similar to Foswiki:Extensions/FlexFormPlugin

In short: MetaDataPlugin marries DataForms with custom %META data.

MetaDataPlugin comes with an example UI to list records and make them editable. See the TimeTracker application for example.

Below screenshot 3 shows an integration with Foswiki:Extensions/HolidaylistPlugin and Foswiki:Extensions/ICalPlugin to render a ical driven resource view where all events are stored in %META:EVENT{}% records.

Note: this plugin requires a Foswiki engine >= 1.1.0.

Screenshots

Syntax

%RENDERMETADATA{...}%

This macro allows to access MetaData records attached to a topic. It can operate in two modes - view and edit - to either display records or render an editor for one specific record. By default RENDERMETADATA will list all records found as a table. Rows of the table can be clicked to edit the related editor. A modal dialog opens with an appropriate edit interface based on the DataForm definition, similar to the interface when editing a DataForm as part of a normal topic edit screen.

Parameter	Description	Default
"..."	key of the MetaData type to be rendered; this name is derived from the topic name holding the DataForm definition (see below)
name	name of one MetaData record to be rendered; special name is id to render a form for a new MetaData record to be created
action	indicates the action to perform on the records, can be edit or view	view
anchor	anchor string appended to action urls
field(s)	list of formfields to render the interface for	all known formfields of a DataForm
name	select the id of a MetaData record to be extracted	all records attached to the given topic
topic	the topic to extract the MetaData from	the current topic
web	the web part of the topic to be processed; note: a web part in the topic parameter will override any value specified via the web parameter	the current web
format	format string to render each meta-data record with, more info below
header	header string to be put in front of the output
footer	footer string to apped to the output
separator	string to be put between each formatted output per formfield
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
edittitle	title of the modal dialog when editing a metadata record
valueseparator
include	a comma separated list of record names to be included in the output, e.g. "id1, id2, id5"
exclude	a comma separated list of record names to be excluded from the output
includeattr	regular expression field attributes part of the DataForm definition must match to be included in the output
excludeattr	regular expression field attributes part of the DataForm definition must match to be excluded from the output
filter	a filter expression that records must match to be displayed. this overrides the include and exclude parameters. note that the given filter will be used to perform a query search by constructing a query of the form 'topic'/key[filter].name' where 'topic' is the topic containing the meta data records, key is the name of the meta data. example: filter="FirstName='Raffael' or FirstName='Judith'"
sort	name of attribute used for sorting, or "random" for randomized ordering	name
reverse	boolean flag to reverse the sorting order	off
mandatory	string to be inserted when a field is mandatory	**
hiddenformat	format string to be used to render hidden formfields
hideempty	boolean flag to hide/show empty formfields; note this only works in "single mode" that is when a name param was specified	off
hidden	list of fields that are rendered hidden
warn	boolean flag to suppress error messages	on
enabledactions	list of enabled actions for a record	edit,delete,move,duplicate
navigation	boolean flag to enable/disable navigation between metadata records in the edit dialog	on
autolink	boolean flag to enable/disable WikiWord linking	on
fieldformat	format string for a single formfield value in a row	$value
fieldheader	header string prepended to the fieldformat result
fieldfooter	footer string appended to the fieldformat result
<field_name>_attributes, <field_name>_autolink, <field_name>_default, <field_name>_description, <field_name>_format, <field_name>_hidden, <field_name>_size, <field_name>_title, <field_name>_tooltip, <field_name>_type, <field_name>_value, <field_name>_values	these parameters allow to override properties of a record as specified in the DataForm definition temporarily, or specify field-specific rendering parameters while iterating over all MetaData

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:

• $actions: edit actions per row; these are normally appended to each row to display the pencil and trashcan icons while hovering over the row
• $attrs: attribute string as given in the DataForm definition
• $count: total number of records rendered
• $default: this is the default value if no value is specified in the topic itself
• $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
• $form: topic of the DataForm definition for the MetaData being rendered
• $index: running index while iterating over all MetaData records
• $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
• $metadata: key of the MetaData used interally
• $name: the original fieldname
• $origvalues: list of all allowed values; for +value formfields this is the original unmapped value of the formfield
• $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
• $type: type of formfield as given in the DataForm definition
• $values: list of all allowed values for the formfield as defined in the DataForm definition
• $<field_name>: value of the given field
• $orig<field_name>: original value of the formfield as stored; for +value formfields this is the original unmapped value of the formfield
• $value: (in <field_name>_format) current value of the formfield; for +value formfields this is the mapped value use $origvalue to get the original one
• $origvalue: (in <field_name>_format) original value of the formfield as stored
• $islocked: boolean flag expanding to '1' when the current topic is locked, is '0' otherwise
• $lockedby: expands to the WikiName of the user currently editing this topic, or the empty string when nobody is editing the topic holding the metadata

%NEWMETADATA{...}%

This macro is used to render a button to start the "Add record" dialog. It takes a known MetaData key and a display title and will render a modal edit dialog according to the associated DataForm definition.

Parameter	Description	Default
"..."	MetaData key
topic	the location where to store the newly created records
format	format string to render the button	defined in the metadataplugin.tmpl template
template	name of the TMPL:DEF to render the button	metadata::new
title	display title for the modal dialog
buttontitle	display title for the button (default is title)
hideempty	boolean flag to hide/show empty formfields	off
icon	name of a famfamfam icon to be used on the button	add

Registering MetaData

Foswiki's store has got the ability to register additional MetaData definitions. The store will then take care that data passed to it is valid and well defined according to the MetaData definitions available. While the Foswiki core already knows about its native MetaData, like %META:PREFERENCE, %META:ATTACHMENT, %META:FIELD and %META:FORM, all additional custom definitions have to be registered early in the process. This is done using the WEBMETADATA preference setting, similar in use to the WEBFORMS preference settings to register plain old DataForms to be attached to topics.

Only MetaData registered using WEBMETADATA may be processed any further.

Example:

   * Set WEBMETADATA = Applications.ProjectApp.InvoiceForm, 
                       Applications.ProjectApp.EffortForm, 
                       Applications.MovieApp.Role, 
                       Applications.CalendarApp.EventTopic

WEBMETADATA is a list of topics holding the DataForm definition to be registered as MetaData to the store. While doing so each DataForm definition is associated with a key to be used storing a record in a topic. This key is then used to store data in the form %META:<key>{...}%.

In the above example MetaDataPlugin will register MetaData to store:

• %META:INVOICE,
• %META:EFFORT,
• %META:ROLE and
• %META:EVENT records.

A MetaData key is derived from the DataForm definition by stripping off any "Topic" and "Form" suffix and translating the remaining name to uppercase. The resulting key is also available using an all-lowercase alias, that is invoice, effort, role and event in the above example.

Examples

To illustrate the use of MetaData, an example wiki application is shipped with MetaDataPlugin. The TimeTracker application may be used to track working efforts and compute resulting earnings based on standard rates and taxes. The application allows to create new TimeTracker topics which have a database of efforts recorded on that tracker.

• TimeTracker: this is the starting point of the application; and defines the DataForm for each TimeTracker topic
• EffortForm: this is a DataForm definition for effort MetaData
• TimeTrackerTemplate: this is a minimal template topic that basically makes sure the WEBMETADATA is set properly (note: that this is not recommended way to go in production environments; set the WEBMETADATA preference either in the WebPreferences or SitePreferences instead)
• TimeTrackerEditTemplate: this is the edit template to edit TimeTracker topics
• TimeTrackerViewTemplate: this is the view template to view a TimeTracker topic and all tracked efforts for it.

Note: to run this application, you'll need:

• Foswiki:Extensions/JQGridPlugin
• Foswiki:Extensions/FlexFormPlugin
• Foswiki:Extensions/JsonRpcContrib

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	>=2.1	Requires version 2.0 of handler API.
Foswiki::Plugins::JQueryPlugin	>=4.10	Required.
Foswiki::Contrib::JsonRpcContrib	>=1.21	Required.
Foswiki::Plugins::JQDataTablesPlugin	>=3.0	Optional
Foswiki::Plugins::FlexFormPlugin	>=2.5	Optional
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required for Foswiki < 2.2

Change History

30 Jan 2019:	added solr index handler to make individual meta data searchable; fixed hideempty parameter; added parameters anchor, enabledactions, fieldheader, fieldfooter, hidden, limit, skip and navigation; added random sorting; now depend on TopicTitlePlugin removing redundant local TopicTitle implementation; added prev-next navigation among metadata records; improved localization; make metadata.js a valid jQuery module, properly separating view and edit code
16 Jan 2017:	added showindex, hidden options to %RENDERMETADATA; added a "single record" mode to render one specific meta data record; better integration with SocialFormfieldsPlugin; fixed sorting of meta data records; improved default markup for meta data tables
16 Dec 2014:	don't cache web.topic in plugin initializer; fixed call to CGI::param()
20 May 2014:	reworked delete; implemented save handlers for meta data; fixed table markup to pleae Foswiki:Extensions:JQDataTablesPlugin; fixed handling of filter parameter
03 Mar 2014:	work around different styles of inconsistencies in renderForDisplay across foswiki core releases
18 Mar 2014:	added support for rev url parameter to render meta data of an old revision
10 Jul 2013:	fixed dependencies on jQuery plugins; improved params to NEWMETADATA; improved table ui
14 Mar 2013:	fixed redirecting from edit
01 Nov 2012:	replace TML table default format strings with HTML tables for more robustness; removed automatic \n → <br /> conversion
06 Sep 2012:	implemented proper locking
05 Sep 2012:	added form validation editing metadata records; propagate fieldname mapping to modal dialogs; indicate mandatory fields by default; made title of edit dialog configurable; remember url params of the screen to redirect to when finishing an action
21 Jun 2012:	fix security bug where access restricted meta data could be accessed; hide edit interface when the user doesnt have edit rights; performance improvements initializing the plugin's core; renamed hideerror to warn to be in line with other macros
14 Jun 2012:	rationalized include and exclude parameters; and filter parameter to RENDERMETADATA; added work-around for bug in Foswiki::Form caching half-constructed form objects
10 May 2012:	fixed error when meta data definition is read-protected; implemented a way to store meta data in a distant / hidden topic; added $origvalue for field-specific format strings
08 May 2012:	added sort and reverse parameters to RENDERMETADATA
27 Apr 2012:	fixed access to the original value of +values formfields
26 Apr 2012:	fixing table editor for firefox; added dependency on Foswiki:Extensions/JsonRpcContrib; fixed row click in table editor
25 Apr 2012:	initial release