summaryrefslogtreecommitdiff
path: root/TWiki/TWikiMetaData.mdwn
blob: 667ed43f0dc67d15f6428826b65a0d518aa2042e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
%TOC% %STARTINCLUDE% <a name="MetaDataDefinition"></a>

# <a name="TWiki_Meta_Data"> TWiki Meta Data </a>

_Topic data not editable from main freeform text box, stored in name/value `META` variable pairs_

## <a name="Overview"> Overview </a>

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.

## <a name="Meta_Data_Syntax"> Meta Data Syntax </a>

* Format is the same as in [[TWikiVariables]], except all fields have a key.
  * <code>%META:&lt;type&gt;\{key1="value1" key2="value2" ...\}%</code>

* 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).

* Each meta variable is on one line.

* `\n` (new line) is represented in values by <code>%\_N\_</code> and `"` (double-quotes) by <code>%\_Q\_%</code>.

> **Example of Format**
>
> <pre>
> %<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
>    text of the topic
> %<nop>META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
>    by="JohnTalintyre" date="976762680"}%
> %<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
> %<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
> %<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
> %<nop>META:FORM{name="WebFormTemplate"}%
> %<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
> %<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
> </nop></nop></nop></nop></nop></nop></nop></nop></pre>

## <a name="Meta_Data_Specifications"> Meta Data Specifications </a>

The current version of Meta Data is 1.0, with support for the following variables.

### <a name="META_TOPICINFO"> </a> META:TOPICINFO

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>Key</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> version </td>
    <td> Same as RCS version </td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
  <tr>
    <td> author </td>
    <td> last to change topic, is the REMOTE_USER </td>
  </tr>
  <tr>
    <td> format </td>
    <td> Format of this topic, will be used for automatic format conversion </td>
  </tr>
</table>

### <a name="META_TOPICMOVED"> </a> META:TOPICMOVED

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.

<code>%META:TOPICMOVED\{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"\}%</code>

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>Key</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> from </td>
    <td> Full name i.e. web.topic </td>
  </tr>
  <tr>
    <td> to </td>
    <td> Full name i.e. web.topic </td>
  </tr>
  <tr>
    <td> by </td>
    <td> Who did it, is the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
</table>

Notes:

* at present version number is not supported directly, it can be inferred from the RCS history.
* there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.

### <a name="META_TOPICPARENT"> </a> META:TOPICPARENT

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> The topic from which this was created, <span style="background:"><font color="">Web Home</font></span><a href="http://LOCATION/WebHome">?</a> 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>
  </tr>
</table>

### <a name="META_FILEATTACHMENT"> </a> META:FILEATTACHMENT

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> Name of file, no path. Must be unique within topic </td>
  </tr>
  <tr>
    <td> version </td>
    <td> Same as RCS revision </td>
  </tr>
  <tr>
    <td> path </td>
    <td> Full path file was loaded from </td>
  </tr>
  <tr>
    <td> size </td>
    <td> In bytes </td>
  </tr>
  <tr>
    <td> date </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
  <tr>
    <td> user </td>
    <td> the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> comment </td>
    <td> As supplied when file uploaded </td>
  </tr>
  <tr>
    <td> attr </td>
    <td><code>h</code> if hidden, optional </td>
  </tr>
</table>

Extra fields that are added if an attachment is moved:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> movedfrom </td>
    <td> full topic name - web.topic </td>
  </tr>
  <tr>
    <td> movedby </td>
    <td> the REMOTE_USER, not <nop>WikiName </nop></td>
  </tr>
  <tr>
    <td> movedto </td>
    <td> full topic name - web.topic </td>
  </tr>
  <tr>
    <td> moveddate </td>
    <td> integer, unx time, seconds since start 1970 </td>
  </tr>
</table>

### <a name="META_FORM"> </a> META:FORM

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> A topic name - the topic represents one of the <span style="background:"><font color="">TWiki Forms</font></span><a href="http://LOCATION/TWikiForms">?</a>. Can optionally include the web name i.e. web.topic, but doesn't normally </td>
  </tr>
</table>

### <a name="META_FIELD"> </a> META:FIELD

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.

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Key</strong></th>
    <th bgcolor="#99CCCC"><strong>Name</strong></th>
  </tr>
  <tr>
    <td> name </td>
    <td> Ties to entry in <span style="background:"><font color="">TWiki Forms</font></span><a href="http://LOCATION/TWikiForms">?</a> template, is title with all bar alphanumerics and . removed </td>
  </tr>
  <tr>
    <td> title </td>
    <td> Full text from <span style="background:"><font color="">TWiki Forms</font></span><a href="http://LOCATION/TWikiForms">?</a> template </td>
  </tr>
  <tr>
    <td> value </td>
    <td> Value user has supplied via form </td>
  </tr>
</table>

### <a name="Recommended_Sequence"> Recommended Sequence </a>

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:

* form fields remain in the order they are defined
* the `diff` function output appears in a logical order

The recommended sequence is:

* META:TOPICINFO
* `text of topic`
* META:TOPICMOVED (optional)
* META:TOPICPARENT (optional)
* META:FILEATTACHMENT (0 or more entries)
* META:FORM (optional)
* META:FIELD (0 or more entries; FORM required)

## <a name="Viewing_Meta_Data_in_Page_Source"> Viewing Meta Data in Page Source </a>

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](%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug)

<a name="MetaDataRendering"></a>

## <a name="Rendering_Meta_Data"> Rendering Meta Data </a>

Meta Data is rendered with the %META% variable. This is mostly used in the `view`, `preview` and `edit` scripts.

Current support covers:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Variable usage:</strong></th>
    <th bgcolor="#99CCCC"><strong>Comment:</strong></th>
  </tr>
  <tr>
    <td> %<nop>META{"form"}% </nop></td>
    <td> Show form data, see <span style="background:"><font color="">TWiki Forms</font></span><a href="http://LOCATION/TWikiForms">?</a></td>
  </tr>
  <tr>
    <td> %<nop>META{"attachments"}% </nop></td>
    <td> Show attachments, exclude hidden </td>
  </tr>
  <tr>
    <td> Options for <span style="background:"><font color="">Attachments</font></span><a href="http://LOCATION/FileAttachments">?</a>: </td>
    <td>   </td>
  </tr>
  <tr>
    <td> all="on" </td>
    <td> Show ALL attachments (including hidden) </td>
  </tr>
  <tr>
    <td> %<nop>META{"moved"}% </nop></td>
    <td> Details of any topic moves </td>
  </tr>
  <tr>
    <td> %<nop>META{"parent [options]"}% </nop></td>
    <td> Show topic parent </td>
  </tr>
  <tr>
    <td> Options for parent: </td>
    <td>   </td>
  </tr>
  <tr>
    <td> dontrecurse="on" </td>
    <td> By default recurses up tree, at some cost </td>
  </tr>
  <tr>
    <td> prefix="..." </td>
    <td> Prefix for parents, only if there are parents; default "" </td>
  </tr>
  <tr>
    <td> suffix="..." </td>
    <td> Suffix, only appears if there are parents; default "" </td>
  </tr>
  <tr>
    <td> separator="..." </td>
    <td> Separator between parents, default is " &amp;gt; " </td>
  </tr>
</table>

## <a name="Known_Issues"> Known Issues </a>

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.

-- [[JohnTalintyre]] - 29 Aug 2001 <br />