Docs For Class midcom_helper

midcom_helper_metadata

Description

This class is an interface to the metadata of MidCOM objects. It is not to be instantinated directly, as a cache is in place to avoide duplicate metadata objects for the same Midgard Object. So, basically, each of these object is a singelton.

It will use an internal mechanism to cache repeated accesses to the same metadata key during its lifetime. (Invalidating this cache will be possible though.)

All metadata is identified by their string-based keys, the original MIDCOM_META_* constants are mapped to these new keys. This has been done to allow for easier extension.

Metadata Key Reference

See also the schema in /midcom/config/metadata_default.dat

timestamp schedule_start: The time upon which the object should be made visible. 0 for no restriction.
timestamp schedule_end: The time upon which the object should be made invisible. 0 for no restriction.
bool nav_noentry: Set this to true if you do not want this object to appear in the navigation without it beeing completly hidden.
bool hide: Set this to true to hide the object on-site, overriding scheduling.
string keywords: The keywords for this object, should be used for META HTML headers.
string description: A short description for this object, should be used for META HTML headers.
string robots: Search engine crawler instructions, one of '' (unset), 'noindex', 'index', 'follow' and 'nofollow'. See the corresponding META HTML header.
timestamp created: The creation time of the object, read-only unless an article is edited.
MidgardPerson creator: The person that created the object, read-only.
timestamp edited: The last-modified time of the object, read-only.
MidgardPerson editor: The person that modified the object, read-only.
timestamp approved: The time of approval of the object, or 0 if not approved. Set automatically through approve/unapprove.
MidgardPerson approver: The person that approved/unapproved the object. Set automatically through approve/unapprove.

Example Usage, Metadata Retrival

 <?php
 $nap = new midcom_helper_nav();
 $node = $nap->get_node($nap->get_current_node());
 
 $meta =& midcom_helper_metadata::retrieve($node[MIDCOM_NAV_GUID]);
 echo "Visible : " . $meta->is_visible() . "</br>";
 echo "Approved : " . $meta->is_approved() . "</br>";
 echo "Keywords: " . $meta->get('keywords') . "</br>";
 ?>

Example Usage, Approval

 <?php
 $article = mgd_get_article($my_article_created_id);
 
 $meta =& midcom_helper_metadata::retrieve($article);
 $article->approve();
 ?>

Located in /midcom/helper/metadata.php (line 70)

Variable Summary

MidgardObject $object

Array $_cache

midcom_helper_datamanager $_datamanager

Array $_schemadb

Method Summary

midcom_helper_metadata midcom_helper_metadata (mixed $object, Array $schemadb)

void approve ()

mixed get (string $key)

midcom_helper_datamanager &get_datamanager ()

bool is_approved ()

bool is_object_visible_onsite ()

bool is_visible ()

void load_datamanager ()

void on_update ([string $key = false])

void release_datamanager ()

midcom_helper_metadata &retrieve (mixed $source)

void set (string $key, mixed $value)

void unapprove ()

void _retrieve_value (string $key)

Variables

MidgardObject $object = null (line 78)

Object to which we are attached to. This object can be accessed from the outside, where neccessary.

Array $_cache = array() (line 86)

Holds the values alread read from the database.

access: private

midcom_helper_datamanager $_datamanager = null (line 102)

Datamanager instance for the given object.

access: private

Array $_schemadb = null (line 94)

The schema database to use for this instance.

access: private

Methods

Constructor midcom_helper_metadata (line 120)

This will construct a new metadata object for an existing content object.

You must never use this constructor directly, it is considered private in this respect. Instead, use the get method, which may be called as a class method.

You may use objects derived from any MidgardObject will do as well as long as the parameter call is available normally.

access: private
see: midcom_helper_metadata::get()

midcom_helper_metadata midcom_helper_metadata (mixed $object, Array $schemadb)

mixed $object: The MidgardObject ot attach to.
Array $schemadb: The schemadb to use.

