Menu Builder

This Module allows you to easily create custom menus/navigation lists in the ProcessWire Admin Panel using drag and drop. In the backend, it uses the nestedSortable jQueryUI plugin by Manuele J Sarfatti.

Features

• Visual menu builder
• Ability to create menus that do not mirror your ProcessWire Page Tree hierarchy/structure
• Menus can contain both ProcessWire pages and custom (external) links
• Create menu hierarchies and nesting via drag and drop
• Lock down menus for editing
• Easily apply CSS IDs and Classes to each and every menu item if you wish
• Optionally set custom links to open in a new tab
• Readily view the structure and settings for each menu and menu item
• For each menu, multiple configurable ways to add menu items from ProcessWire pages - PageAutocomplete, PageListSelectMultiple OR AsmSelect[default] AND ProcessWire Selector
• Using a Selector, you can search for pages to add, for example, template=basic-page, limit=20, sort=title.
• Batch edit menus
• Menus stored as pages (note: just the menu, not the items!)
• Menu items stored as JSON in a field in the menu pages (empty values not stored)
• For page fields, you can specify a selector to return only those specified pages for selection in the page field (only applicable to Asm and Autocomplete)
• For page fields, you can also add CSS classes and IDs as you add the items (similar to custom menu items)
• Menu settings for nestedSortable - e.g. maxLevels (limit nesting levels)
• Advanced features (e.g. add pages via selector, menu settings) permissible to superadmins only
• Delete single or all menu items without deleting the menu itself
• Easily render menus and breadcrumbs in the frontend using MarkupMenuBuilder
• Optionally create complex menu structures by returning only menu items using MarkupMenuBuilder and passing these to your custom recursive menu function
• Fully multi-lingual

How to Install

The module has two components:

• ProcessMenuBuilder: for creating menus in the ProcessWire Admin
• MarkupMenuBuilder: for displaying menus in the frontend (unstyled, unordered list by default)

1. Install the module from within the ProcessWire admin or download the module and copy the file contents to /site/modules/MenuBuilder/
2. In Admin, click Modules > check for new modules
3. Click install ProcessMenuBuilder. The module will automatically install MarkupMenuBuilder
4. Go to Setup > Menu Builder and start creating your menus

Note

• The module installs three fields: 'menu_items', 'menu_pages' and 'menu_settings' and one template 'menus'. If any similarly named fields/template are already present on your site, the module will not install but throw an error instead. You would need to rename your fields/template first.
• To allow access to the Menu Builder admin, a non-superuser must have the permission menu-builder. The permission is created on install.
• Some Menu Builder admin options are only available to Superusers by default. Other users would require specific permissions as described below.

API

MarkupMenuBuilder has three methods available to users.

render()

This method renders a menu/navigation list of a specified menu. The method accepts two arguments/parameters:

render($menu, $options);

The first argument is not optional and can be a Page object, a title, name or id of a menu or an array of menu items returned from a menu's menu_items field. Note that using titles or names in multi-lingual environments also works irrespective of the current user's language. The second argument is an optional array and will fall back to defaults if no user configurations are passed to the method.

The available render() options are. Please note the possible values for each.

$defaultOptions = array(

	'wrapper_list_type' => 'ul',// ul, ol, nav, div, etc.
	'list_type' => 'li',// li, a, span, etc.
	'menu_css_id' => '',// a CSS ID for the menu
	'menu_css_class' => '',// a CSS Class for the menu
	'submenu_css_class' => '',// CSS Class for sub-menus
	'has_children_class' => '',// CSS Class for any menu item that has children
	'first_class'=>'',// CSS Class for the first item in
	'last_class' => '',
	'current_class' => '',
	'default_title' => 0,// 0=show saved titles;1=show actual/current titles
	'include_children' => 4, // whether to include natural/pw children of menu items in navigation; 0=never;1=in menu only;2=in breadcrumbs only;3=in both;4=do not show
	'm_max_level' => 1,// how deep to fetch 'include_children'
	'current_class_level' => 1,// how high up the ancestral tree to apply 'current_class'
	'default_class' => '',// a CSS class to apply to all menu items

);

