This post is the fourth and final in a series about Sitecore SPEAK components.
Now we have seen how a SPEAK component is built in part 1, 2, and 3. In this post I will show a full example of a really simple custom control.
Why create a Custom SPEAK component anyway?
Sitecore delivers 70++ SPEAK controls and components which should cover most needs, but in some cases you might want something completely domain specific in your SPEAK application which cannot be achieved with the standard controls.
Always look for a standard control first to get the full benefit of the SPEAK api only resort to creating your own control as a last option.
Creating the SPEAK control
Okay this control is going to be really kind of pointless it is purely an example. The control will consist of a text which is set as a parameter on the control and a counter for counting how many times it has been clicked. When it has been clicked 2 times the text is reversed and the background color of the control is changed.
Step 1:
First we need to create a project in Visual Studio for the control. The project should just be an empty MVC3 or higher web application project.
In my example I have placed the project under /Components/SpeakExample/ and to make this work the project also needs to contain a web.config file.
<?xml version="1.0"?>
<configuration>
<configSections>
<sectionGroup name="system.web.webPages.razor" type="System.Web.WebPages.Razor.Configuration.RazorWebSectionGroup, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="host" type="System.Web.WebPages.Razor.Configuration.HostSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
<section name="pages" type="System.Web.WebPages.Razor.Configuration.RazorPagesSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
</sectionGroup>
</configSections>
<appSettings>
<add key="webpages:Version" value="2.0.0.0" />
<add key="ClientValidationEnabled" value="true" />
<add key="UnobtrusiveJavaScriptEnabled" value="true" />
</appSettings>
<system.web.webPages.razor>
<host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
<pages pageBaseType="System.Web.Mvc.WebViewPage">
<namespaces>
<add namespace="System.Web.Mvc" />
<add namespace="System.Web.Mvc.Ajax" />
<add namespace="System.Web.Mvc.Html" />
<add namespace="System.Web.Routing" />
<add namespace="Sitecore.Speak" />
</namespaces>
</pages>
</system.web.webPages.razor>
</configuration>
This file also exists in the /sitecore/client/shell folder for making the out-of-the-box controls work. Sitecore actually made a folder under /sitecore/client/shell/speak/yourapps for custom SPEAK applications but I don’t like to have custom code within the /sitecore folder.
Reference the following libraries from the /bin folder:
- Sitecore.Kernel
- Sitecore.Mvc
- Sitecore.Speak.Mvc
Now create a folder called Controls and in this create another folder for the control called ExampleControl
When the folder is created, then add a cshtml file, a js file and a less/css file all called ExampleControl.
Now open the cshtml file and insert the following mark up and code, (see part 3 simple approach):
@using Sitecore.Mvc.Presentation
@using Sitecore.Mvc
@using Sitecore.Web.UI.Controls.Common.UserControls
@model RenderingModel
@{
var userControl = Html.Sitecore().Controls().GetUserControl(Model.Rendering);
userControl.Requires.Script("speakexamples", "ExampleControl.js");
userControl.Requires.Css("speakexamples", "ExampleControl.css");
userControl.Class = "example-control";
var displayedText = userControl.GetString("DisplayedText", "displayedText", "Some text");
userControl.Attributes.Add("data-sc-displayedtext", displayedText);
var htmlAttributes = userControl.HtmlAttributes;
}
<div @htmlAttributes>
<div class="example-text" data-bind="text: displayedText">@displayedText</div>
<div class="example-count" data-bind="text: count">0</div>
</div>
Notice the Knockout data-bind attributes which binds the model attributes to the markup.
And for some styling I did this dirty stuff here:
.example-control {
width: 100%;
padding: 20px 20px;
background-color: red;
}
.example-text, .example-count {
text-align: center;
width: 100%;
display: block;
clear: both;
}
.example-text {
font-size: 1.5em;
background-color: #eee;
}
.example-count {
margin-top: 20px;
font-size: 3.5em;
font-weight: bolder;
}
Step 2:
Now go to Sitecore Rocks and register the cshtml as a rendering. Create the rendering in a rendering folder beneath your custom SPEAK application to keep it confined (see part 2).
Add a parameters template as a child item to the rendering and add a parameter called DisplayedText.
Now set the parameters template field on the rendering item to the newly created sub item (see part 2).
Step 3:
Now to the JavaScript, open the ExampleControl.js file and create a base component which inherits from BlockBase (see part 1).
Create a model attribute for the DisplayedText parameter and another model attribute called count which we give the default value 0. Also add an event for whenever the selector example-text is clicked.
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:displayedText", this.onTextChanged, this);
console.log(this);
},
onTextClicked: function (event) {
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("");
}
});
});
In the initialize method we listen for when the attributes changes and then we create a method for handling the click event and another method for handling the change of count. The onTextClicked method simply counts up the count attribute with one whilst the onCountChanged method checks if the count modulus 2 is equal to zero. If this is the case the background color of the whole control element is changed and the text is reversed. Step 4:
Finally to test this ingenious control we insert it on the presentation details of an item in our SPEAK application in core.
First we need to create the SPEAK application. Create a node item called SpeakExamples and in this create another node item called Pages. Here we create an Speak-DashboardPage item called StartPage and beneath this we create a Speak-PageSettings Item. Under the PageSettings item we create a folder called Texts in which we add a Text item called Header.
In the Text field on the Header Text item we write SPEAK examples.
Now design the layout of the StartPage item and insert the following renderings. Where the HeaderText datasource is set to the newly created Text item.
For more information about setting up a SPEAK application see the Sitecore Order Manager example and the videos from the Rocks guy.
The control now displays like this on the page:
And when the click count modulo two is equal to zero:
Voila.
Quite an overcomplicated approach to achieve this rather pointless functionality but I hope that it still serve as a good example showing how easy it is to set up a custom SPEAK component within a SPEAK application.
Sum up
This post showed how to create a very simple custom SPEAK control. It is based on the previous posts shown in a series about SPEAK components.
Please do not hesitate to write me or drop a comment if you have any questions / suggestions / corrections what so ever. I will just appreciate any feed back and thanks for reading this far.
The code can be downloaded from this post with an action and condition introduced.
Note that this post is based on the version of SPEAK which shipped with Sitecore 7.1.0 rev. 130926. The API is likely to change slightly so Sitecore updates which makes some of this post outdated might occur.