NAP Update (Documentation)

This document will outline the actual NAP keys, where they come from and what they mean, as the actual MidCOM Documentation is not really good at the moment. This has somehow to be reworked to be usable by the end user.

Constants and their usage

MIDCOM_NAV_URL
MIDCOM_NAV_NAME
MIDCOM_NAV_ADMIN
MIDCOM_NAV_SITE

These are the constants for the actual navigational information. Both URL and NAME are always to be used in pairs, and they are both accociated with each of ADMIN (for an AIS url) and SITE (for an on-site URL). This distinction is only for leaves, not for nodes! This is a bug, and should be fixed.

URL represents the "URL name" relative to the uplink node (on-site) or the AIS topic root URL (AIS) that should be called when this object is required. Note, that URL is an empty string for nodes most of the time.

NAME represents the clear-text name that should be shown.

For legacy compatibility, NAV_SITE and NAV_ADMIN can be ommited, they will then be auto-generated from the root URL/NAME parameters. This behavoir is deprecated and should no longer be used.

The root NAV_URL and NAV_NAME keys will be automatically taken from NAV_ADMIN and NAV_SITE depending wether the component is in admin or content mode. Both NAV_ADMIN and NAV_SITE may be null, indicating unavailablibilty of a certain leaf/node in the corresponding mode.

This information is passed from the component to the NAP instance, with the root URL/NAME entries being autogenerated.

This information is available through the NAP query interface.

MIDCOM_NAV_FULLURL
MIDCOM_NAV_ABSOLUTEURL
MIDCOM_NAV_RELATIVEURL

This is the full URL of the current leaf or node using the same rules as the relocate handler. (e.g. http[s], SERVER_NAME and SERVER_PORT added automatically). This is useful if you need the complete URL for a redirect etc.

The ABSOLUTE- and RELATIVEURL are subsets of the full URL, giving you URLS absolute to the the root of the site and to the root of the MidCOM site respecitvly. The absolute URL is the best thing to use for Navigation purposes, though both ABSOLUTE- and FULLURL are automatically updated to match the current host configuration within the shared MidCOM NAP cache.

MIDCOM_NAV_FULLURL is only available in MidCOM 2.1.2 and greater, while ABSOLUTE- and RELATIVEURL is available in MidCOM 2.3.2 and greater.

MIDCOM_NAV_PERMALINK

This key holds the Permalink that is required to access this NAP object. Upon request to this URL you will be redirected to the actual page. Of course, the Permalink is not stable when you change the sites URL or Prefix. Only available in MidCOM 2.1.2 and greater.

MIDCOM_NAV_OBJECT

This is a new key introduced in MidCOM 2.4, which holds the actual Midgard content object accociated with the given NAP object. It is auto-populated for Topics by the NAP framework, and may be populated by NAP interface classes for leaves as well. This is a performance shortcut, you should access this object if and only if you are from the same component. For leaves, there are now restrictions on the type of this object.

MIDCOM_NAV_NODEID
MIDCOM_NAV_ID

The (uplink) node id of the current leaf/node, this is -1 for the root topic's uplink.

As of MidCOM 2.3.2 this is an internally generated value and does no longer match any Object ID as it did previously. Use the other explicitly object related functions to gain access to this.

MIDCOM_NAV_VIEWERGROUPS

This is a listing of all ViewerGroups for a given topic. If it is null, it indicates that none have been defined and that the object can be read by everybody.

ViewerGroups checks are not yet implemented on a leaf level, so this key is NULL there always.

MIDCOM_NAV_SUBNODES
MIDCOM_NAV_LEAVES

These internal variables are not available to the outside (they are removed from resultsets before they leave _basicnav) are used for caching purposes. They list all subnodes and leaves of the current node that are known to avoid database queries.

MIDCOM_NAV_INTERNAL

If you set this flag on a NAP object to true, it will not be available through NAP. It will be completly ignored as if it were non-existang.

Must be passed from the component to the NAP instance.

Is available for nodes and leaves through the NAP query interface.

MIDCOM_NAV_VISIBLE

This is a hint indicating the visibility of an object. It defaults to true if unset, but the NAP code will override it to false if a topic is hidden by ViewerGroups. It has no further relevance within NAP.

May be passed from the component to the NAP instance, has sensible defaults as of 2.0.0.

Is avaialble for nodes and leaves through the NAP query interface.

MIDCOM_NAV_GUID

This is the GUID of the NAP object in question.

It is autogenerated for topics, and needs to be passed from the component to the NAP instance for all leaves. This field is mandatory (it was optional prior 2.3.2).

This is available for nodes and leaves through the NAP query interface.

MIDCOM_NAV_TYPE

Indicates the type of the NAP object, either "leaf" or "node".

It is autogenerated when NAP data is passed to the NAP instance.

It is available for nodes and leaves through the NAP query interface.

MIDCOM_NAV_SCORE

This is the score of the object, reliably set only for nodes, there is an autodetection for article-class leaves, but be careful until this fully stabilizes.

MIDCOM_NAV_TOOLBAR

This is an interface that allows a component to give a flexible number of AIS links to a on-site editing list. Its format is an array of midcom_helper_toolbar compatible items. All URLs will automatically get the correct AIS topic URL prefixed. This, of course, needs to be configured somewhere...

The toolbar items must be indexed using integers indicating their sorting order, it must also be possible to merge both node and leave toolbars into one, so watch out for your indexes.

It may be passed for both nodes and leaves from the component to the NAP instance. It may be omitted, null or an empty array designating that no toolbar is available (which will result in an "empty" toolbar).

It is avaialble for nodes and leaves through the NAP query interface.

MIDCOM_META_*

Metadata: CREATOR/EDITOR are Person-IDs, CREATED/EDITED UNIX-Timestamps