LibrarySites.Banner

Using the Sitecore Rules Engine in a Custom Context: Setting the Context Device

This blog post describes how you can use the rules engine in the Sitecore ASP.NET CMS to invoke rules in a context that you define. Showing how to manage and invoke both global and specific rules, the example uses the rules engine to determine the context device, which controls the presentation components that Sitecore uses to render content. For more information about the rules engine, see the Rules Engine Cookbook on the Sitecore Developer Network (SDN), as well as my previous blog posts Sitecore Rules Engine and Conditional Rendering and Use the Sitecore Rules Engine to Control Item Names. For more information about the context device and presentation components, see the Presentation Component Reference and the Presentation Component API Cookbook.

By default, the DeviceResolver processor in the httpRequestBegin pipeline defined in the web.config file determines the context device:

  1. From the value of the sc_device query string parameter against a specific device name.
  2. By matching other query string parameters as defined by device definition items. 
  3. By matching the web client user-agent string as defined by device definition items.
  4. From attributes of the context site.

 

You can use the rules engine to refine how Sitecore determines the context device. For example, you could set the context device if the host name matches a given string, if the context site is a specific managed site, if the referring URL matches a given string, if search keywords include a specific token, if the context language is a specific language, and so forth. Note that Sitecore 6.4 introduced a number of new conditions for use with the rules engine.

To summarize, a rule consists of some number of conditions and some number of actions. When evaluating a rule, if the condition(s) evaluate to true, Sitecore invokes the actions. For this example, an httpRequestBegin pipeline processor evaluates a list of global rules to determine the context device. If none of the global rules applies, then the processor invokes rules defined in each of the device definition items, and sets the context device to the first such item for which the rule evaluates to true.

There are at least two ways that you can use the rules engine to set the context device. First, you can run some number of global rules, where the rule sets the context device to some specific device if the condition is true. Second, you can run some number of rules associated with each device, and set that device as the context device if the condition evaluates to true.

Download the prototype code and compile it into your Visual Studio project, which includes code that shows how to invoke both global and item-specific rules.

When you need to extend existing functionality in a pipeline, such as device resolution logic, you can replace existing processors in the pipeline, or you can add processors to the pipeline. When possible, avoid tampering with existing functionality. Because custom logic to determine the context device may depend on properties of the Sitecore context including the context site, the context item, the context language, and even the context device as determined by the default DeviceResolver, leave the default DeviceResolver in place, and add the custom device resolver late in the pipeline. More specifically, I think it belongs between ItemResolver and LayoutResolver:

<httpRequestBegin>
...
  <processor type="Sitecore.Pipelines.HttpRequest.DeviceResolver, Sitecore.Kernel" />
  <processor type="Sitecore.Pipelines.HttpRequest.LanguageResolver, Sitecore.Kernel" />
...
  <processor type="Sitecore.Pipelines.HttpRequest.ItemResolver, Sitecore.Kernel" />
  <processor type="Sitecore.Sharedsource.Pipelines.HttpRequest.RulesEngineDeviceResolver, assembly" />
  <processor type="Sitecore.Pipelines.HttpRequest.LayoutResolver, Sitecore.Kernel" />
...

When you define a new context for rules, such as using rules to determine the context device, you can either reuse the existing Sitecore.Rules.RuleContext class, or create a class that inherits from this base class. Primarily to demonstrate this feature, but also to abstract the Sitecore context, I chose to implement a specific context.

To manage global rules for the new rule context, create the User Defined/Rules/SetContextDeviceRule data template. Include a single-line text field named Name, a field of type Rules named Rule, and a field of type Checkbox named Disabled. Set the Source property of the Rule field to /Sitecore/System/Settings/Rules/Determine Context Device (this controls the conditions and actions you can select for this type of rule). This path does not yet exist, but you will create it in a moment. Set the icon for the data template to Software/32x32/shape_ellipse.png.

