Using the Hierarchical menu Orchard module
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.
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:
- By adding BreadcrumbsWidget to your page
- 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):
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
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.
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):
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!
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!
Comments have been disabled for this content.
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:
<span class="hint">
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)
?
pszmyd said
@Olin: Sure, got it on the list:)
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.
jon said
forget that last comment.. I see the nupkg has source inside of it.
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.