In my introduction to Sitecore’s SPEAK framework, I mentioned that SPEAK applications should always be built from a branch template provided by Sitecore. While it is possible to write a SPEAK page from scratch, there are many moving pieces to consider.
Because all SPEAK applications require certain components to function (JS libraries, CSS, a Sitecore layout, etc.), this article will help Sitecore developers understand what components are required in a SPEAK application.
Always remember that a SPEAK application is built with renderings assigned to placeholders that are defined on a layout – just like any other Sitecore page.
Renderings: The Backbone of a SPEAK Application
Here’s the default presentation details provided by the ListPage branch template (/sitecore/client/Business Component Library/version 1/Templates/Branches/Applications):
While it may look like a lot is going on here for a page without any content yet, it’s pretty easy to break this down into smaller chunks.
At the top is a reference to a layout file – Sitecore’s concept of a “master page” – that typically provides top-level markup (<html>, <body>, etc.).
The next section lists renderings and the placeholder that each is assigned. There are renderings for each piece of the page, including top-level content (GlobalHeader, GlobalFooter), for page title content (Text with ID “HeaderTitle”), menu content (Menu), and body content (List, which is specific to this ListPage type). Each of these renderings are assigned to placeholders that position them in very specific parts of the page. The names of the placeholders strongly imply where they are set up in the layout or other renderings.
Building custom SPEAK pages involves adding pre-existing components/renderings to this list, assigning them to the correct placeholder, and wiring up specific parameters to other components. There is no Experience Editor interface for designing pages, so it is important to have a strong understanding of where each placeholder lives.
PageCode: A Major Artery
Perhaps the most important component of a SPEAK page is the PageCode rendering. This is responsible for outputting all the CSS and JavaScript references that every SPEAK application needs on the client. An auto-executing JS function includes a require.js entry point that references jQuery, Knockout, Bootstrap, Backbone, and several other libraries.
The PageCode rendering also has a parameter for referencing your own client-side code:
Your custom PageCode logic is where page-specific code will live, and all the aforementioned JavaScript tools are available to you as well. We will dive into an example of custom page code in a later article.
Where Files Live on Disk
While you may never touch the default SPEAK rendering views or client assets, a quick look at the default layout and views could be helpful in understanding how SPEAK works. It is useful to see how the default views are written to get an idea of how your own custom components may integrate, or what other code they might interact with.
From the Sitecore website root, SPEAK-related files are stored here: \sitecore\shell\client\Speak
This folder breaks down into two folders: Assets for client-side content, and Layouts for mostly server-side code (such as CSHTML views). I would highly recommend looking at the following files to understand the basic pieces of SPEAK that I’ve talked about so far:
- \sitecore\shell\client\Speak\Layouts\Layouts\Speak-Layout.cshtml – core layout file
- \sitecore\shell\client\Speak\Layouts\Renderings\Common\PageCodes\PageCode.cshtml – PageCode file, which renders all CSS/JS to page
- \sitecore\shell\client\Speak\Assets\lib\core\1.1\main.js – require.js configuration file; lists all referenced client-side libraries
Summary
With that, you should have a decent idea of the core responsibilities of components in a SPEAK application: renderings that provide component logic, PageCode for bootstrapping the application, and a quick overview of the core SPEAK components. If you have any questions about the structure of a SPEAK application, leave them in the comments and I’ll follow-up.
