TWiki/TWikiMetaData.mdwn

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