TWiki/TWikiMetaData.mdwn

   1 <a name="TWikiMetaData"></a>
   2
   3 # <a name="TWiki Meta Data"></a> TWiki Meta Data
   4
   5 _Additional topic data, program-generated or from [[TWikiForms]], is stored embedded in the topic text using `META:` tags_
   6
   7 <div>
   8   <ul>
   9     <li><a href="#TWiki Meta Data"> TWiki Meta Data</a><ul>
  10         <li><a href="#Overview"> Overview</a></li>
  11         <li><a href="#Meta Data Syntax"> Meta Data Syntax</a></li>
  12         <li><a href="#Meta Data Specifications"> Meta Data Specifications</a><ul>
  13             <li><a href="#META:TOPICINFO"> META:TOPICINFO</a></li>
  14             <li><a href="#META:TOPICMOVED"> META:TOPICMOVED</a></li>
  15             <li><a href="#META:TOPICPARENT"> META:TOPICPARENT</a></li>
  16             <li><a href="#META:FILEATTACHMENT"> META:FILEATTACHMENT</a></li>
  17             <li><a href="#META:FORM"> META:FORM</a></li>
  18             <li><a href="#META:FIELD"> META:FIELD</a></li>
  19             <li><a href="#Recommended Sequence"> Recommended Sequence</a></li>
  20           </ul>
  21         </li>
  22         <li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
  23         <li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
  24       </ul>
  25     </li>
  26   </ul>
  27 </div>
  28
  29 ## <a name="Overview"></a> Overview
  30
  31 By default, TWiki stores topics in files on disk, in a really simple and obvious directory structure. The big advantage of this approach is that it makes it really easy to manipulate topics from outside TWiki, and is also very safe; there are no complex binary indexes to maintain, and moving a topic from one TWiki to another is as simple as copying a couple of text files.
  32
  33 To keep eveything together in one place, TWiki uses a simple method for embedding additional data (program-generated or from [[TWikiForms]]) in topics. It does this using `META:` tags.
  34
  35 `META:` data includes program-generated info like [[FileAttachment]] and topic movement data, and user-defined [[TWikiForms]] info.
  36
  37 ## <a name="Meta Data Syntax"></a> Meta Data Syntax
  38
  39 - Format is the same as in [[TWikiVariables]], except all fields have a key.
  40   - `%META:<type>{key1="value1" key2="value2" ...}%`
  41
  42 - 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).
  43
  44 - Each meta variable is on one line.
  45
  46 - Values in meta-data are URL encoded so that characters such as \\n can be stored.
  47
  48 > **Example of Format**
  49 >
  50 >     %META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}%
  51 >        text of the topic
  52 >     %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
  53 >        by="TopicMoverWikiName" date="976762680"}%
  54 >     %META:TOPICPARENT{name="NavigationByTopicContext"}%
  55 >     %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
  56 >     %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
  57 >     %META:FORM{name="WebFormTemplate"}%
  58 >     %META:FIELD{name="OperatingSystem" value="OsWin"}%
  59 >     %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
  60
  61 ## <a name="Meta Data Specifications"></a> Meta Data Specifications
  62
  63 The current version of Meta Data is 1.0, with support for the following variables.
  64
  65 ### <a name="META:TOPICINFO"></a> META:TOPICINFO
  66
  67 <table border="1" cellpadding="0" cellspacing="0">
  68   <tr>
  69     <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
  70     <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
  71   </tr>
  72   <tr>
  73     <td> version </td>
  74     <td> Same as RCS version </td>
  75   </tr>
  76   <tr>
  77     <td> date </td>
  78     <td> integer, unix time, seconds since start 1970 </td>
  79   </tr>
  80   <tr>
  81     <td> author </td>
  82     <td> last to change topic, is the REMOTE_USER </td>
  83   </tr>
  84   <tr>
  85     <td> format </td>
  86     <td> Format of this topic, will be used for automatic format conversion </td>
  87   </tr>
  88 </table>
  89
  90 ### <a name="META:TOPICMOVED"></a> META:TOPICMOVED
  91
  92 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.
  93
  94 `%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%`
  95
  96 <table border="1" cellpadding="0" cellspacing="0">
  97   <tr>
  98     <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
  99     <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
 100   </tr>
 101   <tr>
 102     <td> from </td>
 103     <td> Full name, i.e., web.topic </td>
 104   </tr>
 105   <tr>
 106     <td> to </td>
 107     <td> Full name, i.e., web.topic </td>
 108   </tr>
 109   <tr>
 110     <td> by </td>
 111     <td> Who did it, is the REMOTE_USER, not WikiName </td>
 112   </tr>
 113   <tr>
 114     <td> date </td>
 115     <td> integer, unix time, seconds since start 1970 </td>
 116   </tr>
 117 </table>
 118
 119 Notes:
 120
 121 - at present version number is not supported directly, it can be inferred from the RCS history.
 122 - there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
 123
 124 ### <a name="META:TOPICPARENT"></a> META:TOPICPARENT
 125
 126 <table border="1" cellpadding="0" cellspacing="0">
 127   <tr>
 128     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 129     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 130   </tr>
 131   <tr>
 132     <td> name </td>
 133     <td> The topic from which this was created, typically when clicking on a <code>?</code> questionmark link, or by filling out a form. Normally just <code>TopicName</code>, but it can be a full <code>Web.TopicName</code> format if the parent is in a different Web. </td>
 134   </tr>
 135 </table>
 136
 137 ### <a name="META:FILEATTACHMENT"></a> META:FILEATTACHMENT
 138
 139 <table border="1" cellpadding="0" cellspacing="0">
 140   <tr>
 141     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 142     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 143   </tr>
 144   <tr>
 145     <td> name </td>
 146     <td> Name of file, no path. Must be unique within topic </td>
 147   </tr>
 148   <tr>
 149     <td> version </td>
 150     <td> Same as RCS revision </td>
 151   </tr>
 152   <tr>
 153     <td> path </td>
 154     <td> Full path file was loaded from </td>
 155   </tr>
 156   <tr>
 157     <td> size </td>
 158     <td> In bytes </td>
 159   </tr>
 160   <tr>
 161     <td> date </td>
 162     <td> integer, unix time, seconds since start 1970 </td>
 163   </tr>
 164   <tr>
 165     <td> user </td>
 166     <td> the REMOTE_USER, not WikiName </td>
 167   </tr>
 168   <tr>
 169     <td> comment </td>
 170     <td> As supplied when file uploaded </td>
 171   </tr>
 172   <tr>
 173     <td> attr </td>
 174     <td><code>h</code> if hidden, optional </td>
 175   </tr>
 176 </table>
 177
 178 Extra fields that are added if an attachment is moved:
 179
 180 <table border="1" cellpadding="0" cellspacing="0">
 181   <tr>
 182     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 183     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 184   </tr>
 185   <tr>
 186     <td> movedfrom </td>
 187     <td> full topic name - web.topic </td>
 188   </tr>
 189   <tr>
 190     <td> movedby </td>
 191     <td> the REMOTE_USER, not WikiName </td>
 192   </tr>
 193   <tr>
 194     <td> movedto </td>
 195     <td> full topic name - web.topic </td>
 196   </tr>
 197   <tr>
 198     <td> moveddate </td>
 199     <td> integer, unix time, seconds since start 1970 </td>
 200   </tr>
 201 </table>
 202
 203 ### <a name="META:FORM"></a> META:FORM
 204
 205 <table border="1" cellpadding="0" cellspacing="0">
 206   <tr>
 207     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 208     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 209   </tr>
 210   <tr>
 211     <td> name </td>
 212     <td> A topic name - the topic represents one of the [[Main/TWikiForms]]. Can optionally include the web name (i.e., web.topic), but doesn't normally </td>
 213   </tr>
 214 </table>
 215
 216 ### <a name="META:FIELD"></a> META:FIELD
 217
 218 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.
 219
 220 <table border="1" cellpadding="0" cellspacing="0">
 221   <tr>
 222     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 223     <th bgcolor="#99CCCC"><strong> Name </strong></th>
 224   </tr>
 225   <tr>
 226     <td> name </td>
 227     <td> Ties to entry in [[Main/TWikiForms]] template, is title with all bar alphanumerics and . removed </td>
 228   </tr>
 229   <tr>
 230     <td> title </td>
 231     <td> Full text from [[Main/TWikiForms]] template </td>
 232   </tr>
 233   <tr>
 234     <td> value </td>
 235     <td> Value user has supplied via form </td>
 236   </tr>
 237 </table>
 238
 239 ### <a name="Recommended Sequence"></a> Recommended Sequence
 240
 241 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:
 242
 243 - form fields remain in the order they are defined
 244 - the `diff` function output appears in a logical order
 245
 246 The recommended sequence is:
 247
 248 - `META:TOPICINFO`
 249 - `META:TOPICPARENT` (optional)
 250 - text of topic
 251 - `META:TOPICMOVED` (optional)
 252 - `META:FILEATTACHMENT` (0 or more entries)
 253 - `META:FORM` (optional)
 254 - `META:FIELD` (0 or more entries; FORM required)
 255
 256 ## <a name="Viewing Meta Data in Page Source"></a> Viewing Meta Data in Page Source
 257
 258 When viewing a topic the <code>**Raw Text**</code> link can be clicked to show the text of a topic (i.e., 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|%WEB%/%TOPIC%?raw=debug]]
 259
 260 <a name="MetaDataRendering"></a>
 261
 262 ## <a name="Rendering Meta Data"></a> Rendering Meta Data
 263
 264 Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts.
 265
 266 You can render form fields in topic text by using the FORMFIELD variable. Example:%BR% `%FORMFIELD{"TopicClassification"}%` %BR% For details, see [[VarFORMFIELD]].
 267
 268 Current support covers:
 269
 270 <table border="1" cellpadding="0" cellspacing="0">
 271   <tr>
 272     <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
 273     <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
 274   </tr>
 275   <tr>
 276     <td><code>%META{"form"}%</code></td>
 277     <td> Show form data, see [[Main/TWikiForms]]. </td>
 278   </tr>
 279   <tr>
 280     <td><code>%META{"formfield"}%</code></td>
 281     <td> Show form field value. Parameter: <code><b>name="field_name"</b></code>. Example:%BR% <code>%META{ "formfield" name="TopicClassification" }%</code></td>
 282   </tr>
 283   <tr>
 284     <td><code>%META{"attachments"}%</code></td>
 285     <td> Show attachments, except for hidden ones. Options: <br /><code><b>all="on"</b></code>: Show all attachments, including hidden ones. </td>
 286   </tr>
 287   <tr>
 288     <td><code>%META{"moved"}%</code></td>
 289     <td> Details of any topic moves. </td>
 290   </tr>
 291   <tr>
 292     <td><code>%META{"parent"}%</code></td>
 293     <td> Show topic parent. Options: <br /><code><b>dontrecurse="on"</b></code>: By default recurses up tree, at some cost. <br /><code><b>nowebhome="on"</b></code>: Suppress WebHome. <br /><code><b>prefix="..."</b></code>: Prefix for parents, only if there are parents, default <code>""</code>. <br /><code><b>suffix="..."</b></code>: Suffix, only appears if there are parents, default <code>""</code>. <br /><code><b>separator="..."</b></code>: Separator between parents, default is <code>" &gt; "</code>. </td>
 294   </tr>
 295 </table>
 296
 297 **_Note:_** SEARCH can also be used to render meta data, see examples in [[FormattedSearch]] and [[SearchPatternCookbook]].
 298
 299 **_Related Topics:_** [[DeveloperDocumentationCategory]], [[UserDocumentationCategory]]