TWiki/TWikiMetaData.mdwn

   1 <div>
   2   <ul>
   3     <li><a href="#Appendix B: TWiki Meta Data"> Appendix B: 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="Appendix B: TWiki Meta Data"></a> Appendix B: TWiki Meta Data
  27
  28 _Additional topic data, not editable from main freeform text box, 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]] data, and user-defined [[TWikiForms]] info.
  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, unx 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, unx 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, unx 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, unx 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 - `text of topic`
 247 - META:TOPICMOVED (optional)
 248 - META:TOPICPARENT (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 (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](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 Current support covers:
 264
 265 <table border="1" cellpadding="0" cellspacing="0">
 266   <tr>
 267     <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
 268     <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
 269   </tr>
 270   <tr>
 271     <td> %META{"form"}% </td>
 272     <td> Show form data, see [[Main/TWikiForms]]</td>
 273   </tr>
 274   <tr>
 275     <td> %META{"attachments"}% </td>
 276     <td> Show attachments, exclude hidden </td>
 277   </tr>
 278   <tr>
 279     <td> Options for [[Main/FileAttachments]]: </td>
 280     <td>   </td>
 281   </tr>
 282   <tr>
 283     <td> all="on" </td>
 284     <td> Show ALL attachments (including hidden) </td>
 285   </tr>
 286   <tr>
 287     <td> %META{"moved"}% </td>
 288     <td> Details of any topic moves </td>
 289   </tr>
 290   <tr>
 291     <td> %META{"parent [options]"}% </td>
 292     <td> Show topic parent </td>
 293   </tr>
 294   <tr>
 295     <td> Options for parent: </td>
 296     <td>   </td>
 297   </tr>
 298   <tr>
 299     <td> dontrecurse="on" </td>
 300     <td> By default recurses up tree, at some cost </td>
 301   </tr>
 302   <tr>
 303     <td> prefix="..." </td>
 304     <td> Prefix for parents, only if there are parents; default "" </td>
 305   </tr>
 306   <tr>
 307     <td> suffix="..." </td>
 308     <td> Suffix, only appears if there are parents; default "" </td>
 309   </tr>
 310   <tr>
 311     <td> separator="..." </td>
 312     <td> Separator between parents, default is " &gt; " </td>
 313   </tr>
 314 </table>
 315
 316 ## <a name="Known Issues"></a> Known Issues
 317
 318 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.
 319
 320 -- [[JohnTalintyre]] - 29 Aug 2001 <br /> -- [[MikeMannix]] - 02 Oct 2001 <br />