162 lines
7.0 KiB
Plaintext
162 lines
7.0 KiB
Plaintext
%META:TOPICINFO{author="TWikiContributor" date="1168737391" format="1.1" version="19"}%
|
|
%TOC%
|
|
%STARTINCLUDE%
|
|
#TWikiMetaData
|
|
---# 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:<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 =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.
|
|
|
|
<blockquote>
|
|
*Example of Format*
|
|
<pre>
|
|
%<nop>META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}%
|
|
text of the topic
|
|
%<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
|
|
by="TopicMoverWikiName" 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, 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.
|
|
|
|
=%<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, 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, 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 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 <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, 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 <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"}%/%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.
|
|
|
|
You can render form fields in topic text by using the FORMFIELD variable. Example:%BR%
|
|
=%<nop>FORMFIELD{"TopicClassification"}%= %BR%
|
|
For details, see VarFORMFIELD.
|
|
|
|
Current support covers:
|
|
|
|
| *Variable usage:* | *Comment:* |
|
|
| =%<nop>META{"form"}%= | Show form data, see TWikiForms. |
|
|
| =%<nop>META{"formfield"}%= | Show form field value. Parameter: ==name="field_name"==. Example:%BR% =%<nop>META{ "formfield" name="TopicClassification" }%= |
|
|
| =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br /> \
|
|
==all="on"==: Show all attachments, including hidden ones. |
|
|
| =%<nop>META{"moved"}%= | Details of any topic moves. |
|
|
| =%<nop>META{"parent"}%= | Show topic parent. Options: <br /> \
|
|
==dontrecurse="on"==: By default recurses up tree, at some cost. <br /> \
|
|
==nowebhome="on"==: Suppress <nop>%HOMETOPIC%. <br /> \
|
|
==prefix="..."==: Prefix for parents, only if there are parents, default =""=. <br /> \
|
|
==suffix="..."==: Suffix, only appears if there are parents, default =""=. <br /> \
|
|
==separator="..."==: Separator between parents, default is =" > "=. |
|
|
|
|
__Note:__ SEARCH can also be used to render meta data, see examples in FormattedSearch and SearchPatternCookbook.
|
|
|
|
---++ 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.
|
|
|
|
|
|
__Related Topics:__ DeveloperDocumentationCategory, UserDocumentationCategory
|
|
|
|
-- __Contributors:__ TWiki:Main.JohnTalintyre, TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie
|