If there are any global rules for a rule context, or any conditions or actions specific to that rule context, then create a folder to contain those conditions, actions, and rules, and within the new folder, create child folders named Actions, Conditions, and Rules, all using the Common/Folder data template. The Actions folder will contain action definition items specific to this rule context, the Conditions folder will contain condition definition items specific to this context, and the Rules folder will contain global rules for this context. When defining a rule for this context, the user interface will list the conditions and actions defined in the Conditions and Actions folders under this path merged with the contents of the Conditions and Actions folders under the /Sitecore/System/Settings/Rules/Common item. For some rule contexts, you might not need all three of these child folders (for instance, if there are no context-specific Actions or no global rules for this context), or you might not need to create this branch at all (if the rule context uses only Common conditions and actions). For the device resolution context, create the /Sitecore/System/Settings/Rules/Determine Context Device item containing children named Actions and Conditions (if you expect to use global rules, also create a child named Rules). Configure insert options for the Actions child to include only the System/Rules/Action data template. Configure insert options for the Conditions child to include only the System/Rules/Condition data template. Configure insert options for the Rules child to include only the User Defined/Rules/SetContextDeviceRule data template.

Using the System/Rules/Condition data template, create the /Sitecore/System/Settings/Rules/Determine Context Device/Conditions/Context Item Has Layout Details for this Device condition definition item. Set the Text field to where the context item has layout details for this device, and set the Type field to Sitecore.Sharedsource.Rules.Conditions.ContextItemHasLayoutDetailsForThisDevice,assembly. This condition tests whether the context item has layout details for a device, where the item containing the rule is also the device definition item. Because this condition accesses the device that defines the rule, you should only use this condition in rules defined in specific devices, not in global rules.

Using the System/Rules/Action data template, create the /Sitecore/System/Settings/Rules/Determine Context Device/Actions/Set Context Device item action definition item. Set the Text field to set context device to this device, and set the Type field to Sitecore.Sharedsource.Rules.Actions.SetContextDeviceToThisDevice,assembly. Because this action accesses the device that defines the rule, you should only use this action in rules defined in specific devices, not in global rules.

Using the System/Rules/Action data template, create the /Sitecore/System/Settings/Rules/Determine Context Device/Actions/Set Context Device to This Device action definition item. Set the Text field to set the context device to the [DeviceID,tree,root=/sitecore/layout/devices,specific] device, and set the Type field to Sitecore.Sharedsource.Rules.Actions.SetContextDeviceToSpecificDevice,assembly. Global rules for this context can use this action to set the context device.

To add a field to contain the rule to the data template for devices, create the User Defined/Layout/Device data template containing a Detection section containing one field named Rule of type Rules with source set to /Sitecore/System/Settings/Rules/Determine Context Device. You can add any number of fields of type Rules to the data template. Then add this data template to the base templates for the Layout/Device data template. Then, go to the device definition items under /Sitecore/Layout/Devices, and in the Rule field, select conditions and actions. I simply used the condition and action I had just created.

To define global rules, under the /Sitecore/System/Settings/Rules/Determine Context Device/Rules item, insert items using the User Defined/Rules/SetContextDeviceRule data template, and fill out the fields appropriately.

The default DeviceResolver logic for matching user agents matches individual devices. For a prototype processor that uses regular expressions to match the user agents of multiple devices, see the List of User Agent Strings for Mobile Devices on the Sitecore Developer Network (SDN) forums. Alternatively, you could implement a global rule that sets the context device if a condition that matches the user agent against a regular expression evaluates to true. I included code for a prototype of such a condition.

To use this prototype, create the /Sitecore/System/Settings/Rules/Determine Context Device/Conditions/User Agent Matches Expression item using the System/Rules/Condition data template. Set the Text field to where user agent matches [Expression,,,expression] and the Type field to Sitecore.Sharedsource.Rules.Conditions.UserAgentMatchesExpression,assembly. When creating a rule with this condition (such as a global device resolution rule), set Expression to a regular expression something like the following that should match chrome and opera user agents:

^.*(chrome|opera).*$

This post is long and it might seem complicated if you've never used the rules engine before. But note that this took just a few dozen lines of code, and provides a powerful feature with a standardized, browser-based user interface with very flexible configuration options.