Getting Started with Sitecore SPEAK 2.0

With the release of Sitecore 8.1, we now have the ability to work with SPEAK 2.0 which is promised to be less of a steep learning curve, and will give your fingers a bit of a rest when adding custom logic to your page code.

Because it is so new, most of the SPEAK related documentation that you find on the internet today is SPEAK 1.1 related. Most likely, if it doesn't specify a version, it's SPEAK 1.1. The only 2.0 post that you may find is by SPEAK guru, Mike Robbins, where he compares a Sitecore SPEAK 2.0 Component vs SPEAK 1.1. 

So to get started with 2.0, I recommend that you read through Mike's post along with the SPEAK changes document found on the 8.1 Initial Release page that describes the differences between 1.1 and 2.0. 

No SPEAK 2.0 Branches Yet

If you take the plunge and start building new apps using SPEAK 2.0, you will notice that there currently aren't any branches available in 2.0 yet.

What this means is that you have to build out your 2.0 pages manually. Never fear, it's actually not that painful.

SPEAK 2.0 Enabled Dashboard Page

In my POC, I started by building out a simple Dashboard Page. You can use my approach to build out any of the other SPEAK pages based on 2.0.

After talking through some things with one of our star developers, Sergey Perepechin, I got started and created a 1.1 version of the Dashboard that I would use as a guide by looking at the Presentation Details to make sure that I added the correct SPEAK renderings to the correct placeholders.

After this, I created a new item based on the Speak-DashboardPage template.

With this in place, I created a PageSettings item in its usual home; under the SPEAK page:

I then added the various SPEAK 2.0 enabled renderings to the page. The first and most important one I added was the PageCode rendering. For PageCode, I made sure that SpeakCoreVersion was set to Speak Core 2-0.

I worked through adding the rest of the renderings that the Dashboard Page requires, by using my 1.1 Dashboard's Presentation Details as a guide.

It is important to note that some of the rendering's names have change slightly in 2.0, so you will need to review the SPEAK changes document to make sure that you pick the correct ones. DashboardPageStructure is an example of one of these.

Slowly but surely, I matched my renderings and placeholders to the 1.1 version of my Dashboard, using the 2.0 enabled renderings:

The end result; a shiny new SPEAK 2.0 enabled Dashboard Page:

SPEAK 2.0 Page Code

The next thing I wanted to explore was implementing my own 2.0 enabled JavaScript page code. The changes to page code are highlighted in the "Page code changes" section within the  SPEAK changes document.

The new structure is like this:

 function(Speak) {  
   
  Speak.pageCode({  
   
  initialize: function() {},  
   
  initialized: function() {},  
   
  beforeRender: function() {},  
   
  render:function() {},  
   
  afterRender:function() {}  
   
 });  
   
 })(Sitecore.Speak);  

Easy enough, and as they mentioned, we now have a lot more hooks.

Adding a reference to a JavaScript library using SPEAK 2.0 

I am a fan of Sitecore.Services.Client, and have successfully implemented it's EntityService thanks to some great posts and videos by Mike Robbins. Seeing a pattern here? :)

If you haven't checked it out, make sure you at least give this post a read: http://mikerobbins.co.uk/2015/01/06/entityservice-sitecore-service-client/

Ok, so back to what I was trying to test. I wanted to take a function that I had used in a SPEAK 1.1 app's page code, where I implemented EntityService and made a fetchEntities call. 

This is a a sample snippet of the SPEAK 1.1 page code:

1:  require.config({  
2:    paths: {  
3:      entityService: "/sitecore/shell/client/Services/Assets/lib/entityservice"  
4:    }  
5:  });  
6:    
7:  define(["sitecore", "jquery", "underscore", "entityService"], function (Sitecore, $, _, entityService) {  
8:    var AuthorAdmin = Sitecore.Definitions.App.extend({  
9:    
10:      initialized: function () {  
11:    
12:        this.GetRecentlyDrafted();  
13:      },  
14:    
15:      initialize: function () { },  
16:    
17:      GetRecentlyDrafted: function () {  
18:    
19:        var datasource = this.RecentlyDraftedDataSource;  
20:    
21:        var workflowService = new entityService({  
22:          url: "/sitecore/api/ssc/Arke-Sitecore-AuthorAdmin-Controllers/WorkFlowItems"  
23:        });  
24:    
25:        var result = workflowService.fetchEntities().execute().then(function (workFlowItems) {  
26:          for (var i = 0; i < workFlowItems.length; i++) {  
27:            datasource.add(workFlowItems[i]);  
28:          }  
29:        });  
30:    
31:      }  
32:    });  
33:    
34:    return AuthorAdmin;  
35:  });  

After SPEAKING (pardon the pun) to Mike, and spending time going through the SPEAK 2.0 components in my 8.1 instance located at

C:\inetpub\wwwroot\{YourInstanceName}\Website\sitecore\shell\client\Business Component Library\version 2\Layouts\Renderings,

I was able to figure out the correct SPEAK 2.0 version of the page code with a reference to the entity service JavaScript library:

1:  (function (Speak) {  
2:    
3:    require.config({  
4:      paths: {  
5:        entityService: "/sitecore/shell/client/Services/Assets/lib/entityservice"  
6:      }  
7:    });  
8:    
9:    Speak.pageCode(["entityService"], function (entityService) {  
10:      return {  
11:        initialize: function () {  
12:    
13:          this.GetRecentlyDrafted();  
14:    
15:        },  
16:        GetRecentlyDrafted: function () {  
17:    
18:          var datasource = this.RecentlyDraftedDataSource;  
19:    
20:          var workflowService = new entityService({  
21:            url: "/sitecore/api/ssc/Arke-Sitecore-AuthorAdmin-Controllers/WorkFlowItems"  
22:          });  
23:    
24:          var result = workflowService.fetchEntities().execute().then(function (workFlowItems) {  
25:            for (var i = 0; i < workFlowItems.length; i++) {  
26:              datasource.add(workFlowItems[i]);  
27:            }  
28:          });  
29:        }  
30:      }  
31:    });  
32:  })(Sitecore.Speak);  

You will notice that I am accessing a DataSource component on line 18. This is actually a custom JSON SPEAK DataSource component that was developed by Anders Laub.

I really liked his approach and the component's purpose because it separates responsibility.

See his post on it's creation here: http://laubplusco.net/creating-simple-sitecore-speak-json-datasource/

SPEAK 2.0 JSON DataSource Component

My next move was to take Anders' component and convert it to SPEAK 2.0.  As highlighted in Mike's post Sitecore SPEAK 2.0 Component vs SPEAK 1.1, a major difference in 2.0 is that it includes a server side model that represents our rendering parameters for our component. No sweat!

The new SPEAK 2.0 JSON DataSource component was made up of these 3 parts:

Model - JsonDataSourceRenderingModel.cs

1:  using Sitecore.Mvc.Presentation;  
2:    
3:  namespace Arke.Sitecore.AuthorAdmin.Models  
4:  {  
5:    public class JsonDataSourceRenderingModel : SpeakRenderingModel  
6:    {  
7:      public string Json { get; set; }  
8:    }  
9:  }  

You will notice above that my model inherits from SpeakRenderingModel.

Within Sitecore Rocks, you have to specify the class in the Model field:

View - JsonDataSource.cshtml

 @model Arke.Sitecore.AuthorAdmin.Models.JsonDataSourceRenderingModel  
 <script @Model.HtmlAttributes type="text/x-sitecore-jsondatasource">  
 </script>  

Javascript - JsonDataSource.js

1:  (function (Speak) {  
2:    Speak.component([], {  
3:      name: "JsonDataSource",  
4:      initialize: function () {  
5:    
6:        this.Json = null;  
7:    
8:      },  
9:      add: function (data) {  
10:    
11:        var json = this.Json;  
12:    
13:        if (json === null) {  
14:          json = new Array();  
15:        }  
16:    
17:        var newArray = new Array(json.length + 1);  
18:    
19:        for (var i = json.length - 1; i >= 0; i--) {  
20:          newArray[i + 1] = json[i];  
21:        }  
22:    
23:        newArray[0] = data;  
24:        this.Json = newArray;  
25:      }  
26:    });  
27:  })(Sitecore.Speak);  

More to Come!

I hope that this post helps shed some light on getting started with SPEAK 2.0.  I will continue blabbering about SPEAK (love the puns) with my findings in the near future.

Watch this space!