Creating custom Sitecore SPEAK rule Conditions and Actions

After writing my previous post about Sitecore SPEAK rules magic I got really excited when I realized how extremely easy it is to add new actions and conditions to the SPEAK rules engine. So here goes.

To make any real sense of this post I would suggest that you start reading from my first post about SPEAK if you haven’t read the previous posts already.

Setting up the environment

First we create some new folders in our SpeakExamples project from the previous posts. One folder called Rules with two sub-folders, one called Actions and one called Conditions.

Then we add a new source element for the speak.client.resolveScript pipeline in Sitecore.Speak.Config

        <processor type="Sitecore.Resources.Pipelines.ResolveScript.Controls, Sitecore.Speak.Client">
          <sources hint="raw:AddSource">
            <source folder="/sitecore/shell/client/Speak/Assets" deep="true" category="assets" pattern="*.js" />
            <source folder="/sitecore/shell/client/Speak/Layouts/Renderings" deep="true" category="controls" pattern="*.js,*.css" />
            <source folder="/sitecore/shell/client" deep="true" category="client" pattern="*.js,*.css" />
            <source folder="/sitecore/shell/client/speak/layouts/Renderings/Resources/Rules/ConditionsAndActions" deep="true" category="rules" pattern="*.js" />
            <source folder="/Components/SpeakExamples/Controls" deep="true" category="speakexamples" pattern="*.js,*.css" />
            <source folder="/Components/SpeakExamples/Rules" deep="true" category="rules" pattern="*.js" />
          </sources>
        </processor>

</sources>

</processor>

In this new element we “extend” the category named rules which usually only cover the standard rules folder to also include our new Rules folder.

This allows us to add new JavaScript in this category without having to store our code under the /sitecore folder.

You could also create the JavaScript files directly in the Sitecore folder \sitecore\shell\client\Speak\Layouts\Renderings\Resources\Rules\ConditionsAndActions\and skip this step but I think it is really bad practice to put your own code in the \sitecore folder except if there is no way around it which there is in this case.

Creating the Condition

Under the item /sitecore/client/Speak/Layouts/Renderings/Resources/Rule/Rules/ we create a new Condition item which we call ModuloValueEqualToZero and set the text field to:

where the component [name,,,name] attribute [attribute,,,attribute] modulo [value,,,value] is equal to zero

1	where the component [name,,,name] attribute [attribute,,,attribute] modulo [value,,,value] is equal to zero

Then we create a JavaScript file beneath the newly created project folder /Rules/Conditions which we call the same name as the item ModuloValueEqualToZero.js this file returns a condition.

The name of the JavaScript file has to be the exact same name as the Rules item, this is what is used to look up the rules implementation. Not sure I like that it is based on the item name but it is easy to work with.

define([], function () {
  var condition = function (context, args) {
    var componentName = args.name;
    var attribute = args.attribute;
    var value = args.value || 0;

    var component = context.app[componentName];

    if (component == null) {
      throw "Component '" + componentName + "' not found";
    }

    var attributeValue = component.get(attribute);

	if (attributeValue == null) {
      throw "Attribute " + attribute " does not exist on '" + componentName;
    }

	if (typeof attributeValue !== 'number')
		attributeValue = parseInt(attributeValue);

    return attributeValue % value == 0;
  };

  return condition;
});

define([], function () {

var condition = function (context, args) {

var componentName = args.name;

var attribute = args.attribute;

var value = args.value || 0;

var component = context.app[componentName];

if (component == null) {

throw "Component '" + componentName + "' not found";

}

var attributeValue = component.get(attribute);

if (attributeValue == null) {

throw "Attribute " + attribute " does not exist on '" + componentName;

}

if (typeof attributeValue !== 'number')

attributeValue = parseInt(attributeValue);

return attributeValue % value == 0;

};

return condition;

});

The code should be rather self-explanatory. First we read the parameters which is passed from the rule, notice that the parameter names in the args object is the names we set in the text field on the rules item.

Then we validate the parameters and finally check if the attribute value modulo the passed value is equal to zero.

Creating the Action

Under /sitecore/client/Speak/Layouts/Renderings/Resources/Rule/Rules/Actions/ we create a new Action item called CallFuntion and set the text field to:

call function [function,,,function] on component [name,,,name]

1	call function [function,,,function] on component [name,,,name]

Then as we did when we created the condition, we create a JavaScript file for the Action item which we call CallFuntion.js in the folder /Rules/Actions in our SpeakExamples project.

define([], function () {
  var action = function (context, args) {
    var functionName = args.function;
    var componentName = args.name;
    var component = context.app[componentName];

    if (component == null) {
      throw "Component " + component + " does not exist";
    }

    var fn = component.viewModel[functionName];

    if (typeof fn !== "function") {
      throw functionName + " is not a function on " + component;
    }

    fn(component);
  };

  return action;
});

define([], function () {

var action = function (context, args) {

var functionName = args.function;

var componentName = args.name;

var component = context.app[componentName];

if (component == null) {

throw "Component " + component + " does not exist";

}

var fn = component.viewModel[functionName];

if (typeof fn !== "function") {

throw functionName + " is not a function on " + component;

}

fn(component);

};

return action;

});

Notice that we pass the component as a parameter to the function. This will make the function handle “this” as the component so we do not have to re-write the function to be out of context. This action will only work for calling parameter-less functions but that can easily be modified if desired.

This code should be rather self-explanatory as the Condition code was but this on the other hand really shows the power of JavaScript. By using reflection in C# the same could be achieved as well but with a whole lot more pitfalls, this just runs without complaints.

I really like this Action, I think it should be part of the standard API. Even though it is a bit like having a call to eval(someString) from a rule just a bit more clean.

Setting up the rule

First of all make sure everything is saved and then also recycle the app pool of your site or do an iisreset. Otherwise Require will not find your new JavaScript files. These are cached on initialize.

Now we go back to the SpeakExamples StartPage item and add a new RuleDefinition item beneath the Rules folder which we call CountChangedRule:

Then we edit the rule to use our new custom condition and action as follows:

Now we do not need to listen for the change of count in the ExampleControl.js so we remove that one line and we can also remove the if statement checking if count modulo 2 is equals to zero (no lines of code saved really, but we gained a whole lot of flexibility).

define(["sitecore"], function (_sc) {
  _sc.Factories.createBaseComponent({
    name: "ExampleControl",
    base: "BlockBase",
    selector: ".example-control",
    events:
  {
    "click .example-text": "onTextClicked"
  },
    attributes: [
        { name: "displayedText", value: "$el.data:sc-displayedtext" },
        { name: "count", defaultValue: 0 }
    ],
    initialize: function () {
      this._super();
      this.green = false;
//      this.model.on("change:count", this.onCountChanged, this);
      this.model.on("change:isVisible", this.toggleVisible, this);
    },
    toggleVisible: function () {
      if (!this.model.get("isVisible")) {
        this.$el.hide();
      } else {
        this.$el.show();
      }
    },
    onTextClicked: function () {
      this.model.set("count", this.model.get("count") + 1);
    },
    onCountChanged: function () {
//      if (this.model.get("count") % 2 == 0) {
        this.green = !this.green;
        this.$el.css("background-color", this.green ? "lightgreen" : "red");
        this.model.set("displayedText", this.reverse(this.model.get("displayedText")));
//      }
    },
    reverse: function (text) {
      return text.split("").reverse().join("");
    }
  });
});

define(["sitecore"], function (_sc) {

_sc.Factories.createBaseComponent({

name: "ExampleControl",

base: "BlockBase",

selector: ".example-control",

events:

{

"click .example-text": "onTextClicked"

attributes: [

{ name: "displayedText", value: "$el.data:sc-displayedtext" },

{ name: "count", defaultValue: 0 }

initialize: function () {

this._super();

this.green = false;

// this.model.on("change:count", this.onCountChanged, this);

this.model.on("change:isVisible", this.toggleVisible, this);

toggleVisible: function () {

if (!this.model.get("isVisible")) {

this.$el.hide();

} else {

this.$el.show();

}

onTextClicked: function () {

this.model.set("count", this.model.get("count") + 1);

onCountChanged: function () {

// if (this.model.get("count") % 2 == 0) {

this.green = !this.green;

this.$el.css("background-color", this.green ? "lightgreen" : "red");

this.model.set("displayedText", this.reverse(this.model.get("displayedText")));

// }

reverse: function (text) {

return text.split("").reverse().join("");

}

});

Finally we add a new Rule rendering to the StartPage of our SpeakExample application:

Here we set the trigger to change:count and the TargetControl to ExampleControl.

Voila, and now we have the exact same useless functionality as before just made with a custom condition and action.

It is actually really easy to create conditions and actions for the SPEAK rules engine. Even easier than doing it in C#.

Merry Christmas everyone. I hope someone can use this post. Please feel free to comment, thanks.

The code can be downloaded here: SpeakExamples.zip

And the serialized items here: serialization.zip

Extract the project from SpeakExamples.zip in a new folder beneath your Sitecore installation. Extract the serialization.zip archive into a folder called serialization in /App_data and run Tools – Serialization – Update Tree using Sitecore Rocks on the item /sitecore/client/Your Apps and /sitecore/client/Speak/Layouts/Renderings/Resources/Rule/Rules

Anders Laub Christoffersen

Anders has been working with Sitecore for over a decade and has in this time been the lead developer and architect on several large scale enterprise solutions all around the world. Anders was appointed the title of Sitecore Technical MVP in 2014 and has been re-appointed the title every year since then.

Setting up the environment

Creating the Condition

Creating the Action

Setting up the rule

Anders Laub Christoffersen

One thought on “Creating custom Sitecore SPEAK rule Conditions and Actions”