main banner

Development

Sitecore Speak

An introduction to Sitecore Speak featuring a basic example application.

The ability to create Sitecore applications is fundamental in the Sitecore world as most projects have the need for custom functionality within Sitecore. Traditionally, the way to create Sitecore applications relied on using the Sheer UI framework. However, it has several issues which makes using it really hard and tedious, some of them are:

1 - Little and not up to date documentation.

2 - Relies on its own set of controls rather than using controls already know within the web community

3 -  Not based on the technologies used to create Sitecore web pages

4 – Too verbose

With the release of Sitecore 7, the SPEAK framework was released with the aim to replace Sheer UI and to solve most of its problems. SPEAK stands for Sitecore Process Enablement & Accelerator Kit and its main goal is to allow for a consistent interface that promotes easy and quick development of Sitecore applications.

I have been playing around with SPEAK for a few days. The first thing I noticed when I started, was that there is a lot of uncertainty about this framework as there is not much documentation yet and most information found online seems too overwhelming (I think this is because most information is focused on how SPEAK works from within and not on how we can use it), especially if you are not familiar with the latest front-end technologies. You will find bibliography at the end of this post.

After searching around the web and trying a few examples, I decided to create a blog entry where I could describe how to create a basic SPEAK example application (mainly based on Jakob’s Christensen youtube tutorials) and talk about SPEAK fundamentals as we go along.

SPEAK is all about components (these are basically Sitecore renderings).  These components use a MVVM (Model – View – Viewmodel) approach. This pattern allows every component to have a Javascript counter-part that implements the data model of the component. With this approach in place, every change we make to the JavaScript data model will be reflected in our view.

The application we will create is a very basic one; We will start by using some of the already available components on SPEAK (this set of components is known as the component library). Then, we will learn about the PageCode component (very important), and finally, we will create a very simple component ourselves. Let’s start creating our application:

First, to use SPEAK, we will need the Sitecore Rocks extension for Visual Studio. Using Rocks, open a connection to your Sitecore site. Once connected, open the Sitecore Explorer (within Visual Studio) and under the core database we will find a place where we can place our Speak applications. This is {SITE}/core/sitecore/client/Your Apps. We will create a folder named “My First App” where our application will be hosted.

The first thing that our application needs is a page. There are several types of pages you can create using SPEAK, but, in this example, we will create a SPEAK-ListPage (our application is mainly a listing). So, right click on the Properties folder, and go to Add → New Item → Look for ListPage → Select ListPage (see image below) à Call it “ListPage”

Sitecore Speak sample list page item

This will create our “ListPage” item right below our folder: 


Sitecore Speak sample list page folder

We now have a page in our Speak application that can be reached at:

{SITE}/sitecore/client/your%20apps/my first app/ListPage

Our page should look like this: 

Sitecore Speak sample list page

All the components we see on our new page are contained by default on our ListPage item. We can see these renderings by following these steps: right click on ListPage item → Tasks → Design Layout. Here is a screenshot of how the design layout of the component should look.  

Sitecore Speak sample list design layout

Most of the renderings are self-explanatory but there is one that deserves more attention. This is the PageCode rendering. The page code component is in charge of scanning the html and creating a JavaScript model for each component found (this is basically an MVVM pattern).

Now, let’s add a text component that will show a short message at the top of our page. Go to the design layout of our page and add a rendering of type text. 

Sitecore Speak sample list rendering

You will see that such rendering is now listing on the Design Layout of out ListPage: 

Sitecore Speak sample list design layout 2

Double click on it to see the “Edit Rendering Properties” dialog. Here, we can configure several properties of the rendering. In this case, let set the text property to “Hello World”.  Also, make sure to set the PlaceholderKey property to ApplicationContent.Main as shown on the following screenshot. 

Sitecore Speak sample list edit rendering

After refreshing our page, we should see our “Hello World!” text on our page now. 

Sitecore Speak sample list text parameters

Once created, assign such item to the datasource of our text component by using the Design Layout dialog of the ListPage item: 

Sitecore Speak list appereance

As you can see, we have deleted the value “Hello World!” from the text property. Instead, we would use the text property on our datasource.

