\midcom_helper_nav

Main Navigation interface class.

Basically, this class proxies all requests to a midcom_helper_nav_backend class. See the interface definition of it for further details.

Additionally this class implements a couple of helper functions to make common NAP tasks easier.

Important note: Whenever you add new code to this class, or extend it through inheritance, never call the proxy-functions of the backend directly, this is strictly forbidden.

Summary

Methods
Properties
Constants
__construct()
get_current_node()
get_current_leaf()
get_root_node()
list_nodes()
list_leaves()
get_node()
get_leaf()
get_leaf_uplink()
get_node_uplink()
is_node_in_tree()
list_child_elements()
resolve_guid()
find_closest_topic()
get_breadcrumb_line()
get_breadcrumb_data()
get_node_path()
get_current_upper_node()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
_get_backend()
_find_leaf_in_topic()
$_backend
$_backends
$_contextid
N/A

Properties

$_backends

$_backends : array

The cache of instantiated NAP backends

Type

array

$_contextid

$_contextid : integer

The context ID we're associated with.

Type

integer

Methods

__construct()

__construct(integer  $contextid = -1) 

Create a NAP instance for the given context. If unspecified, it uses the currently active context which should be sufficient in most cases.

Parameters

integer $contextid

The id of the context you want to navigate.

get_current_node()

get_current_node() : integer

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

Returns

integer —

The ID of the node in question.

get_current_leaf()

get_current_leaf() : integer

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

integer —

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

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.

list_nodes()

list_nodes(integer  $parent_node, boolean  $show_noentry = false) : Array

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

integer $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. This defaults to false.

Returns

Array —

An Array of Node IDs or false on failure.

list_leaves()

list_leaves(integer  $parent_node, boolean  $show_noentry = false) : Array

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

integer $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. This defaults to false.

Returns

Array —

A list of leaves found, or false on failure.

get_node()

get_node(integer  $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

integer $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_leaf_uplink()

get_leaf_uplink(string  $leaf_id) : integer

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

integer —

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

get_node_uplink()

get_node_uplink(integer  $node_id) : integer

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

Parameters

integer $node_id

The Leaf-ID to search an uplink for.

Returns

integer —

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

is_node_in_tree()

is_node_in_tree(integer  $node_id, integer  $root_id) : boolean

Checks if the given node is within the tree of another node.

Parameters

integer $node_id

The node in question.

integer $root_id

The root node to use.

Returns

boolean —

True, if the node is a subnode of the root node, false otherwise.

list_child_elements()

list_child_elements(integer  $parent_node_id) : Array

List all child elements, nodes and leaves alike, of the node with ID $parent_node_id. For every child element, an array of ID and type (node/leaf) is given as

  • MIDCOM_NAV_ID => 0,
  • MIDCOM_NAV_TYPE => 'node'

If there are no child elements at all the method will return an empty array, in case of an error false. NOTE: This method should be quite slow, there's room for improvement... :-)

Parameters

integer $parent_node_id

The ID of the parent node.

Returns

Array —

A list of found elements, or false on failure.

resolve_guid()

resolve_guid(string  $guid, boolean  $node_is_sufficient = false) : mixed

Try to resolve a guid into a NAP object.

The code is optimized trying to avoid a full-scan if possible. To do this it will treat topic and article guids specially: In both cases the system will translate it using the topic id into a node id and scan only that part of the tree non-recursively.

A full scan of the NAP data is only done if another MidgardObject is used.

Note: If you want to resolve a GUID you got from a Permalink, use the Permalinks service within MidCOM, as it covers more objects than the NAP listings.

Parameters

string $guid

The GUID of the object to be looked up.

boolean $node_is_sufficient

if we could return a good guess of correct parent node but said node does not list the $guid in leaves return the node or try to do a full (and very expensive) NAP scan ?

Returns

mixed —

Either a node or leaf structure, distinguishable by MIDCOM_NAV_TYPE, or false on failure.

find_closest_topic()

find_closest_topic(  $object) 

Parameters

$object

get_breadcrumb_line()

get_breadcrumb_line(string  $separator = ' > ', string  $class = null, integer  $skip_levels, string  $current_class = null, array  $skip_guids = array()) : string

Construct a breadcrumb line.

Gives you a line like 'Start > Topic1 > Topic2 > Article' using NAP to traverse upwards till the root node. $separator is inserted between the pairs, $class, if non-null, will be used as CSS-class for the A-Tags.

The parameter skip_levels indicates how much nodes should be skipped at the beginning of the current path. Default is to show the complete path. A value of 1 will skip the home link, 2 will skip the home link and the first subtopic and so on. If a leaf or node is selected, that normally would be hidden, only its name will be shown.

Parameters

string $separator

The separator to use between the elements.

string $class

If not-null, it will be assigned to all A tags.

integer $skip_levels

The number of topic levels to skip before starting to work (use this to skip 'Home' links etc.).

string $current_class

The class that should be assigned to the currently active element.

array $skip_guids

Array of guids that are skipped.

Returns

string —

The computed breadcrumb line.

get_breadcrumb_data()

get_breadcrumb_data(  $id = null) : array

Construct source data for a breadcrumb line.

Gives you the data needed to construct a line like 'Start > Topic1 > Topic2 > Article' using NAP to traverse upwards till the root node. The components custom breadcrumb data is inserted at the end of the computed breadcrumb line after any set NAP leaf.

See get_breadcrumb_line for a more end-user oriented way of life.

Return Value

The breadcrumb data will be returned as a list of associative arrays each containing these keys:

  • MIDCOM_NAV_URL The fully qualified URL to the node.
  • MIDCOM_NAV_NAME The clear-text name of the node.
  • MIDCOM_NAV_TYPE One of 'node', 'leaf', 'custom' indicating what type of entry this is.
  • MIDCOM_NAV_ID The Identifier of the structure used to build this entry, this is either a NAP node/leaf ID or the list key set by the component for custom data.
  • 'napobject' This contains the original NAP object retrieved by the function. Just in case you need more information than is available directly.

The entry of every level is indexed by its MIDCOM_NAV_ID, where custom keys preserve their original key (as passed by the component) and prefixing it with 'custom-'. This allows you to easily check if a given node/leave is within the current breadcrumb-line by checking with array_key_exists.

Adding custom data

Custom elements are added to this array by using the MidCOM custom component context at this time. You need to add a list with the same structure as above into the custom component context key midcom.helper.nav.breadcrumb. (This needs to be an array always, even if you return only one element.)

Note, that the URL you pass in that list is always prepended with the current anchor prefix. It is not possible to specify absolute URLs there. No leading slash is required.

Example:

$tmp = [ [ MIDCOM_NAV_URL => "list/{$this->_category}/{$this->_mode}/1/", MIDCOM_NAV_NAME => $this->_category_name, ], ]; midcom_core_context::get()->set_custom_key('midcom.helper.nav.breadcrumb', $tmp);

Parameters

$id

Returns

array —

The computed breadcrumb data as outlined above.

get_node_path()

get_node_path(  $node_id = null) : 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).

Parameters

$node_id

Returns

Array —

The node path array.

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_backend()

_get_backend() : \midcom_helper_nav_backend

This function maintains one NAP Class per context. Usually this is enough, since you mostly will access it in context 0, the default. The problem is, that this is not 100% efficient: If you instantiate two different NAP Classes in different contexts both referring to the same root node, you will get two different instances.

Returns

\midcom_helper_nav_backend

The backend instance in the cache.

_find_leaf_in_topic()

_find_leaf_in_topic(  $topic,   $guid) 

Parameters

$topic
$guid