Docs For Class midcom_helper

Class midcom_helper_nav

Description

Main Navigation interface class.

Basically, this class proxies all requests to a midcom_helper__basicnav 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 basicnav directly, this is strictly forbidden.

see: midcom_helper__basicnav
todo: End-User documentation of node and leaf data, as the one in basicnav is incomplete too.

Located in /midcom.core/midcom/helper/nav.php (line 27)

Method Summary

midcom_helper_nav __construct ([int $contextid = -1])

array get_breadcrumb_data ([ $id = null])

string get_breadcrumb_line ([string $separator = ' > '], [string $class = null], [int $skip_levels = 0], [string $current_class = null], [array $skip_guids = array()])

int get_current_leaf ()

int get_current_node ()

Array get_leaf (string $leaf_id)

int get_leaf_uplink (string $leaf_id)

Array get_node (int $node_id)

int get_node_uplink (int $node_id)

int get_root_node ()

Array get_toolbar_definition (Array $nap_object)

boolean is_node_in_tree (int $node_id, $root_id, int $root_node)

Array list_child_elements (int $parent_node_id)

Array list_leaves ( $parent_leaf, [boolean $show_noentry = false], int $parent_node)

Array list_nodes (int $parent_node, [boolean $show_noentry = false])

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

string view_current_page_url (string $baseurl)

Methods

Constructor __construct (line 53)

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

midcom_helper_nav __construct ([int $contextid = -1])

int $contextid: The id of the context you want to navigate.

get_breadcrumb_data (line 668)

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. (mgd_is_in_topic_tree was originally used for this purpose, but this check is not only much faster but more flexible as it isn't limited to topic).

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->set_custom_context_data('midcom.helper.nav.breadcrumb', $tmp);

return: The computed breadcrumb data as outlined above.
todo: Maybe cache this? I don't know how complex it really is, but DB accesses are already cached by the _basicnav core. So it is not that hard.

array get_breadcrumb_data ([ $id = null])

get_breadcrumb_line (line 547)

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.

return: The computed breadrumb line.

string get_breadcrumb_line ([string $separator = ' > '], [string $class = null], [int $skip_levels = 0], [string $current_class = null], [array $skip_guids = array()])

string $separator: The separator to use between the elements.
string $class: If not-null, it will be assigned to all A tags.
int $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.

get_current_leaf (line 87)

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 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.
see: midcom_helper__basicnav::get_current_leaf()

int get_current_leaf ()

get_current_node (line 73)

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.
see: midcom_helper__basicnav::get_current_node()

int get_current_node ()

get_leaf (line 161)

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
see: midcom_helper__basicnav::get_leaf()

Array get_leaf (string $leaf_id)

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

get_leaf_uplink (line 174)

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

return: The ID of the Node for which we have a match, or false on failure.
see: midcom_helper__basicnav::get_leaf_uplink()

int get_leaf_uplink (string $leaf_id)

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

get_node (line 147)

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
see: midcom_helper__basicnav::get_node()

Array get_node (int $node_id)

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

get_node_uplink (line 187)

Returns the ID of the node to which $node_id is associated 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.
see: midcom_helper__basicnav::get_node_uplink()

int get_node_uplink (int $node_id)

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

get_root_node (line 101)

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.
see: midcom_helper__basicnav::get_root_node()

int get_root_node ()

get_toolbar_definition (line 229)

This function returns the toolbar definition for the NAP object passed. This must supersede 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.

is_node_in_tree (line 199)

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

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

boolean is_node_in_tree (int $node_id, $root_id, int $root_node)

int $node_id: The node in question.
int $root_node: The root node to use.
$root_id

list_child_elements (line 249)

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

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

Array list_child_elements (int $parent_node_id)

int $parent_node_id: The ID of the parent node.

list_leaves (line 133)

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.
see: midcom_helper__basicnav::list_leaves()

Array list_leaves ( $parent_leaf, [boolean $show_noentry = false], int $parent_node)

int $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 parameter has no effect in AIS. This defaults to false.
$parent_leaf

list_nodes (line 117)

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.

return: An Array of Node IDs or false on failure.
see: midcom_helper__basicnav::list_nodes()

Array list_nodes (int $parent_node, [boolean $show_noentry = false])

int $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 parameter has no effect in AIS. This defaults to false.

resolve_guid (line 316)

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 then the NAP listings.

return: Either a node or leaf structure, distinguishable by MIDCOM_NAV_TYPE, or false on failure.
see: midcom_services_permalinks

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

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 ?

view_current_page_url (line 481)

This function provides an interface to construct links like 'View this page'.

It takes the currently displayed content element (either a leaf or node) and constructs the respective URL relative to the root of the website as passed to the function.

return: The full URL to the on-site element in question, null if there is no on-site representation, false on failure

string view_current_page_url (string $baseurl)

string $baseurl: The base url that leads to the root page of the MidCOM site.

Documentation generated on Fri, 10 Oct 2008 22:05:19 +0300 by phpDocumentor 1.4.2