Sitecore SPEAK rules magic

At this time of year everyone is speaking about Christmas magic, but today I will show you some SPEAK magic using rules.

Following the example I gave in my last post where we made a text clickable and then changed the background color depending on the click, now let us make a rule which hides the control when count is equal to let say 22.

Setting up the Sitecore SPEAK rule

First we create a folder called Rules beneath the StartPage PageSettings item and in this folder we create a RuleDefinition item which we call HideControlRule.


Now we want to create a condition like this one:

rule definition

This makes my Sitecore Rocks throw an exception because the equals to operator item does not exist in the core database.

Exception thrown by Rocks

Everything is still good though, I notice that Rocks has inserted the same operator ID in the raw value of the rule field as expected by a switch-case in PropertyValue.js

Now when we have created the rule then we need to insert a Rule rendering on the StartPage layout.

rule rendering parameters

Here we set the control to ExampleControl, the trigger as change:count and then we point to the rule item we just created.

And then we also ensure that the ExampleControl have the ID ExampleControl:

remember to set the id

Last but not least we need to make some code which listens to change on the isVisible attribute and fires a function for toggling visibility of the view element.

The isVisible attribute is inherited from the ControlBase SPEAK component but there is no standard implementation which shows and hides the element. I think that is kind of strange actually but it is easy to write, just a bit redundant to have in all of your custom controls (Why is this function not standard Sitecore? Am I missing something).

When clicking the ExampleControl displayText 22 times then the control hides itself as expected.

This is again a somewhat useless example but so is the entire ExampleControl. I still hope that it serves as a good example.

A more useful rule

A good time-saving example is to enable/disable a button using a rule. For example the condition could be if the text attribute of a text box is empty then the enabled attribute of a button is false. The event trigger will then be change of the text box text attribute.

This is easy to do in code but even easier to define. The rule is also more flexible and easy to extent than the code, it is simply just adding a new action to it.

Looking at the SPEAK dialog InsertAnchorDialog underĀ /sitecore/client/Sitecore/Common/Dialogs we can see an example of such a rule.

Enable Button When Has Text

The Rule is set on the InsertAnchorDialog layout just as we saw in the ExampleControl example.

Looking at the dialog we have a bit of an issue though (just type in <hostname>/sitecore/client/Sitecore/Common/Dialogs/InsertAnchorDialog in your browser)

– No text in the text field button is disabled, all is good.

Disabled Button

– We type in text and the button enables, great.

Enabled Button

– Then we remove the text again but the button is still enabled. Not that great.

Button Still Enabled

Fixing the Sitecore standard dialog

So to fix this we need to make a “reverse” rule which states that when the Text.text attribute is equal to empty string then disable the button.

Notice that empty string is not “” it is a real empty string as value. Rocks will write value when you open the rules editor again but it is really just an empty string in the raw value.

Disable Button Rule

Then we insert a Rule rendering on the InsertAnchorDialog and point to our new rule item, set the trigger to change:text and set the TargetControl to Text.

Disable Button Rule Rendering

And now it works both ways, the button is disabled again when the text attribute of the Text Textbox is empty.

Dissecting the SPEAK rules engine

All conditions and actions used in SPEAK are placed as items in the core database underĀ /sitecore/client/Speak/Layouts/Renderings/Resources/Rule/Rules

Actions and condition items

Each item contains the syntax used by the Action or Condition which is quite straight forward. It seems like it should be easy to create your own but I have not tried this yet.

The JavaScript for the actions and conditions is placed in the physical folder <website>\sitecore\client\shell\Speak\Layouts\Renderings\Resources\Rules\ConditionsAndActions\

Which is set as the category rules for the SPEAK custom handler / RequireJS.

Now from looking in the markup for the rule we just created we can see that there is a data attribute called sc-rulescript which is a path to rule.js with a query parameter that contains the ID of the rules definition.

This is an auto-generated rule Javascript which looks like this for the ExampleControl rule we created in the start of this post.

Extremely simple actually but also extremely powerful.

So what can Sitecore SPEAK rules be used for?

In the long run editors might be able to define their own rules and then you would not need a developer for making a simple Sitecore application at all, just a well-trained editor. The UI will need quite some improvements before this could become a reality. But is it feasible at all? Not sure, and we developers like to code everything ourselves most of the time which also can be an obstacle.

If creating SPEAK rules instead of coding can save us time then it will be more than welcome. To really help us save time it will require that a larger collection of actions and conditions exists out-of-the-box though. I would also like to see some more documentation from Sitecore in how to write new conditions and actions even though it seems quite easy. For example an action for calling some function on a component would be quite useful. I’ve implemented this action along with a condition in my next post.

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.

6 thoughts on “Sitecore SPEAK rules magic

  1. This makes my Sitecore Rocks throw an exception because the equals to operator item does not exist in the core database.

    This bug is already fixed in CMS 7.2 it’s going to be released in the nearest time.

Leave a Reply

Your email address will not be published. Required fields are marked *