McNeese Website Documentation

Menu System

What is the Menu System

The menu system provides an accessible way to find and navigate pages and files on the website. These user-editable menus are provided on a per-group basis and each group has exactly one menu. The users who are authorized to edit these menus will need to understand how the menu system works before making any changes to a menu.

The menu system makes many of the technical aspects of accessible and dynamic menus transparent to users. Users must never build menus for the content themselves, but instead must use the menu system described here. Using this system helps you comply with accessibility laws and helps the system make good choices when displaying or not dislaying a given menu.

This documentation contains the website menu. The menu itself is being presented differently in this web document than it does as a web page. When this documentation gets printed, the menu does not get printed. This works because the menu system understands the difference between a web page, a web document, and a printed page. When a user builds their own menu instead of using the menu system, the menu system does not know anything about this custom menu to properly display it on the different media types.

How the Menu System Works

Everything that is added to the menu is called a menu item. A menu is constructed entirely of menu items. There are 5 different types menu items:

Link

This is the standard menu item. This provides a link to a local page or a page at a remote website. Do not use this when linking to files, instead, use the item type called file.
Label

A label can be considered a place holder menu item. It displays text, but cannot be clicked on and it goes nowhere. Use this for structuring purposes or to communicate that some link is disabled.
File

A file menu item provides a link to some file. This specifically tells the user to expect the link goes to a file and that they can download the file. This should only be used to link to files, for all other types of links use the item type called link.
Menu

Referred to as a menu item menu, this is an advanced menu item that allows a user to add a menu from another group. These menus allow for importing another menu without having to manage or be responsible any of the links.
Menu Item

Almost confusingly referred to as a menu item menu item, this is an advanced menu item that allows a user to add a menu item from another group. This menu item allows for importing a single menu item from another menu without being responsible for its properties. This should only be used under exceptional circumstances as menu items are easily deleted and replaced. If another user can delete the menu item pointed to by this menu item menu item at their whim, then there is no guarantee this menu item will ever function properly.

Processing all of the menu items can take a lot of time and resources. This slows down page load times which can give viewers a bad experience. To alleviate this performance issue, the menu system implements what is called caching. When changes are made to a menu in the menu system, the cache for that menu must be cleared before the changes become visible.

Each menu has exactly one url path assigned to it. The menu associated with a given path will only appear on pages at a given path and all sub-paths. Multiple menus are allowed to appear on a given path.

The website documentation menu has a path of /documentation/website. Any sub-path, such as /documentation/website/menu-system, will show the menu. The menu will never appear on /documentation/elsewhere or even /website.

Updating a Menu

My menus page screenshot — Menu System - Image 1

The menu system settings for menus in which you are authorized to manage can be accessed by selecting the My Menus tab on My Workbench page. If the My Menus tab is not listed in the tabs on the My Workbench page, then there are no menus in which you are authorized to manage. The menus are sorted alphabetically. Multiple menus are allowed to have the same name, so be sure to pay attention to the menu path or the menu id that is also displayed.

Edit a single menu page screenshot — Menu System - Image 2

Selecting a menu on the My Menus tab should bring up an edit page for that specific menu. This page can be logically broken down into three parts.

menu settings
The menu settings provide global controls such as:
- setting the menu path
- assigning the menu weight
- enabling parent visibility
- altering the breadcrumb name
menu items
The menu items part is where menu items are managed. This area contains a table with the following columns:
- item name
- item type
- operations
- id
There also exists an additional field called row weights that is used when drag and drop support is not available.
operations
The operations part provides links to perform specific tasks. The provided links are:
- add new menu item
- update menu
- reset cache
- cancel

There are two important steps to perform when making changes to a particular menu. The first is that the Update Menu button must be clicked to save any of the changes made, with the exception of adding, editing, or deleting menu items. The second is that the Clear Menu Cache button must be clicked in order to make the changes visible. If the menu cache is not cleared, then the changes that were made to the menu will not be visible for anyone to see. Use the menu item add, edit, and delete links to perform their respective operation. The ordering of the menu items can be performed on this page by dragging and dropping, by using the order weight fields, or by editing a menu item and changing its parent item and weight.

The menu settings contain all of the menu-specific settings that appropriately privileged users are allowed to change. The most important of the menu-specific settings is the menu path. The menu path designates where all menu items associated with the menu get placed under. Some menu items may even prepend the menu path to its links. If the menu path is incorrect and you do not have access to change it, then seek support for getting the issue resolved. Menus are only display at their menu path and all child paths. The other menu settings, that are hidden under advanced settings, are:

menu weight
show parents
breadcrumb name

The menu weight defines where this menu gets displayed when more than one menu are displayed at the same url path. The show parents checkbox allows for hiding the parent menus. The breadcrumb name gives users to change the name of the menu as it appears in the breadcrumbs.

Menu Item Properties

