Using the Hierarchical menu Orchard module

Tags: orchard, menu, english

Many of you asked me to provide the explanation of how to use the hierarchical menu module. As the new release arrived I took all features together and wrote this short tutorial. Also, I’d like to thank the community for the info about the ordering issue – I’ve managed to fix it in the recent version.

So, getting to the point…

Main features

Initially, module had only the functionality to build the menu hierarchy based on a menu items’ Position property. In the latest version I added some new features, also in high demand – the breadcrumbs shape and widget, the sub-menu widget and the recently seen widget.

image

 

Multi-level, hierarchical main menu

The core functionality. It builds the menu tree structure based on Position property (using dot-notation). It’s usage is automatic – when you enable the feature in the admin Dashboard it overrides the default menu right away.

Breadcrumbs

You can add the breadcrumbs to your site in two ways: 

  1. By adding BreadcrumbsWidget to your page
  2. By using Breadcrumbs shape. You should think about this method as using a helper. It is suitable, when you want to hardcode the breadcrumbs placement, e.g. inside your themes/parts and such so it’s definitely targeted to developers. If you want to create your own module and use this helper in it, try reading the introduction first.

Usage. Adding the breadcrumbs widget to your page(s):

image

You can specify three parameters:

  • Separator string – string used to separate links in breadcrumbs path
  • Leading text (optional) – text displayed before the breadcrumbs path
  • Display last breadcrumb as link? – Whether to display last breadcrumb as link instead of ordinary text

The most suitable zone for placing Breadcrumbs, as shown on screenshot, is BeforeContent, but you are free to choose different one.

Sub-menu widget

Widget you can place on your pages, to display an additional menu. When creating a widget, you can choose from 3 different display modes:

  • AllItems – displays all items from the given menu (though resembling the default menu)
  • SubItems – displays only the items from given menu placed below the currently displayed item
  • SameLevel – displays items from the given menu placed on the same level as currently displayed item

image

And this is how each of those display modes look like, assuming you are currently on page named “Second 1.2”  as shown on picture below. It’s a screenshot from the ThemeMachine theme.

image

The currently visited item is marked with the “current” CSS class to allow easy styling, but unfortunately the ThemeMachine theme doesn’t display it differently out-of-the-box.

Recently Seen widget

This widget displays links to pages user has recently visited. You can provide two optional parameters to filter links to display:

  • Positive filtering regular expression – only URLs matching this pattern will be displayed (white-list)
  • Negative filtering regular expression – URLs matching this pattern won’t be displayed (black-list)

You can use any combination of both to achieve the desired output. If you specify both expressions – the displayed URLs set will correspond to the intersection of both of result sets.

In the example below I entered a simple expression for filtering the visits to admin panel (/Admin) and logon/registration screens (/Users):

image

You can find more information about regular expressions syntax here and here, and in lots of other available sources on the web.

There should also be a parameter specifying whether to display the visit count for each URL, but somehow I forgot to include it with this release, for what I want to apologize. This and another parameter – limiting the number of links displayed will both be available in the next release, coming in the next few days.

Styling the hierarchical menu

Many of you asked how to properly display the menu, as, by default, the lower-level menu items are not displaying well. There are lots of answers to this questions, as there are lots of different approaches – using your own JavaScript, CSS, jQuery, Suckerfish, and so on.

I will write about it in the next article and try to provide you some examples, so stay tuned!UĊ›miech

 

I’d be grateful for posting your comments about problems, if any – I’ll do my best to help. If you think some feature would be useful, but isn’t here yet – also don’t hesitate to post your proposition – I’ll see what I can do.

Cheers!

blog comments powered by Disqus