Docs For Class midcom_helper_

midcom_helper__basicnav

Description

This class is the basic building stone of the Navigation Access Point System of MidCOM.

It is responsible for collecting the available Information and for building the navigational Tree out of it. This class is only the internal interface to the NAP System and is used by midcom_helper_nav as a node cache. The framework should ensure that only one class of this type is active at one time.

Basicnav will give you a very abstract view of the content tree, modified by the NAP classes of the components. You can retrieve a node/leaf tree of the content, and for each element you can retrieve an URL name and a long name for Navigation display.

Leaves and Nodes are both indexed by Integer constants which are assigned by the framework. The framework defines two starting points in this tree: The root node and the "current" node. The current node defined through the topic of the component that declared to be able to handle the request.

The class will load the neccessary information on demand to minimize database traffic.

The interface functions should enable you to build any navigation tree you desire. The public nav class will give you some of those high-level functions.

Node data interchange format

Node NAP data consists of a simple key => value array with the following keys required by the component:

MIDCOM_NAV_NAME => The Real (= displayable) name of the element
MIDCOM_NAV_TOOLBAR => Toolbar data (see below)
MIDCOM_META_CREATOR => Creator of the element (MidgardPerson)
MIDCOM_META_CREATED => Creation date (UNIX Timestamp)
MIDCOM_META_EDITOR => Last modifier of the element (MidgardPerson)
MIDCOM_META_EDITED => Last modification date (UNIX Timestamp)

Other keys delivered to NAP users include:

MIDCOM_NAV_URL => The URL name of the element, which is automatically defined by NAP.

Leaf data interchaneg format

Basically for each leaf the usual meta information is returned:

MIDCOM_META_CREATOR => Creator of the element (MidgardPerson)
MIDCOM_META_CREATED => Creation date (UNIX Timestamp)
MIDCOM_META_EDITOR => Last modifier of the element (MidgardPerson)
MIDCOM_META_EDITED => Last modification date (UNIX Timestamp)
MIDCOM_NAV_GUID => Optional argument denoting the GUID of the referred element
MIDCOM_NAV_TOOLBAR => Toolbar data (see below)

MidCOM NAP has reduced the separation of Admin Mode and Site Mode NAP Data. Both Site- and Administrative Mode data is now delivered to NAP (and from there to the NAP user) in a single call. This is done by creating two sub-arrays retrievable under the keys MIDCOM_NAV_SITE and MIDCOM_NAV_ADMIN. Both of those arrays contain MIDCOM_NAV_URL and MIDCOM_NAV_NAME values. For compatibility and ease of use the top-level entries of MIDCOM_NAV_NAME and MIDCOM_NAV_URL are still existent and in use. Therefore, three possible constellation exist:

1) Both Values present

 MIDCOM_NAV_SITE => Array (MIDCOM_NAV_URL, MIDCOM_NAV_NAME),
 MIDCOM_NAV_ADMIN => Array (MIDCOM_NAV_URL, MIDCOM_NAV_NAME),
 [... all other tags ...]

The top-level entries MIDCOM_NAV_NAME and _URL will be automatically popluated according to Admin- or non-Admin mode, so that the displaying code for all standard-situations won't have to consider this difference.

2) One element omitted

If any Element does have only one of those pairs (like a "Create New Category"-Link for example), set the unavailable Array Entry to null:

 MIDCOM_NAV_SITE => null,
 MIDCOM_NAV_ADMIN => Array (MIDCOM_NAV_URL, MIDCOM_NAV_NAME),
 [... all other tags ...]

Note, that if one of the elements is missing like outlined above, the list-methods of NAP will not show them in the corresponding mode. The element of the above example would only be included in the listings if the system was running in Admin-Mode. Copying of the primary values will still happen like in (1).

3) Compatibility syntax

For ease-of-use and for backwards compatibility, you can deliver an old style data like this:

 MIDCOM_NAV_URL => "blah",
 MIDCOM_NAV_NAME => "blubb",
 [... all other tags ...]

The Datamanger will automatically transform (3) to the syntax described in (1) by copying the values.

