3 <li><a href="#TWiki Meta Data"> TWiki Meta Data</a><ul>
4 <li><a href="#Overview"> Overview</a></li>
5 <li><a href="#Meta Data Syntax"> Meta Data Syntax</a><ul>
6 <li><a href="#Specifications"> Specifications</a><ul>
7 <li><a href="#TOPICINFO"> TOPICINFO</a></li>
8 <li><a href="#TOPICMOVED"> TOPICMOVED</a></li>
9 <li><a href="#TOPICPARENT"> TOPICPARENT</a></li>
10 <li><a href="#FILEATTACHMENT"> FILEATTACHMENT</a></li>
11 <li><a href="#FORM"> FORM</a></li>
12 <li><a href="#FIELD"> FIELD</a></li>
15 <li><a href="#Recommended Sequence"> Recommended Sequence</a></li>
18 <li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
19 <li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
20 <li><a href="#Known Issues"> Known Issues</a></li>
26 <a name="MetaDataDefinition"></a>
28 # <a name="TWiki Meta Data"></a> TWiki Meta Data
30 _Topic data not editable from main freeform text box, stored in name/value `META` variable pairs_
32 ## <a name="Overview"></a> Overview
34 TWikiMetaData uses `META` variables to store topic data that's separate from the main free-form content. This includes program-generated info like [[FileAttachment]] data, and user-defined [[Form Template|Main/TWikiDocumentation#TWiki_Form_Templates]] info.
36 ## <a name="Meta Data Syntax"></a> Meta Data Syntax
38 - Format is the same as in [[TWikiVariables|Main/TWikiDocumentation#TWiki_Variables]], except all fields have a key.
39 - %META:<type>\{key1="value1" [key2="value2" [...]]\}%
41 - 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).
43 - Each meta variable is on one line.
45 - `\n` (new line) is represented in values by `%_N_` and `"` (double-quotes) by `%_Q_%`.
47 > **Example of Format**
49 > %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
51 > %<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName"
52 > by="JohnTalintyre" date="976762680"}%
53 > %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
54 > %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
55 > %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
56 > %<nop>META:FORM{name="WebFormTemplate"}%
57 > %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
58 > %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
60 ### <a name="Specifications"></a> Specifications
62 The current version of Meta Data is 1.0, with support for the following variables.
64 #### <a name="TOPICINFO"></a> TOPICINFO
66 <table border="1" cellpadding="0" cellspacing="0">
68 <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
69 <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
73 <td> Same as RCS version </td>
77 <td> integer, unx time, seconds since start 1970 </td>
81 <td> last to change topic, is the REMOTE_USER </td>
85 <td> Format of this topic, will be used for automatic format conversion </td>
89 #### <a name="TOPICMOVED"></a> TOPICMOVED
91 This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
93 %META:TOPICMOVED\{from="Codev.OldName" to="CoDev.NewName" by="talintj" date="976762680"\}%
95 <table border="1" cellpadding="0" cellspacing="0">
97 <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
98 <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
102 <td> Full name i.e. web.topic </td>
106 <td> Full name i.e. web.topic </td>
110 <td> Who did it, is the REMOTE_USER, not WikiName </td>
114 <td> integer, unx time, seconds since start 1970 </td>
120 - at present version number is not supported directly, it can be inferred from the RCS history.
121 - there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
123 #### <a name="TOPICPARENT"></a> TOPICPARENT
125 <table border="1" cellpadding="0" cellspacing="0">
127 <th bgcolor="#99CCCC"><strong> Key </strong></th>
128 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
132 <td> The topic from which this was created, [[Main/WebHome]] if done from <code>Go</code>, othewise topic where <code>?</code> 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. </td>
136 #### <a name="FILEATTACHMENT"></a> FILEATTACHMENT
138 <table border="1" cellpadding="0" cellspacing="0">
140 <th bgcolor="#99CCCC"><strong> Key </strong></th>
141 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
145 <td> Name of file, no path. Must be unique within topic </td>
149 <td> Same as RCS revision </td>
153 <td> Full path file was loaded from </td>
161 <td> integer, unx time, seconds since start 1970 </td>
165 <td> the REMOTE_USER, not WikiName </td>
169 <td> As supplied when file uploaded </td>
173 <td><code>h</code> if hidden, optional </td>
177 Extra fields that are added if an attachment is moved:
179 <table border="1" cellpadding="0" cellspacing="0">
182 <td> full topic name - web.topic </td>
186 <td> the REMOTE_USER, not WikiName </td>
190 <td> full topic name - web.topic </td>
194 <td> integer, unx time, seconds since start 1970 </td>
198 #### <a name="FORM"></a> FORM
200 <table border="1" cellpadding="0" cellspacing="0">
202 <th bgcolor="#99CCCC"><strong> Key </strong></th>
203 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
207 <td> A topic name - the topic is a [[Main/TWikiDocumentation#Form_Template]]. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
211 #### <a name="FIELD"></a> FIELD
213 Should only be present if there is a FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.
215 <table border="1" cellpadding="0" cellspacing="0">
217 <th bgcolor="#99CCCC"><strong> Key </strong></th>
218 <th bgcolor="#99CCCC"><strong> Name </strong></th>
222 <td> Ties to entry in [[Main/TWikiDocumentation#Form_Template]], is title with all bar alphanumerics and . removed </td>
226 <td> Full text from [[Main/TWikiDocumentation#Form_Template]]</td>
230 <td> Value user has supplied via form </td>
234 ### <a name="Recommended Sequence"></a> Recommended Sequence
236 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:
238 - form fields remain in the order they are defined
239 - the `diff` function output appears in a logical order
241 The recommended sequence is:
245 - TOPICMOVED (optional)
246 - TOPICPARENT (optional)
247 - FILEATTACHMENT (0 or more entries)
249 - FIELD (0 or more entries; FORM required)
251 ## <a name="Viewing Meta Data in Page Source"></a> Viewing Meta Data in Page Source
253 When viewing a topic the <code>**Raw Text**</code> link can be clicked to show the text of a topic (ie: 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](http://www.dementia.org/twiki//view/%WEB%/%TOPIC%?raw=debug)
255 <a name="MetaDataRendering"></a>
257 ## <a name="Rendering Meta Data"></a> Rendering Meta Data
259 Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts.
261 Current support covers:
263 <table border="1" cellpadding="0" cellspacing="0">
265 <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
266 <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
269 <td> %META{"form"}% </td>
270 <td> Show form data, see [[Main/TWikiDocumentation#Form_Templates]]</td>
273 <td> %META{"attachments"}% </td>
274 <td> Show attachments, exclude hidden </td>
277 <td> Options for [[Main/FileAttachments]]: </td>
282 <td> Show ALL attachments (including hidden) </td>
285 <td> %META{"moved"}% </td>
286 <td> Details of any topic moves </td>
289 <td> %META{"parent [options]"}% </td>
290 <td> Show topic parent </td>
293 <td> Options for parent: </td>
297 <td> dontrecurse="on" </td>
298 <td> By default recurses up tree, at some cost </td>
301 <td> prefix="..." </td>
302 <td> Prefix for parents, only if there are parents; default "" </td>
305 <td> suffix="..." </td>
306 <td> Suffix, only appears if there are parents; default "" </td>
309 <td> seperator="..." </td>
310 <td> Separator between parents, default is " > " </td>
314 - **Future Development:** There are numerous development directions and specific features to consider. A couple of obvious possibilities:
315 - Rendering to formats other than tables: bullet lists, formatted body text;
316 - Specifying templates to be used for rendering.
318 ## <a name="Known Issues"></a> Known Issues
320 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.
322 -- [[JohnTalintyre]] - 29 Aug 2001 <br />