TWikiMetaData « TWiki « netfrag.org

%META:TOPICINFO{author="MikeMannix" date="1007383980" format="1.0" version="1.9"}%
%META:TOPICPARENT{name="WebHome"}%
%TOC%
%STARTINCLUDE%
#MetaDataDefinition
---# 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.
      * =%<nop>META:&lt;type&gt;{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 =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.

<blockquote style="background-color:#f0f0f0">
*Example of Format*
<pre>
%<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
   text of the topic
%<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
   by="JohnTalintyre" date="976762680"}%
%<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
%<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%<nop>META:FORM{name="WebFormTemplate"}%
%<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
%<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
</pre>
</blockquote>

---++ 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.

=%<nop>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 <nop>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, 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, unx time, seconds since start 1970 |
   | user    | the REMOTE_USER, not <nop>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 <nop>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 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
   * =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 <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>

#MetaDataRendering
---++ Rendering Meta Data

Meta Data is rendered with the %<nop>META% variable. This is mostly used in the =view=, =preview= and =edit= scripts.

Current support covers:

  | *Variable usage:*   | *Comment:*  |
  | %<nop>META{"form"}% | Show form data, see TWikiForms |
  | %<nop>META{"attachments"}% | Show attachments, exclude hidden |
  | Options for [[FileAttachments][Attachments]]: | |
  | all="on" | Show ALL attachments (including hidden) |
  | %<nop>META{"moved"}% | Details of any topic moves |
  | %<nop>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 " > " |

---++ 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 <br />
-- MikeMannix - 03 Dec 2001