Add or editing a menu item can be simple, once all of the fields uses purposes are understood. A few of the fields are available primarily for handling exceptional cases and often may be ignore by the users. Each menu item has 5 common fields: name, parent item, weight, active path, item type, and when to expand. Name is the name of the menu item as it will be displayed on the menu (with menu item menus and menu item menu items being the exception). Parent item and weight are used to provide hierarchy between different menu items. The active path is used to manually specify the path in which the menu item is considered active and is usually left alone. Under most circumstance, the active path should be left alone. The item type designates what this item is, how it gets presented, and also controls what additional fields are made available. When to expand designates that whether or not child menu items are displayed if the menu item has any child items.

Menu Item Hierarchy

To understand what the parent item and weight are, one needs to understand the menu item hierarchy. The menu item hierarchy is simply the parent child relationship between multiple menu items. If a menu item is to be displayed nested within another, then the nested menu item is a child menu item. The menu item that has nested menu items is called the parent menu item. Menu items that are position above or below another menu item are ordered first by menu weight and the second by the menu name, alphabetically. Menu items with a larger weight are considered heavier and therefore are position below menu items with a smaller weight.

There are two ways to set or change a menu items hierarchy. The first would be to manually set the parent item and manually set the weight. The second is by drag and dropping the menu items while viewing the menu settings page. For the second way, the drag and drop can be done by clicking and holding the Drag to re-order icon that is found on the far left side of each row in the menu items table. Dragging left to right will nest or unnest a menu item, which is the same as changing the menu items parent. Dragging up or down will change the menu items weight. Letting go of the menu item will place that menu item. The drag and drop method does not perform a save, so in order to save the drag and drop changes, be sure to click on the Update Menu button found in the operations area of the page.

Menu Item Types

There are different types of menu items and each provides its own fields and some even change how the standard fields are interpreted. To properly create and use menu items it is very important to understand what each menu item type is, their purpose, and how to use them. There are 5 types of menu items.

Link

Links are the most common type of menu items. This item type provides a link to some other page or website. Do not use this to refer to links to files, instead use the file item type. This provides the field called url. The url field is the address in which the menu item points to. The address can be absolute or relative. Absolute paths should only refer to pages on an external website. Relative paths should always point to a pages node id and are specified by /node/[nid] with [nid] being replaced with the actual node id. Using the node id path will also auto-populate the active path field, allowing the user to ignore the active path field entirely.

Lets say you have a page called my-page in the group called my-group with a node id of 1234. The url path to the page is displayed at /my-group/my-page. To make a menu item link point to my-page, do not use the url path of /my-group/my-page. Instead, use /node/1234 in the url field. This is very important because if the owner of the page changes its name to something like /my-group/my-old-page, the menu system needs to point to the correct place. Using the node id guarantees that the menu system can identify that the path has changed and update itself without user-intervention. What this boils down to is that using the node id correctly, the menu item link will never need to be updated if the page's path changes.
Label

A label is a placeholder. It provides no link to anything, but it can provide structure and even provide a breadcrumb path. There is only one field provided here and that is the disabled checkbox. Enabling the disabled checkbox tells the menu system to style the menu item differently to make the menu item text look like a disbled menu item. This can be useful if you want to create your menu structure before you create your actual pages because the pages that do not yet exist cannot have a node id.
File

A file is a special type of a link that provides additional context to help make the menu system more accessible. When this type of menu item is displayed, additional information is presented to the user to communicate that it is a file and what type of file it is. The type of file must be manually selected. There are two fields provided here. The first is the file field. This can be either an absolute path for files on another website or a relative path for files on this website. The entire path of the file must be specified so it is recommended to use the select link provided in the description. This link will open up a file browser to make it easier to find (or upload) and use a given file. The second field is the file type field. Simply select the type of file. Select the generic file for file types that are not available.
Menu

The menu type allows for importing another menu and placing it somewhere in your menu. This is an advanced field that allows for combining menus that have no parent/child relationship based on the menu hierarchy. This provides a field called menu. The menu field displays all available menus on the system. Simply select the menu of your choice. When using an imported menu, you do not have control over content inside of the menu, but you can choose to override whether or not the menu is expanded or collapsed by default.
Menu Item

The menu item type allows for importing a single menu item from some other menu and placing it onto your menu. This is a special purpose only field and should not be used under most circumstances. This provides a field called menu item. The menu item field only accepts the numeric id value for the menu item to be used. When using an imported menu item, you do not have control over content inside of the menu item, but you can choose to override whether or not the menu is expanded or collapsed by default.

Terminology

Cache: Cache refers to information that was created from performing some given task and then stored for user later on to avoid re-performing the task in which the cache represents. See also Caching.
Caching: Caching is a method used to improvide performance by doing a specific task only one time. The idea is that if a given task must be done repeatedly and nothing has changed, then the results of performing that task will never change no matter how many times it is done. Therefore, do the task one time and then re-use the results from that task for every subsequent request to perform that task. This is used to improve performance for tasks that are done repeatedly, which happens very often on websites.
Media Type: A media type refers to the tools or way in which content is displayed. Common examples of different media types are: printed on paper, displayed on a projector, a computer screen, and a screen reader. Websites often need to understand what media type is in use before displaying its content.