Meta data

Additional data, Foswiki-generated or from forms, may be embedded in the topic text using META: macros

Overview

The default store engines store topics in plain-text files on disk, in a simple and obvious directory structure. The big advantage of this approach is that it makes it very easy to manipulate topics from outside Foswiki, and it is also very robust; 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 everything together in one place, meta-data (Foswiki-generated or from forms) is embedded directly in topics, using special macros. These macros are easy to spot, as they all start with the reserved META: prefix.

META: data includes information such as file attachments, topic movement history, and form field values. For efficiency reasons, the topic history is not stored in this meta-data, but is expected to be implemented elsewhere by the store engine.

Meta data syntax

• Format is the same as for any other macros except that each meta-data macro must be on a line on its own.
  • %META:<type>{key1="value1" key2="value2" ...}%
• The characters %"\r\n{} are encoded in argument values, using the standard URL encoding.
• Meta-data is divided into core meta-data, described below, and extension meta-data, which shares the same syntax but is used by extensions.
• Dates are stored as "epoch times" i.e. the integer number of seconds since 1st January 1970.

Example of core meta-data

%META:TOPICINFO{version="6" date="1655468868" author="LastEditor" format="1.0"}%
   text of the topic
%META:TOPICMOVED{from="Real.SecretAgents" to="Hollywood.SecretAgents"
   by="CoverUp" date="1655468868"}%
%META:TOPICPARENT{name="MilitaryIntelligence5"}%
%META:FILEATTACHMENT{name="CV.txt" version="3" ... }%
%META:FILEATTACHMENT{name="Photo.gif" version="1" ... }%
%META:FORM{name="SecretAgentForm"}%
%META:FIELD{name="ChosenWeapon" value="Beretta"}%
%META:FIELD{name="Paramour" value="PussyGalore"}%
%META:PREFERENCE{name="ALLOWTOPICCHANGE" value="JamesBond"}%
%META:PREFERENCE{name="DENYTOPICVIEW" value="ErnstBlofeld"}%

Core meta-data

The following meta-data macros are supported by the Foswiki core. Other macros may be used by extensions; see the extension documentation for more details. The core will read and write these extension macros, but will otherwise ignore them.

Some fields are required by macros, while others are optional. Required fields are marked with a ® symbol. The ® character is not part of the attribute name.

META:TOPICINFO

This macro caches some of the information that would normally be derived from the underlying store engine. It does this for efficiency reasons.

Note that the version and date fields are advisory only and cannot be trusted. This is because processes outside of Foswiki's control may write topic files without maintaining these fields.

META:TOPICMOVED

This only exists if the topic has been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta datum exists in the topic. Older ones can to be found in the topic history.

%META:TOPICMOVED{from="Real.SecretAgents" to="Hollywood.SecretAgents" by="CoverUp" date="1416592876"}%

Notes:

• the moved version numbers can be deduced from the topic history.

META:TOPICPARENT

The topic from which this topic was created, typically when clicking on a ? question mark link, or by filling out a form. The topic parent may also be manipulated in the user interface.

META:FILEATTACHMENT

Reference to a file attached to this topic.

Extra fields that are added if an attachment is moved:

META:FORM

META:FIELD

Should only be present if there is a META:FORM entry.

META:PREFERENCE

Out-of-band preference.

Recommended sequence

There is no absolute need for meta-data macros to be listed in a specific order within a topic, but it makes sense to do so, because form fields are displayed in the order they are defined when the topic is viewed.

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)
• META:PREFERENCE (0 or more entries)

Viewing meta-data embedded in page source

You can append the raw=debug parameter to the URL to view the topic text with embedded meta-data, e.g: debug view for this topic. raw=all lets you view the topic source as plain text, e.g: plain text view for this topic.

Including meta data in viewed topics

%META

Meta-data belonging to the viewed topic can be included in the view using the %META macro. See VarMETA for details.

%FORMFIELD

The %FORMFIELD macro lets you inspect the values of form field meta-data in other topics. See VarFORMFIELD for details.

%SEARCH

%SEARCH can also be used to extract meta data. See VarSEARCH and the examples in FormattedSearch and SearchPatternCookbook.

Extending meta-data in Extensions

Extensions can extend meta-data with information of their own. See Foswiki::Func for more information.

Related Topics: DeveloperDocumentationCategory