This class is an interface to the metadata of MidCOM objects.

It is not to be instantiated directly, as a cache is in place to avoid duplicate metadata objects for the same Midgard Object. So, basically, each of these objects is a singleton.

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

Metadata Key Reference

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

  • timestamp schedulestart: The time upon which the object should be made visible. 0 for no restriction.
  • timestamp scheduleend: The time upon which the object should be made invisible. 0 for no restriction.
  • boolean navnoentry: Set this to true if you do not want this object to appear in the navigation without it being completely hidden.
  • boolean 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 published: The publication time of the object, read-only.
  • MidgardPerson publisher: The person that published the object (i.e. author), read-only except on articles and pages.
  • 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 revised: The last-modified time of the object, read-only.
  • MidgardPerson revisor: 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 Retrieval

get_node($nap->get_current_node());

$meta = midcom_helper_metadata::retrieve($node[MIDCOM_NAV_GUID]);
echo "Visible : " . $meta->is_visible() . "
"; echo "Approved : " . $meta->is_approved() . "
"; echo "Keywords: " . $meta->get('keywords') . "
"; ?>

Example Usage, Approval

approve();
?>
package midcom.helper

 Methods

__construct (\GUID $guid, mixed $object, string $schemadb)

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.

see \midcom_helper_metadata::get()

Parameters

$guid

\GUIDThe GUID of the object as it is in the global metadata object cache.

$object

mixedThe MidgardObject to attach to.

$schemadb

stringThe URL of the schemadb to use.

__get ($key)

Parameters

$key

__isset ($key)

Parameters

$key

__set ($key, $value)

Parameters

$key

$value

approve ()

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.

can_unlock ()

Check whether current user can unlock the object
todo enable specifying user ?

Returns

booleanindicating privileges

find_schemaname (array $schemadb, \midcom_core_dbaobject $object)

Helper function to determine the schema to use for a particular object
Static

Parameters

$schemadb

arrayThe schema DB

$object

\midcom_core_dbaobjectthe object to work on

Returns

stringThe schema name

force_approve ()

Approve, if object is already approved update and approve.

This is to get the approval timestamp to current time in all cases

get (string $key)

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.

see \midcom_helper_metdata::_retrieve_value()

Parameters

$key

stringThe key to retrieve

Returns

mixedThe key's value.

get_datamanager ()

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.

see \midcom_helper_metadata::on_update()

Returns

\midcom_helper_datamanager2A initialized Datamanager instance for the selected object.

is_approved ()

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

Returns

booleanIndicating approval state.

is_locked ()

Check if the requested object is locked

Returns

booleanTrue if the object is locked, false if it isn't

is_object_visible_onsite ()

This is a helper function which indicates whether 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 whether to show an item or not.

Returns

booleanIndicating visibility.

is_visible ()

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

This does not check approval, use is_approved for that.

see \midcom_helper_metadata::is_approved()

Returns

booleanIndicating visibility state.

load_datamanager ()

Loads the datamanager for this instance.

This will patch the schema in case we are dealing with an article.

lock (int $timeout, String $user)

Set the object lock

Parameters

$timeout

intLength of the lock timeout

$user

StringGUID of the midgard_person object

Returns

booleanIndicating success

on_update (string $key)

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.

Parameters

$key

stringThe key that was updated. Leave empty for a complete update by the Datamanager.

release_datamanager ()

retrieve (mixed $source)

Returns a metadata object for a given content object.
Static

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.

Parameters

$source

mixedThe object to attach to, this may be either a MidgardObject, a GUID or a NAP data structure (node or leaf).

Returns

\midcom_helper_metadataA reference to the created metadata object.

set (string $key, mixed $value)

Frontend for setting a single metadata option

Parameters

$key

stringThe key to set.

$value

mixedThe value to set.

set_multiple (array $properties)

Frontend for setting multiple metadata options

Parameters

$properties

arrayArray of key => value properties.

unapprove ()

Unapproves the object.

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

unlock (boolean $soft_unlock)

Unlock the object

Parameters

$soft_unlock

booleanIf this is true, the changes are not written to disk

Returns

booleanIndicating success

_retrieve_value (string $key)

Retrieves a given metadata key, postprocesses it where necessary 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 existent 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.

Parameters

$key

stringThe key to retrieve.

_set_property (string $key, mixed $value)

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 midcom_error.

Parameters

$key

stringThe key to set.

$value

mixedThe value to set.

 Properties

 

\MidgardObject $__object

Object to which we are attached to.

This object can be accessed from the outside, where necessary.

 

string $guid

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

Array $_cache

Holds the values already read from the database.
 

\midcom_helper_datamanager2 $_datamanager

Datamanager instance for the given object.
 

string $_schemadb_path

The schema database URL to use for this instance.