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.

todo End-User documentation of node and leaf data, as the one in the backend is incomplete too.
package midcom.helper
see \global\midcom_helper_nav_backend

 Methods

__construct (int $contextid)

Create a NAP instance for the given context.

If unspecified, it uses the currently active context which should be sufficient in most cases.

Parameters

$contextid

intThe id of the context you want to navigate.

find_closest_topic ($object)

Parameters

$object

get_breadcrumb_data ($id)

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 then 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 = Array
(
    Array
    (
        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);
todo Maybe cache this? I don't know how complex it really is, but DB accesses are already cached by the _backend core. So it is not that hard.

Parameters

$id

Returns

arrayThe computed breadcrumb data as outlined above.

get_breadcrumb_line (string $separator, string $class, int $skip_levels, string $current_class, array $skip_guids)

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

$separator

stringThe separator to use between the elements.

$class

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

$skip_levels

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

$current_class

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

$skip_guids

arrayArray of guids that are skipped.

Returns

stringThe computed breadcrumb line.

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

see \midcom_helper_nav_backend::get_current_leaf()

Returns

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

see \midcom_helper_nav_backend::get_current_node()

Returns

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

see \midcom_helper_nav_backend::get_leaf()

Parameters

$leaf_id

stringThe leaf-id to be retrieved.

Returns

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

get_node (int $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.

see \midcom_helper_nav_backend::get_node()

Parameters

$node_id

intThe node ID to be retrieved.

Returns

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

get_node_path ($node_id)

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

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.

see \midcom_helper_nav_backend::get_root_node()

Returns

intThe ID of the root node.

is_node_in_tree (int $node_id, int $root_id)

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

Parameters

$node_id

intThe node in question.

$root_id

intThe root node to use.

Returns

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

list_child_elements (int $parent_node_id)

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

$parent_node_id

intThe ID of the parent node.

Returns

ArrayA list of found elements, or false on failure.

list_leaves (int $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.

see \midcom_helper_nav_backend::list_leaves()

Parameters

$parent_node

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

$show_noentry

booleanShow all objects on-site which have the noentry flag set. This defaults to false.

Returns

ArrayA list of leaves found, or false on failure.

list_nodes (int $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.

see \midcom_helper_nav_backend::list_nodes()

Parameters

$parent_node

intThe id of the node of which the subnodes are searched.

$show_noentry

booleanShow all objects on-site which have the noentry flag set. This defaults to false.

Returns

ArrayAn Array of Node IDs or false on failure.

resolve_guid (string $guid, boolean $node_is_sufficient)

This function tries 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.

see \midcom_services_permalinks

Parameters

$guid

stringThe GUID of the object to be looked up.

$node_is_sufficient

booleanif 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

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

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

see \midcom_helper_nav

Returns

\midcom_helper_nav_backendA reference to the backend instance in the cache.

 Properties

 

\midcom_helper_nav_backend $_backend

A reference to the backend instance in use.
 

array $_backends

The cache of instantiated NAP backends
 

int $_contextid

The context ID we're associated with.