-
Notifications
You must be signed in to change notification settings - Fork 38
/
MetaData.txt
164 lines (118 loc) · 8.27 KB
/
MetaData.txt
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
%META:TOPICINFO{author="ProjectContributor" date="1252721244" format="1.1" version="$Rev$"}%
%META:TOPICPARENT{name="DeveloperDocumentationCategory"}%
%STARTINCLUDE%
#MetaData
---+ Meta data
_Additional data, Foswiki-generated or from [[DataForms][forms]], may be embedded in the topic text using =META:= macros_
%TOC%
---++ Overview
The default store engines store topics in plain-text files on disk, in a simple and obvious directory structure. The big advantage of this approach is that it makes it very easy to manipulate topics from outside Foswiki, and it is also very robust; there are no complex binary indexes to maintain, and moving a topic from one installation to another is as simple as copying a couple of text files.
To keep everything together in one place, meta-data (Foswiki-generated or from [[DataForms][forms]]) is embedded directly in topics, using special macros. These macros are easy to spot, as they all start with the reserved =META:= prefix.
=META:= data includes information such as file attachments, topic movement history, and [[DataForms][form field]] values. For efficiency reasons, the topic history is *not* stored in this meta-data, but is expected to be implemented elsewhere by the store engine.
---++ Meta data syntax
* Format is the same as for any other [[%SYSTEMWEB%.Macros][macros]] *except* that each meta-data macro *must* be on a line on its own.
* =%<nop>META:<type>{key1="value1" key2="value2" ...}%=
* The characters =%"\r\n{}= are encoded in argument values, using the standard URL encoding.
* Meta-data is divided into _core_ meta-data, described below, and _extension_ meta-data, which shares the same syntax but is used by extensions.
* Dates are stored as "epoch times" i.e. the integer number of seconds since 1st January 1970.
<blockquote>
*Example of core meta-data*
<pre>
%<nop>META:TOPICINFO{version="1.6" date="976762663" author="LastEditor" format="1.0"}%
text of the topic
%<nop>META:TOPICMOVED{from="Real.SecretAgents" to="Hollywood.SecretAgents"
by="CoverUp" date="976762680"}%
%<nop>META:TOPICPARENT{name="MilitaryIntelligence5"}%
%<nop>META:FILEATTACHMENT{name="CV.txt" version="1.3" ... }%
%<nop>META:FILEATTACHMENT{name="Photo.gif" version="1.1" ... }%
%<nop>META:FORM{name="SecretAgentForm"}%
%<nop>META:FIELD{name="ChosenWeapon" value="Beretta"}%
%<nop>META:FIELD{name="Paramour" value="PussyGalore"}%
%<nop>META:PREFERENCE{name="ALLOWTOPICCHANGE" value="JamesBond"}%
%<nop>META:PREFERENCE{name="DENYTOPICVIEW" value="ErnstBlofeld"}%
</pre>
</blockquote>
---++ Core meta-data
The following meta-data macros are supported by the Foswiki core. Other macros may be used by extensions; see the extension documentation for more details. The core will read and write these extension macros, but will otherwise ignore them.
Some fields are required by macros, while others are optional. Required fields are marked with a %REG% symbol. The %REG% character is *not* part of the attribute name.
---+++ META:TOPICINFO
This macro caches some of the information that would normally be derived from the underlying store engine. It does this for efficiency reasons.
| *Key* | *Comment* |
| author%REG% | Canonical user identifier of last user to change the topic. The exact format of this depends on the user mapping manager. |
| version | Topic version; either CVS format (1.1), or a plain integer. |
| date | epoch time |
| format | Format of this topic, will be used for automatic format conversion |
| reprev | Set when a revision is overwritten by the same author within the {ReplaceIfEditedAgainWithin} window (set in [[%SCRIPTURL{configure}%][ =configure= ]]). If =reprev= is the same as =version=, it prevents Foswiki from attempting to do a 3-way merge when merging overlapping edits by two different users. |
---+++ META:TOPICMOVED
This only exists if the topic has been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta datum exists in the topic. Older ones can to be found in the topic history.
=%<nop>META:TOPICMOVED{from="Real.SecretAgents" to="Hollywood.SecretAgents" by="CoverUp" date="976762680"}%=
| *Key* | *Comment* |
| from%REG% | Full name, i.e., web.topic |
| to%REG% | Full name, i.e., web.topic |
| by%REG% | Canonical user identifier of who moved the topic. The exact format of this depends on the user mapping manager. |
| date%REG% | epoch time |
Notes:
* the moved version numbers can be deduced from the topic history.
---+++ META:TOPICPARENT
The topic from which this topic was created, typically when clicking on a =?= question mark link, or by filling out a form. The topic parent may also be manipulated in the user interface.
| *Key* | *Comment* |
| name%REG% | Normally just =TopicName=, but it can be a full =Web.TopicName= format if the parent is in a different Web. |
---+++ META:FILEATTACHMENT
Reference to a file attached to this topic.
| *Key* | *Comment* |
| name%REG% | Name of file, no path. Must be unique within topic |
| version | Either a CVS format revision (1.1) or a plain integer |
| path | Full path file was loaded from |
| size | In bytes |
| date | epoch time when the file was attached |
| user | Canonical user identifier of user who uploaded the attachment. The exact format of this depends on the user mapping manager. |
| comment | As supplied when file uploaded |
| attr | =h= if hidden, optional |
Extra fields that are added if an attachment is moved:
| *Key* | *Comment* |
| movedfrom | full topic name - web.topic |
| movedby | Canonical user identifier of user who moved the attachment. The exact format of this depends on the user mapping manager. |
| movedto | full topic name - web.topic |
| moveddate | epoch time |
---+++ META:FORM
| *Key* | *Comment* |
| name%REG% | The name of the topic containing the [[DataForms][form definition]]. Can optionally include the web name (i.e., web.topic), but doesn't normally |
---+++ META:FIELD
Should only be present if there is a =META:FORM= entry.
| *Key* | *Name* |
| name%REG% | Ties to entry in the [[DataForms][form definition]]. This is the title with all characters except alphanumerics and . removed |
| value%REG% | Value user has supplied via form |
| title | Full text from the [[DataForms][form definition]] |
---+++ META:PREFERENCE
Out-of-band [[PreferenceSettings][preference]].
| *Key* | *Name* |
| name%REG% | Preference name |
| value%REG% | Preference value |
| type | =Set= or =Local= (Set is the default) |
---+++ Recommended sequence
There is no absolute need for meta-data macros to be listed in a specific order within a topic, but it makes sense to do so, because form fields are displayed in the order they are defined when the topic is viewed.
The recommended sequence is:
* =META:TOPICINFO=
* =META:TOPICPARENT= (optional)
* text of topic
* =META:TOPICMOVED= (optional)
* =META:FILEATTACHMENT= (0 or more entries)
* =META:FORM= (optional)
* =META:FIELD= (0 or more entries; FORM required)
* =META:PREFERENCE= (0 or more entries)
---++ Viewing meta-data embedded in page source
You can append the <code>raw=debug</code> parameter to the URL to view the topic text with embedded meta-data, e.g: <a href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>. <code>raw=all</code> lets you view the topic source as plain text, e.g: <a href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%?raw=all">plain text view for this topic</a>.
#MetaDataRendering
---++ Including meta data in viewed topics
---+++ =%META=
Meta-data belonging to the viewed topic can be included in the view using the =%META= macro. See VarMETA for details.
---+++ =%FORMFIELD=
The =%FORMFIELD= macro lets you inspect the values of form field meta-data in other topics. See VarFORMFIELD for details.
---+++ =%SEARCH=
=%SEARCH= can also be used to extract meta data. See VarSEARCH and the examples in FormattedSearch and SearchPatternCookbook.
---++ Extending meta-data in Extensions
Extensions can extend meta-data with information of their own. See
[[%SCRIPTURL{view}%/%SYSTEMWEB%/PerlDoc?module=Foswiki::Func#StaticMethod_registerMETA_40_36name_44_37syntax_41][Foswiki::Func]] for more information.
---
*Related Topics:* DeveloperDocumentationCategory, UserDocumentationCategory
%META:PREFERENCE{name="REG" value="<span style='color:green'>®</span>"}%