Permission-Based Menu Visibility, Orchard Core Basics Companion - This week in Orchard (31/01/2025)
This time, we will check out the new Permission-Based Menu Visibility, the new Orchard Core Basics Companion website, and the updated documentation for fields with alternate display modes. Let's get right into the news!
Orchard Core updates
Permission-Based Menu Visibility
The Menu module enables you to build front-end menus for your users through a user-friendly interface. We've enhanced this feature by allowing you to require one or more permissions before a menu item becomes visible to the user.
If you're using a custom Menu Item in your project and want to incorporate this functionality, you can achieve it by attaching the Menu Item Permission Part to your custom Menu Item content type.
Here, we have a site with the Blog recipe, which defines content types using the MenuItem stereotype. If you edit the predefined Main Menu content item, you can see that this content item has two Link Menu Items: Home and About. Let's edit the Link Menu Item called About. Here, you can see the new Permissions option, which allows you to define the permissions required to display this menu item. You can add multiple permissions, but we just added one, the Access admin panel permission. This means that if the currently logged-in user doesn't have this permission, they can't see the About menu item. Note, this only means that this user can't see this item on the menu, but they can still have permission to view the About page by entering the URL of the content item, for example.
We are visiting our site using an anonymous user in the incognito mode, where the user doesn't have the Access admin panel permission. You can see that the anonymous user only sees the Home menu item but not the About one.
A new option, called Check content permissions, has been added to the Content Menu Item. This feature allows you to control the visibility of a menu item based on the user's permissions. When this option is enabled, the system ensures that the current user has the View Content permission for the selected item before displaying it. To check it out, we created a new Page content item called My new page. After, we ensured that the anonymous user didn't have permission to view the Page content type. Now we can head back to our Main Menu, where we added a new Content Menu Item, which links to a Content URL. Here, we ticked the Check content permissions checkbox and selected our My new page content item. As you can see, the anonymous user still only sees the Home menu item because they don't have permission to view the page content items.
When caching your menu, it's crucial to include the cache-context to ensure the menu is properly cached and invalidated based on the user's roles. This ensures the menu is displayed correctly for each logged-in user based on their specific roles. For example, here's how you can add the menu with cache-context using Razor:
<menu alias="alias:main-menu" cache-id="main-menu" cache-fixed-duration="00:05:00" cache-tag="alias:main-menu" cache-context="user.Roles" />
Notice the cache-context="user.Roles" attribute. Alternatively, here's how you can implement the same functionality using Liquid:
{% shape "menu", alias: "alias:main-menu", cache_id: "main-menu", cache_fixed_duration: "00:05:00", cache_tag: "alias:main-menu", cache_context: "user.Roles" %}
Again, notice the inclusion of cache_context: "user.Roles". Be sure to update all instances where you create a menu shape by adding the cache-context attribute. This ensures the menu is cached correctly and tailored based on the user's roles.
Add documentation for fields with alternate display modes
The placement module changes behavior when using a custom field mode, like a Text Field with a Header display mode. The shape needs to change from TextField to TextField_Display, and it needs a fully differentiated [ContentPart]-[FieldName]_[FieldType]Display_[DisplayMode] otherwise, it just doesn't work.
The requirements for using the placement module or the placement.json file are stricter when using a content field with a display mode other than standard. Here you can see that the documentation is updated by adding the field display modes.
News from the community
Orchard Core Basics Companion (OCBC) Website
The Orchard Core Basics Companion (OCBC) website is a bit of a documentation for Orchard Core beginners. You can see that the site's content is a walkthrough from the very beginning for developers about development. You can gain an understanding of all the fundamental Orchard Core concepts, how to work with them, and how to code everything. This was created by Goh Chun Lin, who works in a company where they will potentially introduce Orchard Core. If you are an Orchard Core beginner or know somebody who has just started working with Orchard Core, this can be a helpful resource that is really worth checking out!
Orchard Harvest 2025 survey
After last year, the Orchard Harvest Conference will be held again in 2025. Last year, it was held in Las Vegas, and we had a really great time there. We would like to try to organize it again in Europe this year. But first, we would like to assess the potential interest and what would be needed. You can fill in the questionnaire here, which should take about 5 minutes. Please share your thoughts with us in the survey. We are curious about who we will meet in 2025! :)
Orchard Dojo Newsletter
Lombiq's Orchard Dojo Newsletter has 460 subscribers! We have started this newsletter to inform the community around Orchard of the latest news about the platform. By subscribing to this newsletter, you will get an e-mail whenever a new post is published to Orchard Dojo, including This week in Orchard of course.
Do you know of other Orchard enthusiasts who would like to read our weekly articles? Tell them to subscribe here!