diff options
Diffstat (limited to 'TWiki/TWikiMetaData.mdwn')
| -rw-r--r-- | TWiki/TWikiMetaData.mdwn | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/TWiki/TWikiMetaData.mdwn b/TWiki/TWikiMetaData.mdwn new file mode 100644 index 00000000..dc035ff6 --- /dev/null +++ b/TWiki/TWikiMetaData.mdwn @@ -0,0 +1,299 @@ +%TOC% %STARTINCLUDE% <a name="MetaDataDefinition"></a> + +# <a name="TWiki_Meta_Data"> TWiki Meta Data </a> + +_Additional topic data, program-generated or from [[TWikiForms]], is stored in `META` variable name/value 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]] and topic movement data, and user-defined [[TWikiForms]] info. Use `META` variables to format and display Meta Data. + +## <a name="Meta_Data_Syntax"> Meta Data Syntax </a> + +* Format is the same as in [[TWikiVariables]], except all fields have a key. + * <code>%META:<type>\{key1="value1" key2="value2" ...\}%</code> + +* 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** +> +> <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"}% +> </nop></nop></nop></nop></nop></nop></nop></nop></pre> + +## <a name="Meta_Data_Specifications"> Meta Data Specifications </a> + +The current version of Meta Data is 1.0, with support for the following variables. + +### <a name="META_TOPICINFO"> </a> META: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="META_TOPICMOVED"> </a> 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. + +<code>%META:TOPICMOVED\{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"\}%</code> + +<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="META_TOPICPARENT"> </a> META: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, [[WebHome]] 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="META_FILEATTACHMENT"> </a> META: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> + <th bgcolor="#99CCCC"><strong>Key</strong></th> + <th bgcolor="#99CCCC"><strong>Comment</strong></th> + </tr> + <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="META_FORM"> </a> META: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 represents one of the [[TWikiForms]]. Can optionally include the web name i.e. web.topic, but doesn't normally </td> + </tr> +</table> + +### <a name="META_FIELD"> </a> 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. + +<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 [[TWikiForms]] template, is title with all bar alphanumerics and . removed </td> + </tr> + <tr> + <td> title </td> + <td> Full text from [[TWikiForms]] template </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: + +* 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) + +## <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 [[TWikiForms]]</td> + </tr> + <tr> + <td> %<nop>META{"attachments"}% </nop></td> + <td> Show attachments, exclude hidden </td> + </tr> + <tr> + <td> Options for [[FileAttachments]]: </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> separator="..." </td> + <td> Separator between parents, default is " &gt; " </td> + </tr> +</table> + +## <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 /> -- [[MikeMannix]] - 03 Dec 2001 |