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!

22 Comments

  • Skywalker said

    I just wanted to give you a Big Thank You for writing this module! I managed to style it properly and used the SuckerFish menu javascript. As I'm still learning how it all works with Shapes and Widgets and stuff in Orchard, I'm really looking forward to your next article to learn more.

    Cheers!

  • Skywalker said

    One thing I'm really missing (or don't understand how to accomplish) is how to determine if the current menu item being rendered (in MenuItem.cshtml) is part of the current path (by which I mean the url). The reason I need to know this is to add the "current" css class to that item, so that if a user is on a submenu page, both that submenu as well as its parent menu items will be highlighted.

    For example, if the user is on this url: "/home/products/orchard-cms", and there is a main menu with the a menu item called "home" and a subm menuitem called "products", both these menuitems should have the "current" css class.

    I'm having a bit of a hard time figuring out how exactly the Navigation API works, so your module will have support for this situation.

    Thanks! Skywalker

  • Olin said

    You really did a good work !! it work very fine :D I'm really awaiting new articles ;)

    One interesting functionnality could be to display a menu from a specific "node" with the menuWidget like if you configure your widget to display from a specific item name , it will only show childs of this menu.

    Moreover another option could be to decide sublevel number which will be displayed !

    And i've spotted a bug, or i think its one : in configuration section, you can set the Limit menu levels displayed and and when i put 1 level my menu become "flat" with 1.1.1 with 1.1 but the logical way could be the suggestion i make above ? (or gave us the choise :) )

    congrat'z again !! :)

  • Olin said

    Hello szmyd, i've spotted a real bug :) When you select a node with childs Current class is applied to the current link, bug on his childs too ^^

  • Olin said

    Another cool feature could be to add a "Most seen widget"

    which show a selected number (configured in widget configuration) of page which have the biggest views count

    PS: sorry for this spam :p

  • pszmyd said

    Hi! @Skywalker: I was thinking about this, but because of the way the menu rendering works it is not that simple (as the menu items are render from top to the bottom). I'll try to find a way to do it (eg. by getting such information prior to rendering) and put in the next release.

    @Olin: No problem - constructive comments are always a good thing:) Thanks for the bug info, I'll fix it as soon as I can.

    "Most seen widget" - thanks for the idea, I'll surely put that into the next release:)

    About the Limit property. When you set that property (to >0) than all menus (main and those in the MenuWidget) will get levels limited, and lower levels flattened accordingly. This is because I based my widget on the menu building engine, which does the limiting before I get the items. In the next release I'll disconnect those two, so the widgets won't be affected by global "Levels" setting (instead I'll give the separate option in the widget).

    Cheers!

  • tobias said

    Hi piotr, very cool module! One thing i noticed ist that it doesn't play well with translated content. I for example have a site in multiple languages and want to show the menu only for the actual language. What is the best practice for such a scenario?

    I tryed to set up "Show menu" on each (also translated) page and set the navigation hierarchy for each page (default language beginning with 1, 1.1, 1.2, ... and translated beginning with 100, 100.1, 100.2, ...). Now the menu can ignore the other languages and render only the current language menu. On the other side it would be nice to configure the navigation structure only for the main language and the tranlation would autmatically be handled, when switching to another language...

  • John Tarbox said

    In SubMenuPartTypePartSettings.cshtml you have the line 6 as:

    yet I never see this line (or class) rendered to the browser. Am I missing something?

  • Olin said

    hello szmyd,

    is there a simple way to display a menu widget beginning from a specific node ?

    if i have : 1 1.1 1.1.1 1.1.2 1.2 2

    and i configure my menu from 1.1, i will only see: 1.1.1 and 1.1.2 ?

    Thanks :)

    Concerning most viewed pages ? when will you make this available ? :)

    Thanks a lot for your job ! =)

  • Springy said

    The framework internally seems to support multiple menus.

    Using the menu widget I can display 'main' or 'admin' -- but is there a way for creating additional menus (like a 'footer' menu?)

  • pszmyd said

    From the UI - by default no - but I'm working on it and provide such possibility soon (very soon - in couple of days).

    The "main" and "admin" menus are hardcoded and atm hardcoding menus in separate INavigationProvider implementing classes is the only way to create custom menus...

  • Olin said

    Will you add my propositions to the next release ? (-most viewed pages with item count parameter and the regex filter you already make And -menu from a specific node with node name parameter)

    ?

  • Olin said

    Hello pszmyd!

    Will the module be localizable ?

    (because de host > ... in breadcumb is painful for me :D )

  • pszmyd said

    @Olin: Breadcrumbs widget takes data from the titles of corresponding items/pages and the main menu items defined in Navigation pane, so it's localizable this way. Main menu item titles are localizable by default, so it's doable. I'll write more about that soon.

  • Olin said

    Hi again pszmyd !

    The home word was written in cshtml file so i've modified it :)

    An usefull feature could be to add pages to "hierarchy" but to make them invisible in menus. So these pages will be visible from breadcrumb, but not in menu( visible in menu if widget is configurated for display them)

  • jon said

    Is there is location to download the source code? I'd love to see how this is made.

  • cj said

    Can someone provide a styling example? I'm having issues with the sub-menu always showing. I know I'm missing something small.

  • pszmyd said

    @cj: Thanks for the feedback - I'll provide a live example with the new release (in a few days).

  • Vinney said

    Thank you for your excellent work! I'm new to Orchard but your controls and blog posts are helping me become productive quickly.

    I just had one quick suggestion for you, since we now have the ability to create multiple menus, it would be helpful to be able to reference the nav element by id. Perhaps you could give each nav an id equal to the menu name.

    Thanks again!

  • Vinney said

    Is it just me or is there a problem with the delete function? When I click delete on the menu level, I get a server error:

    A required anti-forgery token was not supplied or was invalid.