data/TWiki/TWikiMetaData.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.20;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.20
       
     9 date	2008.01.22.03.21.34;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	1.19;
       
    12 
       
    13 1.19
       
    14 date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
       
    15 branches;
       
    16 next	1.18;
       
    17 
       
    18 1.18
       
    19 date	2006.04.01.05.55.13;	author TWikiContributor;	state Exp;
       
    20 branches;
       
    21 next	1.17;
       
    22 
       
    23 1.17
       
    24 date	2006.02.01.12.01.19;	author TWikiContributor;	state Exp;
       
    25 branches;
       
    26 next	1.16;
       
    27 
       
    28 1.16
       
    29 date	2004.08.15.09.54.47;	author PeterThoeny;	state Exp;
       
    30 branches;
       
    31 next	1.15;
       
    32 
       
    33 1.15
       
    34 date	2004.01.25.02.24.09;	author PeterThoeny;	state Exp;
       
    35 branches;
       
    36 next	1.14;
       
    37 
       
    38 1.14
       
    39 date	2004.01.16.07.10.44;	author PeterThoeny;	state Exp;
       
    40 branches;
       
    41 next	1.13;
       
    42 
       
    43 1.13
       
    44 date	2003.07.26.20.52.23;	author PeterThoeny;	state Exp;
       
    45 branches;
       
    46 next	1.12;
       
    47 
       
    48 1.12
       
    49 date	2003.06.18.21.19.00;	author PeterThoeny;	state Exp;
       
    50 branches;
       
    51 next	1.11;
       
    52 
       
    53 1.11
       
    54 date	2002.12.11.07.30.00;	author PeterThoeny;	state Exp;
       
    55 branches;
       
    56 next	1.10;
       
    57 
       
    58 1.10
       
    59 date	2002.01.12.23.23.53;	author MikeMannix;	state Exp;
       
    60 branches;
       
    61 next	1.9;
       
    62 
       
    63 1.9
       
    64 date	2001.12.03.12.53.00;	author MikeMannix;	state Exp;
       
    65 branches;
       
    66 next	1.8;
       
    67 
       
    68 1.8
       
    69 date	2001.10.02.07.38.10;	author MikeMannix;	state Exp;
       
    70 branches;
       
    71 next	1.7;
       
    72 
       
    73 1.7
       
    74 date	2001.09.16.05.57.08;	author MikeMannix;	state Exp;
       
    75 branches;
       
    76 next	1.6;
       
    77 
       
    78 1.6
       
    79 date	2001.09.14.09.05.09;	author PeterThoeny;	state Exp;
       
    80 branches;
       
    81 next	1.5;
       
    82 
       
    83 1.5
       
    84 date	2001.09.12.06.56.27;	author MikeMannix;	state Exp;
       
    85 branches;
       
    86 next	1.4;
       
    87 
       
    88 1.4
       
    89 date	2001.09.08.14.30.25;	author MikeMannix;	state Exp;
       
    90 branches;
       
    91 next	1.3;
       
    92 
       
    93 1.3
       
    94 date	2001.09.07.13.13.06;	author MikeMannix;	state Exp;
       
    95 branches;
       
    96 next	1.2;
       
    97 
       
    98 1.2
       
    99 date	2001.08.30.20.50.27;	author MikeMannix;	state Exp;
       
   100 branches;
       
   101 next	1.1;
       
   102 
       
   103 1.1
       
   104 date	2001.08.30.16.20.58;	author MikeMannix;	state Exp;
       
   105 branches;
       
   106 next	;
       
   107 
       
   108 
       
   109 desc
       
   110 @none
       
   111 @
       
   112 
       
   113 
       
   114 1.20
       
   115 log
       
   116 @buildrelease
       
   117 @
       
   118 text
       
   119 @%META:TOPICINFO{author="TWikiContributor" date="1168737391" format="1.1" version="20"}%
       
   120 %STARTINCLUDE%
       
   121 #TWikiMetaData
       
   122 ---+ TWiki Meta Data
       
   123 
       
   124 _Additional topic data, program-generated or from TWikiForms, is stored embedded in the topic text using =META:= tags_
       
   125 
       
   126 %TOC%
       
   127 
       
   128 ---++ Overview
       
   129 
       
   130 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.
       
   131 
       
   132 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.
       
   133 
       
   134 =META:= data includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info.
       
   135 
       
   136 ---++ Meta Data Syntax
       
   137 
       
   138    * Format is the same as in TWikiVariables, except all fields have a key.
       
   139       * =%<nop>META:&lt;type&gt;{key1="value1" key2="value2" ...}%=
       
   140 
       
   141    * 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).
       
   142 
       
   143    * Each meta variable is on one line.
       
   144 
       
   145    * Values in meta-data are URL encoded so that characters such as \n can be stored.
       
   146 
       
   147 <blockquote>
       
   148 *Example of Format*
       
   149 <pre>
       
   150 %<nop>META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}%
       
   151    text of the topic
       
   152 %<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
       
   153    by="TopicMoverWikiName" date="976762680"}%
       
   154 %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
       
   155 %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
       
   156 %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
       
   157 %<nop>META:FORM{name="WebFormTemplate"}%
       
   158 %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
       
   159 %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
       
   160 </pre>
       
   161 </blockquote>
       
   162 
       
   163 ---++ Meta Data Specifications
       
   164 
       
   165 The current version of Meta Data is 1.0, with support for the following variables.
       
   166 
       
   167 ---+++ META:TOPICINFO
       
   168 
       
   169 |  *Key*  |  *Comment*          |
       
   170 | version | Same as RCS version |
       
   171 | date    | integer, unix time, seconds since start 1970 |
       
   172 | author  | last to change topic, is the REMOTE_USER |
       
   173 | format  | Format of this topic, will be used for automatic format conversion |
       
   174 
       
   175 ---+++ META:TOPICMOVED
       
   176 
       
   177 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.
       
   178 
       
   179 =%<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%=
       
   180 
       
   181 |  *Key*  |  *Comment*          |
       
   182 | from | Full name, i.e., web.topic |
       
   183 | to   | Full name, i.e., web.topic |
       
   184 | by   | Who did it, is the REMOTE_USER, not <nop>WikiName |
       
   185 | date | integer, unix time, seconds since start 1970 |
       
   186 
       
   187 Notes: 
       
   188    * at present version number is not supported directly, it can be inferred from the RCS history.
       
   189    * there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
       
   190  
       
   191 ---+++ META:TOPICPARENT
       
   192 
       
   193 | *Key*   | *Comment* |
       
   194 | name    | The topic from which this was created, typically when clicking on a =?= questionmark link, or by filling out a form.  Normally just =TopicName=, but it can be a full =Web.TopicName= format if the parent is in a different Web. |
       
   195 
       
   196 ---+++ META:FILEATTACHMENT
       
   197 
       
   198 | *Key*   | *Comment* |
       
   199 | name    | Name of file, no path.  Must be unique within topic |
       
   200 | version | Same as RCS revision  |
       
   201 | path    | Full path file was loaded from |
       
   202 | size    | In bytes |
       
   203 | date    | integer, unix time, seconds since start 1970 |
       
   204 | user    | the REMOTE_USER, not <nop>WikiName |
       
   205 | comment | As supplied when file uploaded |
       
   206 | attr    | =h= if hidden, optional |
       
   207 
       
   208 Extra fields that are added if an attachment is moved:
       
   209 
       
   210 | *Key*   | *Comment* |
       
   211 | movedfrom | full topic name - web.topic |
       
   212 | movedby   | the REMOTE_USER, not <nop>WikiName |
       
   213 | movedto   | full topic name - web.topic |
       
   214 | moveddate | integer, unix time, seconds since start 1970 |
       
   215 
       
   216 ---+++ META:FORM
       
   217 
       
   218 | *Key*   | *Comment* |
       
   219 | name    | A topic name - the topic represents one of the TWikiForms.  Can optionally include the web name (i.e., web.topic), but doesn't normally |
       
   220 
       
   221 ---+++ META:FIELD
       
   222 
       
   223 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.
       
   224 
       
   225 | *Key*   | *Name*   |
       
   226 | name    | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
       
   227 | title   | Full text from TWikiForms template |
       
   228 | value   | Value user has supplied via form |
       
   229 
       
   230 ---+++ Recommended Sequence
       
   231 
       
   232 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:
       
   233 
       
   234    * form fields remain in the order they are defined
       
   235    * the =diff= function output appears in a logical order
       
   236 
       
   237 The recommended sequence is:
       
   238 
       
   239    * =META:TOPICINFO=
       
   240    * =META:TOPICPARENT= (optional)
       
   241    * text of topic
       
   242    * =META:TOPICMOVED= (optional)
       
   243    * =META:FILEATTACHMENT= (0 or more entries)
       
   244    * =META:FORM= (optional)
       
   245    * =META:FIELD= (0 or more entries; FORM required)
       
   246 
       
   247 ---++ Viewing Meta Data in Page Source
       
   248 
       
   249 When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (i.e., as seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>
       
   250 
       
   251 #MetaDataRendering
       
   252 ---++ Rendering Meta Data
       
   253 
       
   254 Meta Data is rendered with the %<nop>META% variable. This is mostly used in the =view=, =preview= and =edit= scripts.
       
   255 
       
   256 You can render form fields in topic text by using the FORMFIELD variable. Example:%BR%
       
   257 =%<nop>FORMFIELD{"TopicClassification"}%= %BR%
       
   258 For details, see VarFORMFIELD.
       
   259 
       
   260 Current support covers:
       
   261 
       
   262 | *Variable usage:*   | *Comment:*  |
       
   263 | =%<nop>META{"form"}%= | Show form data, see TWikiForms. |
       
   264 | =%<nop>META{"formfield"}%= | Show form field value. Parameter: ==name="field_name"==. Example:%BR% =%<nop>META{ "formfield" name="TopicClassification" }%= |
       
   265 | =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br /> \
       
   266     ==all="on"==: Show all attachments, including hidden ones. |
       
   267 | =%<nop>META{"moved"}%= | Details of any topic moves. |
       
   268 | =%<nop>META{"parent"}%= | Show topic parent. Options: <br /> \
       
   269     ==dontrecurse="on"==: By default recurses up tree, at some cost. <br /> \
       
   270     ==nowebhome="on"==: Suppress <nop>%HOMETOPIC%. <br /> \
       
   271     ==prefix="..."==: Prefix for parents, only if there are parents, default =""=. <br /> \
       
   272     ==suffix="..."==: Suffix, only appears if there are parents, default =""=. <br /> \
       
   273     ==separator="..."==: Separator between parents, default is =" &gt; "=. |
       
   274 
       
   275 __Note:__ SEARCH can also be used to render meta data, see examples in FormattedSearch and SearchPatternCookbook.
       
   276 
       
   277 __Related Topics:__ DeveloperDocumentationCategory, UserDocumentationCategory
       
   278 
       
   279 @
       
   280 
       
   281 
       
   282 1.19
       
   283 log
       
   284 @buildrelease
       
   285 @
       
   286 text
       
   287 @d1 1
       
   288 a1 2
       
   289 %META:TOPICINFO{author="TWikiContributor" date="1168737391" format="1.1" version="19"}%
       
   290 %TOC%
       
   291 d4 3
       
   292 a6 1
       
   293 ---# TWiki Meta Data
       
   294 d8 1
       
   295 a8 1
       
   296 _Additional topic data, program-generated or from TWikiForms, is stored in =META= variable name/value pairs_
       
   297 d12 5
       
   298 a16 1
       
   299 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.  
       
   300 d27 1
       
   301 a27 1
       
   302    * =\n= (new line) is represented in values by =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.
       
   303 a158 5
       
   304 ---++ Known Issues
       
   305 
       
   306 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.
       
   307 
       
   308 
       
   309 a160 1
       
   310 -- __Contributors:__ TWiki:Main.JohnTalintyre, TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie
       
   311 @
       
   312 
       
   313 
       
   314 1.18
       
   315 log
       
   316 @buildrelease
       
   317 @
       
   318 text
       
   319 @d1 1
       
   320 a1 1
       
   321 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="18"}%
       
   322 d24 1
       
   323 a24 1
       
   324 <blockquote style="background-color:#f0f0f0">
       
   325 d71 1
       
   326 a71 1
       
   327 | name    | The topic from which this was created, %HOMETOPIC% if done from =Go=, othewise topic where =?= 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. |
       
   328 d152 2
       
   329 d161 1
       
   330 a161 1
       
   331 
       
   332 @
       
   333 
       
   334 
       
   335 1.17
       
   336 log
       
   337 @buildrelease
       
   338 @
       
   339 text
       
   340 @d1 1
       
   341 a1 1
       
   342 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="17"}%
       
   343 d15 2
       
   344 a16 2
       
   345 	* Format is the same as in TWikiVariables, except all fields have a key.
       
   346 		* =%<nop>META:&lt;type&gt;{key1="value1" key2="value2" ...}%=
       
   347 d18 1
       
   348 a18 1
       
   349 	* 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).
       
   350 d20 1
       
   351 a20 1
       
   352 	* Each meta variable is on one line.
       
   353 d22 1
       
   354 a22 1
       
   355 	* =\n= (new line) is represented in values by =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.
       
   356 d28 1
       
   357 a28 1
       
   358 	text of the topic
       
   359 d30 1
       
   360 a30 1
       
   361 	by="TopicMoverWikiName" date="976762680"}%
       
   362 d46 1
       
   363 a46 1
       
   364 |  *Key*  |  *Comment*			 |
       
   365 d48 1
       
   366 a48 1
       
   367 | date	 | integer, unix time, seconds since start 1970 |
       
   368 d58 1
       
   369 a58 1
       
   370 |  *Key*  |  *Comment*			 |
       
   371 d60 2
       
   372 a61 2
       
   373 | to	| Full name, i.e., web.topic |
       
   374 | by	| Who did it, is the REMOTE_USER, not <nop>WikiName |
       
   375 d65 2
       
   376 a66 2
       
   377 	* at present version number is not supported directly, it can be inferred from the RCS history.
       
   378 	* there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
       
   379 d70 2
       
   380 a71 2
       
   381 | *Key*	| *Comment* |
       
   382 | name	 | The topic from which this was created, %HOMETOPIC% if done from =Go=, othewise topic where =?= 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. |
       
   383 d75 2
       
   384 a76 2
       
   385 | *Key*	| *Comment* |
       
   386 | name	 | Name of file, no path.  Must be unique within topic |
       
   387 d78 4
       
   388 a81 4
       
   389 | path	 | Full path file was loaded from |
       
   390 | size	 | In bytes |
       
   391 | date	 | integer, unix time, seconds since start 1970 |
       
   392 | user	 | the REMOTE_USER, not <nop>WikiName |
       
   393 d83 1
       
   394 a83 1
       
   395 | attr	 | =h= if hidden, optional |
       
   396 d87 1
       
   397 a87 1
       
   398 | *Key*	| *Comment* |
       
   399 d89 2
       
   400 a90 2
       
   401 | movedby	| the REMOTE_USER, not <nop>WikiName |
       
   402 | movedto	| full topic name - web.topic |
       
   403 d95 2
       
   404 a96 2
       
   405 | *Key*	| *Comment* |
       
   406 | name	 | A topic name - the topic represents one of the TWikiForms.  Can optionally include the web name (i.e., web.topic), but doesn't normally |
       
   407 d102 4
       
   408 a105 4
       
   409 | *Key*	| *Name*	|
       
   410 | name	 | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
       
   411 | title	| Full text from TWikiForms template |
       
   412 | value	| Value user has supplied via form |
       
   413 d111 2
       
   414 a112 2
       
   415 	* form fields remain in the order they are defined
       
   416 	* the =diff= function output appears in a logical order
       
   417 d116 7
       
   418 a122 7
       
   419 	* =META:TOPICINFO=
       
   420 	* =META:TOPICPARENT= (optional)
       
   421 	* text of topic
       
   422 	* =META:TOPICMOVED= (optional)
       
   423 	* =META:FILEATTACHMENT= (0 or more entries)
       
   424 	* =META:FORM= (optional)
       
   425 	* =META:FIELD= (0 or more entries; FORM required)
       
   426 d135 1
       
   427 a135 1
       
   428 For details, see TWikiVariables#VarFORMFIELD.
       
   429 d139 1
       
   430 a139 1
       
   431 | *Variable usage:*	| *Comment:*  |
       
   432 d143 1
       
   433 a143 1
       
   434 	 ==all="on"==: Show all attachments, including hidden ones. |
       
   435 d146 5
       
   436 a150 5
       
   437 	 ==dontrecurse="on"==: By default recurses up tree, at some cost. <br /> \
       
   438 	 ==nowebhome="on"==: Suppress <nop>%HOMETOPIC%. <br /> \
       
   439 	 ==prefix="..."==: Prefix for parents, only if there are parents, default =""=. <br /> \
       
   440 	 ==suffix="..."==: Suffix, only appears if there are parents, default =""=. <br /> \
       
   441 	 ==separator="..."==: Separator between parents, default is =" &gt; "=. |
       
   442 @
       
   443 
       
   444 
       
   445 1.16
       
   446 log
       
   447 @none
       
   448 @
       
   449 text
       
   450 @d1 1
       
   451 a1 2
       
   452 %META:TOPICINFO{author="PeterThoeny" date="1092563687" format="1.0" version="1.16"}%
       
   453 %META:TOPICPARENT{name="WebHome"}%
       
   454 d4 1
       
   455 a4 1
       
   456 #MetaDataDefinition
       
   457 d27 1
       
   458 a27 1
       
   459 %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
       
   460 d30 1
       
   461 a30 1
       
   462 	by="JohnTalintyre" date="976762680"}%
       
   463 d126 1
       
   464 a126 1
       
   465 When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (i.e., as seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>
       
   466 d133 3
       
   467 a135 1
       
   468 __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.
       
   469 d142 1
       
   470 a142 1
       
   471 | =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br > \
       
   472 d156 3
       
   473 a158 3
       
   474 -- TWiki:Main.JohnTalintyre - 29 Aug 2001 %BR%
       
   475 -- TWiki:Main.MikeMannix - 03 Dec 2001 %BR%
       
   476 -- TWiki:Main.PeterThoeny - 15 Aug 2004
       
   477 @
       
   478 
       
   479 
       
   480 1.15
       
   481 log
       
   482 @none
       
   483 @
       
   484 text
       
   485 @d1 1
       
   486 a1 1
       
   487 %META:TOPICINFO{author="PeterThoeny" date="1074997449" format="1.0" version="1.15"}%
       
   488 d3 156
       
   489 a158 155
       
   490 %TOC%
       
   491 %STARTINCLUDE%
       
   492 #MetaDataDefinition
       
   493 ---# TWiki Meta Data
       
   494 
       
   495 _Additional topic data, program-generated or from TWikiForms, is stored in =META= variable name/value pairs_
       
   496 
       
   497 ---++ Overview
       
   498 
       
   499 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.  
       
   500 
       
   501 ---++ Meta Data Syntax
       
   502 
       
   503 	* Format is the same as in TWikiVariables, except all fields have a key.
       
   504 		* =%<nop>META:&lt;type&gt;{key1="value1" key2="value2" ...}%=
       
   505 
       
   506 	* 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).
       
   507 
       
   508 	* Each meta variable is on one line.
       
   509 
       
   510 	* =\n= (new line) is represented in values by =%<nop>_<nop>N_<nop>= and ="= (double-quotes) by =%<nop>_Q_%=.
       
   511 
       
   512 <blockquote style="background-color:#f0f0f0">
       
   513 *Example of Format*
       
   514 <pre>
       
   515 %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
       
   516 	text of the topic
       
   517 %<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
       
   518 	by="JohnTalintyre" date="976762680"}%
       
   519 %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
       
   520 %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
       
   521 %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
       
   522 %<nop>META:FORM{name="WebFormTemplate"}%
       
   523 %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
       
   524 %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
       
   525 </pre>
       
   526 </blockquote>
       
   527 
       
   528 ---++ Meta Data Specifications
       
   529 
       
   530 The current version of Meta Data is 1.0, with support for the following variables.
       
   531 
       
   532 ---+++ META:TOPICINFO
       
   533 
       
   534 |  *Key*  |  *Comment*			 |
       
   535 | version | Same as RCS version |
       
   536 | date	 | integer, unix time, seconds since start 1970 |
       
   537 | author  | last to change topic, is the REMOTE_USER |
       
   538 | format  | Format of this topic, will be used for automatic format conversion |
       
   539 
       
   540 ---+++ META:TOPICMOVED
       
   541 
       
   542 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.
       
   543 
       
   544 =%<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%=
       
   545 
       
   546 |  *Key*  |  *Comment*			 |
       
   547 | from | Full name, i.e., web.topic |
       
   548 | to	| Full name, i.e., web.topic |
       
   549 | by	| Who did it, is the REMOTE_USER, not <nop>WikiName |
       
   550 | date | integer, unix time, seconds since start 1970 |
       
   551 
       
   552 Notes: 
       
   553 	* at present version number is not supported directly, it can be inferred from the RCS history.
       
   554 	* there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
       
   555  
       
   556 ---+++ META:TOPICPARENT
       
   557 
       
   558 | *Key*	| *Comment* |
       
   559 | name	 | The topic from which this was created, %HOMETOPIC% if done from =Go=, othewise topic where =?= 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. |
       
   560 
       
   561 ---+++ META:FILEATTACHMENT
       
   562 
       
   563 | *Key*	| *Comment* |
       
   564 | name	 | Name of file, no path.  Must be unique within topic |
       
   565 | version | Same as RCS revision  |
       
   566 | path	 | Full path file was loaded from |
       
   567 | size	 | In bytes |
       
   568 | date	 | integer, unix time, seconds since start 1970 |
       
   569 | user	 | the REMOTE_USER, not <nop>WikiName |
       
   570 | comment | As supplied when file uploaded |
       
   571 | attr	 | =h= if hidden, optional |
       
   572 
       
   573 Extra fields that are added if an attachment is moved:
       
   574 
       
   575 | *Key*	| *Comment* |
       
   576 | movedfrom | full topic name - web.topic |
       
   577 | movedby	| the REMOTE_USER, not <nop>WikiName |
       
   578 | movedto	| full topic name - web.topic |
       
   579 | moveddate | integer, unix time, seconds since start 1970 |
       
   580 
       
   581 ---+++ META:FORM
       
   582 
       
   583 | *Key*	| *Comment* |
       
   584 | name	 | A topic name - the topic represents one of the TWikiForms.  Can optionally include the web name (i.e., web.topic), but doesn't normally |
       
   585 
       
   586 ---+++ META:FIELD
       
   587 
       
   588 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.
       
   589 
       
   590 | *Key*	| *Name*	|
       
   591 | name	 | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
       
   592 | title	| Full text from TWikiForms template |
       
   593 | value	| Value user has supplied via form |
       
   594 
       
   595 ---+++ Recommended Sequence
       
   596 
       
   597 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:
       
   598 
       
   599 	* form fields remain in the order they are defined
       
   600 	* the =diff= function output appears in a logical order
       
   601 
       
   602 The recommended sequence is:
       
   603 
       
   604 	* META:TOPICINFO
       
   605 	* =text of topic=
       
   606 	* META:TOPICMOVED (optional)
       
   607 	* META:TOPICPARENT (optional)
       
   608 	* META:FILEATTACHMENT (0 or more entries)
       
   609 	* META:FORM (optional)
       
   610 	* META:FIELD (0 or more entries; FORM required)
       
   611 
       
   612 ---++ Viewing Meta Data in Page Source
       
   613 
       
   614 When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (i.e., as seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>
       
   615 
       
   616 #MetaDataRendering
       
   617 ---++ Rendering Meta Data
       
   618 
       
   619 Meta Data is rendered with the %<nop>META% variable. This is mostly used in the =view=, =preview= and =edit= scripts.
       
   620 
       
   621 __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.
       
   622 
       
   623 Current support covers:
       
   624 
       
   625 | *Variable usage:*	| *Comment:*  |
       
   626 | =%<nop>META{"form"}%= | Show form data, see TWikiForms. |
       
   627 | =%<nop>META{"formfield"}%= | Show form field value. Parameter: ==name="field_name"==. Example:%BR% =%<nop>META{ "formfield" name="TopicClassification" }%= |
       
   628 | =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br > \
       
   629 	 ==all="on"==: Show all attachments, including hidden ones. |
       
   630 | =%<nop>META{"moved"}%= | Details of any topic moves. |
       
   631 | =%<nop>META{"parent"}%= | Show topic parent. Options: <br /> \
       
   632 	 ==dontrecurse="on"==: By default recurses up tree, at some cost. <br /> \
       
   633 	 ==nowebhome="on"==: Suppress <nop>%HOMETOPIC%. <br /> \
       
   634 	 ==prefix="..."==: Prefix for parents, only if there are parents, default =""=. <br /> \
       
   635 	 ==suffix="..."==: Suffix, only appears if there are parents, default =""=. <br /> \
       
   636 	 ==separator="..."==: Separator between parents, default is =" &gt; "=. |
       
   637 
       
   638 ---++ Known Issues
       
   639 
       
   640 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.
       
   641 
       
   642 -- TWiki:Main.JohnTalintyre - 29 Aug 2001 <br />
       
   643 -- TWiki:Main.MikeMannix - 03 Dec 2001 <br />
       
   644 -- TWiki:Main.PeterThoeny - 10 Jan 2002
       
   645 @
       
   646 
       
   647 
       
   648 1.14
       
   649 log
       
   650 @none
       
   651 @
       
   652 text
       
   653 @d1 1
       
   654 a1 1
       
   655 %META:TOPICINFO{author="PeterThoeny" date="1074237044" format="1.0" version="1.14"}%
       
   656 d49 1
       
   657 a49 1
       
   658 | date	 | integer, unx time, seconds since start 1970 |
       
   659 d63 1
       
   660 a63 1
       
   661 | date | integer, unx time, seconds since start 1970 |
       
   662 d81 1
       
   663 a81 1
       
   664 | date	 | integer, unx time, seconds since start 1970 |
       
   665 d92 1
       
   666 a92 1
       
   667 | moveddate | integer, unx time, seconds since start 1970 |
       
   668 @
       
   669 
       
   670 
       
   671 1.13
       
   672 log
       
   673 @none
       
   674 @
       
   675 text
       
   676 @d1 1
       
   677 a1 1
       
   678 %META:TOPICINFO{author="PeterThoeny" date="1059252743" format="1.0" version="1.13"}%
       
   679 d155 3
       
   680 a157 3
       
   681 -- JohnTalintyre - 29 Aug 2001 <br />
       
   682 -- MikeMannix - 03 Dec 2001 <br />
       
   683 -- Main.PeterThoeny - 10 Jan 2002
       
   684 @
       
   685 
       
   686 
       
   687 1.12
       
   688 log
       
   689 @none
       
   690 @
       
   691 text
       
   692 @d1 1
       
   693 a1 1
       
   694 %META:TOPICINFO{author="PeterThoeny" date="1055971140" format="1.0" version="1.12"}%
       
   695 d72 1
       
   696 a72 1
       
   697 | name	 | The topic from which this was created, WebHome if done from =Go=, othewise topic where =?= 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. |
       
   698 @
       
   699 
       
   700 
       
   701 1.11
       
   702 log
       
   703 @none
       
   704 @
       
   705 text
       
   706 @d1 1
       
   707 a1 1
       
   708 %META:TOPICINFO{author="PeterThoeny" date="1039591800" format="1.0" version="1.11"}%
       
   709 d134 2
       
   710 d140 1
       
   711 @
       
   712 
       
   713 
       
   714 1.10
       
   715 log
       
   716 @none
       
   717 @
       
   718 text
       
   719 @d1 1
       
   720 a1 1
       
   721 %META:TOPICINFO{author="MikeMannix" date="1010877833" format="1.0" version="1.10"}%
       
   722 d48 4
       
   723 a51 4
       
   724 	| version | Same as RCS version |
       
   725 	| date	 | integer, unx time, seconds since start 1970 |
       
   726 	| author  | last to change topic, is the REMOTE_USER |
       
   727 	| format  | Format of this topic, will be used for automatic format conversion |
       
   728 d60 4
       
   729 a63 4
       
   730 	| from | Full name i.e. web.topic |
       
   731 	| to	| Full name i.e. web.topic |
       
   732 	| by	| Who did it, is the REMOTE_USER, not <nop>WikiName |
       
   733 	| date | integer, unx time, seconds since start 1970 |
       
   734 d72 1
       
   735 a72 1
       
   736 	| name	 | The topic from which this was created, WebHome if done from =Go=, othewise topic where =?= 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. |
       
   737 d77 8
       
   738 a84 8
       
   739 	| name	 | Name of file, no path.  Must be unique within topic |
       
   740 	| version | Same as RCS revision  |
       
   741 	| path	 | Full path file was loaded from |
       
   742 	| size	 | In bytes |
       
   743 	| date	 | integer, unx time, seconds since start 1970 |
       
   744 	| user	 | the REMOTE_USER, not <nop>WikiName |
       
   745 	| comment | As supplied when file uploaded |
       
   746 	| attr	 | =h= if hidden, optional |
       
   747 d89 4
       
   748 a92 4
       
   749 	| movedfrom | full topic name - web.topic |
       
   750 	| movedby	| the REMOTE_USER, not <nop>WikiName |
       
   751 	| movedto	| full topic name - web.topic |
       
   752 	| moveddate | integer, unx time, seconds since start 1970 |
       
   753 d97 1
       
   754 a97 1
       
   755 	| name	 | A topic name - the topic represents one of the TWikiForms.  Can optionally include the web name i.e. web.topic, but doesn't normally |
       
   756 d103 4
       
   757 a106 4
       
   758 	| *Key*	| *Name*	|
       
   759 	| name	 | Ties to entry in TWikiForms template, is title with all bar alphanumerics and . removed |
       
   760 	| title	| Full text from TWikiForms template |
       
   761 	| value	| Value user has supplied via form |
       
   762 d127 1
       
   763 a127 1
       
   764 When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (ie: as seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>
       
   765 d136 3
       
   766 a138 3
       
   767   | *Variable usage:*	| *Comment:*  |
       
   768   | =%<nop>META{"form"}%= | Show form data, see TWikiForms. |
       
   769   | =%<nop>META{"attachments"}%= | Show attachments, except for hidden ones. Options: <br > \
       
   770 d140 2
       
   771 a141 2
       
   772   | =%<nop>META{"moved"}%= | Details of any topic moves. |
       
   773   | =%<nop>META{"parent"}%= | Show topic parent. Options: <br /> \
       
   774 d154 1
       
   775 a154 1
       
   776 -- Main.PeterThoeny - 10 Jan 2002
       
   777 @
       
   778 
       
   779 
       
   780 1.9
       
   781 log
       
   782 @none
       
   783 @
       
   784 text
       
   785 @d1 1
       
   786 a1 1
       
   787 %META:TOPICINFO{author="MikeMannix" date="1007383980" format="1.0" version="1.9"}%
       
   788 d137 10
       
   789 a146 11
       
   790   | %<nop>META{"form"}% | Show form data, see TWikiForms |
       
   791   | %<nop>META{"attachments"}% | Show attachments, exclude hidden |
       
   792   | Options for [[FileAttachments][Attachments]]: | |
       
   793   | all="on" | Show ALL attachments (including hidden) |
       
   794   | %<nop>META{"moved"}% | Details of any topic moves |
       
   795   | %<nop>META{"parent [options]"}% | Show topic parent |
       
   796   | Options for parent: | |
       
   797   | dontrecurse="on" | By default recurses up tree, at some cost |
       
   798   | prefix="..." | Prefix for parents, only if there are parents; default "" |
       
   799   | suffix="..." | Suffix, only appears if there are parents; default "" |
       
   800   | separator="..." | Separator between parents, default is " > " |
       
   801 d153 2
       
   802 a154 1
       
   803 -- MikeMannix - 03 Dec 2001	
       
   804 @
       
   805 
       
   806 
       
   807 1.8
       
   808 log
       
   809 @none
       
   810 @
       
   811 text
       
   812 @d1 1
       
   813 a1 1
       
   814 %META:TOPICINFO{author="MikeMannix" date="1002008290" format="1.0" version="1.8"}%
       
   815 d6 1
       
   816 a6 1
       
   817 ---# Appendix B: TWiki Meta Data
       
   818 d8 1
       
   819 a8 1
       
   820 _Additional topic data, not editable from main freeform text box, stored in =META= variable name/value pairs_
       
   821 d12 1
       
   822 a12 1
       
   823 <nop>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.
       
   824 d154 1
       
   825 a154 1
       
   826 -- MikeMannix - 02 Oct 2001 <br />
       
   827 @
       
   828 
       
   829 
       
   830 1.7
       
   831 log
       
   832 @none
       
   833 @
       
   834 text
       
   835 @d1 1
       
   836 a1 1
       
   837 %META:TOPICINFO{author="MikeMannix" date="1000619828" format="1.0" version="1.7"}%
       
   838 d6 1
       
   839 a6 1
       
   840 ---# TWiki Meta Data
       
   841 d153 2
       
   842 a154 1
       
   843 -- JohnTalintyre - 29 Aug 2001 <br />
       
   844 @
       
   845 
       
   846 
       
   847 1.6
       
   848 log
       
   849 @none
       
   850 @
       
   851 text
       
   852 @d1 1
       
   853 a1 1
       
   854 %META:TOPICINFO{author="PeterThoeny" date="1000458670" format="1.0" version="1.6"}%
       
   855 d8 1
       
   856 a8 1
       
   857 _Topic data not editable from main freeform text box, stored in name/value =META= variable pairs_
       
   858 d153 1
       
   859 a153 1
       
   860 -- JohnTalintyre - 29 Aug 2001 <br />
       
   861 @
       
   862 
       
   863 
       
   864 1.5
       
   865 log
       
   866 @none
       
   867 @
       
   868 text
       
   869 @d1 1
       
   870 a1 1
       
   871 %META:TOPICINFO{author="MikeMannix" date="1000277787" format="1.0" version="1.5"}%
       
   872 a2 2
       
   873 %INCLUDE{"UtilTempDocNote"}%
       
   874 
       
   875 d12 1
       
   876 a12 1
       
   877 <nop>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 [[TWikiDocumentation#TWiki_Form_Templates][Form Template]] info.
       
   878 d16 2
       
   879 a17 2
       
   880 	* Format is the same as in [[TWikiDocumentation#TWiki_Variables][TWikiVariables]], except all fields have a key.
       
   881 		* %<nop>META:&lt;type&gt;{key1="value1" [key2="value2" [...]]}%
       
   882 d27 1
       
   883 a27 1
       
   884 <verbatim>
       
   885 d30 1
       
   886 a30 1
       
   887 %<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName"
       
   888 d38 1
       
   889 a38 1
       
   890 </verbatim>
       
   891 d41 1
       
   892 a41 1
       
   893 ---+++ Specifications
       
   894 d45 1
       
   895 a45 1
       
   896 ---++++ TOPICINFO
       
   897 d47 5
       
   898 a51 5
       
   899 	|  *Key*  |  *Comment*			 |
       
   900 	| version	| Same as RCS version |
       
   901 	| date		| integer, unx time, seconds since start 1970 |
       
   902 	| author	 | last to change topic, is the REMOTE_USER |
       
   903 	| format	 | Format of this topic, will be used for automatic format conversion |
       
   904 d53 1
       
   905 a53 1
       
   906 ---++++ TOPICMOVED
       
   907 d55 1
       
   908 a55 1
       
   909 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.
       
   910 d57 1
       
   911 a57 1
       
   912 %<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName" by="talintj" date="976762680"}%
       
   913 d59 5
       
   914 a63 5
       
   915 	|  *Key*  |  *Comment*			 |
       
   916 	| from		| Full name i.e. web.topic |
       
   917 	| to		  | Full name i.e. web.topic |
       
   918 	| by		  | Who did it, is the REMOTE_USER, not <nop>WikiName |
       
   919 	| date		| integer, unx time, seconds since start 1970 |
       
   920 d69 1
       
   921 a69 1
       
   922 ---++++ TOPICPARENT
       
   923 d71 1
       
   924 a71 1
       
   925 	| *Key*	| *Comment* |
       
   926 d74 1
       
   927 a74 1
       
   928 ---++++ FILEATTACHMENT
       
   929 d76 1
       
   930 a76 1
       
   931 	| *Key*	| *Comment* |
       
   932 d88 1
       
   933 d94 1
       
   934 a94 1
       
   935 ---++++ FORM
       
   936 d96 2
       
   937 a97 2
       
   938 	| *Key*	| *Comment* |
       
   939 	| name	 | A topic name - the topic is a [[TWikiDocumentation#Form_Template][Form Template]].  Can optionally include the web name i.e. web.topic, but doesn't normally |
       
   940 d99 1
       
   941 a99 1
       
   942 ---++++ FIELD
       
   943 d101 1
       
   944 a101 1
       
   945 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.
       
   946 d104 2
       
   947 a105 2
       
   948 	| name	 | Ties to entry in [[TWikiDocumentation#Form_Template][Form Template]], is title with all bar alphanumerics and . removed |
       
   949 	| title	| Full text from [[TWikiDocumentation#Form_Template][Form Template]] |
       
   950 d117 1
       
   951 a117 1
       
   952 	* TOPICINFO
       
   953 d119 5
       
   954 a123 5
       
   955 	* TOPICMOVED (optional)
       
   956 	* TOPICPARENT (optional)
       
   957 	* FILEATTACHMENT (0 or more entries)
       
   958 	* FORM (optional)
       
   959 	* FIELD (0 or more entries; FORM required)
       
   960 d137 1
       
   961 a137 1
       
   962   | %<nop>META{"form"}% | Show form data, see [[TWikiDocumentation#Form_Templates][Form Templates]] |
       
   963 d147 1
       
   964 a147 5
       
   965   | seperator="..." | Separator between parents, default is " > " |
       
   966 
       
   967 	* *Future Development:* There are numerous development directions and specific features to consider. A couple of obvious possibilities:	
       
   968 		* Rendering to formats other than tables: bullet lists, formatted body text; 
       
   969 		* Specifying templates to be used for rendering.
       
   970 @
       
   971 
       
   972 
       
   973 1.4
       
   974 log
       
   975 @none
       
   976 @
       
   977 text
       
   978 @d1 1
       
   979 a1 1
       
   980 %META:TOPICINFO{author="MikeMannix" date="999959425" format="1.0" version="1.4"}%
       
   981 d3 2
       
   982 @
       
   983 
       
   984 
       
   985 1.3
       
   986 log
       
   987 @none
       
   988 @
       
   989 text
       
   990 @d1 1
       
   991 a1 1
       
   992 %META:TOPICINFO{author="MikeMannix" date="999868902" format="1.0" version="1.3"}%
       
   993 d109 6
       
   994 a114 7
       
   995 There no absolute need for meta data variables to be in a specific order, however, it does for the following reasons:
       
   996 	* Keep (form) fields in the order they are defined
       
   997 	* Allow diff command to give output in a logically sensible order
       
   998 
       
   999 These could be done in other ways, but this adds complexity
       
  1000 	* Order fields - definition could be read on each rendering (expensive)
       
  1001 	* Diff - render data before doing diff, has something to offer, but not likely to be available for next TWiki release
       
  1002 a115 1
       
  1003 So the order is:
       
  1004 d117 6
       
  1005 a122 6
       
  1006 	* text of topic
       
  1007 	* TOPICMOVED - optional
       
  1008 	* TOPICPARENT - optional
       
  1009 	* FILEATTACHMENT - 0 or more entries
       
  1010 	* FORM - optional
       
  1011 	* FIELD - 0 or more entries (FORM required)
       
  1012 d131 1
       
  1013 a131 1
       
  1014 Meta Data is rendered with the %<nop>META% variable. This is mostly used in the ==view==, ==preview== and ==edit== scripts.
       
  1015 d133 1
       
  1016 a133 1
       
  1017 Current support is fairly basic:
       
  1018 d138 1
       
  1019 a138 1
       
  1020   | Options for attachments: | |
       
  1021 d154 1
       
  1022 a154 1
       
  1023 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.
       
  1024 @
       
  1025 
       
  1026 
       
  1027 1.2
       
  1028 log
       
  1029 @none
       
  1030 @
       
  1031 text
       
  1032 @d1 1
       
  1033 a1 1
       
  1034 %META:TOPICINFO{author="MikeMannix" date="999204627" format="1.0" version="1.2"}%
       
  1035 d5 154
       
  1036 a158 1
       
  1037 %INCLUDE{"%TWIKIWEB%.MetaDataDefinition"}%
       
  1038 @
       
  1039 
       
  1040 
       
  1041 1.1
       
  1042 log
       
  1043 @none
       
  1044 @
       
  1045 text
       
  1046 @d1 1
       
  1047 a1 1
       
  1048 %META:TOPICINFO{author="MikeMannix" date="999188491" format="1.0" version="1.1"}%
       
  1049 a4 1
       
  1050 ---# TWiki Meta Data
       
  1051 @