Custom Site Rule and Macro

April 17, 2018

Blog | Development | Custom Site Rule and Macro
Custom Site Rule and Macro

Recently I’ve been delving into Rules and am finally understanding how powerful the Sitecore Rules Engine really is.  Out of the box, Sitecore has a great amount of conditions, actions, and Macros you can use. But sometimes you want to make things specific to your business needs or make it clearer for the editors.  That is what I am going to show you today – how easy it is to create your own Rules and Macros and all within Sitecore’s powerful Rules Engine.

Example

Before I jump into what I did and how, let me lay the groundwork. A recent request came across from a client that has a multi-site Sitecore instance, they asked us to create new features and page types (templates) but limit them to a particular site. Given how things were structured, leveraging Standard Values and Branch Templates to drive the Insert Options, my first thought was that we would need to start creating new variants of the already existing templates and roll them out to the unique site with different Insert Options.

This option was less than ideal, but then I remembered this post showing the ability to create Insert Option Rules that would conditionally add/remove Insert Options based on spoken word rules.  This was nearly perfect: add the Insert Option to the Standard Values and block/remove it from everywhere except the unique site.  This could’ve been handled by the preexisting where the item is the specific item or one of its descendants Rule, which allows the user to select an item out of the content tree. I wanted to take it a step further, deriving that item based on the Sites that were defined in the <sites> config nodes. (In the event that the item a site node used as its root path changed, the logic would remain intact). So I decided to create a custom Rule Macro:

Custom Macro

Like I mentioned above, the existing Condition, where the item is the specific item or one of its descendants, would likely achieve what we wanted to do in the example –  limit insert options based on a site – that would be a specific item in the tree.  What I ultimately wanted was something similar, but that would instead select a Site from the configuration.  This helps cover changes to a Site’s root path or any kind of restructuring to the content tree. If a root path changes, no logic adjustment is necessary.  I wanted the ability to have the rule read like where the current item is site or a descendant of.  Let me introduce the actual code for the macro:

Create the Macro Item

Given the code for the Macro, create the Item (of type /sitecore/templates/System/Rules/Macro) that will invoke the above code, under the /sitecore/system/Settings/Rules/Definitions/Macros location in the tree. I named this Macro SiteInfo since it’s basically pulling the information from the SiteFactory for the conditional.

Create the Macro Item in Sitecore

Update Type Value

The only piece left for the Macro is to update the Type to reflect your fully qualified class for the Macro code.

Update Type Value in Sitecore

Below, you will see the actual result of the SiteInfo Macro itself when used in a Rule:

result of the SiteInfo Macro example in sitecore

Custom Rule

The SiteInfo Macro itself only just allows us to select a Site (or more realistically, the item at the rootPath of the site) but we will still need to make a custom Rule in order to actually use this item effectively. In this case, we will create a custom rule named Descendant of Site Rule. In short, what this rule does is compares the Item being invoked on the pipeline (most likely in our scenario, the folder we right-clicked on) to that of the site we selected in the Macro, and yields us a true|false answer to pass on to whatever action we will invoke (in our case: remove specific insert option).

Create New Condition

Register the new Rule within Sitecore. For this, we will create a custom Element Folder under the /sitecore/system/Settings/Rules/Definitions/Elements node; let’s call it User Defined. Under that User Defined Element Folder create a new Condition named Descendant of Site:

Create new condition for custom rule in Sitecore

Then, under the Data/Text field, put the spoken text where the current item is [siteItemId,SiteInfo,,site] or descendant of and under the Script/Type put YourNamespace.Rules.DescendantOfSiteRule,YourNamespace:

Example of Sitecore Data and Script

Add Tags to Element

Now it’s time to add some tags. Under the User Defined Element Folder, there should be a Default/Tags item. On this item, add Insert Options to the Taxonomy/Tags field so that this new rule shows up anywhere the Insert Options ruleset is available:

Add Tags to Elements in Sitecore

Add New Insert Options Rule

Once that’s set, you should be able to complete the last step needed to scaffold this: define a new Insert Options Rule under the /sitecore/system/Settings/Rules/Insert Options item. All rules under this node get executed any time a right click and Insert X/From Template shows up. This new Insert Option Rule allows you to define all the necessary logic (given all of the above) to include or exclude your desired Insert Options given your specified site:

Add new insert options rule in Sitecore

Hopefully, this post will help you see the potential that Rules and Custom Rules can give you nearly limitless power. This all gives you the ability to adapt to business rules and make your life managing the content tree easier.

A word of caution: Be smart about any and all Rules you create and invoke. They execute within the user experience and any time-consuming process may give a negative experience to the content editors.  Also, where possible, use except where instead of writing a handful of where statements to help both readability and processing.

Steve VandenBush

Technical Lead
Tags
  • Development
  • Macros
  • Rules
  • Sitecore

Recent Work

Check out what else we've been working on