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:
- Little and not up to date documentation.
- Relies on its own set of controls rather than using controls already know within the web community
- Not based on the technologies used to create Sitecore web pages
- 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”:
This will create our “ListPage” item right below our 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:
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.
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.
You will see that such rendering is now listing on the Design Layout of out ListPage:
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.
After refreshing our page, we should see our “Hello World!” text on our page now.
Once created, assign such item to the datasource of our text component by using the Design Layout dialog of the ListPage item:
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.
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:
*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:
If we were to refresh our list page at this point, we will see a table with no data on it (only 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:
The Id under the RootItemId field refers to the parent item the Datasource rendering will use to search. Such structure is shown below:
At this point our page will PageList will show some data on it:
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.
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.
Name the file ListPageCode.js. The created file should look like this:
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:
Refresh the page to see the result:
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:
It is important that you also create a new Template item and place it under the CheckBMW component.
Name this item CheckBMW-Parameters and add a field named “items” to it as follows:
Also, make sure to set the base template of our CheckBMW-Parameters to ControlBase
Finally, set the following code on the CheckBMW.js file.
Moreover, modify your CheckBMW view to look as follows (note that our view references our JavaScript file):
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.
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
