Navigation Access Point

1. NAP basics
2. Navigational Information emitted by a component
3. Low-Level Access to the tree
4. High-Level Access to the tree
5. A data structure for navigational meta-data
6. Using the NAP System

Navigation Access Point, or NAP is the MidCOM service providing navigational information about a website. The NAP information can be traversed using the API described below to develop custom navigation.

NAP basics

With MidCOM, the creation of navigational structures has to be abstracted. You cannot simply traverse topic trees in your style elements to create the navigational structure. Each component has to have the chance to tell you what may go into the navigation, and what not.

For that purpose, MidCOM defines an interface each component must implement that provides an abstract access to the tree-like structure of the content tree. MidCOM uses that concept class called midcom_helper_nav to access this information.

This allows the framework to build up a simple leaf/node Tree Structure that can be traversed by an application. In addition to this, to simplify certain often-used navigational needs, MidCOM defines a set of helper classes that give you an easier way of accessing navigational data.

It is important that you use this interface the component infrastucture provides you to build up your site navigation, since the regular Midgard functions have no way of knowing wether a specific topic or article is "open" for naviagion display or not.

Navigational Information emitted by a component

Each component has to be able to answer these questions:

1. Is the topic in question a topic storing internal data that should not be directly accessed by the Navigation System? If no, recursive processing at that point will be able to continue. If yes, navigation recursion will stop at that point.

2. If the component is visible as a node in the tree, has it any direct children ("leaves") that are visible in the navigation tree? The order of these elements is defined by the component.

3. If the component is the one that displays the primary element of the page, which is the active leaf?

For every visible element (whether this is a node or a leaf), the component has to deliver this information:

• A URL-conforming name of the element, that is used by the framework to construct URLs. Only the "local" part of the URL is needed here, relative to the folder currently in question. This is only required for leaves, as the URL of an Node is automatically determined by MidCOM using the name-Field of the Topic.

• The clear-text name of the element, that the applications can use to show it in the navigation tree.

• A flag which shows, wether the element in question should be displayed in the generated navigation trees. How this flag is handled, is entirely up to the site builder. MidCOM only relays it to the style code.

• The Meta-Information available about this element. This includes the four meta-parameters accessible via constants MIDCOM_META_CREATOR, MIDCOM_META_CREATED, MIDCOM_META_EDITOR and MIDCOM_META_EDITED.

Low-Level Access to the tree

This is the part where the framework collects the information about the navigational hierarchy.

The helper class midcom_helper__basicnav is responsible for this. It is responsible to locate an entry point, the root node, from which it is possible to repeatedly call list_nodes(node_id) and list_leaves(node_id) to build up the tree.

This class is only used internally by the framework to do the low level collection of the various items. The application will not see this class directly, but use the interface defined in the next chapter. A Singleton Pattern is used to ensure that only one instance of this class is active at a single time.

High-Level Access to the tree

This is the real interface a site builder uses to create the required navigational elements. Basically it is a class that proxies requests to the single instance of the Low-Level API. It serves you as a base class from which you can derive application-specific navigation classes. This class serves as proxy to the Low-Level Interface.

In a consequence, this will result in a set of classes used for often occurring problems. You will usually use this class to build your navigation elements in your website, sticking to the inherited low-level functions for basic operations. You might also derive a custom class from this one if you have a very special requirement.

It might also be possible to build User-Interface Level classes, which fully encaspulate the NAP System to create a Navigational Element for a site. In that case you would use a NAP class inside your wrapper class which in turn has received the neccessary Style information to automagically build what you need.

A data structure for navigational meta-data

All navigational data is passed in the form of associative arrays of the type int mixed. The following keys are defined for nodes:

• MIDCOM_NAV_NAME: The description of the element.
• MIDCOM_NAV_VISIBLE: Should the element be shown in the built navigation tree?
• MIDCOM_META_CREATOR: The creator of the element.
• MIDCOM_META_CREATED: The creation date of the element.
• MIDCOM_META_EDITOR: The last modifier of the element.
• MIDCOM_META_EDITED: The last modification date of the element.

For leaves, the structure is a bit more complex:

• MIDCOM_NAV_SITE: Array containing Navigational title (MIDCOM_NAV_NAME) and URL (MIDCOM_NAV_URL) of the element for display on the main site.
• MIDCOM_NAV_ADMIN: Array containing Navigational title (MIDCOM_NAV_NAME) and URL (MIDCOM_NAV_URL) of the element for display within the Administrative Interface System context.
• MIDCOM_NAV_VISIBLE: Should the element be shown in the built navigation tree?
• MIDCOM_META_CREATOR: The creator of the element.
• MIDCOM_META_CREATED: The creation date of the element.
• MIDCOM_META_EDITOR: The last modifier of the element.
• MIDCOM_META_EDITED: The last modification date of the element.

The values of these keys contain the information requested. By using this Property-List like approach, it gives us further flexibility down the road should we ever need them.

Using the NAP System

The NAP Helper classes know everything they need to work out their magic. This means the only thing you, as a site builder, need to do is to instantinate one of the NAP Helpers and use them right away. They will access the MidCOM Framework where neccessary. You do not need to worry about this interaction between the NAPs and the MidCOM components, this is why we have the NAP infrastructure.