1 rizwank 1.1 %META:TOPICINFO{author="PeterThoeny" date="1092563687" format="1.0" version="1.16"}%
  2             %META:TOPICPARENT{name="WebHome"}%
  3             %TOC%
  4             %STARTINCLUDE%
  5             #MetaDataDefinition
  6             ---# TWiki Meta Data
  7             
  8             _Additional topic data, program-generated or from TWikiForms, is stored in =META= variable name/value pairs_
  9             
 10             ---++ Overview
 11             
 12             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.  
 13             
 14             ---++ Meta Data Syntax
 15             
 16             	* Format is the same as in TWikiVariables, except all fields have a key.
 17             		* =%<nop>META:&lt;type&gt;{key1="value1" key2="value2" ...}%=
 18             
 19             	* 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).
 20             
 21             	* Each meta variable is on one line.
 22 rizwank 1.1 
 23             	* =\n= (new line) is represented in values by =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.
 24             
 25             <blockquote style="background-color:#f0f0f0">
 26             *Example of Format*
 27             <pre>
 28             %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
 29             	text of the topic
 30             %<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
 31             	by="JohnTalintyre" date="976762680"}%
 32             %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
 33             %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
 34             %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
 35             %<nop>META:FORM{name="WebFormTemplate"}%
 36             %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
 37             %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
 38             </pre>
 39             </blockquote>
 40             
 41             ---++ Meta Data Specifications
 42             
 43 rizwank 1.1 The current version of Meta Data is 1.0, with support for the following variables.
 44             
 45             ---+++ META:TOPICINFO
 46             
 47             |  *Key*  |  *Comment*			 |
 48             | version | Same as RCS version |
 49             | date	 | integer, unix time, seconds since start 1970 |
 50             | author  | last to change topic, is the REMOTE_USER |
 51             | format  | Format of this topic, will be used for automatic format conversion |
 52             
 53             ---+++ META:TOPICMOVED
 54             
 55             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.
 56             
 57             =%<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%=
 58             
 59             |  *Key*  |  *Comment*			 |
 60             | from | Full name, i.e., web.topic |
 61             | to	| Full name, i.e., web.topic |
 62             | by	| Who did it, is the REMOTE_USER, not <nop>WikiName |
 63             | date | integer, unix time, seconds since start 1970 |
 64 rizwank 1.1 
 65             Notes: 
 66             	* at present version number is not supported directly, it can be inferred from the RCS history.
 67             	* there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
 68              
 69             ---+++ META:TOPICPARENT
 70             
 71             | *Key*	| *Comment* |
 72             | 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. |
 73             
 74             ---+++ META:FILEATTACHMENT
 75             
 76             | *Key*	| *Comment* |
 77             | name	 | Name of file, no path.  Must be unique within topic |
 78             | version | Same as RCS revision  |
 79             | path	 | Full path file was loaded from |
 80             | size	 | In bytes |
 81             | date	 | integer, unix time, seconds since start 1970 |
 82             | user	 | the REMOTE_USER, not <nop>WikiName |
 83             | comment | As supplied when file uploaded |
 84             | attr	 | =h= if hidden, optional |
 85 rizwank 1.1 
 86             Extra fields that are added if an attachment is moved:
 87             
 88             | *Key*	| *Comment* |
 89             | movedfrom | full topic name - web.topic |
 90             | movedby	| the REMOTE_USER, not <nop>WikiName |
 91             | movedto	| full topic name - web.topic |
 92             | moveddate | integer, unix time, seconds since start 1970 |
 93             
 94             ---+++ META:FORM
 95             
 96             | *Key*	| *Comment* |
 97             | 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 |
 98             
 99             ---+++ META:FIELD
100             
101             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.
102             
103             | *Key*	| *Name*	|
104             | name	 | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
105             | title	| Full text from TWikiForms template |
106 rizwank 1.1 | value	| Value user has supplied via form |
107             
108             ---+++ Recommended Sequence
109             
110             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:
111             
112             	* form fields remain in the order they are defined
113             	* the =diff= function output appears in a logical order
114             
115             The recommended sequence is:
116             
117             	* =META:TOPICINFO=
118             	* =META:TOPICPARENT= (optional)
119             	* text of topic
120             	* =META:TOPICMOVED= (optional)
121             	* =META:FILEATTACHMENT= (0 or more entries)
122             	* =META:FORM= (optional)
123             	* =META:FIELD= (0 or more entries; FORM required)
124             
125             ---++ Viewing Meta Data in Page Source
126             
127 rizwank 1.1 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 <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>
128             
129             #MetaDataRendering
130             ---++ Rendering Meta Data
131             
132             Meta Data is rendered with the %<nop>META% variable. This is mostly used in the =view=, =preview= and =edit= scripts.
133             
134             __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.
135             
136             Current support covers:
137             
138             | *Variable usage:*	| *Comment:*  |
139             | =%<nop>META{"form"}%= | Show form data, see TWikiForms. |
140             | =%<nop>META{"formfield"}%= | Show form field value. Parameter: ==name="field_name"==. Example:%BR% =%<nop>META{ "formfield" name="TopicClassification" }%= |
141             | =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br > \
142             	 ==all="on"==: Show all attachments, including hidden ones. |
143             | =%<nop>META{"moved"}%= | Details of any topic moves. |
144             | =%<nop>META{"parent"}%= | Show topic parent. Options: <br /> \
145             	 ==dontrecurse="on"==: By default recurses up tree, at some cost. <br /> \
146             	 ==nowebhome="on"==: Suppress <nop>%HOMETOPIC%. <br /> \
147             	 ==prefix="..."==: Prefix for parents, only if there are parents, default =""=. <br /> \
148 rizwank 1.1 	 ==suffix="..."==: Suffix, only appears if there are parents, default =""=. <br /> \
149             	 ==separator="..."==: Separator between parents, default is =" &gt; "=. |
150             
151             ---++ Known Issues
152             
153             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.
154             
155             -- TWiki:Main.JohnTalintyre - 29 Aug 2001 %BR%
156             -- TWiki:Main.MikeMannix - 03 Dec 2001 %BR%
157             -- TWiki:Main.PeterThoeny - 15 Aug 2004
158