Important note: The difference outlined above is only valid for leaves (read "articles"), because the topic structure is essentially the same in both AIS and live Site.

Toolbar Syntax

You can add toolbars to your NAP information, that can be used for simple on-site editing. They are indexed using integers and consist of an midcom_helper_toolbar::add_item() compatible array with one exception: The URL is always realtive to the AIS topic welcome page, but see the example (it assumes that the referenced l10n libraries are available, of course):

 $toolbar[0] = Array (
     MIDCOM_TOOLBAR_URL =&gt; '',
     MIDCOM_TOOLBAR_LABEL =&gt; $this-&gt;_l10n-&gt;get('create article'),
     MIDCOM_TOOLBAR_HELPTEXT =&gt; null,
     MIDCOM_TOOLBAR_ICON =&gt; 'stock-icons/16x16/stock_new.png',
     MIDCOM_TOOLBAR_ENABLED =&gt; true
 );
 $toolbar[100] = Array(
     MIDCOM_TOOLBAR_URL =&gt; 'config.html',
     MIDCOM_TOOLBAR_LABEL =&gt; $this-&gt;_l10n_midcom-&gt;get('component configuration'),
     MIDCOM_TOOLBAR_HELPTEXT =&gt; $this-&gt;_l10n_midcom-&gt;get('component configuration helptext'),
     MIDCOM_TOOLBAR_ICON =&gt; 'stock-icons/16x16/stock_folder-properties.png',
     MIDCOM_TOOLBAR_ENABLED =&gt; true
 );

You can now use a similar in your leaf data and place further buttons between these two using indexes like 50,51,52.

DEPRECATED INFORMATION

The key MIDCOM_NAV_VISIBLE is deprecated from MidCOM 2.4.0 on, visibility is taken into account automatically. The key is set to true for all values now for backwards compatibility and will be removed entirely in MidCOM 2.6.0

todo: Bring the information from http://www.nathan-syntronics.de/midgard/midcom_fs-transition/nap-update.html somehow into this.

Located in /midcom/helper/_basicnav.php (line 158)

Variable Summary

bool $_adminmode

int $_current

int $_currentleaf

Array $_guid_map

int $_lastgoodnode

Array $_leaves

Array $_loaded_leaves

midcom_helper__componentloader $_loader

midcom_services_cache_backend $_nap_cache

Array $_nodes

int $_root

Method Summary

midcom_helper__basicnav midcom_helper__basicnav (int $context)

int get_current_leaf ()

int get_current_node ()

Array get_leaf (string $leaf_id)

int get_leaf_uplink (string $leaf_id)

Array get_loaded_object_by_guid (GUID $guid)

Array get_node (int $node_id)

int get_node_uplink (int $node_id)

int get_root_node ()

Array get_toolbar_definition (Array $nap_object)

Array list_leaves (int $parent_node, bool $show_noentry)

Array list_nodes (int $parent_node, bool $show_noentry)

bool _check_leaf_id (string $leaf_id)

Array _get_leaves (Array $node)

Array _get_leaves_from_database (Array $node)

Array _get_node (int $id)

Array _get_node_from_database (int $id)

bool _is_object_visible (Array $napdata)

int _loadNode (mixed $node_id, int $nodeid)

int _loadNodeData (mixed $param, [bool $idmode = true])

void _load_leaves (Array $node)

void _update_leaflist_urls (Array &$leaves)

void _write_leaves_to_cache (Array $node, Array $leaves)

Variables

bool $_adminmode (line 260)

This one is true, if the system is in content administration mode and therefore working with a different topic. See Constructor Documentation for details.

Internal runtime state variable.

access: private

int $_current (line 179)

The GUID of the currently active Navigation Node, determied by the active MidCOM Topic or one of its uplinks, if the subtree in question is invisible.

NAP data variable.

access: private

int $_currentleaf (line 186)

The GUID of the currently active leaf.

NAP data variable.

access: private

Array $_guid_map = array() (line 228)

This map tracks all loaded GUIDs along with their NAP structures. This cache is used by nav's resolve_guid function to short-circut already known GUIDs.

NAP data variable.

access: private

int $_lastgoodnode (line 269)

This is a temporary storage where _loadNode can return the last known good node in case the current node not visible. It is evaluated by the constructor.

Internal runtime state variable.

access: private

Array $_leaves (line 203)

This is the leaf cache. It is an array which contains elements indexed by their leaf ID. The data is again stored in an accociative array:

NAP data variable.

MIDCOM_NAV_NODEID => ID of the parent node (int)
MIDCOM_NAV_URL => URL name of the leaf (string)
MIDCOM_NAV_NAME => Textual name of the leaf (string)
MIDCOM_META_CREATOR => Creator of the element (MidgardPerson)
MIDCOM_META_CREATED => Creation date (UNIX Timestamp)
MIDCOM_META_EDITOR => Last modifier of the element (MidgardPerson)
MIDCOM_META_EDITED => Last modification date (UNIX Timestamp)

todo: Update the data structure documentation
access: private

Array $_loaded_leaves = array() (line 237)

This array holds a list of all topics for which the leaves have been loaded.

NAP data variable.

If the id of the node is in this array, the leaves are available, otheriwise, the leaves ahve to be loaded.

access: private

midcom_helper__componentloader $_loader (line 252)

This is a reference to the systemwide component loader class.

Internal runtime state variable.

access: private

midcom_services_cache_backend $_nap_cache = null (line 276)

A reference to the NAP cache store

Internal runtime state variable.

access: private

Array $_nodes (line 220)

This is the node cache. It is an array which contains elements indexed by their node ID. The data is again stored in an accociative array:

NAP data variable.

MIDCOM_NAV_NODEID => ID of the parent node (-1 for the root node) (int)
MIDCOM_NAV_URL => URL name of the leaf (string)
MIDCOM_NAV_NAME => Textual name of the leaf (string)
MIDCOM_META_CREATOR => Creator of the element (MidgardPerson)
MIDCOM_META_CREATED => Creation date (UNIX Timestamp)
MIDCOM_META_EDITOR => Last modifier of the element (MidgardPerson)
MIDCOM_META_EDITED => Last modification date (UNIX Timestamp)

todo: Update the data structure documentation
access: private

int $_root (line 171)

The GUID of the MidCOM Root Content Topic

NAP data variable.

access: private

Methods

Constructor midcom_helper__basicnav (line 1071)

Constructor

The only constructor of the Basicnav class. It will initialize Root-Topic, Current-Topic and all cache arrays. The function will load all nodes between root and current node.

If the current node is behind an invisible or undecendable node, the last known good node will be used instead for the current node.

The constructor retrievs all initialisation data from the component context. A special process is used, if the context in question is of the type MIDCOM_REQUEST_CONTENTADM: The system then goes into Administration Mode, querying the components for the administrative data instead of their regular data. In addition, the root topic is set to the administrated topic instead of the regular root topic. This way you can build up Admin Interface Navigation for "external" trees.

midcom_helper__basicnav midcom_helper__basicnav (int $context)

int $context: The Context ID for which to create NAP data for, defaults to 0

get_current_leaf (line 1152)

Retrieve the ID of the currently displayed leaf. This is a leaf that is displayed by the handling topic. If no leaf is active, this function returns FALSE. (Remeber to make a type sensitve check, e.g.

nav::get_current_leaf() !== false to distinguish "0" and "false".)

return: The ID of the leaf in question or false on failure.

int get_current_leaf ()

get_current_node (line 1138)

Retrieve the ID of the currently displayed node. Defined by the topic of the component that declared able to handle the request.

return: The ID of the node in question.

int get_current_node ()

get_leaf (line 1366)

This will give you a key-value pair describeing the leaf with the ID $node_id. The defined keys are described above in leaf data interchange format. You will get false if the leaf ID is invalid.

return: The leaf-data as outlined in the class introduction, false on failure

Array get_leaf (string $leaf_id)

string $leaf_id: The leaf-id to be retrieved.

get_leaf_uplink (line 1410)

Returns the ID of the node to which $leaf_id is accociated to, false on failure.

return: The ID of the Node for which we have a match, or false on failure.

int get_leaf_uplink (string $leaf_id)

string $leaf_id: The Leaf-ID to search an uplink for.

get_loaded_object_by_guid (line 1393)

This is a helper function used by midcom_helper_nav::resolve_guid(). It checks if the object denoted by the passed GUID is already loaded into memory and returns it, if available. This should speed up GUID lookup heavy code.

Access is restricted to midcom_helper_nav::resolve_guid().

return: A NAP structure if the GUID is known, null otherwise.
access: protected

Array get_loaded_object_by_guid (GUID $guid)

GUID $guid: The GUID to look up in the in-memory cache.

get_node (line 1296)

This will give you a key-value pair describeing the node with the ID $node_id. The defined keys are described above in Node data interchange format. You will get false if the node ID is invalid.

return: The node-data as outlined in the class introduction, false on failure

Array get_node (int $node_id)

int $node_id: The node-id to be retrieved.

get_node_uplink (line 1434)

Returns the ID of the node to which $node_id is accociated to, false on failure. The root node's uplink is -1.

return: The ID of the Node for which we have a match, -1 for the root node, or false on failure.

int get_node_uplink (int $node_id)

int $node_id: The Leaf-ID to search an uplink for.

get_root_node (line 1166)

Retrieve the ID of the root node. Note that this ID is dependent from the ID of the MidCOM Root topic and therefore will change as easily as the root topic ID might. The MIDCOM_NAV_URL entry of the root node's data will always be empty.

return: The ID of the root node.

int get_root_node ()

get_toolbar_definition (line 1483)

This function returns the toolbar definition for the NAP object passed. This must superseed all calls to $nap_object[MIDCOM_NAV_TOOLBAR] as this information is not usable directly - it would result from the MidCOM cache and thus be out of date always (and especially not adapted to the current user).

Implementation note: This is a hotfix, that works around the current problem. It is not very performant if you query large numbers of NAP toolbars at this time. We have some basic caching in this function, but nevertheless we need a better solution here.

return: Toolbar definition array as originally stored in the MIDCOM_NAV_TOOLBAR key (so this can be null as well).

Array get_toolbar_definition (Array $nap_object)

Array $nap_object: The NAP data structure of the object for which a toolbar should be retrieved.

list_leaves (line 1248)

Lists all leaves of $parent_node. If there are no leaves you will get an empty array, if there was an error (for instance an unknown parent node ID) you will get FALSE.

return: A list of leaves found, or false on failure.

Array list_leaves (int $parent_node, bool $show_noentry)

int $parent_node: The ID of the node of which the leaves are searched.
bool $show_noentry: Show all objects on-site which have the noentry flag set. This parameter has no effect in AIS.

list_nodes (line 1181)

Lists all Sub-nodes of $parent_node. If there are no subnodes you will get an empty array, if there was an error (for instance an unkown parent node ID) you will get FALSE.

return: An Array of Node IDs or false on failure.

Array list_nodes (int $parent_node, bool $show_noentry)

int $parent_node: The id of the node of which the subnodes are searched.
bool $show_noentry: Show all objects on-site which have the noentry flag set. This parameter has no effect in AIS.

_check_leaf_id (line 1327)

Verifies the existence of a given leaf. Call this before getting a leaf from the $_leaves cache. It will load all neccessary nodes/leaves as neccessary.

return: true if the leaf exists, false otherwise.

bool _check_leaf_id (string $leaf_id)

string $leaf_id: A valid NAP leaf id ($nodeid-$leafid pattern).

_get_leaves (line 466)

Return the list of leaves for a given node. This helper will construct complete leaf data structures for each leaf found. It will first check the cache for the leaf structures, and query the database only if the corresponding objects have not been found there.

No visibility checks are made at this point.

return: All leaves found for that node, in complete post processed leave data structures.
access: private

Array _get_leaves (Array $node)

Array $node: The node data structure for which to retrieve the leaves.

_get_leaves_from_database (line 616)

This helper is responsible for loading the leaves for a given node out of the database. It will complete all default fields to provide full blown nap structures.

It will also build the base relative URLs which will later be completed by the _get_leaves() interface functions.

Important notes:

The ViewerGroups property is copied from the parent topic, to ensure the same level of visibility.
The IDs constructed for the leaves are the concatenation of the ID delivered by the component and the topics' GUID.

return: All leaves found for that node, in complete post processed leave data structures.
access: private

Array _get_leaves_from_database (Array $node)

Array $node: The node data structure for which to retrieve the leaves.

_get_node (line 293)

This helper object will construct a complete node data structure for a given topic, without any dependant objects like subtopics or leaves. It does not do any visibility checks, it just prepares the object for later processing.

This code is NAP cache aware, if the resulting information is already in the NAP cache, it is retrieved from there.

return: NAP node data structure or NULL in case no NAP information is available for this topic.
access: private

Array _get_node (int $id)

int $id: The ID of the topic for which the NAP information is requested.

_get_node_from_database (line 346)

Reads a node data structure from the database, completes all defaults and derived properties (like ViewerGroups).

return: Node data structure or NULL in case no NAP information is available for this topic.
access: private

Array _get_node_from_database (int $id)

int $id: The ID of the topic for which the NAP information is requested.

_is_object_visible (line 746)

Checks, if the NAP object indicated by $napdata is visible within the current runtime environment. It will work with both nodes and leaves.

This includes checks for:

Nonexistant NAP information (null values)
Viewergroups
Scheduling/Hiding (only on-site)
Approval (only on-site)

return: Indicating visibility.
access: private

bool _is_object_visible (Array $napdata)

Array $napdata: The NAP data structure for the object to check (supports NULL values).

_loadNode (line 956)

This function is the controlling instance of the loading mechanism. It

is able to load the navigation data of any topic within MidCOMs topic tree into memory. Any uplink nodes that are not loaded into memory will be loaded until any other known topic is encountered. After the neccessary data has been loaded with calls to _loadNodeData.

If all load calls were successful, MIDCOM_ERROK is returned. Any error will be indicated with a corresponding return value and an error message in $midcom_errstr.

return: MIDCOM_ERROK on succes, one of the MIDCOM_ERR... constants upon an error
access: private

int _loadNode (mixed $node_id, int $nodeid)

int $nodeid: The ID of the topic to be loaded

_loadNodeData (line 854)

Load the Navigational information accociated with the topic $param, which can be passed as an ID or as a MidgardTopic object. This is differentiated by the flag $idmode (true for id, false for MidgardTopic).

This method does query the topic for all information and completes it to build up a full NAP data structure

It determines the URL_NAME of the topic automatically using the name of the topic in question.

The currently active leaf is only queried if and only if the currently processed topic is equal to the current context's content topic. This should prevent dynamically loaded components from disrupting active leaf information, as this can happen if dynamic_load is called before showing the navigation.

return: One of the MGD_ERR constants

int _loadNodeData (mixed $param, [bool $idmode = true])

mixed $param: Topic to be processed.
bool $idmode: $param is an integer if true, an MidgardTopic otherwise.

_load_leaves (line 913)

Loads the leaves for a given node from the cache or database.

It will relay the code to _get_leaves() and check the object visibility upon return.

void _load_leaves (Array $node)

Array $node: The NAP node data structure to load the nodes for.

_update_leaflist_urls (line 512)

This helper updates the URLs in the reference-passed leaf list.

FULLURL, ABSOLUTEURL and PERMALINK are built upon RELATIVEURL, NAV_NAME and NAV_URL are populated based on the administration mode with either NAV_ADMIN or NAV_SITE values.

access: private

void _update_leaflist_urls (Array &$leaves)

Array $leaves: A reference to the list of leaves which has to be processed.

_write_leaves_to_cache (line 567)

Writes the leaves passed to this function to the cache, assigning them to the specified node.

The function will bail out on any critical error. Data inconsistencies will be logged and overwritten silently otherwise.

access: private

void _write_leaves_to_cache (Array $node, Array $leaves)

Array $node: The node datastructure to which the leaves should be assigned.
Array $leaves: The leaves to store in the cache.

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