Sitecore SPEAK List Component, Custom Tile and Knockout Databinding
In this post I will walk through using the Sitecore SPEAK List Component using Knockout databinding and a custom tile to create a custom look and feel of the List component.
I'm assuming you have already got a SPEAK application or understand the basics of creating a SPEAK application. (There are some great posts on Sitecore SPEAK from Martina if your new to SPEAK).
Core DB SPEAK Component
In the presentation details of the component add a new List Component and create a datasource component (In my example here im using Query Data Source which i'm populating later using Entity Service).
List Component Rendering Properties
Within the rendering properties of the list component, this is where you can specify how the list component will render its data. There are three view models available in Sitecore 8 for the list component:
- TileList - Displays results as a set of square tiles floated in a grid formation. You can also specify a custom title.
- IconList - Displays icons for each of the sitecore items it renders out.
- DetailList - This view renders the results out as a grid of results.
To have full control over the appearance of how the results are rendered out by the list component we can use the TileList option.
In the TileHtmlFileName field you can specify the location of a custom cshtml file. This cshtml file can dictate the HTML, styling and knockout databinding for a single item in the list component. This location is relative to the sitecore folder within your solution.
Its a good idea to separate out our custom tiles from the standard sitecore folder of tile ("sitecore\shell\client\Business Component Library\Layouts\Renderings\ListsAndGrids\ListControls\DefaultTile.cshtml") and create your own folder. You can also use this example tile as a template for creating your own tile.
The TileHtmlFileName field allows you to specify a location of a custom CSS file for your custom tile. This follows the same pattern as the Html file above.
Set the items property under Data Bindings to the items property of your datasource. This will provide your list component with its data.
List Component Rendering Properties
In your Visual Studio I replicate the folder structure of my custom tile that I specified in the TileHtmlFileName field, and add in a new cshtml for my tile.
Custom Tile cshtml
Custom Tile and Knockout Databinding
In the custom tile cshtml file, this is where we can specify the html markup for an individual item bound to the list component via the datasource.
Below is an example of the standard Sitecore tile that comes with a fresh install of Sitecore.
When creating a custom tile, I usually copy this HTML to use as a template. This has the required HTML and CSS classes to look pretty good as a starting point.
Knockout databinding works on standard html, by allowing you to databind attributes and inner elements to properties of the model that's provided by the datasource. In this example we are binding the following model to our list component from the datasource.
We have the following properties:
- itemId - The ID of the Sitecore item. Also needed for SPEAK components to support selected item events.
- Path - Path to a image.
- Name - Filename of the image
Knockout Attribute Databinding
To use knockout for databinding, the syntax is to add a data-bind attribute to the HTML element. Within the data-bind attribute, we can tell knockout which HTML attribute we want to bind to which property in our model. Within the data-bind attribute, add attr to tell knockout we want to bind an attribute of the HTML element, we can tell knockout which attribute of the HTML tag we wish to databind followed by which property in the model we want to databind too.
So take this case for example: One of the properties we have in our model is the path of the image. To display this in the tile we create a standard HTML tag, however we want the src property to be set by knockout from the path property in our model (Note the property name is case sensitive).
As you can see below we set the databind the src attribute of the img tag to the Path property in our model (The model coming from the datasource bound to the list component).
Knockout Inner Text Databinding
Databinding to the inner text of a HTML element works very similar to databinding an attribute. We use the knockout data-bind attribute again, instead of using attr we use the text syntax followed by the property in the model we wish to databind.
So in this example we want to use a span tag, and databind its inner text property to the Name property in the model.
Below is the full markup for the custom tile.
Example Project Source
An example SPEAK application is available on GitHub demonstrating Knockout databinding and the SPEAK list component.