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 = new midcom_db_article($my_article_created_id);
 
 $meta =& midcom_helper_metadata::retrieve($article);
 $article->approve();
 ?>

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

Variable Summary

GUID $guid

MidgardObject $object

Array $_cache

midcom_helper_datamanager $_datamanager

string $_schemadb

Method Summary

midcom_helper_metadata midcom_helper_metadata (GUID $guid, mixed $object, string $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

GUID $guid = '' (line 86)

The guid of the object, it is cached for fast access to avoid repeated database queries.

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 94)

Holds the values alread read from the database.

access: private

midcom_helper_datamanager $_datamanager = null (line 110)

Datamanager instance for the given object.

access: private

string $_schemadb = null (line 102)

The schema database URL to use for this instance.

access: private

Methods

Constructor midcom_helper_metadata (line 129)

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 (GUID $guid, mixed $object, string $schemadb)

GUID $guid: The GUID of the object as it is in the global metadata object cache.
mixed $object: The MidgardObject ot attach to.
string $schemadb: The URL of the schemadb to use.

approve (line 546)

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 150)

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 171)

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 482)

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

return: Indicating approval state.

bool is_approved ()

is_object_visible_onsite (line 529)

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 500)

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 184)

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 330)

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 218)

void release_datamanager ()

retrieve (line 598)

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 242)

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 565)

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 380)

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.
Parameters are accessed using their midgard-created member variables instead of accessing the database using $object->parameter directly for performance reasons (this will implicitly use the NAP cache for these values as well. (Implementation note: Variable variables have to be used for this, as we have dots in the member name.)

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 Tue, 15 Aug 2006 12:44:23 +0300 by phpDocumentor 1.3.0RC3