approve (line 493)

Approves the object.

This sets the approved timestamp to the current time and the approver person GUID to the GUID of the person currently authenticated.

void approve ()

get (line 140)

This function will return a single metadata key from the object. Its return type depends on the metadata key that is requested (see the class introduction).

You will not get the data from the datamanager using this calls, but the only slightly post-processed metadata values. See _retrieve_value for post processing.

return: The key's value.
see: midcom_helper_metdata::_retrieve_value();

mixed get (string $key)

string $key: The key to retrieve

get_datamanager (line 161)

Return a Datamanager instance for the current object.

This is returned by reference, which must be honored, as usual.

Also, whenever the containing datamanager stores its data, you must call the on_update() method of this class. This is very important or backwards compatibility will be broken.

return: A initialized Datamanager instance for the selected object.
see: midcom_helper_metadata::on_update()

midcom_helper_datamanager &get_datamanager ()

is_approved (line 428)

Checks wether the article has been approved since its last editing.

return: Indicating approval state.

bool is_approved ()

is_object_visible_onsite (line 475)

This is a helper function which indicates wether a given object may be shown onsite taking approval, scheduling and visibility settings into account. The important point here is that it also checks the global configuration defaults, so that this is basically the same base on which NAP decides wether to show an item or not.

return: Indicating visibility.

bool is_object_visible_onsite ()

is_visible (line 446)

Checks the object's visibility regarding scheduling and the hide flag.

This does not check approval, use is_approved for that.

return: Indicatinv visibility state.
see: midcom_helper_metadata::is_approved()

bool is_visible ()

load_datamanager (line 174)

Loads the datamanager for this instance. This will patch the schema in case we are dealing with an article.

void load_datamanager ()

on_update (line 304)

This is the update event handler for the Metadata system. It must be called whenever metadata changes to synchronize the various backwards-compatibility values in place throughout the system.

void on_update ([string $key = false])

string $key: The key that was updated. Leave empty for a complete update by the Datamanger.

release_datamanager (line 198)

void release_datamanager ()

retrieve (line 537)

Returns a metadata object for a given content object.

You may bass any one of the following arguments to the function:

Any class derived from MidgardObject, you must only ensure, that the parameter and guid member functions stays available.
Any valid GUID
Any NAP object structure, the content object is deduced from MIDCOM_NAV_GUID in this case.

Important note: The metadata object is returned by reference. You are very much encouraged to honor this reference, otherwise, the internal metadata value cache won't really help.

return: A reference to the created metadata object.

midcom_helper_metadata &retrieve (mixed $source)

mixed $source: The object to attach to, this may be either a MidgardObject, a GUID or a NAP data structure (node or leaf).

set (line 222)

Directly set a metadata option.

The passed value will be stored using the follow transformations:

Storing into the approver field will automatically recognize Person Objects and simple IDs and transform them into a GUID.
created can only be set with articles.
creator, editor and edited cannot be set.

Any error will trigger generate_error.

void set (string $key, mixed $value)

string $key: The key to set.
mixed $value: The value to set.

unapprove (line 508)

Unapproves the object.

This resets the approved timestamp and sets the approver person GUID to the GUID of the person currently authenticated.

void unapprove ()

_retrieve_value (line 351)

Retrieves a given metadata key, postprocesses it where neccessary and stores it into the local cache.

Person references (both guid and id) get resolved into the corresponding Person object.
created, creator, edited and editor are taken from the corresponding MidgardObject fields.

Note, that we hide any errors from not existant properties explicitly, as a few of the MidCOM objects do not support all of the predefined meta data fields, PHP will default to "0" in these cases. For Person IDs, this "0" is rewritten to "1" to use the MidgardAdministrator account instead.

access: private

void _retrieve_value (string $key)

string $key: The key to retrive.

Documentation generated on Mon, 21 Nov 2005 18:18:32 +0100 by phpDocumentor 1.3.0RC3