ocPortal Tutorial: Customising what's on the menus
Written by Chris Graham, ocProducts'menus' usually reside on panel-pages ('panels') which are placed around the main section of the website. They consist of links which may be organised in a tree structure, and displayed in various ways (for example, as popup menus, or expansion 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
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 menusThere are advantages and disadvantages for both types of menu inside a panel page.
+ 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
+ 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
Clearly which to use is a personal/needs-based choice, and there is nothing stopping you using both of them.
Template sets / menu typesThe 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:
- embossed (the default type, a very simple single-layered type for side-placed menus; does not support multiple-levels)
- tree (for side-placed menus where branches can be contracted and expanded as drawers; supports multiple-levels)
- popup (a very nice type for side-placed menus where branches may popup as overlays by hovering the mouse over other branches; supports multiple-levels)
- dropdown (a nice type for top-placed menus, similar to dropdown menus on Windows applications; supports multiple-levels)
- 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; does not support multiple-levels)
- select (select menu items via a dropdown list; does not support multiple-levels)
The menus themselves aren't saved against how the data is to be used, but for usability reasons ocPortal will adapt the menu interface a bit depending on the context you're editing for (i.e. the edit menu button will open up the menu editor in with an interface optimised for how the menu was displayed for that instance).
Links to edit a panel page and to edit managed menus
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.
- Panel pages need to be Comcode pages if you want to use the ocPortal Comcode/managed menu features, but otherwise 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 or Tempcode 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.
Adding a new top (horizontal) menuIt is a bit harder to add a new horizontal menu ('dropdown' or 'top' menu types) because you may well not realise that there are actually 'panel_top' pages you can put them on.
There are three reasons you might not realise this:
- The default 'panel_top' is usually invisible, because it's been given some special tempcode to only show on certain pages (forum zone pages, the recommend page, and a few others)
- 'panel_top' menus are not given edit buttons, due to space constraints
- By default there's a system of redirects in place that might confuse you. You might have seen a top panel in the forum zone but seen no forum:panel_top page, and hence assumed it was rendered by some other mechanism. The truth is that the forum shows the :panel_top page, due to some default transparent redirects. These redirects exist because this default panel (the one that hides most of the time) cuts across zones, linking community pages together
You can edit the :panel_top menu from the Content Management zone, as if it were any other Comcode page. If you like you can rip out the Tempcode 'IF' directive that's there, leaving only the block code ([block="community_menu" type="top"]side_stored_menu[/block]). That change will make the menu start showing everywhere where the panel shows (that's a lot of places, due to the transparent redirects).
CachingThe menu block is cached. There is one small issue with the caching: if you have multiple links on a menu under the same page (e.g. to two different galleries), it won't show the 'current page' properly when cached because it caches against page-name rather than URL (necessary to stop the database getting huge).
To resolve this you will need to turn off the caching for the block by adding a parameter like cache=0. This will not affect performance much.
The menu editor
The menu editor
- 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 simple link and/or be a container for more child branches. For a branch with children that branch can be set to 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 so it can have children (contracted or expanded branch), 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)
Entry pointsEntry points are used in the site-tree tool in the menu editor.
Entry points are basically 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 add 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).
Entry points are the subset of all "page links" that point to specific parts of the software, rather than some content that you have added. Page links are described in full in the ocPortal site structure tutorial.
Don't worry too much about entry point syntax as ocPortal will automatically convert any local URLs that you paste into the menu editor's URL field.
To copy an entry point to a branch in the menu editor 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
ImagesAny theme images available with a prefix of menu_items/ will be available for attachment to menu items, so long as those theme images are defined in the default theme.
You can have different versions of the images for different themes, but they must be available on the default theme too.
The simple way to add them if you don't want to use the theme image management to upload them individually is to upload the images to themes/default/images_custom/menu_items/.
Match-keysThe menu system can use match-keys 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 "Restrict link visibility" field blank, none of this checking happens, and the branch is shown.
Match-keys may also be used in other places in ocPortal, for other kinds of matching purposes.
Match-key s are usually written exactly like page links, but are instead used only for matching. They do not need to point to anything, unlike page links which are actually convertible into real URLs.
For an explanation of page links and entry points, see the ocPortal site structure tutorial.
The only differences between a page link and a match-key are:
- Match-keys may use '_WILD' as the zone or page in order to skip checking against zone/page
- Related to the above, it makes no sense to use '_SEARCH' or '_SELF' as the zone/page in a match-key
- While all specified components of a match-key enforce a match, the URL may also have additional parameters and the match-key does not need to state them – i.e. the match-key may specify a subset of the parameters of a URL, broadening the match
An example match-key list is '_WILD:cms_downloads:type=ad,_WILD:cms_galleries:type=ed'. This would match URLs that were generated from the following page links (whether these page links points themselves actually work is irrelevant):
It would not match URLs generated from the following page links:
In the menu editor, multiple match-keys may be entered in the "Restrict link visibility" field with commas to separate them.
Indicating of the current pageocPortal will try and calculate the current page and pass this into the templating.
However, it can only do this accurately while caching is enabled if each menu link goes to a different zone/page/type combination.
If you have menu items that only vary based on some other parameter you will need to disable caching for your menu block.
Chaining menus together / menu auto-generation (advanced)There are some advanced features for those wanting to have auto-generated deep menus.
- If a menu branch's tooltip is set to !!!<pagelink> (e.g. !!!site:downloads) then the category tree from the module will be inserted underneath that branch. This works with virtually any module that supports categories, including forum:forumview
- … also, if you ask the side_stored_menu block to load a menu named !!!<pagelink>, this will insert the category tree as if it were a standalone menu
- If a menu branch's tooltip is set to @@<menuname> then the menu will be inserted underneath that branch. This is very useful for generating drop-down menus that automatically absorb the left-hand-side menus from multiple zones – removing the need to maintain two sets of menus
- 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)