| Package =TWiki::Meta |
|
< < | Meta-data handling. |
> > | 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. |
|
A meta-data object is a hash of different types of meta-data (keyed on
the type, such as 'FIELD' and 'TOPICINFO'). |
| single meta-datum.
If there may be multiple entries of the same top-level type (i.e. for FIELD |
|
< < | and FILEATTACHMENT) then the array hash multiple entries. These types |
> > | 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.
For unkeyed types, the array has only one entry. |
|
< < | The module knows nothing about how meta-data is stored. That is entirely the
responsibility of the Store module. |
> > | Pictorially,
- TOPICINFO
- author => '...'
- date => '...'
- ...
- FILEATTACHMENT
- [0] -> { name => '...' ... }
- [1] -> { name => '...' ... }
- FIELD
- [0] -> { name => '...' ... }
- [1] -> { name => '...' ... }
|
| |
|
< < | Meta-data objects are created by the Store engine when topics are read. They
are populated using the put method. |
> > | As well as the meta-data, the object also stores the web name, topic
name and remaining text after meta-data extraction. |
|
|
|
< < | ClassMethod new ($session,$web,$topic) |
> > | ClassMethod new ($session,$web,$topic,$text)
-
$session - a TWiki object (e.g. =$TWiki::Plugins::SESSION)
-
$web , $topic - the topic that the metadata relates to
Construct a new, empty object to contain meta-data for the given topic.
- $text - optional raw text to convert to meta-data form
|
| |
|
< < | Construct a new, empty Meta collection. |
| |
|
> > |
Break circular references. |
| |
|
< < | |
> > |
Get the session
|
|
Get the web name
|
|
< < | |
> > | |
|
Get the topic name
|
|
> > |
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.
|
| |
|
< < | Put a hash of key=value pairs into the given type set in this meta. |
> > | 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 ) |
| |
|
< < | See the main comment for this package to understand how meta-data is
represented. |
> > | For example,
$meta->put( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
|
|
|
|
< < | Put a hash of key=value pairs into the given type set in this meta. The
entries are keyed by 'name'. |
> > | Put a hash of key=value pairs into the given type set in this meta, replacing
any existing value with the same key.
For example,
$meta->putKeyed( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
|
| |
|
< < | See the main comment for this package to understand how meta-data is
represented. |
|
|
|
< < | Replaces all the items of a given key with a new array
This is the logical inverse of the find method |
> > | Replaces all the items of a given key with a new array.
For example,
$meta->putAll( 'FIELD',
{ name => 'MinAge', title => 'Min Age', value =>'50' },
{ name => 'MaxAge', title => 'Max Age', value =>'103' },
{ name => 'HairColour', title => 'Hair Colour', value =>'white' }
);
|
|
ObjectMethod get ($type,$key) -> \%hash
Find the value of a meta-datum in the map. If the type is |
|
< < | keyed, the $key parameter is required to say which
entry you want. Otherwise it can be undef. |
> > | keyed (idenitifed by a name ), the $key parameter is required
to say which entry you want. Otherwise you will just get the first value. |
| |
|
< < | WARNING SMELL If key is undef but the type is keyed you get the FIRST entry |
| If you want all the keys of a given type use the 'find' method.
The result is a reference to the hash for the item. |
|
> > | For example,
my $ma = $meta->get( 'FIELD', 'MinAge' );
my $topicinfo = $meta->get( 'TOPICINFO' ); # get the TOPICINFO hash
|
|
|
|
< < | Get all meta data for a specific type |
> > | 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. |
|
> > | For example,
my $attachments = $meta->find( 'FILEATTACHMENT' );
|
| |
|
< < |
See tests/unit/MetaTests.pm for an example
The result is a hash the same as the array provided by find but keyed by the keyName.
NB. results are indeterminate if the key you choose is not unique in the find.
Flattens a keyed hash structure, taking only the values.
Returns a hash.
See tests/unit/MetaTests.pm for an example |
|
|
|
If $type is undef, will copy ALL TYPES. |
|
< < | If $nameFilter is defined (an RE), it will copy only data where
{name} matches $nameFilter. |
> > | If $nameFilter is defined (a perl refular expression), it will copy
only data where {name} matches $nameFilter. |
| |
|
< < | SMELL: This is a shallow copy |
> > | Does not copy web, topic or text. |
|
ObjectMethod count ($type) -> $integer |
|
< < | Return the number of entries of the given type that are in this meta set |
> > | Return the number of entries of the given type |
| |
| ObjectMethod stringify ($types) -> $string
Return a string version of the meta object. Uses \n to separate lines. |
|
< < | If $types is specified, return only types specified by that RE. |
> > | If $types is specified, return only types
that match it. Types should be a perl regular expression. |
| |
| Returns the name of the FORM, or '' if none. |
|
> > |
ObjectMethod *renderFormForDisplay () -> $html
Render the form contained in the meta for display.
ObjectMethod *renderFormFieldForDisplay ($name,$format,$attrs) -> $text
Render a single formfield, using the $format. See
TWiki::Form::FormField::renderForDisplay for a description of how the value
is rendered.
ObjectMethod *getEmbeddedStoreForm () -> $text
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.
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.
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. |