Modules::SimpleMenu - generic menu-builder for ExSite

SimpleMenu is a multi-purpose menu-builder for ExSite websites. It will create context-specific menus on any web page in a site. Context-specific means that the site navigation links will reflect the current location in the site.

SimpleMenu can also serve as a code template for a customized menu builder, since it contains a general purpose menu-construnction algorithm based on the ExSite page placement parameters.

SimpleMenu can build four types of menus:

vertical

navigation links are stacked in a vertical list, with submenus exploded within this list. This is the default menu type.

horizontal

navigation links are listed left-to-right, menubar style. Only the top-level links in the site are shown, and no submenus are displayed.

path

the path from the site home page to the current page is displayed in the ``cookie crumb'' format, ie. page1 > page2 > page3

sitemap

the full site structure is shown, with child pages indented beneath their parents.

When inserting a web application tag into a block of HTML, any of the above types may be provided as a parameter.

When manually coding a SimpleMenu dynamic content tag, the format is:

<!--&SimpleMenu(format)-->

where ``format'' is one of the above menu types.

Sub-menus

SimpleMenu builds global menus for the whole website by default. That is, the ``top'' level pages displayed in the menu are those that have no parent page defined. Sub-menus show pages that have a common parent page.

SimpleMenu automatically inserts sub-menus into vertically-formatted menus if the viewer is viewing a top-level parent page that has child pages, or is viewing any of those child pages. It does descend any further into the menu hierarchy than this.

If you want to build a menu starting from one of the submenus, instead of from the top-level, then add a ``submenu'' keyword to the parameters:

<!--&SimpleMenu(vertical,submenu)-->

<!--&SimpleMenu(horizontal,submenu)-->

In these cases, the menu shows the pages that are children of the currently-viewed page. If the currently-viewed page has no children, then it shows the submenu to which the current page belongs. This is the same as the top-level menu if the viewer is currently on a top-level page. If you never want to show ONLY submenu pages, and never top-level pages, then change submenu to submenu-only in the above parameters.

Customizing Menu Appearance

CSS

The following CSS classes are used, and may be customized in any given site's stylesheets:

div.vmenu

All vertically-formatted menus are wrapped in a div of the ``vmenu'' class.

span.hmenu

All horizontally-formatted menus are wrapped in a span of the ``hmenu'' class.

span.pmenu

All path menus are wrapped in a span of the ``pmenu'' class.

ul.sitemap

All sitemaps are contained in an unnumbered list of the ``sitemap'' class.

a.menu

All menu links in vertical, horizontal, and path menus are of the ``menu'' class.

a.submenu

All submenu links in vertically-formatted menus are of the ``submenu'' class.

a#toppage

If a submenu is open in a vertically-formatted menu, the parent page has the id ``toppage''.

a#thispage

The page currently being viewed has the id of ``thispage'' (unless it has already been tagged as ``toppage'', above.

Menu Templates

Vertically-formatted menus will attempt to inline special content objects to spice up the menu presentation:

SimpleMenuTop

This content will be placed before all menu links.

SimpleMenuMid

This content will be placed between all menu links.

SimpleMenuBot

This content will be placed after all menu links.

Using these content objects, a template can incorporate custom table layouts, border graphics, and other visual tricks to lay out the menu.

You can do the same thing with horizontally-formatted menus, using content objects named SimpleMenuTopH, SimpleMenuMidH, and SimpleMenuBotH.

Menu Spacer Strings

If the content objects noted above do not exist, then SimpleMenu will used some simple spacer strings in their place. These are defined in the SimpleMenu configuration file, which should be located in cgi/conf/SimpleMenu.conf:

hmenu_spacer

inserted between menu links in a horizontal menu. Default:  | 

pmenu_spacer

inserted between menu links in a path menu. Default:  > 

vmenu_spacer

inserted between menu links in a vertical menu. Default:
Note that if you use display:block in your CSS for menu links, the vmenu_spacer should be left blank to prevent extra blank lines from being added to your menu layout.

submenu_prefix

inserted in front of submenu links. Default:    · 

Subsections in Menus

By default, SimpleMenu displays only the pages within a section. If you add the following configuration setting in its config file:

    show_subsections = 1

Then it will also include subsections under the current section. Subsections are listed after all pages, and in the order the subsections were created. These cannot be reordered.

Configuring Menus

Page order and nesting in menus is determined by the following page attributes:

parent_id

Sets the page that this pages nests under. Set to 0 to make this page a top-level page.

rank

This is a number used to sort pages at a particular level in the menus. Rank 1 pages are placed before rank 2 pages, etc. Pages of the same rank have no particular order with respect to each other.

You can set these values manually in the page configuration forms of most of the CMS tools.

The easiest way to reorganize your menus, however, is to use the SimpleMenu control panel which allows you to configure these settings using a simple drag-and-drop interface. Click and drag any page to any other position in the site map. The new position will be shown with a dashed line so that you can tell what level of the menus you are dropping it into. Once you have your sitemap organized the way you want, you must click the ``Save'' button to have SimpleMenu rewrite the above menu configuration parameters for all of the affected pages.

Note that you can only reorder pages in the menu; subsections always appear at the end of the menu in a fixed order.