diff options
Diffstat (limited to 'TWiki/MetaDataDefinition.mdwn')
| -rw-r--r-- | TWiki/MetaDataDefinition.mdwn | 300 |
1 files changed, 1 insertions, 299 deletions
diff --git a/TWiki/MetaDataDefinition.mdwn b/TWiki/MetaDataDefinition.mdwn index 6c22e00d..59c09d4e 100644 --- a/TWiki/MetaDataDefinition.mdwn +++ b/TWiki/MetaDataDefinition.mdwn @@ -1,299 +1 @@ -%TOC% %STARTINCLUDE% <a name="MetaDataDefinition"></a> - -# <a name="TWiki_Meta_Data"> TWiki Meta Data </a> - -## <a name="What_is_Meta_Data_in_TWiki_"> What is Meta Data in TWiki? </a> - -**_What, indeed!_** - -### <a name="Defining_Meta_Data_Variables"> Defining Meta Data Variables </a> - -See Meta Data Rendering for variables used to display meta data. - -Current version: **1\.0** - -### <a name="Syntax"> Syntax </a> - -* Format is as for \[[TWikiDocumentation#TWiki\_Variables, 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> - -> **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> - -#### <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="">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 no absolute need for meta data variables 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="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="Future_Support_for_Plugins"> Future Support for Plugins </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 needs only minor alteration. - -<a name="MetaDataRendering"></a> - -## <a name="Rendering_Meta_Data"> Rendering Meta Data </a> - -Various types of meta data can be stored in topics. The data is rendered using the %META% variable. This is mostly used in the <code>**view**</code>, <code>**preview**</code> and <code>**edit**</code> scripts. - -Current support is fairly basic: - -<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 attachments: </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> - </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 " &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. - --- [[JohnTalintyre]] - 29 Aug 2001 <br /> +#### <a name="Merged_into_TWikiMetaData_this_t"> </a> Merged into [[TWikiMetaData]] - this topic to be rolled back. |