path: root/TWiki/TWikiMetaData.mdwn

%TOC% %STARTINCLUDE% <a name="MetaDataDefinition"></a>

# <a name="TWiki_Meta_Data"> TWiki Meta Data </a>

_Topic data not editable from main freeform text box, stored in name/value `META` variable pairs_

## <a name="Overview"> Overview </a>

TWikiMetaData uses `META` variables to store topic data that's separate from the main free-form content. This includes program-generated info like [[FileAttachment]] data, and user-defined [[TWikiDocumentation]] info.

## <a name="Meta_Data_Syntax"> Meta Data Syntax </a>

* Format is the same as in [[TWikiDocumentation]], except all fields have a key.
  * %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 <code>%\_N\_</code> and `"` (double-quotes) by <code>%\_Q\_%</code>.

> **Example of Format**
>
>     %<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"}%

### <a name="Specifications"> Specifications </a>

The current version of Meta Data is 1.0, with support for the following variables.

#### <a name="TOPICINFO"> </a> TOPICINFO

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>Key</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> version </td>
    <td> Same as RCS version </td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
  <tr>
    <td> author </td>
    <td> last to change topic, is the REMOTE_USER </td>
  </tr>
  <tr>
    <td> format </td>
    <td> Format of this topic, will be used for automatic format conversion </td>
  </tr>
</table>

#### <a name="TOPICMOVED"> </a> TOPICMOVED

This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent 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"\}%

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>Key</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> from </td>
    <td> Full name i.e. web.topic </td>
  </tr>
  <tr>
    <td> to </td>
    <td> Full name i.e. web.topic </td>
  </tr>
  <tr>
    <td> by </td>
    <td> Who did it, is the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
</table>

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.

#### <a name="TOPICPARENT"> </a> TOPICPARENT

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> The topic from which this was created, <span style="background:"><font color="">Web Home</font></span><a href="http://LOCATION/WebHome">?</a> if done from <code>Go</code>, othewise topic where <code>?</code> 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. </td>
  </tr>
</table>

#### <a name="FILEATTACHMENT"> </a> FILEATTACHMENT

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> Name of file, no path. Must be unique within topic </td>
  </tr>
  <tr>
    <td> version </td>
    <td> Same as RCS revision </td>
  </tr>
  <tr>
    <td> path </td>
    <td> Full path file was loaded from </td>
  </tr>
  <tr>
    <td> size </td>
    <td> In bytes </td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
  <tr>
    <td> user </td>
    <td> the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> comment </td>
    <td> As supplied when file uploaded </td>
  </tr>
  <tr>
    <td> attr </td>
    <td><code>h</code> if hidden, optional </td>
  </tr>
</table>

Extra fields that are added if an attachment is moved:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <td> movedfrom </td>
    <td> full topic name - web.topic </td>
  </tr>
  <tr>
    <td> movedby </td>
    <td> the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> movedto </td>
    <td> full topic name - web.topic </td>
  </tr>
  <tr>
    <td> moveddate </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
</table>

#### <a name="FORM"> </a> FORM

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> A topic name - the topic is a <span style="background:"><font color="">Form Template</font></span><a href="http://LOCATION/TWikiDocumentation">?</a>. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
  </tr>
</table>

#### <a name="FIELD"> </a> FIELD

Should only be present if there is a FORM entry. Note that this data is used when viewing a topic, the form template definition is not read.

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Name</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> Ties to entry in <span style="background:"><font color="">Form Template</font></span><a href="http://LOCATION/TWikiDocumentation">?</a>, is title with all bar alphanumerics and . removed </td>
  </tr>
  <tr>
    <td> title </td>
    <td> Full text from <span style="background:"><font color="">Form Template</font></span><a href="http://LOCATION/TWikiDocumentation">?</a></td>
  </tr>
  <tr>
    <td> value </td>
    <td> Value user has supplied via form </td>
  </tr>
</table>

### <a name="Recommended_Sequence"> Recommended Sequence </a>

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:

* TOPICINFO
* `text of topic`
* TOPICMOVED (optional)
* TOPICPARENT (optional)
* FILEATTACHMENT (0 or more entries)
* FORM (optional)
* FIELD (0 or more entries; FORM required)

## <a name="Viewing_Meta_Data_in_Page_Source"> Viewing Meta Data in Page Source </a>

When viewing a topic the <code>**Raw Text**</code> link can be clicked to show the text of a topic (ie: 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](%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug)

<a name="MetaDataRendering"></a>

## <a name="Rendering_Meta_Data"> Rendering Meta Data </a>

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

Current support covers:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Variable usage:</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment:</strong></th>
  </tr>
  <tr>
    <td> %<nop>META{"form"}% </nop></td>
    <td> Show form data, see <span style="background:"><font color="">Form Templates</font></span><a href="http://LOCATION/TWikiDocumentation">?</a></td>
  </tr>
  <tr>
    <td> %<nop>META{"attachments"}% </nop></td>
    <td> Show attachments, exclude hidden </td>
  </tr>
  <tr>
    <td> Options for <span style="background:"><font color="">Attachments</font></span><a href="http://LOCATION/FileAttachments">?</a>: </td>
    <td>   </td>
  </tr>
  <tr>
    <td> all="on" </td>
    <td> Show ALL attachments (including hidden) </td>
  </tr>
  <tr>
    <td> %<nop>META{"moved"}% </nop></td>
    <td> Details of any topic moves </td>
  </tr>
  <tr>
    <td> %<nop>META{"parent [options]"}% </nop></td>
    <td> Show topic parent </td>
  </tr>
  <tr>
    <td> Options for parent: </td>
    <td>   </td>
  </tr>
  <tr>
    <td> dontrecurse="on" </td>
    <td> By default recurses up tree, at some cost </td>
  </tr>
  <tr>
    <td> prefix="..." </td>
    <td> Prefix for parents, only if there are parents; default "" </td>
  </tr>
  <tr>
    <td> suffix="..." </td>
    <td> Suffix, only appears if there are parents; default "" </td>
  </tr>
  <tr>
    <td> seperator="..." </td>
    <td> Separator between parents, default is " &amp;gt; " </td>
  </tr>
</table>

* **Future Development:** There are numerous development directions and specific features to consider. A couple of obvious possibilities:
  * Rendering to formats other than tables: bullet lists, formatted body text;
  * Specifying templates to be used for rendering.

## <a name="Known_Issues"> Known Issues </a>

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 />