TWiki Meta Data
Additional topic data, program-generated or from TWikiForms, is stored embedded in the topic text using META:
tags
Overview
By default, TWiki stores topics in files on disk, in a really simple and obvious directory structure. The big advantage of this approach is that it makes it really easy to manipulate topics from outside TWiki, and is also very safe; there are no complex binary indexes to maintain, and moving a topic from one TWiki to another is as simple as copying a couple of text files.
To keep eveything together in one place, TWiki uses a simple method for embedding additional data (program-generated or from
TWikiForms) in topics. It does this using
META:
tags.
META:
data includes program-generated info like
FileAttachment and topic movement 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.
- Values in meta-data are URL encoded so that characters such as \n can be stored.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="TopicMoverWikiName" 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 |
by |
Who did it, is the REMOTE_USER, not WikiName |
date |
integer, unix time, seconds since start 1970 |
from |
Full name, i.e., web.topic |
to |
Full name, i.e., web.topic |
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, typically when clicking on a red-link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
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
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the
view
,
preview
and
edit
scripts.
You can render form fields in topic text by using the FORMFIELD variable. Example:
%FORMFIELD{"TopicClassification"}%
For details, see
VarFORMFIELD.
Current support covers:
Variable usage: |
Comment: |
%META{"form"}% |
Show form data, see TWikiForms. |
%META{"formfield"}% |
Show form field value. Parameter: name="field_name" . Example: %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 WebHome. 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 " > " . |
Note: SEARCH can also be used to render meta data, see examples in
FormattedSearch and
SearchPatternCookbook.
Related Topics: DeveloperDocumentationCategory,
UserDocumentationCategory