Now that we know how to add components to our page, we can start creating our listing of items. Let’s add another rendering which will display our listing. We will do this using a ListControl rendering. 

Sitecore Speak list second rendering

Our ListControl needs to know which are the columns on the listing. Therefore, we will need to create an item of Template ListControl Parameters and under it, let’s create two items of template ColumnField. Set the fields as follows:

Sitecore Speak list control parameters 3

*Make sure to set the DataField values of the ColumnField items correctly, as you can imagine, this is the name of the actual field from which the column will take its data.

Once we have our columns, let’s set the datasource property of the ListControl to the item ListControl Parameters as follows: 

Sitecore Speak list control parameters 4

If we were to refresh our list page at this point, we will see a table with no data on it (only headers). 

Sitecore Speak list headers

It is now time to set a datasource for our table. For this, we need to create a Datasource component which will be in charge of reaching the Sitecore database for our items. So, add a new rendering of type SearchDataSource and set the following properties: 

Sitecore Speak list properties

The Id under the RootItemId field refers to the parent item the Datasource rendering will use to search. Such structure is shown below: 

Sitecore Speak list id structure

At this point our page will PageList will show some data on it: 

Sitecore Speak page list preview 3

If we would like to add some filter (search) functionality to our table we could add a Textbox rendering, and set the Text property of our datasource to it. SPEAK will automatically filter the list contents by the textbox value. 

Sitecore Speak list text box

So far, we have wired up existing SPEAK components and take advantage of their functionality. However, SPEAK also allow us to implement custom functionality. Here is where the concept of the PageCode component comes in handy. As we said, the PageCode is in charge of creating properties for each of the components in our SPEAK application. All these properties can be reached throughout the ViewModel created by PageCode. Let’s say we would like to show a message when a car of brand “BMW” has been found.

So, the first thing we need to do is to create our PageCode JavaScript file. Go to /sitecore/shell/client/My First App and create a new item. Go to Sitecore -> SPEAK and select SPEAK Page Code

Sitecore Speak list page code

Name the file ListPageCode.js. The created file should look like this: 

Sitecore Speak list page code js

This code will allow us to extend our Sitecore SPEAK application. The initialized method will run once our page gets initialized. At this point, we have a reference to all renderings we have on our page.

Let’s add some code that will basically bind a function to the “change” event of our DataSource. In our handler, we will check if our list has any item whose itemName contains the word “BMW”, if so, we will update the very first Text rendering we added. Here is what our code will look like after those changes: 

Sitecore Speak list datasource

Refresh the page to see the result: 

Sitecore Speak list text box 2

As you can see, our page now includes the mentioned text indicator. This was all done using the PageCode component.

Now, what if we want to create our own component? We can also do that. Just add a new SPEAK component (same approach as the PageCode but this time select SPEAK component). You will be prompted to select the location where you need the rendering to be placed on Sitecore (select PageList). Call the new component “CheckForBMW”. You should see the following items on your solution: 

Sitecore Speak list items

It is important that you also create a new Template item and place it under the CheckBMW component. 

Sitecore Speak list template

Name this item CheckBMW-Parameters and add a field named “items” to it as follows: 

Sitecore Speak list add file

Also, make sure to set the base template of our CheckBMW-Parameters to ControlBase

Sitecore Speak list control base

Finally, set the following code on the CheckBMW.js file. 

Sitecore Speak code 2

Moreover, modify your CheckBMW view to look as follows (note that our view references our JavaScript file):

Sitecore Speak code 3

The last step is to set the “items” property of our rendering to {DataSource: items}, so that we can refer to “items” in our component which will in turn refer to the items property of the DataSource.

Run the page again. You should see two messages indicating a BMW brand car was found. The first is from the PageCode rendering while the second one comes from our CheckBMW component. 

Sitecore Speak list check bmw component

That’s it, we have used SPEAK to create a very basic example application on which we learned about SPEAK components including the PageCode and how to implement our own.

I hope you enjoyed!

Bibliography

CMS View

YouTube

MH Welander

Sitecore Art


Jorge H.

Jorge has a Bachelor's and a Master’s degree in Computer Science which gave him a very strong background in the field. He has been working with the .NET platform for more than five years now and more recently with content management systems. He likes basketball, music, programming, and technology in general.

Articles