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><ul>
   6             <li><a href="#Specifications"> Specifications</a><ul>
   7                 <li><a href="#TOPICINFO"> TOPICINFO</a></li>
   8                 <li><a href="#TOPICMOVED"> TOPICMOVED</a></li>
   9                 <li><a href="#TOPICPARENT"> TOPICPARENT</a></li>
  10                 <li><a href="#FILEATTACHMENT"> FILEATTACHMENT</a></li>
  11                 <li><a href="#FORM"> FORM</a></li>
  12                 <li><a href="#FIELD"> FIELD</a></li>
  13               </ul>
  14             </li>
  15             <li><a href="#Recommended Sequence"> Recommended Sequence</a></li>
  16           </ul>
  17         </li>
  18         <li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
  19         <li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
  20         <li><a href="#Known Issues"> Known Issues</a></li>
  21       </ul>
  22     </li>
  23   </ul>
  24 </div>
  25
  26 <a name="MetaDataDefinition"></a>
  27
  28 # <a name="TWiki Meta Data"></a> TWiki Meta Data
  29
  30 _Topic data not editable from main freeform text box, stored in name/value `META` variable pairs_
  31
  32 ## <a name="Overview"></a> Overview
  33
  34 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 [[Form Template|Main/TWikiDocumentation#TWiki_Form_Templates]] info.
  35
  36 ## <a name="Meta Data Syntax"></a> Meta Data Syntax
  37
  38 - Format is the same as in [[TWikiVariables|Main/TWikiDocumentation#TWiki_Variables]], except all fields have a key.
  39   - %META:&lt;type&gt;\{key1="value1" [key2="value2" [...]]\}%
  40
  41 - 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).
  42
  43 - Each meta variable is on one line.
  44
  45 - `\n` (new line) is represented in values by `%_N_` and `"` (double-quotes) by `%_Q_%`.
  46
  47 > **Example of Format**
  48 >
  49 >     %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
  50 >        text of the topic
  51 >     %<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName"
  52 >        by="JohnTalintyre" date="976762680"}%
  53 >     %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
  54 >     %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
  55 >     %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
  56 >     %<nop>META:FORM{name="WebFormTemplate"}%
  57 >     %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
  58 >     %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
  59
  60 ### <a name="Specifications"></a> Specifications
  61
  62 The current version of Meta Data is 1.0, with support for the following variables.
  63
  64 #### <a name="TOPICINFO"></a> TOPICINFO
  65
  66 <table border="1" cellpadding="0" cellspacing="0">
  67   <tr>
  68     <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
  69     <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
  70   </tr>
  71   <tr>
  72     <td> version </td>
  73     <td> Same as RCS version </td>
  74   </tr>
  75   <tr>
  76     <td> date </td>
  77     <td> integer, unx time, seconds since start 1970 </td>
  78   </tr>
  79   <tr>
  80     <td> author </td>
  81     <td> last to change topic, is the REMOTE_USER </td>
  82   </tr>
  83   <tr>
  84     <td> format </td>
  85     <td> Format of this topic, will be used for automatic format conversion </td>
  86   </tr>
  87 </table>
  88
  89 #### <a name="TOPICMOVED"></a> TOPICMOVED
  90
  91 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.
  92
  93 %META:TOPICMOVED\{from="Codev.OldName" to="CoDev.NewName" by="talintj" date="976762680"\}%
  94
  95 <table border="1" cellpadding="0" cellspacing="0">
  96   <tr>
  97     <th align="center" bgcolor="#99CCCC"><strong> Key </strong></th>
  98     <th align="center" bgcolor="#99CCCC"><strong> Comment </strong></th>
  99   </tr>
 100   <tr>
 101     <td> from </td>
 102     <td> Full name i.e. web.topic </td>
 103   </tr>
 104   <tr>
 105     <td> to </td>
 106     <td> Full name i.e. web.topic </td>
 107   </tr>
 108   <tr>
 109     <td> by </td>
 110     <td> Who did it, is the REMOTE_USER, not WikiName </td>
 111   </tr>
 112   <tr>
 113     <td> date </td>
 114     <td> integer, unx time, seconds since start 1970 </td>
 115   </tr>
 116 </table>
 117
 118 Notes:
 119
 120 - at present version number is not supported directly, it can be inferred from the RCS history.
 121 - there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
 122
 123 #### <a name="TOPICPARENT"></a> TOPICPARENT
 124
 125 <table border="1" cellpadding="0" cellspacing="0">
 126   <tr>
 127     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 128     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 129   </tr>
 130   <tr>
 131     <td> name </td>
 132     <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>
 133   </tr>
 134 </table>
 135
 136 #### <a name="FILEATTACHMENT"></a> FILEATTACHMENT
 137
 138 <table border="1" cellpadding="0" cellspacing="0">
 139   <tr>
 140     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 141     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 142   </tr>
 143   <tr>
 144     <td> name </td>
 145     <td> Name of file, no path. Must be unique within topic </td>
 146   </tr>
 147   <tr>
 148     <td> version </td>
 149     <td> Same as RCS revision </td>
 150   </tr>
 151   <tr>
 152     <td> path </td>
 153     <td> Full path file was loaded from </td>
 154   </tr>
 155   <tr>
 156     <td> size </td>
 157     <td> In bytes </td>
 158   </tr>
 159   <tr>
 160     <td> date </td>
 161     <td> integer, unx time, seconds since start 1970 </td>
 162   </tr>
 163   <tr>
 164     <td> user </td>
 165     <td> the REMOTE_USER, not WikiName </td>
 166   </tr>
 167   <tr>
 168     <td> comment </td>
 169     <td> As supplied when file uploaded </td>
 170   </tr>
 171   <tr>
 172     <td> attr </td>
 173     <td><code>h</code> if hidden, optional </td>
 174   </tr>
 175 </table>
 176
 177 Extra fields that are added if an attachment is moved:
 178
 179 <table border="1" cellpadding="0" cellspacing="0">
 180   <tr>
 181     <td> movedfrom </td>
 182     <td> full topic name - web.topic </td>
 183   </tr>
 184   <tr>
 185     <td> movedby </td>
 186     <td> the REMOTE_USER, not WikiName </td>
 187   </tr>
 188   <tr>
 189     <td> movedto </td>
 190     <td> full topic name - web.topic </td>
 191   </tr>
 192   <tr>
 193     <td> moveddate </td>
 194     <td> integer, unx time, seconds since start 1970 </td>
 195   </tr>
 196 </table>
 197
 198 #### <a name="FORM"></a> FORM
 199
 200 <table border="1" cellpadding="0" cellspacing="0">
 201   <tr>
 202     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 203     <th bgcolor="#99CCCC"><strong> Comment </strong></th>
 204   </tr>
 205   <tr>
 206     <td> name </td>
 207     <td> A topic name - the topic is a [[Main/TWikiDocumentation#Form_Template]]. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
 208   </tr>
 209 </table>
 210
 211 #### <a name="FIELD"></a> FIELD
 212
 213 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.
 214
 215 <table border="1" cellpadding="0" cellspacing="0">
 216   <tr>
 217     <th bgcolor="#99CCCC"><strong> Key </strong></th>
 218     <th bgcolor="#99CCCC"><strong> Name </strong></th>
 219   </tr>
 220   <tr>
 221     <td> name </td>
 222     <td> Ties to entry in [[Main/TWikiDocumentation#Form_Template]], is title with all bar alphanumerics and . removed </td>
 223   </tr>
 224   <tr>
 225     <td> title </td>
 226     <td> Full text from [[Main/TWikiDocumentation#Form_Template]]</td>
 227   </tr>
 228   <tr>
 229     <td> value </td>
 230     <td> Value user has supplied via form </td>
 231   </tr>
 232 </table>
 233
 234 ### <a name="Recommended Sequence"></a> Recommended Sequence
 235
 236 There no absolute need for meta data variables to be in a specific order, however, it does for the following reasons:
 237
 238 - Keep (form) fields in the order they are defined
 239 - Allow diff command to give output in a logically sensible order
 240
 241 These could be done in other ways, but this adds complexity
 242
 243 - Order fields - definition could be read on each rendering (expensive)
 244 - Diff - render data before doing diff, has something to offer, but not likely to be available for next TWiki release
 245
 246 So the order is:
 247
 248 - TOPICINFO
 249 - text of topic
 250 - TOPICMOVED - optional
 251 - TOPICPARENT - optional
 252 - FILEATTACHMENT - 0 or more entries
 253 - FORM - optional
 254 - 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 (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)
 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 <code>**view**</code>, <code>**preview**</code> and <code>**edit**</code> scripts.
 265
 266 Current support is fairly basic:
 267
 268 <table border="1" cellpadding="0" cellspacing="0">
 269   <tr>
 270     <th bgcolor="#99CCCC"><strong> Variable usage: </strong></th>
 271     <th bgcolor="#99CCCC"><strong> Comment: </strong></th>
 272   </tr>
 273   <tr>
 274     <td> %META{"form"}% </td>
 275     <td> Show form data, see [[Main/TWikiDocumentation#Form_Templates]]</td>
 276   </tr>
 277   <tr>
 278     <td> %META{"attachments"}% </td>
 279     <td> Show attachments, exclude hidden </td>
 280   </tr>
 281   <tr>
 282     <td> Options for attachments: </td>
 283     <td>   </td>
 284   </tr>
 285   <tr>
 286     <td> all="on" </td>
 287     <td> Show ALL attachments (including hidden) </td>
 288   </tr>
 289   <tr>
 290     <td> %META{"moved"}% </td>
 291     <td> Details of any topic moves </td>
 292   </tr>
 293   <tr>
 294     <td> %META{"parent [options]"}% </td>
 295     <td> Show topic parent </td>
 296   </tr>
 297   <tr>
 298     <td> Options for parent: </td>
 299     <td>   </td>
 300   </tr>
 301   <tr>
 302     <td> dontrecurse="on" </td>
 303     <td> By default recurses up tree, at some cost </td>
 304   </tr>
 305   <tr>
 306     <td> prefix="..." </td>
 307     <td> Prefix for parents, only if there are parents; default "" </td>
 308   </tr>
 309   <tr>
 310     <td> suffix="..." </td>
 311     <td> Suffix, only appears if there are parents; default "" </td>
 312   </tr>
 313   <tr>
 314     <td> seperator="..." </td>
 315     <td> Separator between parents, default is " &gt; " </td>
 316   </tr>
 317 </table>
 318
 319 - **Future Development:** There are numerous development directions and specific features to consider. A couple of obvious possibilities:
 320   - Rendering to formats other than tables: bullet lists, formatted body text;
 321   - Specifying templates to be used for rendering.
 322
 323 ## <a name="Known Issues"></a> Known Issues
 324
 325 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.
 326
 327 -- [[JohnTalintyre]] - 29 Aug 2001 <br />