Navigator

What does this do?

The "Navigator" module is an engine for generating navigations from the CMSMS content tree and a Smarty template. This module provides flexible filtering capabilities to allow building numerous navigations based on different criteria, and a simple to use hierarchical data format for generating navigations with complete flexibility. This module has no Admin interface of its own, instead it uses the DesignManager to manage menu templates.

How do I use it?

The simplest way to use this module is to insert the {Navigator} tag into a template. The module accepts numerous parameters to alter its behavior and filter the data.

Why do I care about templates?

This is the power of CMSMS. Navigations can be built automatically using the data from your content hierarchy, and a smarty template. There is no need to edit a navigation object each time a content page is added or removed from the system. Additionally, navigation templates can easily include JavaScript or advanced functionality and can be shared between websites.

This module is distributed with a few sample templates, they are only samples. You are free and encouraged to copy them and modify the templates to your liking. Styling of the navigation is accomplished by editing a CMSMS stylesheet. Stylesheets are not included with the Navigator module.

The node object:

Each nav template is provided with an array of node objects that match the criteria specified on the tag. Below is a description of the members of the node object:

  • $node->id -- The content object integer ID.
  • $node->url -- URL to the content object. This should be used when building links.
  • $node->accesskey -- Access Key, if defined.
  • $node->tabindex -- Tab index, if defined.
  • $node->titleattribute -- Description, or Title attribute (title), if defined.
  • $node->hierarchy -- Hierarchy position. (i.e. 1.3.3)
  • $node->default -- TRUE if this node refers to the default content object.
  • $node->menutext -- Menu Text
  • $node->raw_menutext -- Menu Text without having html entities converted
  • $node->alias -- Page alias
  • $node->extra1 -- This field contains the value of the extra1 page property, unless the loadprops-parameter is set to NOT load the properties.
  • $node->extra2 -- This field contains the value of the extra2 page property, unless the loadprops-parameter is set to NOT load the properties.
  • $node->extra3 -- This field contains the value of the extra3 page property, unless the loadprops-parameter is set to NOT load the properties.
  • $node->image -- This field contains the value of the image page property (if non empty), unless the loadprops-parameter is set to NOT load the properties.
  • $node->thumbnail -- This field contains the value of the thumbnail page property (if non empty), unless the loadprops-parameter is set to NOT load the properties.
  • $node->target -- This field contains Target for the link (if non empty), unless the loadprops-parameter is set to NOT load the properties.
  • $node->created -- Item creation date
  • $node->modified -- Item modified date
  • $node->parent -- TRUE if this node is a parent of the currently selected page
  • $node->current -- TRUE if this node is the currently selected page
  • $node->has_children -- TRUE if this node has any children at all.
  • $node->children -- An array of node objects representing the displayable children of this node. Not set if node does not have children to display.
  • $node->children_exist -- TRUE if this node has any children that could be displayed but are not being displayed due to other filtering parameters (number of levels, etc).

Examples:

  • A simple navigation that is only 2 levels deep, using the default template:
    {Navigator number_of_levels=2}
  • Display a simple navigation two levels deep starting with the children of the current page. Use the default template:
    {Navigator number_of_levels=2 start_page=$page_alias}
    Display a simple navigation two levels deep starting with the children of the current page. Use the default template:
    {Navigator number_of_levels=2 childrenof=$page_alias}
    Display a navigation two levels deep starting with the current page, its peers, and everything below them. Use the default template:
    {Navigator number_of_levels=2 start_page=$page_alias show_root_siblings=1}
    Display a navigation of the specified menu items and their children. Use the template named mymenu:
    {Navigator items='alias1,alias2,alias3' number_of_levels=3 template=mymenu}

Note: The order of the parameters matters in the above example. You must specify the items first, then the number of levels.

Parameters

  • (optional) items="contact,home" - Specify a comma separated list of page aliases that this menu should display.
  • (optional) nlevels="1" - Alias for number_of_levels
  • (optional) number_of_levels="1" - This setting will limit the depth of the generated menu to the specified number of levels. By default the value for this parameter is implied to be unlimited, except when using the items parameter, in which case the number_of_levels parameter is implied to be 1
  • (optional) show_all="1" - This option will cause the menu to show all nodes even if they are set to not show in the menu. It will still not display inactive pages however.
  • (optional) show_root_siblings="1" - This option only becomes useful if start_element or start_page are used. It basically will display the siblings along side of the selected start_page/element.
  • (optional) start_element="1.2" - Starts the menu displaying at the given start_element and showing that element and it's children only. Takes a hierarchy position (e.g. 5.1.2).
  • (optional) start_page="" - Starts the menu displaying at the given start_page and showing that element and it's children only. Takes a page alias.
  • (optional) start_text="" - Useful only in the breadcrumbs action, this parameter allows specifying some optional text to display at the beginning of the breadcrumb navigation. An example would be "You Are Here"
  • (optional) start_level="" - This option will have the menu only display items starting at the given level relative to the current page. An easy example would be if you had one menu on the page with number_of_levels=1 . Then as a second menu, you have start_level=2. Now, your second menu will show items based on what is selected in the first menu. The minimum value for this parameter is 2
  • (optional) template="" - The template to use for displaying the menu. The named template must exist in the DesignManager or an error will be displayed. If this parameter is not specified the default template of type Navigator::Navigation will be used
  • (optional) childrenof="" - This option will have the menu only display items that are descendants of the selected page id or alias. i.e: will only display the children of the current page.
  • (optional) action="" - Specify the action of the module. This module supports two actions:
    default - Used to build a primary navigation. (this action is implied if no action name is specified).
    breadcrumbs - Used to build a mini navigation consisting of the path from the root of the site down to the current page.
  • (optional) loadprops="" - Use this parameter when NOT using advanced properties in your menu manager template. This will disable the loading of all of the content properties for each node (such as extra1, image, thumbnail, etc.). This will dramatically decrease the number of queries required to build a menu, and increase memory requirements, but will remove the possibility for much more advanced menus
  • (optional) collapse="" - When enabled, only items directly related to the current active page will be output
  • (optional) root="" - Used only in the "breadcrumbs" action this parameter indicates that the breadcrumbs should go no further up the page tree than the specified page alias. Specifying a negative integer value will only display the breadcrumbs up to the top level and will ignore the default page.
  • (optional) includeprefix="" - Include only those items who's page alias matches one of the specified (comma separated) prefixes. This parameter cannot be combined with the excludeprefix parameter.
  • (optional) excludeprefix="" - Exclude all items (and their children) who's page alias matches one of the specified (comma separated) prefixes. This parameter must not be used in conjunction with the includeprefix parameter.