\midcom_helper_nav_backend

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

Summary

Methods
Properties
Constants
__construct()
list_nodes()
list_leaves()
get_loaded_object_by_guid()
get_node()
get_leaf()
get_current_node()
get_current_leaf()
get_current_upper_node()
get_root_node()
get_node_path()
get_leaf_uplink()
get_node_uplink()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
init_topics()
_loadNode()
_loadNodeData()
_load_leaves()
_get_leaves()
_check_leaf_id()
_get_parent_id()
$_root
$_current
$_currentleaf
$_leaves
$_nodes
$_loaded_leaves
$_loader
$_nap_cache
$_node_path
$_user_id
N/A

Properties

$_root

$_root : integer

The ID of the MidCOM Root Content Topic

Type

integer

$_current

$_current : integer

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

Type

integer

$_currentleaf

$_currentleaf : string

The GUID of the currently active leaf.

Type

string

$_leaves

$_leaves : array<mixed,\midcom_helper_nav_leaf>

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)

Type

array<mixed,\midcom_helper_nav_leaf>

$_nodes

$_nodes : array<mixed,\midcom_helper_nav_node>

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)

Type

array<mixed,\midcom_helper_nav_node>

$_loaded_leaves

$_loaded_leaves : array<mixed,\midcom_helper_nav_leaf>

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.

Type

array<mixed,\midcom_helper_nav_leaf>

$_node_path

$_node_path : Array

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

Type

Array

$_user_id

$_user_id : string

User id for ACL checks. This is set when instantiating to avoid unnecessary overhead

Type

string

Methods

__construct()

__construct(integer  $context) 

Constructor

It will initialize Root Topic, Current Topic and all cache arrays. The constructor retrieves all initialization data from the component context.

Parameters

integer $context

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

list_nodes()

list_nodes(mixed  $parent_node, boolean  $show_noentry) : Array

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

Parameters

mixed $parent_node

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

boolean $show_noentry

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

Returns

Array —

An array of node IDs or false on failure.

list_leaves()

list_leaves(mixed  $parent_node, boolean  $show_noentry) : Array

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

Parameters

mixed $parent_node

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

boolean $show_noentry

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

Returns

Array —

A list of leaves found, or false on failure.

get_loaded_object_by_guid()

get_loaded_object_by_guid(string  $guid) : Array

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

string $guid

The GUID to look up in the NAP cache.

Returns

Array —

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

get_node()

get_node(mixed  $node_id) : Array

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

mixed $node_id

The node ID to be retrieved.

Returns

Array —

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

get_leaf()

get_leaf(string  $leaf_id) : Array

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

string $leaf_id

The leaf-id to be retrieved.

Returns

Array —

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

get_current_node()

get_current_node() : mixed

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

Returns

mixed —

The ID of the node in question.

get_current_leaf()

get_current_leaf() : string

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

string —

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

get_current_upper_node()

get_current_upper_node() : mixed

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

Returns

mixed —

The ID of the node in question.

get_root_node()

get_root_node() : integer

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

integer —

The ID of the root node.

get_node_path()

get_node_path() : Array

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

Array —

The node path array.

get_leaf_uplink()

get_leaf_uplink(string  $leaf_id) : mixed

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

Parameters

string $leaf_id

The Leaf-ID to search an uplink for.

Returns

mixed —

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

get_node_uplink()

get_node_uplink(mixed  $node_id) : mixed

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

Parameters

mixed $node_id

The node ID to search an uplink for.

Returns

mixed —

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

init_topics()

init_topics(\midcom_db_topic  $root, integer  $context) 

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

Parameters

\midcom_db_topic $root
integer $context

_loadNode()

_loadNode(mixed  $node_id, integer  $parent_id = null) : integer

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

mixed $node_id

The node ID of the node to be loaded

integer $parent_id

The node's parent ID, if known

Returns

integer —

MIDCOM_ERROK on success, MIDCOM_ERRFORBIDDEN when inaccessible

_loadNodeData()

_loadNodeData(mixed  $topic) : integer

Load the navigational information associated with the topic $param, which can be passed as an ID or as a MidgardTopic object.

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

mixed $topic

Topic object or ID to be processed

Returns

integer —

MIDCOM_ERROK on success, MIDCOM_ERRFORBIDDEN when inaccessible

_load_leaves()

_load_leaves(\midcom_helper_nav_node  $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

\midcom_helper_nav_node $node

The NAP node data structure to load the nodes for.

_get_leaves()

_get_leaves(\midcom_helper_nav_node  $node) : Array

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

\midcom_helper_nav_node $node

The node data structure for which to retrieve the leaves.

Returns

Array —

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

_check_leaf_id()

_check_leaf_id(string  $leaf_id) : boolean

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

string $leaf_id

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

Returns

boolean —

true if the leaf exists, false otherwise.

_get_parent_id()

_get_parent_id(integer  $topic_id) : integer

Determine a topic's parent id without loading the full object

Parameters

integer $topic_id

The topic ID

Returns

integer —

The parent ID or false