Meta data

Additional topic data, program-generated or from DataForms, is stored embedded in the topic text using META: tags

Overview

By default, topics are stored 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, and is also very safe; there are no complex binary indexes to maintain, and moving a topic from one installation to another is as simple as copying a couple of text files.

To keep eveything together in one place, meta-data (program-generated or from DataForms) is embedded directly in topics. It does this using META: tags.

META: data includes program-generated info like FileAttachment, topic movement data and user-defined information from DataForms.

Meta data syntax

  • Format is the same as in macros, except all fields have a key.
    • %META:<type>{key1="value1" key2="value2" ...}%

  • Order of fields within the meta-data is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the data themselves is defined).

  • Each meta-datum 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 syntax.

META:TOPICINFO

Key Comment
version Same as SVN 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 datum 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 SVN history.
  • there is only one META:TOPICMOVED in a topic, older move information can be found in the SVN history.

META:TOPICPARENT

Key Comment
name The topic from which this was created, typically when clicking on a ? questionmark 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 SVN 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 DataForms. 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 definition is not read.

Key Name
name Ties to entry in DataForms template, is title with all bar alphanumerics and . removed
title Full text from DataForms template
value Value user has supplied via form

Recommended sequence

There is no absolute need for Meta data to be listed in a specific order within a topic, but it makes sense to do so for 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 [View 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% macro. This is mostly used in the view, preview and edit scripts.

You can render form fields in topic text by using the FORMFIELD macro. Example:
%FORMFIELD{"TopicClassification"}%
For details, see VarFORMFIELD.

Current support covers:

Macro usage: Comment:
%META{"form"}% Show form data, see DataForms.
%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 " > ".

HELP SEARCH can also be used to render meta data, see examples in FormattedSearch and SearchPatternCookbook.


Related Topics: DeveloperDocumentationCategory, UserDocumentationCategory

 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback