Placements module, Admin UI improvements - This week in Orchard (17/01/2021)

Gábor Domonkos's avatar
Admin UI, Placement, This week in Orchard, Shortcodes

This time we would like to show you the new features of the Placements module, drop a few lines about the 1.0 version of the Shortcodes module and give a recap about the latest improvements of the admin UI. Check out our post for more!

Orchard Core updates

Placements module V2

We can do quite everything without creating any module or theme, but it's not possible to override default placement. It could be helpful to have a UI where you can easily define placement rules. Either we can add this to Part/Field settings or add a distinct UI (like the "Templates" one) where we can define a list of placement rules.

The Placements module adds an optional feature that lets the user define custom placements rules in the admin UI. This V2 of the module is a rewrite of the original one, it uses IShapePlacementProvider to provide placements at runtime. The IShapePlacementProvider interface allows to asynchronously (useful if it relies on an async placement store) build an IPlacementInfoResolver for each IBuildShapeContext. The IPlacementInfoResolver implementation keeps placement rules for the current IBuildShapeContext to be able to quickly resolve shape placements synchronously.

But don't go into too many technical details right now, lets's see how you can use this feature!

Set up your site using the Blank site recipe then head to Configuration -> Features to enable the Placements module. Now you will find a new option under Design, called Placement. But don't go that far! We set up our site using the Blank site recipe so we don't really have much content on our site. To test out that feature we will need to define at least one content type. Let's do it quickly! We have just created a new Page content type, added a Link Field to it, and some Parts: the Title Part, the Flow Part, and the HtmlBody Part.

Our Page content type

Let's create a new Page content item and preview it! You should see something like that: the title of the page content item, the link field, the widgets in the Flow Part, and the content of the HtmlBody Part.

Preview the Page content item

Now it's time to go back to our Placements module. Let's say we would like to hide the LinkField of our page. To do that, navigate to Design -> Placements and add a new placement. Call it LinkField because we would like to modify that field right now. And the Placement rules text is prepopulated with null values. To hide the Link Field, just simply modify the place value to "-". Note that this will hide every Link Field of the site!

Hiding every Link Field

But sometimes it's not obvious how to write the placement rules correctly for the first time. You have to know some words about the content templates, shape differentiators, content part and field differentiators, and so on. And here comes another great feature of the Placements module! Let's say we would like to hide the editor of the link field. Navigate to Content -> Content Definition -> Content Types and select the Page. Hit Edit and Edit again near the Link Field. Here you will find a new Edit placements button that contains some predefined placements for our Link Field (named Source). If you click some of those, a new placement will be created. Let's select Placement in admin editor for the Source field in a Page. This will generate the following placement:

Hiding the editor of the Link Field from placement

As you can see here, the type of shape is LinkField_Edit and the differentiator has the Page-Source value. That means to target the editor of the Link Field called Source of the Page content type. If you say "-" for the place, it will hide the editor of the Link Field when creating or editing Page content items.

New IsImageFile Orchard helper

Instead of using a RegEx or something like that, there is now a new IsImageFile Orchard helper that uses a static HashSet that contains the possible allowed file extensions that an image file could have. Just use this helper to determine if a path is an image file.

IsImageFile Orchard helper

Shortcodes 1.0.0 is here

There is a Shortcodes module in GitHub created by Sébastien Ros that is a shortcodes processor for .NET with a focus on performance and simplicity. It allows text content editors to inject specialized content blocks using custom arguments, like images, Twitter embeds, youtube videos, only with simple blocks like [video 123]. It has several features, like supporting async shortcode to execute database queries and async operations more efficiently under load or supporting named and positioned arguments. And this is the library that is integrated into Orchard Core to be able to work with shortcodes. We mentioned the Shortcodes feature of the CMS several times in This week in Orchard, for example here, now let's focus on the latest changes of the module.

The big news is now this module was come out from the beta version! Let's mention the biggest change of this new version. David Hayden was trying to write a blog post with some C# code inside and in the C# code there were some attributes and there were some Shortcodes in the attributes. When you evaluate a Shortcode using this library it just outputs to nothing if it's unknown. This means all the attributes from the code were removed. From now if there is an unknown Shortcode or it can't be parsed, the module will just output it as is.

Shortcodes module NuGet

AutoroutesEntries Atomicity and Size

This allows for synchronization between multiple nodes of a cluster, specifically for AutoRoutes. If you are on one node and you create a new AutoRoute, then the other nodes will update their AutoRoute mapping for the new AutoRoute. It's not just about data to load, it's also updating the resolution list: a dictionary that maps content items to routes.

Managing AutorouteEntries

There is an AutoRoutePartIndex that is used to detect what had changed since the synchronization of the last element. Every YesSql index is updating things with an incremental identifier so, if there is a change on one AutoRoutePart it's not updating the previous indexes, it's just adding new indexes and removing the previous one. Now, this index is used to just sync every node to the new state. It's like a synchronous pattern, the index just shows the new things that happened on the AutoRouteParts, and then it's applied directly to the AutoroutesEntries structure. Check out the AutoroutePartIndexProvider class in the dev branch!

The AutoroutePartIndexProvider


Admin UI improvements

The admin UI of Orchard Core got several improvements lately. In the demo of our current post, we will check out the updated UI. Let's start!

When you navigate to the admin UI of your site you can see the Orchard logo and the name of your site on the left side of the top bar. From now if you click on it, it will navigate to the home page of the admin theme. But don't worry, you can still easily navigate to your site, just use the little arrow at the right of the top bar. Oh, and one more thing: if you click on that little user icon on the right, you can see the user name of the currently logged-in user.

The header of the admin theme

If you have the Tenants feature enabled you can add tenants to your site. The list of the tenants is now a little bit different. You can see the name of the database preset, the description, the used recipe, and the state of the tenant.

The Tenants page

Now let's navigate to the content items list to check out the new design there too. You can see that every line start with the display text of the content item, followed by the content type, the status of the content item, the date of the latest modification, and the author of the content item. You can see that the About article has a draft and a published version too.

Content items list

And lastly, go to the Design -> Widgets page and check out the design there. You could see we have two widgets right now, the one with the display text My widget is a content type of Container that has two versions and associated with the Homepage layer. The other one is placed on the Always layer.

Widgets page

And that's not all of the improvements and more are just on the way! Check out this recording on YouTube to know more!

News from the community

Work with us!

You've completed the Dojo Course, congratulations! You’re now officially an Orchard Core developer. Would you like to work on a variety of challenging Orchard Core projects with the biggest Orchard team in the world? Work with us! Just send us an e-mail to crew at Please include what you’re most interested in professionally and attach around 100 lines of any kind of code that you’re especially proud of or just link to the favorite open-source project of your own on GitHub or else.

Orchard Dojo Newsletter

Lombiq's Orchard Dojo Newsletter has 184 subscribers! We have started this newsletter to inform the community around Orchard with the latest news about the platform. By subscribing to this newsletter, you will get an e-mail whenever a new post published to Orchard Dojo, including This week in Orchard of course.

Do you know of other Orchard enthusiasts who you think would like to read our weekly articles? Tell them to subscribe here!

If you are interested in more news around Orchard and the details of the topics above, don't forget to check out the recording of this week's Orchard meeting!

No Comments

Add a Comment