Menus

The Mara menu system is designed to provide a highly functional pair of cascading menus, one optimised for top-of-page usage and the other for sidebar usage. These menus are capable of handling a very large number of links without overcrowding the page, and provide a quick and intuitive method of navigating the site. In most cases they will reduce or even eliminate the need for hyperlinks within the body text of pages, thus saving greatly on  link-maintenance work by the webmaster. 

A key design objective has been to create expanding menus which do not require tedious page reloads when navigating from section to section, giving virtually instantaneous access to any menu section. The sidebar menu gives a clear indication of which page is currently open, and which site section it belongs to. This also eliminates the need for 'breadcrumbs' -the menu providing such placeholder information in itself. 

In the event that a visitor is unable to use the cascading menus, an automatically-generated sitemap page provides a very traditional and text-interface friendly list of the menu links.

Menu contents are determined by a simple textfile structure, the files being in sitecfg/ By default, the lefthand cascading menu is built from tree.mnu, and the top bar menu from quicklink.mnu The file structure is as follows:

[SectionText=SectionDescription
    LinkText=Hyperlink=LinkDescription
    [SectionText=SectionDescription
       LinkText=Hyperlink=LinkDescription
    ]
]

The menu editorSquare brackets enclose a menu sublevel. Sublevels may be nested to any depth, but in the case of lefthand menus please take account of the amount of screen space taken up by excessvely lengthy or multiply-nested entries. Basically, it is best to keep the LinkText short and use the Description to provide clarification where needed.

By default, sublevels are collapsed, but preceding a section's left bracket with + will cause that section to be expanded by default. The sublevel containing the current page and its parents are automatically expanded. 'Text' is what is displayed in the menu. Descriptions are optional, and if present are shown when the mouse is hovered over the item.

It is permissible to have a menu without sublevel brackets, in which case it will appear as a traditional flatfile menu.

For local pages, the hyperlink should consist of the plain filename only, for example mypage.php Do not add http://, the domain,  or other prefixes. If your site contains subdirectories, the files in these should be referred to by a relative path from the root of the website. For example, subsection/pageone.php

In Mara 6 we use .php as the default filename extension. This differs from Hyperframe, which used .htm or .html. The reason for the change is for greater compatibility, especially with hosts which do not support php code in html files. If you'd prefer to use use .htm(l) then it's easy enough to change the default extension in siteini.php

Don't worry about what will happen if the page bearing the menu is not in the default location - the menu system will take care of that. All links should be relative to the base directory of the website -the one with codebase, sitecfg, theme, etc in it. It doesn't actually matter if you start the local link with a / or not, but standard practice is that you should not.

To refer to the site's homepage -the default file in the top directory level- the hyperlink should be null, or a / on its own. 

For offsite links, do include http:// or https:// and the full domain - this tells the system that you are entering a link to another website. Such links will automatically open in a new browser tab, so as to retain the tab open on your site. This behaviour is generally preferred on business sites, where a visitor directed permanently off your site is potentially a lost sale. 

Items are NOT enclosed in quotes. (Unless of course you want quotes displayed onscreen). Indenting is optional and has no effect on behaviour. The syntax is relatively tolerant of mistakes, and will attempt to display some kind of menu even if there are unbalanced brackets or suchlike present. That is not of course an excuse for careless menu coding, but resilient systems are always preferable to fragile ones.

A menu editor is included, under Edit>Edit Menu. This allows you to test your changes before saving. Previous menu versions are included in the rollback archive, in case you should need to undo a serious mistake. Alternatively, a menu can be prepared in any texteditor (Geany or Notepad++ are recommended) and uploaded by ftp.

Extensionless URLs and subdirectories

On sites with these features, and in order to be able to distinguish between a filename and a subdirectory, the following rules apply:

To make the all local menu links appear as an extensionless URL in the browser bar, simply change the multiviews setting in siteini.php from 0 to 1.  There is no need to remove the extensions from the menu entries, in fact this should not be done as it would make it difficult for the location-tracking logic to tell which file is being referenced.

Compatibility:

The new menu system in v4 will work in most modern browsers, including Firefox 3 on, IE8-on, and most mobile browsers.  It will also work in IE6/7 with full functionality but with a somewhat inelegant display.

The change to a click-operated or tap-operated top menu as opposed to mouseover-operated, is mainly in the interests of touchscreen devices, although we think you will agree that it is more ergonomic all-round, even on mouse-driven desktops. In particular, with click operation it will not have any adverse result if in navigating to an item you allow the mouse cursor to stray outside of the menu box for a short while. That, and passing the mouse over the menu area enroute to an inpage link  will not cause spurious menu popups.

The new menus have been tested on iPad, Android and Kindle Fire, and show good ergonomics.

An issue has been noted on Galaxy Tab 4 tablets, in that the auto-zoom feature these possess makes it difficult to activate menu items, the auto-zoom 'stealing the click' away from the menu link. This, on links that don't need zooming anyway as they are perfectly large enough to read! Since this auto-zoom feature is problematic in other situations too, we hope that Samsung may modify it in the near future. Galaxy Tab 3 and earlier models are not affected.