TWiki Meta Data

TWiki Meta Data

Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value 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 and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.

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, 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
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, unix 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, WebHome 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, 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.

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.

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 `" > "`.

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.

-- TWiki:Main.JohnTalintyre - 29 Aug 2001
-- TWiki:Main.MikeMannix - 03 Dec 2001
-- TWiki:Trash.PeterThoeny - 15 Aug 2004