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></li>
6 <li><a href="#Meta Data Specifications"> Meta Data Specifications</a><ul>
7 <li><a href="#META:TOPICINFO"> META:TOPICINFO</a></li>
8 <li><a href="#META:TOPICMOVED"> META:TOPICMOVED</a></li>
9 <li><a href="#META:TOPICPARENT"> META:TOPICPARENT</a></li>
10 <li><a href="#META:FILEATTACHMENT"> META:FILEATTACHMENT</a></li>
11 <li><a href="#META:FORM"> META:FORM</a></li>
12 <li><a href="#META:FIELD"> META:FIELD</a></li>
13 <li><a href="#Recommended Sequence"> Recommended Sequence</a></li>
16 <li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
17 <li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
18 <li><a href="#Known Issues"> Known Issues</a></li>
24 <a name="MetaDataDefinition"></a>
26 # <a name="TWiki Meta Data"></a> TWiki Meta Data
28 _Additional topic data, program-generated or from [[TWikiForms]], is stored in `META` variable name/value pairs_
30 ## <a name="Overview"></a> Overview
32 [[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.
34 ## <a name="Meta Data Syntax"></a> Meta Data Syntax
36 - Format is the same as in [[TWikiVariables]], except all fields have a key.
37 - `%META:<type>{key1="value1" key2="value2" ...}%`
39 - 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).
41 - Each meta variable is on one line.
43 - `\n` (new line) is represented in values by `%_N_` and `"` (double-quotes) by `%_Q_%`.
45 > **Example of Format**
47 > %META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
49 > %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
50 > by="JohnTalintyre" date="976762680"}%
51 > %META:TOPICPARENT{name="NavigationByTopicContext"}%
52 > %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
53 > %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
54 > %META:FORM{name="WebFormTemplate"}%
55 > %META:FIELD{name="OperatingSystem" value="OsWin"}%
56 > %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
58 ## <a name="Meta Data Specifications"></a> Meta Data Specifications
60 The current version of Meta Data is 1.0, with support for the following variables.
62 ### <a name="META:TOPICINFO"></a> META:TOPICINFO
64 <table border="1" cellpadding="0" cellspacing="0">
66 <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
67 <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
71 <td> Same as RCS version </td>
75 <td> integer, unx time, seconds since start 1970 </td>
79 <td> last to change topic, is the REMOTE_USER </td>
83 <td> Format of this topic, will be used for automatic format conversion </td>
87 ### <a name="META:TOPICMOVED"></a> META:TOPICMOVED
89 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.
91 `%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%`
93 <table border="1" cellpadding="0" cellspacing="0">
95 <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
96 <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
100 <td> Full name i.e. web.topic </td>
104 <td> Full name i.e. web.topic </td>
108 <td> Who did it, is the REMOTE_USER, not WikiName </td>
112 <td> integer, unx time, seconds since start 1970 </td>
118 - at present version number is not supported directly, it can be inferred from the RCS history.
119 - there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
121 ### <a name="META:TOPICPARENT"></a> META:TOPICPARENT
123 <table border="1" cellpadding="0" cellspacing="0">
125 <th bgcolor="#99CCCC"><strong> Key </strong></th>
126 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
130 <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>
134 ### <a name="META:FILEATTACHMENT"></a> META:FILEATTACHMENT
136 <table border="1" cellpadding="0" cellspacing="0">
138 <th bgcolor="#99CCCC"><strong> Key </strong></th>
139 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
143 <td> Name of file, no path. Must be unique within topic </td>
147 <td> Same as RCS revision </td>
151 <td> Full path file was loaded from </td>
159 <td> integer, unx time, seconds since start 1970 </td>
163 <td> the REMOTE_USER, not WikiName </td>
167 <td> As supplied when file uploaded </td>
171 <td><code>h</code> if hidden, optional </td>
175 Extra fields that are added if an attachment is moved:
177 <table border="1" cellpadding="0" cellspacing="0">
179 <th bgcolor="#99CCCC"><strong> Key </strong></th>
180 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
184 <td> full topic name - web.topic </td>
188 <td> the REMOTE_USER, not WikiName </td>
192 <td> full topic name - web.topic </td>
196 <td> integer, unx time, seconds since start 1970 </td>
200 ### <a name="META:FORM"></a> META:FORM
202 <table border="1" cellpadding="0" cellspacing="0">
204 <th bgcolor="#99CCCC"><strong> Key </strong></th>
205 <th bgcolor="#99CCCC"><strong> Comment </strong></th>
209 <td> A topic name - the topic represents one of the [[Main/TWikiForms]]. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
213 ### <a name="META:FIELD"></a> META:FIELD
215 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.
217 <table border="1" cellpadding="0" cellspacing="0">
219 <th bgcolor="#99CCCC"><strong> Key </strong></th>
220 <th bgcolor="#99CCCC"><strong> Name </strong></th>
224 <td> Ties to entry in [[Main/TWikiForms]] template, is title with all bar alphanumerics and . removed </td>
228 <td> Full text from [[Main/TWikiForms]] template </td>
232 <td> Value user has supplied via form </td>
236 ### <a name="Recommended Sequence"></a> Recommended Sequence
238 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:
240 - form fields remain in the order they are defined
241 - the `diff` function output appears in a logical order
243 The recommended sequence is:
247 - META:TOPICMOVED (optional)
248 - META:TOPICPARENT (optional)
249 - META:FILEATTACHMENT (0 or more entries)
250 - META:FORM (optional)
251 - META:FIELD (0 or more entries; FORM required)
253 ## <a name="Viewing Meta Data in Page Source"></a> Viewing Meta Data in Page Source
255 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)
257 <a name="MetaDataRendering"></a>
259 ## <a name="Rendering Meta Data"></a> Rendering Meta Data
261 Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts.
263 Current support covers:
265 <table border="1" cellpadding="0" cellspacing="0">
267 <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
268 <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
271 <td><code>%META{"form"}%</code></td>
272 <td> Show form data, see [[Main/TWikiForms]]. </td>
275 <td><code>%META{"attachments"}%</code></td>
276 <td> Show attachments, except for hidden ones. Options: <br /><code><b>all="on"</b></code>: Show all attachments, including hidden ones. </td>
279 <td><code>%META{"moved"}%</code></td>
280 <td> Details of any topic moves. </td>
283 <td><code>%META{"parent"}%</code></td>
284 <td> Show topic parent. Options: <br /><code><b>dontrecurse="on"</b></code>: By default recurses up tree, at some cost. <br /><code><b>nowebhome="on"</b></code>: Suppress WebHome. <br /><code><b>prefix="..."</b></code>: Prefix for parents, only if there are parents, default <code>""</code>. <br /><code><b>suffix="..."</b></code>: Suffix, only appears if there are parents, default <code>""</code>. <br /><code><b>separator="..."</b></code>: Separator between parents, default is <code>" > "</code>. </td>
288 ## <a name="Known Issues"></a> Known Issues
290 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.
292 -- [[JohnTalintyre]] - 29 Aug 2001 <br /> -- [[MikeMannix]] - 03 Dec 2001 <br /> -- [[PeterThoeny]] - 10 Jan 2002