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.

ALERT! 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.

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

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

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

PackageForm edit

Author Michael Daum
Version 6.00
Release 30 Jan 2019
Description Bring custom meta data to wiki apps
Repository https://github.com/foswiki/MetaDataPlugin
Copyright © 2011-2019 Michael Daum http://michaeldaumconsulting.com
License GPL (Gnu General Public License)
Home Foswiki:Extensions/MetaDataPlugin
Support Foswiki:Support/MetaDataPlugin
Topic revision: r1 - 30 January 2019, ProjectContributor
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback