diff options
| -rw-r--r-- | TWiki/MetaDataDefinition.mdwn | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/TWiki/MetaDataDefinition.mdwn b/TWiki/MetaDataDefinition.mdwn new file mode 100644 index 00000000..7aab24a0 --- /dev/null +++ b/TWiki/MetaDataDefinition.mdwn @@ -0,0 +1,233 @@ +## <a name="Meta_Data_Definition"> Meta Data Definition </a> + +See [[MetaDataRendering]] for display of meta data + +Current version: **1\.0** + +Table of contents: %TOC% + +### <a name="Example_of_format"> Example of format </a> + +<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="General_notes"> General notes </a> + +* Format is as for %TWIKIWEB%.TWikiVariables, except all fields have a key. + * %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' is represented in values by <code>**%\_N\_**</code> and '"' by <code>**%\_Q\_%**</code> + +### <a name="Logical_order"> Logical order </a> + +There no absolute need for meta data to be in a specific order, however, it does for the following reasons: + +* Keep (form) fields in the order they are defined +* Allow diff command to give output in a logically sensible order + +These could be done in other ways, but this adds complexity + +* Order fields - definition could be read on each rendering (expensive) +* Diff - render data before doing diff, has something to offer, but not likely to be available for next TWiki release + +So the order 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="Specification"> Specification </a> + +#### <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 field 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="">TWiki Form Template</font></span><a href="http://LOCATION/TWikiFormTemplate">?</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="">TWiki Form Template</font></span><a href="http://LOCATION/TWikiFormTemplate">?</a>, is title with all bar alphanumerics and . removed </td> + </tr> + <tr> + <td> title </td> + <td> Full text from <span style="background:"><font color="">TWiki Form Template</font></span><a href="http://LOCATION/TWikiFormTemplate">?</a></td> + </tr> + <tr> + <td> value </td> + <td> Value user has supplied via form </td> + </tr> +</table> + +### <a name="Viewing_meta_data"> Viewing meta data </a> + +When viewing a topic the `Raw Text` link can be clicked to show the text of a topic (i.e. as is seen when editing). This is done by adding `raw=on` to URL. `raw=debug` shows the meta data as well as the topic data e.g. [for this topic](%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug) + +### <a name="Other"> Other </a> + +There is currently no support for meta data for Plugins. However, the format is readily extendable and the `Meta.pm` code that supports the format only needs minor alteration. + +-- [[Main/JohnTalintyre]] - 16 Aug 2001 <br /> |