%TOC% %STARTINCLUDE% #MetaDataDefinition ---# TWiki Meta Data _Additional topic data, program-generated or from TWikiForms, is stored in =META= variable name/value pairs_ ---++ Overview TWikiMetaData uses =META= variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use =META= variables to format and display Meta Data. ---++ Meta Data Syntax * Format is the same as in TWikiVariables, except all fields have a key. * =%META:<type>{key1="value1" key2="value2" ...}%= * Order of fields within the meta variables is not defined, except that if there is a field with key =name=, this appears first for easier searching (note the order of the variables themselves is defined). * Each meta variable is on one line. * =\n= (new line) is represented in values by =%_N_= and ="= (double-quotes) by =%_Q_%=.
*Example of Format*
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
	text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
	by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
---++ Meta Data Specifications The current version of Meta Data is 1.0, with support for the following variables. ---+++ META:TOPICINFO | *Key* | *Comment* | | version | Same as RCS version | | date | integer, unix time, seconds since start 1970 | | author | last to change topic, is the REMOTE_USER | | format | Format of this topic, will be used for automatic format conversion | ---+++ META:TOPICMOVED This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history. =%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%= | *Key* | *Comment* | | from | Full name, i.e., web.topic | | to | Full name, i.e., web.topic | | by | Who did it, is the REMOTE_USER, not WikiName | | date | integer, unix time, seconds since start 1970 | Notes: * at present version number is not supported directly, it can be inferred from the RCS history. * there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history. ---+++ META:TOPICPARENT | *Key* | *Comment* | | name | The topic from which this was created, %HOMETOPIC% if done from =Go=, othewise topic where =?= or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed. | ---+++ META:FILEATTACHMENT | *Key* | *Comment* | | name | Name of file, no path. Must be unique within topic | | version | Same as RCS revision | | path | Full path file was loaded from | | size | In bytes | | date | integer, unix time, seconds since start 1970 | | user | the REMOTE_USER, not WikiName | | comment | As supplied when file uploaded | | attr | =h= if hidden, optional | Extra fields that are added if an attachment is moved: | *Key* | *Comment* | | movedfrom | full topic name - web.topic | | movedby | the REMOTE_USER, not WikiName | | movedto | full topic name - web.topic | | moveddate | integer, unix time, seconds since start 1970 | ---+++ META:FORM | *Key* | *Comment* | | name | A topic name - the topic represents one of the TWikiForms. Can optionally include the web name (i.e., web.topic), but doesn't normally | ---+++ META:FIELD Should only be present if there is a META:FORM entry. Note that this data is used when viewing a topic, the form template definition is not read. | *Key* | *Name* | | name | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed | | title | Full text from TWikiForms template | | value | Value user has supplied via form | ---+++ Recommended Sequence There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons: * form fields remain in the order they are defined * the =diff= function output appears in a logical order The recommended sequence is: * =META:TOPICINFO= * =META:TOPICPARENT= (optional) * text of topic * =META:TOPICMOVED= (optional) * =META:FILEATTACHMENT= (0 or more entries) * =META:FORM= (optional) * =META:FIELD= (0 or more entries; FORM required) ---++ Viewing Meta Data in Page Source When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic #MetaDataRendering ---++ Rendering Meta Data Meta Data is rendered with the %META% variable. This is mostly used in the =view=, =preview= and =edit= scripts. __Note:__ Rendering meta data is currently not supported in topic text. As a workaround, use FormattedSearch on the current topic only to render form fields. Current support covers: | *Variable usage:* | *Comment:* | | =%META{"form"}%= | Show form data, see TWikiForms. | | =%META{"formfield"}%= | Show form field value. Parameter: ==name="field_name"==. Example:%BR% =%META{ "formfield" name="TopicClassification" }%= | | =%META{"attachments"}%= | Show attachments, except for hidden ones. Options:
\ ==all="on"==: Show all attachments, including hidden ones. | | =%META{"moved"}%= | Details of any topic moves. | | =%META{"parent"}%= | Show topic parent. Options:
\ ==dontrecurse="on"==: By default recurses up tree, at some cost.
\ ==nowebhome="on"==: Suppress %HOMETOPIC%.
\ ==prefix="..."==: Prefix for parents, only if there are parents, default =""=.
\ ==suffix="..."==: Suffix, only appears if there are parents, default =""=.
\ ==separator="..."==: Separator between parents, default is =" > "=. | ---++ Known Issues At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the =Meta.pm= code that supports the format needs only minor alteration. -- TWiki:Main.JohnTalintyre - 29 Aug 2001 %BR% -- TWiki:Main.MikeMannix - 03 Dec 2001 %BR% -- TWiki:Main.PeterThoeny - 15 Aug 2004