renderBreadcrumbs()

This method renders a breadcrumb navigation of a specified menu. The method also accepts two arguments/parameters:

renderBreadcrumbs($menu, $options);

Similar to render(), the first argument is not optional and can be a Page object, a title, name or id of a menu or an array of menu items returned from a menu's menu_items field. This means that you only have to retrieve a menu once and pass that to both render() and renderBreadcrumbs(). Note that using titles or names in multi-lingual environments also works irrespective of the current user's language. The second argument is an optional array and will fall back to defaults if no user configurations are passed to the method. The options are very similar to those of render(). Hence, as applicable, you can create one array of options and pass it to both render() and renderBreadcrumbs(). The methods will pick up what's of relevance to them.

The available renderBreadcrumbs() options are shown below. Please note the possible values for each.

$defaultOptions = array(

	'wrapper_list_type' => 'ul',// ul, ol, nav, div, etc.
	'list_type' => 'li',// li, a, span, etc.
	'menu_css_id' => '',
	'menu_css_class' => '',
	'current_css_id' => '',
	'current_class' => '',
	'divider' => '»',// e.g. Home >> About Us >> Leadership
	// prepend home page at the as topmost item even if it isn't part of the breadcrumb
	'prepend_home' => 0,// 0=no;1=yes
	'default_title' => 0,// 0=show saved titles;1=show actual/current titles
	'include_children' => 4,// whether to include natural/pw children of menu items in navigation; 0=never;1=in menu only;2=in breadcrumbs only;3=in both;4=do not show
	'b_max_level' => 1,// how deep to fetch 'include_children'

);

getMenuItems()

This is a new method since version 0.1.5. The method greatly simplifies the creation of custom complex menus. Use this method instead of render() if you wish to have total control over your menu logic and markup. Examples of how to use this method can be found in these gists as well as in this post in the support forum. The method accepts three arguments:

getMenuItems($menu, $type, $options);

Similar to render(), the first argument is not optional and can be a Page object, a title, name or id of a menu or an array of menu items returned from a menu's menu_items field.

The second argument determines the type of items that the method will return. A value of 1 will return an array and one of 2 (the default) will return a WireArray Menu Object.

The third argument is similar to the $options passed to render() but accepts slightly only a limited number of options as noted below.

getMenuItems() Options

• From the options available to render() above, 5 also apply to getMenuItems(): default_title, default_class, include_children, m_max_level and current_class_level. In addition, getMenuItems() also takes a number of options only applicable to it as outlined below.
• In this section the term navigation is used in the context of menus only.
• The term 'Class(es)' indicates that multiple CSS Classes can be applied, separated by space.

1. default_title: Controls whether to display Menu Builder saved menu item titles/labels versus displaying pages' actual/current titles. This is useful in scenarios where, for example, you need dynamic titles such as in a multi-lingual environment where you would want navigation labels to change depending on the current language. The default option is to display saved titles. To instead display actual titles, set option to 'default_title' => 1 in your options array.
2. default_class: For menus only and at all menu levels (i.e. nesting), a CSS Class(es) applied to each menu item (e.g. a Bootstrap or Foundation CSS Class).
3. include_children: Controls whether to display viewable descendant ProcessWire pages (children, grandchildren, etc.) of Menu Builder ProcessWire pages' navigation items at runtime as opposed to editing and saving them in Menu Builder admin. This is useful in a number of cases. For instance, you may wish to limit the number of menu items appearing in a particular menu in the the Menu Builder admin, e.g. in cases where these are many. This option can be applied globally (i.e. at a menu-level/$options level) and locally (at a menu-item-level). Item-level settings mean that only children of the specified item will be included. The 'include_children' option is disabled by default. Please see below for further details on how to use the feature.
4. m_max_level: This is a menu-only option related to the include children feature. It limits the depth from within which viewable descendant pages can be retrieved for display in a menu. The default is 1. This means that only fetch immediate children. A value of 2 means fetch both children and grandchildren, etc. The option can