ocPortal Tutorial: Customising what's on the menus

Written by Chris Graham, ocProducts

{!DOC_MENUS} There are two ways to define menus:

Comcode menus. These are described in the 'Comcode' tutorial.
Menu-editor managed menus. These are described in this tutorial.

Panel-pages are described in the 'Site structure' tutorial, and also in the 'Custom pages of information (via Comcode)' tutorial.

Comcode menus and menu-editor managed menus are alternatives to each other: both produce the same visual interface, using the same templates, but one is written and laid out in plain-text (Comcode menus) and one is constructed in an editor (managed menus).

Table of contents

ocPortal Tutorial: Customising what's on the menus

Comcode menus verses Managed menus

There are advantages and disadvantages for both types of menu inside a panel page.

Comcode menus:
+ Quick to edit for those who prefer to do things in a quick but technical way
+ Unifies the panel pages and menus under a single editing interface
- Complex syntax

Managed menus:
+ Relatively user friendly
+ Provides menus with greater power (context dependant menus)
+ Provides an interface to find all 'entry points' and easily add them to the menu
- Not accessible for those with disabilities
- Works best at a high resolution

Clearly which to use is a personal/needs-based choice, and there is nothing stopping you using both of them.

Panel pages

Links to edit a panel page and to edit managed menus

Please see the 'site structure' tutorial for more information on panel pages. This section is only intended to provide a brief orientation to help further clarify the menu relationship. Basically panel pages are pages beginning with the name 'panel_' in the zone of the page being viewed.

Your panel pages by default are just Comcode pages that use the block tag for arrangement of blocks such as the 'login/personal-stats block' (side_personal_stats), and the managed menu block, 'side_stored_menu'. Blocks are described in the 'Advanced custom pages of information (via Comcode)' tutorial, but basically, you can use any of the blocks that begin with the name 'side_' on your panel pages to add dynamic elements, as well as any Comcode (Comcode menus are actually created using the Comcode 'menu' tag). To edit a panel page, make sure you are logged in as a staff member and click the 'edit page' link underneath the pages as they are seen.

Some information:

Panel pages need to be Comcode pages if you want to use the ocPortal Comcode/managed menu features, but there is nothing stopping you constructing panel pages as HTML or modules if you wish to.
You will very rarely want to put Comcode menus or managed menus onto anything other than a panel page, although there is nothing stopping you putting them anywhere Comcode is supported.

These two statements may confuse you, but I thought it was important at this point to make it clear that ocPortal is completely flexible when it comes to menu management: we provide default features, but you can divert from them as you wish to when it comes to your own website. The rest of this tutorial will assume that you are using the standard combination of managed menus on Comcode panel pages.

Adding and editing managed menus

Adding a new menu

The easiest way to edit a managed menu is to click the 'edit menu' link shown underneath, much like when clicking the 'edit page' link to edit the panel page. The easiest way to add a new managed menu is to edit a panel page so as to include a 'side_stored_menu' block that uses a menu with a code-name of what you want to create: ocPortal will detect the menu is missing, and place a link to create the menu there instead of the menu itself (in much the same way it detects a missing page and allows the creation of a new Comcode page). It is important to not click to add a new menu from the Comcode page confirmation screen, unless you open the add link in a new window/tab: this is because the Comcode page editing will not have been confirmed, hence making you repeat the page editing process.

The menu editor

The menu editing interface is split into three main sections:

the actual menu tree structure
a form for editing a branch in the tree structure (invisible, until one of the branches is selected)
a site-tree tool to find 'entry points' for insertion into the selected branch's URL field

Menus are a tree structure made up of branches, where each branch may be a:

page - an actual link entry on the menu
or, a node - a drawer, that may contain links. Nodes may be initially expanded or contracted.

The 'add branch' tool, used in conjunction with the branch-type drop-down list (shown for each branch) allows the full structure to be developed. When you change a branch to a contracted/expanded node, you will see that suddenly you may create sub-branches for it.

In the form part of the interface there are the following fields:

a field for a caption
a field for a tooltip
a field for a URL or entry-point
a field for match keys - match keys are a powerful tool for making menus 'context sensitive'.
a check-box to determine if the link opens in a new window
a check-box to determine whether the link will be shown only if there is permission to actually view the page (slight efficiency hit)

The site-tree tool

Entry points are described in full in the 'Site structure' tutorial, but basically they are ocPortal links that are robust to changes in your website and are of the syntax, "<zone>:<page>[:<param>=<val>...]". In other words, they all have at least a zone and a page, and may also specify additional parameters: for example, "site:downloads:type=ad" is the entry point to a download. If you do not want to hard-code what zone a page is in (perhaps because you might move it in the future), you may specify '_SEARCH' (do a search, which is slightly inefficient) or '_SELF' (the zone the menu is being displayed in).

To copy an entry point to a page branch you need to:

select the caption field of an item in the menu (this will cause an editing form to become available for that menu item)
click the entry point in the site-tree tool

You will then see the URL has been changed to the entry point you want. Do not be alarmed that this was placed in the 'URL' field, as the field also supports page links (of which entry points are a type of).

Match keys

Match keys are basically page links (entry points are a type of page link) that are used for matching against the URL the menu is being viewed from, to determine whether a branch will be shown. If the URL matches against one of the match keys for a branch, then the branch will be shown, otherwise it won't. Note that if you leave the 'match keys' field blank, none of this checking happens, and the branch is shown.

Match keys are entered into the field with commas to separate them. The only differences between a page link and a match key are:

Match keys may use '_WILD' as the zone in order to skip checking against zone.
Match keys may use '_WILD' as the page in order to skip checking against page.
The additional "<key>=<value>" parts of the match key enforce a match from the URL the menu is being viewed from, but the URL may also have additional parameters and the match key does not need to state them.
It makes no sense to use '_SEARCH' or '_SELF' in a match key.

An example match key list is "_WILD:downloads:type=ad,adminzone:admin_downloads:type=ed". This would match URLs that were generated from the following page links (whether these page links points themselves actually work is irrelevant):

site:downloads:type=ad
randomzone:downloads:type=ad
:downloads:type=ad:wide=1
adminzone:admin_downloads:type=ed
adminzone:admin_downloads:type=ed:keep_novalidate=1

It would not match URLs generated from the following page links:

site:galleries:type=ad
randomzone:downloads
:downloads:type=ed:wide=1
adminzone:admin_downloads:type=ad
adminzone:admin_downloads:type=ad:keep_novalidate=1

Template sets

The Comcode/managed menu system supports 'template sets' to allow different kinds of menu on a website. The template set to use is specified as one of the parameters to the 'side_stored_menu' block.

The following template sets exist:

dropdown (a nice type for top-placed menus, similar to dropdown menus on Windows applications)
embossed (a very simple single-layered type for top-placed menus)
popup (a very nice type for side-placed menus where branches may popup as overlays by hovering the mouse over other branches)
top (a very simple single-layered type for top-placed menus that provides the same look as the Admin Zone uses for navigation between sections)
tree (the default type, for side-placed menus where branches can be contracted and expanded as drawers)

Concepts

Match key: Page link style identifiers used to do pattern matching against URLs
Comcode menu: A menu created via the Comcode 'menu' tag
Managed menu: A menu created by the menu editor
Panel page: A specially named page that sits on an edge of the main page for all pages in its zone (although a templator could place it anywhere, edges are most common)