%TOC% %STARTINCLUDE% # TWiki Meta Data _Topic data not editable from main freeform text box, stored in name/value `META` variable 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]] data, and user-defined [[TWikiForms]] info. ## 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, unx 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, unx 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, Web Home? 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, unx 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, unx time, seconds since start 1970
### META:FORM
Key Comment
name A topic name - the topic represents one of the TWiki Forms?. 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 TWiki Forms? template, is title with all bar alphanumerics and . removed
title Full text from TWiki Forms? 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 * `text of topic` * META:TOPICMOVED (optional) * META:TOPICPARENT (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 (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](%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug) ## Rendering Meta Data Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts. Current support covers:
Variable usage: Comment:
%META{"form"}% Show form data, see TWiki Forms?
%META{"attachments"}% Show attachments, exclude hidden
Options for Attachments?:  
all="on" Show ALL attachments (including hidden)
%META{"moved"}% Details of any topic moves
%META{"parent [options]"}% Show topic parent
Options for parent:  
dontrecurse="on" By default recurses up tree, at some cost
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 " &gt; "
## 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. -- [[JohnTalintyre]] - 29 Aug 2001