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.

It 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 a 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 necessary 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

Other keys delivered to NAP users include:

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

Leaf data interchange format

Basically for each leaf the usual meta information is returned:

  • MIDCOM_NAV_URL => URL of the leaf element
  • MIDCOM_NAV_NAME => Name of the leaf element
  • MIDCOM_NAV_GUID => Optional argument denoting the GUID of the referred element
  • MIDCOM_NAV_SORTABLE => Optional argument denoting whether the element is sortable

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

package midcom.helper

 Methods

__construct (int $context)

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 undescendable node, the last known good node will be used instead for the current node.

The constructor retrieves all initialization data from the component context.

Parameters

$context

intThe Context ID for which to create NAP data for, defaults to 0

get_current_leaf ()

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. (Remember to make a type sensitive check, e.g. nav::get_current_leaf() !== false to distinguish "0" and "false".)

Returns

stringThe ID of the leaf in question or false on failure.

get_current_node ()

Retrieve the ID of the currently displayed node.

Defined by the topic of the component that declared able to handle the request.

Returns

mixedThe ID of the node in question.

get_current_upper_node ()

Retrieve the ID of the upper node of the currently displayed node.

Returns

mixedThe ID of the node in question.

get_leaf (string $leaf_id)

This will give you a key-value pair describing 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.

Parameters

$leaf_id

stringThe leaf-id to be retrieved.

Returns

ArrayThe leaf-data as outlined in the class introduction, false on failure

get_loaded_object_by_guid (string $guid)

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.

Parameters

$guid

stringThe GUID to look up in the NAP cache.

Returns

ArrayA NAP structure if the GUID is known, null otherwise.

get_node (mixed $node_id)

This will give you a key-value pair describing 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.

Parameters

$node_id

mixedThe node ID to be retrieved.

Returns

ArrayThe node data as outlined in the class introduction, false on failure

get_node_path ()

Retrieve the IDs of the nodes from the URL.

First value at key 0 is the root node ID, possible second value is the first subnode ID etc. Contains only visible nodes (nodes which can be loaded).

Returns

ArrayThe node path array.

get_root_node ()

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.

Returns

intThe ID of the root node.

list_leaves (mixed $parent_node, boolean $show_noentry)

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.

Parameters

$parent_node

mixedThe ID of the node of which the leaves are searched.

$show_noentry

booleanShow all objects on-site which have the noentry flag set.

Returns

ArrayA list of leaves found, or false on failure.

list_nodes (mixed $parent_node, boolean $show_noentry)

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 unknown parent node ID) you will get false.

Parameters

$parent_node

mixedThe ID of the node of which the subnodes are searched.

$show_noentry

booleanShow all objects on-site which have the noentry flag set.

Returns

ArrayAn array of node IDs or false on failure.

_check_leaf_id (string $leaf_id)

Verifies the existence of a given leaf.

Call this before getting a leaf from the $_leaves cache. It will load all necessary nodes/leaves as necessary.

Parameters

$leaf_id

stringA valid NAP leaf id ($nodeid-$leafid pattern).

Returns

booleantrue if the leaf exists, false otherwise.

_get_leaves (array $node)

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.

Parameters

$node

arrayThe node data structure for which to retrieve the leaves.

Returns

ArrayAll leaves found for that node, in complete post processed leave data structures.

_get_leaves_from_database (array $node)

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 note: - The IDs constructed for the leaves are the concatenation of the ID delivered by the component and the topics' GUID.

Parameters

$node

arrayThe node data structure for which to retrieve the leaves.

Returns

ArrayAll leaves found for that node, in complete post processed leave data structures.

_get_node (mixed $topic_id, mixed $up)

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.

Parameters

$topic_id

mixedThe node ID for which the NAP information is requested.

$up

mixedThe node ID of the parent node. Optional and not normally needed.

Returns

ArrayNAP node data structure or null in case no NAP information is available for this topic.

_get_node_from_database (mixed $topic_id, mixed $up)

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

If the topic is missing a component, it will set the component to midcom.core.nullcomponent.

Parameters

$topic_id

mixedThe ID of the node for which the NAP information is requested.

$up

mixedThe node ID of the parent node. Optional and not normally needed.

Returns

ArrayNode data structure or null in case no NAP information is available for this topic.

_get_parent_id (integer $topic_id)

Small helper to determine a topic's parent id without loading the full object

Parameters

$topic_id

integerThe topic ID

Returns

integerThe parent ID or false

_get_subnodes ($parent_node)

Parameters

$parent_node

_is_object_visible (array $napdata)

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:

  • Nonexistent NAP information (null values)
  • Scheduling/Hiding (only on-site)
  • Approval (only on-site)

Parameters

$napdata

arrayThe NAP data structure for the object to check (supports null values).

Returns

booleanIndicating visibility.

_loadNode (mixed $node_id, mixed $up)

This function is the controlling instance of the loading mechanism.

It is able to load the navigation data of any topic within MidCOM's 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 necessary 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.

Parameters

$node_id

mixedThe node ID of the node to be loaded

$up

mixedThe node ID of the parent node. Optional and not normally needed.

Returns

intMIDCOM_ERROK on success, one of the MIDCOM_ERR... constants upon an error

_loadNodeData (mixed $topic_id, $up)

Load the navigational information associated 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.

Parameters

$topic_id

mixedTopic ID to be processed

$up

Returns

intOne of the MGD_ERR constants

_load_leaves (array $node)

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.

Parameters

$node

arrayThe NAP node data structure to load the nodes for.

_nodeid (int $topic_id, mixed $up)

Generate node ID from topic ID and up value.

Parameters

$topic_id

intTopic ID.

$up

mixedThe up part.

Returns

mixedThe generated node ID.

_up (mixed $nodeid)

Retrieve the up part from the given node ID.

(To get the topic ID part, just cast the node ID to int with (int). That's why there's no method for that. :))

Parameters

$nodeid

mixedThe node ID.

Returns

mixedThe up part.

_update_leaflist_urls (array $leaves)

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 NAV_SITE values

Parameters

$leaves

arrayA reference to the list of leaves which has to be processed.

_write_leaves_to_cache (array $node, array $leaves)

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.

Parameters

$node

arrayThe node data structure to which the leaves should be assigned.

$leaves

arrayThe leaves to store in the cache.

 Properties

 

int $_current

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

string $_currentleaf

The GUID of the currently active leaf.
 

int $_lastgoodnode

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.

 

Array $_leaves

This is the leaf cache.

It is an array which contains elements indexed by their leaf ID. The data is again stored in an associative array:

  • 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)
todo Update the data structure documentation
 

Array $_loaded_leaves

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

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

 

\midcom_helper__componentloader $_loader

This is a reference to the systemwide component loader class.
 

\midcom_services_cache_module_nap $_nap_cache

A reference to the NAP cache store
 

Array $_node_path

This array holds the node path from the URL.

First value at key 0 is the root node ID, possible second value is the first subnode ID etc. Contains only visible nodes (nodes which can be loaded).

 

Array $_nodes

This is the node cache.

It is an array which contains elements indexed by their node ID. The data is again stored in an associative array:

  • 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)
todo Update the data structure documentation
 

int $_root

The GUID of the MidCOM Root Content Topic
 

string $_user_id

This private helper holds the user id for ACL checks.

This is set when instantiating to avoid unnecessary overhead