MetaDataPlugin < System

---+!! %TOPIC%
%SHORTDESCRIPTION%

%TOC%

This plugin allows to store data sets to Foswiki topics. Foswiki itself 
is a structured wiki already using %SYSTEMWEB%.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 %SYSTEMWEB%.DataForms (like normal forms).
   1 !MetaData types are registered to the Foswiki store using =Foswiki::Meta::registerMETA()=
   1 Records are stored as =%<nop>META:MYDATA{...}%= hashes.
   1 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 Sandbox.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 =%<nop>META:EVENT{}%= records.

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

---++ Screenshots
<a href='%ATTACHURLPATH%/MetaDataPluginSnap1.png' class='foswikiImage' title='screenshot 1'><img src='%ATTACHURLPATH%/MetaDataPluginSnap1.png' width='300' /></a>

<a href='%ATTACHURLPATH%/MetaDataPluginSnap2.png' class='foswikiImage' title='screenshot 2'><img src='%ATTACHURLPATH%/MetaDataPluginSnap2.png' width='300' /></a>

<a href='%ATTACHURLPATH%/MetaDataPluginSnap3.png' class='foswikiImage' title='screenshot 3'><img src='%ATTACHURLPATH%/MetaDataPluginSnap3.png' width='300' /></a>

---++ Syntax

---+++ =%<nop>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 [[%SYSTEMWEB%.DataForms][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 to be rendered; this name is derived from the topic name holding the !DataForm definition (see below) | |
| action | indicates the action to perform on the records, can be =edit= or =view= | view |
| 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="&lt;fieldname1>=&lt;title1>, &lt;fieldname2>=&lt;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 [[%SYSTEMWEB%.QuerySearch][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 | name |
| reverse | boolean flag to reverse the sorting order | off |
| mandatory | string to be inserted when a field is mandatory | <span class='foswikiAlert'>**</span> |
| hiddenformat | format string to be used to render hidden formfields | |
| hideempty | boolean flag to hide/show empty formfields | off |
| warn | boolean flag to suppress error messages | on |
| autolink | boolean flag to enable/prevent !WikiWord linking | on |
| fieldformat | format string for a single formfield value in a row | =$value= |
| &lt;field_name>_attributes, %BR% \
  &lt;field_name>_autolink, %BR% \
  &lt;field_name>_default, %BR% \
  &lt;field_name>_description, %BR% \
  &lt;field_name>_format, %BR% \
  &lt;field_name>_hidden, %BR% \
  &lt;field_name>_size, %BR% \
  &lt;field_name>_title, %BR% \
  &lt;field_name>_tooltip, %BR% \
  &lt;field_name>_type, %BR% \
  &lt;field_name>_value, %BR% \
  &lt;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
   * =$&lt;field_name>=: value of the given field
   * =$orig&lt;field_name>=: original value of the formfield as stored; for =+value= formfields this is the original _unmapped_ value of the formfield
   * =$value=: (in &lt;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 &lt;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

---+++ =%<nop>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 =%<nop>META:PREFERENCE=, =%<nop>META:ATTACHMENT=, =%<nop>META:FIELD= and =%<nop>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:
<pre>
   * Set <!-- -->WEBMETADATA = Applications.ProjectApp.InvoiceForm, 
                       Applications.ProjectApp.EffortForm, 
                       Applications.MovieApp.Role, 
                       Applications.CalendarApp.EventTopic
</pre>

=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 =%<nop>META:&lt;key>{...}%=.

In the above example !MetaDataPlugin will register !MetaData to store:

   * =%<nop>META:INVOICE=,
   * =%<nop>META:EFFORT=,
   * =%<nop>META:ROLE= and
   * =%<nop>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.

   * Sandbox.TimeTracker: this is the starting point of the application; and defines the !DataForm for each !TimeTracker topic 
   * Sandbox.EffortForm: this is a !DataForm definition for effort !MetaData
   * Sandbox.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)
   * Sandbox.TimeTrackerEditTemplate: this is the edit template to edit !TimeTracker topics
   * Sandbox.TimeTrackerViewTemplate: this is the view template to view a !TimeTracker topic and all tracked efforts for it.

%X% 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. 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.


---++ Info
<!--
   * Set SHORTDESCRIPTION = Bring custom meta data to wiki apps
-->

|  Author(s): | Michael Daum|
|  Copyright: | &copy; 2011-2014 Michael Daum http://michaeldaumconsulting.com |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Version: | 4.10 |
|  Release: | 4.10 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 -> &lt;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 | 
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Foswiki::Plugins</td><td align="left">&gt;=2.1</td><td align="left">Requires version 2.0 of handler API.</td></tr><tr><td align="left">Foswiki::Contrib::JsonRpcContrib</td><td align="left">&gt;=1.21</td><td align="left">Required.</td></tr><tr><td align="left">Foswiki::Plugins::JQGridPlugin</td><td align="left">&gt;=2.0</td><td align="left">Optional</td></tr><tr><td align="left">Foswiki::Plugins::FlexFormPlugin</td><td align="left">&gt;=2.5</td><td align="left">Optional</td></tr></table> |
|  Home page: | Foswiki:Extensions/%TOPIC% |
|  Support: | Foswiki:Support/%TOPIC% |
Topic attachments
I	Attachment	Action	Size	Date	Who
png	MetaDataPluginSnap1.png	manage	26.9 K	25 Apr 2012 - 12:15	ProjectContributor
png	MetaDataPluginSnap2.png	manage	18.2 K	25 Apr 2012 - 11:40	ProjectContributor
png	MetaDataPluginSnap3.png	manage	32.6 K	25 Apr 2012 - 11:51	ProjectContributor
This topic: System > MetaDataPlugin
Topic revision: 29 Apr 2014, ProjectContributor (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback