LibrarySites.Banner

Creating custom conditions, Part 1

The rules engine in Sitecore is very powerful and used for a lot of things behind the scenes. When Creating Sitecore projects, the most obvious place the rules engine is used is for applying conditional rending rules like changing the content for a user based on that users browser behavior.

The rules in Sitecore is straight forward one or more conditions that gets evaluated and if they return true, one or more actions are carried out.

This series of blog posts will go through the different kinds if custom conditions that you can easily create and explain how to.

There are already a lot of conditions available out of the box. Both DMS specific, like “Where the visitors is from specific country”, but also a lot of common conditions like “when fieldname compares to specific value”.

If the condition that you want to use for your customer is not there, you can of course create it yourself. As with everything else in Sitecore it is possible to extend the rules engine for example by creating new custom conditions.

This first post will go through the areas, settings and items in Sitecore that relates to the conditions and explain the parameterized text string that is used in conditions.

Conditions are located in subfolders under sitecore/system/Settings/Rules. the conditions are located under the rules category they belong to:

image

When creating a custom condition you need a condition definition item. the definition item is based on the Condition template located here: /sitecore/templates/System/Rules/Condition.

Once created, the condition item contains 5 fields. It is the Text field and the Type field that I will focus on in these series of blog posts.

The Type field is the easy one, here you just reference your custom code: “namespace.method name, the assembly”.

The Text field

The Text field is more tricky! this is where you write the text and the changeable parameters that the editor will see when using your custom condition.

Example: one of the standard conditions looks like this when an editor uses it:

“where the country compares to specific country.”

the corresponding condition items Text field looks like this:

where the country [operatorid,StringOperator,,compares to] [value,Tree,root=/sitecore/system/Settings/Analytics/Lookups/Countries,specific country]

The above string shows that you can combine normal text with parameterized lists. More specifically you can use 4 different parameters for each parameter set (each parameter set is defined by the square brackets).

Each parameter set will be shown to the editor as one underlined clickable word. In the above example the first parameter list gets shown as “compares to” and the second set is shown as “specific country”.

if you use the words “where”, “when” and/or “if”, those words will automatically be underlined and can be changed to “except where”, “except when” and “except if”, when the editor uses the condition.

The 4 parameters

The 4 parameters you can add for each parameter set has different purposes. If you look at the above example one of the parameter set looks like this:

[value,Tree,root=/sitecore/system/Settings/Analytics/Lookups/Countries,specific country]

The first parameter is the name of the property that the parameter sets in your class that you have written for your custom condition. The property needs to be public.

In the above example this means that you need a public property named “value” in your class.

The second parameter could be the name of an item which is stored under “/sitecore/system/Settings/Rules/Common/Macros”. The items stored in this area all corresponds to different predefined functionality.

If the parameter name does not match any of the macro items, or if you leave the parameter blank, a standard text input box will pop up when the editor clicks the clickable word. The value of the text box that the editor writes will set the property corresponding to the first parameter.

An example of a condition using a blank parameter as the second parameter is covered in Part 2 of this blog series.

Macro items

Below is a description of each out of the macro items. In the next parts of this blog series I will create examples for each of the macro items.

DateTime: Opens a Date and Time picker window. The DateTime that the editor chooses will be stored in the property corresponding to the first parameter.

image

Operator: Opens a dialogue where the editor can choose from different operators as shown in the screenshot. The operators available out of the box are defined in /sitecore/system/Settings/Rules/Common/Operators

image

Pattern: Opens a dialogue where the editor can choose from the created patterns.

image

PositiveInteger: Opens a standard text box, but the editor can only put in positive integers in the text box. A validation popup is shown if the value is not a positive integer.

Profile: Opens a dialogue where the editor can choose from the created profiles

image

ProfileKey: Opens a dialogue where the editor can choose from any of the created profile keys.

image

Script: Opens a dialogue where the editor can choose a script item.

StringOperator: The same as Operator but the options available are defined in /sitecore/system/Settings/Rules/Common/String Operators

Template: Opens a dialogue where the editor can choose from any of the created templates.

image

Tree: Opens up a tree list where the editor can choose any item. the 3rd. parameter can be used to limit the tree list.

image

Treelist: The same as the Tree macro, but allows the editor to choose multiple items from the tree list. the 3rd. parameter must be used to define the tree list. If the 3rd. parameter is left blank the condition will give the editor a .Net error.

The third parameter is usually used to pass a path to the macro parameter (the second parameter). the notation is “root=/sitecore/subitem/subitem/etc.”

This parameter doesn’t have an affect on all macros and can be left blank (except for the TreeList macro).

The following macros uses the third parameter:

PositiveInteger: For this macro the third parameter is not used as a path. Instead a default value can be written which will appear in the the text field that pops up.

Tree and TreeList: limits the tree that the editor can choose from. The notation has to be as explained above, “root=/sitecore/subitem/subitem/etc.”

If the name of the second parameter does not match any macros or the second parameter is blank, the third parameter is passed into the text field of the text box that pops up when using the condition.

The third parameter is ignored for all other macros.

The Fourth parameter

This parameter is the word that will appear as the text the editor can click on when using the condition. this parameter is free text but spaces are not allowed, it needs to be a single word.

The next blog posts will show examples of custom conditions for each of the different macros starting with the “empty” macro where the a text box will pop up.