buildrelease
[openafs-wiki.git] / 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="TWikiMetaData"></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="LastEditorWikiName" format="1.0"}%
48 >        text of the topic
49 >     %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
50 >        by="TopicMoverWikiName" 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|%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 You can render form fields in topic text by using the FORMFIELD variable. Example:%BR% `%FORMFIELD{"TopicClassification"}%` %BR% For details, see [[VarFORMFIELD]].
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 **_Related Topics:_** [[DeveloperDocumentationCategory]], [[UserDocumentationCategory]]