HedgeBlog

Introduction to Sitecore SPEAK Behaviors

The Sitecore SPEAK platform allows developers to build robust applications for use in the Content Manager environment. SPEAK contains many common UI element building blocks that allow developers to easily build applications that integrate into the Sitecore desktop.

But what if one of the common elements doesn’t do exactly what you want? What if there were a component that had almost all of the functionality you need, but was missing some small feature? There are a few possible ways to resolve this situation.

  • Build your own UI element by copying the closest one and modifying it.
  • Use the page script for your SPEAK application to find the control and add the functionality through Javascript.
  • Use a SPEAK Behavior.

The first two have problems like forward compatibility, difficulty re-using the control on multiple pages and the effort required to dig deeply into the inner structure of a SPEAK component to determine how it works. Using SPEAK Behaviors bypasses some of these problems and can easily be reused on multiple pages or even multiple projects.

This example of behaviors was created using Sitecore 7.1 (rev 140130). I suspect the techniques presented below will work with other versions of Sitecore that are before 7.5. Sitecore 7.5 and above have a new version of SPEAK, so there may be a few differences but the general ideas will still apply.

Our New Behavior

As one of a small group of web developers that is still mourning the passing of the <Blink> tag, I am always looking to new platforms to see if they have brought it back. Unfortunately, SPEAK choose not to implement blinking as an option for their labels. However, SPEAK Behaviors offer us the unique opportunity to easily re-introduce it. Our goal is to take the existing label control and add a behavior that causes the label to blink.

Applying a Behavior to a UI Element

Behaviors are very easy to add to an existing element. They are easily set in the rendering property page for a UI element.

When the page renders, the specified behavior will be applied to the UI element.

Creating a New Behavior

Setting up a new behavior is relatively simple. The easiest way to begin is to locate the existing behaviors and use them as a template for setting up the new one.

Creating a SPEAK Behavior Rendering

Behaviors are located in the SPEAK/Layouts folder. The full path to the folder is /sitecore/client/SPEAK/Layouts/Renderings/Behaviors. In this case, I created a sub-folder for my behavior called “BlinkTest”:

This folder will hold my “Blink” behavior.

To create the Behavior, simply create a new view rendering in the folder and name it. Once you have created the rendering, you must configure it to be a Behavior. This requires a few simple steps.

First, the Path property is set to the value /sitecore/shell/client/SPEAK/Layouts/Renderings/Behaviors/Behavior.cshtml. This .cshtml file implements the server side functionality for the behavior. Currently, this is just a script include, since everything with behaviors happens on the client.

Next, the following Default Parameters need to be set on the rendering:

  • PlaceHolder: Page.Code
  • PageScriptFileName: [Path to the behavior script file]
  • Name: [Behavior Name]

The last step is to create the Parameters Template and set the Parameter Template property on the Behavior. This is done by right-clicking on the behavior in the Sitecore Explorer and selecting “Create SPEAK Parameters Template”. This creates a template named “[Behavior Name]-Parameters” under the rendering. Other behaviors do not name their Parameter Template this way, so I removed the “-Parameters” from the name.

Once the Parameter Template is created and correctly hooked up to the Behavior Rendering, you need to change the base type of the Template. It must inherit from “BehaviorBase” instead of “ControlBase”. To change this, right-click on the Template Editor for the Template and select “Set Base Templates”. In the Base Templates popup, search for “BehaviorBase” and add it to the Template. Remove “ControlBase” from the bottom. Click “Ok” and save the Template.

Next, right-click on the Template Editor page select “Create Standard Values”. At this point, your Behavior rendering should be created.

Creating the Code File

When the Behavior Rendering was created, The Default Parameter PageScriptFileName was set to the location of the script file. For this example, I chose to locate the script file in a location that was different than the one Sitecore is using for their behaviors. The actual script for the blink tag is relatively simple.

//Make sure we have the components we need before trying to register the behavior
define(["sitecore"], function (_sc) {
    //Create the behavior
    _sc.Factories.createBehavior("Blink", {
        //Use the afterRender "event" to add our functionality
        afterRender: function () {
            //Locate the actual UI element
            var control = this.$el;

            var blinkOn = false;

            //This implementation assumes black text on a white background
            window.setInterval(function () {
                //Very simple implementation of blink.
                if (blinkOn) {
                    control.css("color", "black");
                    blinkOn = false;
                }
                else {
                    control.css("color", "white");
                    blinkOn = true;
                }
            }, 1000);
        }
    });
});

Sitecore behaviors are simply JS objects that implement a few simple functions. The Sitecore UI calls these functions when rendering the page and the developer can then perform any operations needed to implement the behavior. This behavior uses the afterRender event. Sitecore also has events called initialize, beforeRender and render for behaviors.

The this object contains a number of very useful objects. The example above uses the $el object in this, which is the jQuery wrapped UI element. You also have access to the app and model objects as well. This give the developer pretty much anything they need to implement their functionality.

Note: The Sitecore Behavior script file seems to be cached by the browser. You will need to manually clear the file from the cache after updating it.

Adding the Behavior to the Page

To use your new Behavior, you need to add the behavior to the page. This is done by adding the rendering to the layout the same way you would add any other rendering.

Now you can easily add the Blink behavior to any labels on your form as shown above.

Going Further

There were a number of things I didn’t implement in this behavior. This component really should look at the type of UI element it is being applied to and react accordingly. This sort of functionality is key to making the component into a real Behavior.

The flexibility Sitecore built into their Behavior mechanism allows developers to implement some very cool functionality relatively easily. (Note: Blinking text is not cool). Please feel free to let me know what you think in the comments below.

0

Leave a Comment

HedgeBlog is the blog of Hedgehog, a full-service digital agency. It's our fresh take on what's new, what's now, what's next in technology, online media, and beyond. Drop by, chime in, and be inspired.

Newsletter