TWiki/TWikiMetaDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Meta="></a> Package =TWiki::Meta
   2
   3 All TWiki topics have **data** (text) and **meta-data** (information about the topic). Meta-data includes information such as file attachments, form fields, topic parentage etc. When TWiki loads a topic from the store, it represents the meta-data in the topic using an object of this class.
   4
   5 A meta-data object is a hash of different types of meta-data (keyed on the type, such as 'FIELD' and 'TOPICINFO').
   6
   7 Each entry in the hash is an array, where each entry in the array contains another hash of the key=value pairs, corresponding to a single meta-datum.
   8
   9 If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array has multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
  10
  11 For unkeyed types, the array has only one entry.
  12
  13 Pictorially,
  14
  15 - TOPICINFO
  16   - author =&gt; '...'
  17   - date =&gt; '...'
  18   - ...
  19 - FILEATTACHMENT
  20   - [0] -&gt; \{ name =&gt; '...' ... \}
  21   - [1] -&gt; \{ name =&gt; '...' ... \}
  22 - FIELD
  23   - [0] -&gt; \{ name =&gt; '...' ... \}
  24   - [1] -&gt; \{ name =&gt; '...' ... \}
  25
  26 As well as the meta-data, the object also stores the web name, topic name and remaining text after meta-data extraction.
  27
  28 <div>
  29   <ul>
  30     <li><a href="#Package =TWiki::Meta="> Package TWiki::Meta</a><ul>
  31         <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic,$text)</tt></a></li>
  32         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>session</strong> ()"> ObjectMethod session <tt>()</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>web</strong> ()"> ObjectMethod web <tt>()</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>topic</strong> ()"> ObjectMethod topic <tt>()</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>text</strong> ([$text]) ->"> ObjectMethod text <tt>([$text]) -&gt; $text</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>put</strong> ($type,\%args"> ObjectMethod put <tt>($type,\%args)</tt></a></li>
  38         <li><a href="#ObjectMethod <strong>putKeyed</strong> ($type,\"> ObjectMethod putKeyed <tt>($type,\%args)</tt></a></li>
  39         <li><a href="#ObjectMethod *putAll*"> ObjectMethod putAll <tt></tt></a></li>
  40         <li><a href="#ObjectMethod <strong>get</strong> ($type,$key)"> ObjectMethod get <tt>($type,$key) -&gt; \%hash</tt></a></li>
  41         <li><a href="#ObjectMethod <strong>find</strong> ($type) -> @"> ObjectMethod find <tt>($type) -&gt; @values</tt></a></li>
  42         <li><a href="#ObjectMethod <strong>remove</strong> ($type,$ke"> ObjectMethod remove <tt>($type,$key)</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>copyFrom</strong> ($otherM"> ObjectMethod copyFrom <tt>($otherMeta,$type,$nameFilter)</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>count</strong> ($type) ->"> ObjectMethod count <tt>($type) -&gt; $integer</tt></a></li>
  45         <li><a href="#ObjectMethod *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($fromrev) -&gt; ($date,$author,$rev,$comment)</tt></a></li>
  46         <li><a href="#ObjectMethod <strong>merge</strong> ($otherMeta"> ObjectMethod merge <tt>($otherMeta,$formDef)</tt></a></li>
  47         <li><a href="#ObjectMethod <strong>stringify</strong> ($types"> ObjectMethod stringify <tt>($types) -&gt; $string</tt></a></li>
  48         <li><a href="#ObjectMethod *for_EachSelectedVa"> ObjectMethod forEachSelectedValue <tt>($types,$keys,\&amp;fn,\%options)</tt></a></li>
  49         <li><a href="#ObjectMethod <strong>getParent</strong> () -> $"> ObjectMethod getParent <tt>() -&gt; $parent</tt></a></li>
  50         <li><a href="#ObjectMethod <strong>get_FormName</strong> () -"> ObjectMethod getFormName <tt>() -&gt; $formname</tt></a></li>
  51         <li><a href="#ObjectMethod *render_FormForDisp"> ObjectMethod renderFormForDisplay <tt>() -&gt; $html</tt></a></li>
  52         <li><a href="#ObjectMethod *render_FormFieldFo"> ObjectMethod renderFormFieldForDisplay <tt>($name,$format,$attrs) -&gt; $text</tt></a></li>
  53         <li><a href="#ObjectMethod *get_EmbeddedStoreF"> ObjectMethod getEmbeddedStoreForm <tt>() -&gt; $text</tt></a></li>
  54         <li><a href="#ObjectMethod <strong>get_MetaFor</strong> () ->"> ObjectMethod getMetaFor <tt>() -&gt; $meta</tt></a></li>
  55       </ul>
  56     </li>
  57   </ul>
  58 </div>
  59
  60 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic,$text)`
  61
  62 - `$session` - a TWiki object (e.g. =$TWiki::Plugins::SESSION)
  63 - `$web`, `$topic` - the topic that the metadata relates to
  64
  65 Construct a new, empty object to contain meta-data for the given topic.
  66
  67 - $text - optional raw text to convert to meta-data form
  68
  69 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  70
  71 Break circular references.
  72
  73 ## <a name="ObjectMethod &lt;strong&gt;session&lt;/strong&gt; ()"></a> [[ObjectMethod]] **session** `()`
  74
  75 Get the session
  76
  77 ## <a name="ObjectMethod &lt;strong&gt;web&lt;/strong&gt; ()"></a> [[ObjectMethod]] **web** `()`
  78
  79 Get the web name
  80
  81 ## <a name="ObjectMethod &lt;strong&gt;topic&lt;/strong&gt; ()"></a> [[ObjectMethod]] **topic** `()`
  82
  83 Get the topic name
  84
  85 ## <a name="ObjectMethod &lt;strong&gt;text&lt;/strong&gt; ([$text]) -"></a><a name="ObjectMethod &lt;strong&gt;text&lt;/strong&gt; ([$text]) - "></a> [[ObjectMethod]] **text** `([$text]) -> $text`
  86
  87 Get/set the topic body text. If $text is undef, gets the value, if it is defined, sets the value to that and returns the new text.
  88
  89 ## <a name="ObjectMethod &lt;strong&gt;put&lt;/strong&gt; ($type,\%args"></a> [[ObjectMethod]] **put** `($type,\%args)`
  90
  91 Put a hash of key=value pairs into the given type set in this meta. This will **not** replace another value with the same name (for that see `putKeyed`)
  92
  93 For example,
  94
  95     $meta->put( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
  96
  97 ## <a name="ObjectMethod &lt;strong&gt;putKeyed&lt;/strong&gt; ($type,\"></a> [[ObjectMethod]] **putKeyed** `($type,\%args)`
  98
  99 Put a hash of key=value pairs into the given type set in this meta, replacing any existing value with the same key.
 100
 101 For example,
 102
 103     $meta->putKeyed( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
 104
 105 ## <a name="ObjectMethod &lt;strong&gt;putAll*"></a><a name="ObjectMethod *putAll&lt;/strong&gt; "></a> [[ObjectMethod]] **putAll** ``
 106
 107 Replaces all the items of a given key with a new array.
 108
 109 For example,
 110
 111     $meta->putAll( 'FIELD',
 112          { name => 'MinAge', title => 'Min Age', value =>'50' },
 113          { name => 'MaxAge', title => 'Max Age', value =>'103' },
 114          { name => 'HairColour', title => 'Hair Colour', value =>'white' }
 115      );
 116
 117 ## <a name="ObjectMethod &lt;strong&gt;get&lt;/strong&gt; ($type,$key)"></a><a name="ObjectMethod &lt;strong&gt;get&lt;/strong&gt; ($type,$key) "></a> [[ObjectMethod]] **get** `($type,$key) -> \%hash`
 118
 119 Find the value of a meta-datum in the map. If the type is keyed (idenitifed by a `name`), the `$key` parameter is required to say _which_ entry you want. Otherwise you will just get the first value.
 120
 121 If you want all the keys of a given type use the 'find' method.
 122
 123 The result is a reference to the hash for the item.
 124
 125 For example,
 126
 127     my $ma = $meta->get( 'FIELD', 'MinAge' );
 128     my $topicinfo = $meta->get( 'TOPICINFO' ); # get the TOPICINFO hash
 129
 130 ## <a name="ObjectMethod &lt;strong&gt;find&lt;/strong&gt; ($type) - @v"></a> [[ObjectMethod]] **find** `($type) -> @values`
 131
 132 Get all meta data for a specific type. Returns the array stored for the type. This will be zero length if there are no entries.
 133
 134 For example,
 135
 136     my $attachments = $meta->find( 'FILEATTACHMENT' );
 137
 138 ## <a name="ObjectMethod &lt;strong&gt;remove&lt;/strong&gt; ($type,$ke"></a> [[ObjectMethod]] **remove** `($type,$key)`
 139
 140 With no type, will remove all the contents of the object.
 141
 142 With a $type but no $key, will remove _all_ items of that type (so for example if $type were FILEATTACHMENT it would remove all of them)
 143
 144 With a $type and a $key it will remove only the specific item.
 145
 146 ## <a name="ObjectMethod &lt;strong&gt;copyFrom&lt;/strong&gt; ($otherM"></a> [[ObjectMethod]] **copyFrom** `($otherMeta,$type,$nameFilter)`
 147
 148 Copy all entries of a type from another meta data set. This will destroy the old values for that type, unless the copied object doesn't contain entries for that type, in which case it will retain the old values.
 149
 150 If $type is undef, will copy ALL TYPES.
 151
 152 If $nameFilter is defined (a perl refular expression), it will copy only data where `{name}` matches $nameFilter.
 153
 154 Does **not** copy web, topic or text.
 155
 156 ## <a name="ObjectMethod &lt;strong&gt;count&lt;/strong&gt; ($type) - $"></a> [[ObjectMethod]] **count** `($type) -> $integer`
 157
 158 Return the number of entries of the given type
 159
 160 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo&lt;/strong&gt; "></a> [[ObjectMethod]] **getRevisionInfo** `($fromrev) -> ($date,$author,$rev,$comment)`
 161
 162 Try and get revision info from the meta information, or, if it is not present, kick down to the Store module for the same information.
 163
 164 Returns ( $revDate, $author, $rev, $comment )
 165
 166 $rev is an integer revision number.
 167
 168 ## <a name="ObjectMethod &lt;strong&gt;merge&lt;/strong&gt; ($otherMeta"></a> [[ObjectMethod]] **merge** `($otherMeta,$formDef)`
 169
 170 - `$otherMeta` - a block of meta-data to merge with $this
 171 - `$formDef` reference to a TWiki::Form that gives the types of the fields in $this
 172
 173 Merge the data in the other meta block.
 174
 175 - File attachments that only appear in one set are preserved.
 176 - Form fields that only appear in one set are preserved.
 177 - Form field values that are different in each set are text-merged
 178 - We don't merge for field attributes or title
 179 - Topic info is not touched
 180 - The `mergeable` method on the form def is used to determine if that fields is mergeable. if it isn't, the value currently in meta will _not_ be changed.
 181
 182 ## <a name="ObjectMethod &lt;strong&gt;stringify&lt;/strong&gt; ($types"></a> [[ObjectMethod]] **stringify** `($types) -> $string`
 183
 184 Return a string version of the meta object. Uses \\n to separate lines. If `$types` is specified, return only types that match it. Types should be a perl regular expression.
 185
 186 ## <a name="ObjectMethod &lt;strong&gt;for_EachSelectedVa"></a> [[ObjectMethod]] \*forEachSelectedValue `($types,$keys,\&fn,\%options)`
 187
 188 Iterate over the values selected by the regular expressions in $types and $keys.
 189
 190 - `$types` - regular expression matching the names of fields to be processed. Will default to qr/^[A-Z]+$/ if undef.
 191 - `$keys` - regular expression matching the names of keys to be processed. Will default to qr/^[a-z]+$/ if undef.
 192
 193 Iterates over each value, calling `\&fn` on each, and replacing the value with the result of \\&amp;fn.
 194
 195 \\%options will be passed on to $fn, with the following additions:
 196
 197 - `_type` =&gt; the type name (e.g. "FILEATTACHMENT")
 198 - `_key` =&gt; the key name (e.g. "user")
 199
 200 ## <a name="ObjectMethod &lt;strong&gt;getParent&lt;/strong&gt; () - $p"></a> [[ObjectMethod]] **getParent** `() -> $parent`
 201
 202 Gets the TOPICPARENT name.
 203
 204 ## <a name="ObjectMethod &lt;strong&gt;get_FormName&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getFormName** `() -> $formname`
 205
 206 Returns the name of the FORM, or '' if none.
 207
 208 ## <a name="ObjectMethod &lt;strong&gt;render_FormForDisp"></a> [[ObjectMethod]] \*renderFormForDisplay `() -> $html`
 209
 210 Render the form contained in the meta for display.
 211
 212 ## <a name="ObjectMethod &lt;strong&gt;render_FormFieldFo"></a> [[ObjectMethod]] \*renderFormFieldForDisplay `($name,$format,$attrs) -> $text`
 213
 214 Render a single formfield, using the $format. See TWiki::Form::FormField::renderForDisplay for a description of how the value is rendered.
 215
 216 ## <a name="ObjectMethod &lt;strong&gt;get_EmbeddedStoreF"></a> [[ObjectMethod]] \*getEmbeddedStoreForm `() -> $text`
 217
 218 Generate the embedded store form of the topic. The embedded store form has meta-data values embedded using %META: lines. The text stored in the meta is taken as the topic text.
 219
 220 ## <a name="ObjectMethod &lt;strong&gt;get_MetaFor&lt;/strong&gt; () -"></a><a name="ObjectMethod &lt;strong&gt;get_MetaFor&lt;/strong&gt; () - "></a> [[ObjectMethod]] **getMetaFor** `() -> $meta`
 221
 222 This method will load (or otherwise fetch) the meta-data for a named web/topic. The request might be satisfied by a read from the store, or it might be satisfied from a cache. The caller doesn't care.
 223
 224 This is an object method rather than a static method because it depends on the implementation of Meta - it might be this base class, or it might be a caching subclass, for example.