How to add a custom rendering in all your future Sitecore SXA sites

Sitecore SXA and custom renderings

There are already blogs about how to create custom renderings in Sitecore SXA. The official Sitecore documentation site has an article on how to create your rendering and add it to the toolbox. You can read on my own blog how to do this with variants.

In short, the steps are:

• Create a rendering (controller, action method, repository ...)
• Create a controller rendering in Sitecore
• Add a new rendering to the toolbox

Once you completed these steps you will have a new component in the toollbox for your site. But a Sitecore instance with SXA will probably host multiple sites, so what if you created a rendering that you want to use on all your future SXA sites? I found some information on that and would like to share it, using an existing component as example to show you how to create your own. This will also show that it is possible to add your rendering to the existing component groups in SXA, but that might be not such a good idea considering that upgrades of SXA might remove your additions. And of course, you don't want to mix features.

Adding your rendering to the available components of new SXA sites

First step is to open the Sitecore content editor. I will use the "Page Content" renderings group to show what you can do as this is one with some nice examples.

Branch Template

First thing to do is to create a branch template that will create the item(s) needed to make our component(s) available when a new site is generated. Go to /sitecore/templates/Branches/Feature/Experience Accelerator and you will find already quite some folders with branch templates for the existing components. As we are using Page Content as example, lets check that folder:

The folder contains a few branches, but we'll focus on the Available Page Content Renderings now. This is the branch template that will be used to create the item with the renderings that are included in the "Page Content" rendering group - you'll find all of them in the $name item in the branch. 

To create your own you need to define a new branch template just like it with a proper name. If you just want to add your rendering to an existing group, you can simply add it to the proper branch template and your done - you don't need any further steps in that case but be aware that updates might delete your addition (of course, this is easily checked and re-added if needed).

Site Setup

If you created your own branch to have your own rendering group, go to /sitecore/system/Settings/Feature/Experience Accelerator. You will recognize the folders there for all the default rendering groups and you should create your own here.

First item in the folder is a "Site Setup" item, where we can define the name of the group and whether it is checked by default (or installed by default).

The Site Setup has several children - steps that will be taken during setup. The first ones you can see in the Page Content example are all of type "AddItem" (/sitecore/templates/Foundation/Experience Accelerator/Scaffolding/Actions/Site/AddItem)

AddItem

Let's take the first one as example as this is the most interesting one:

Add Available Renderings

In the AddItem item, you choose a location and a template (and a name). To add the available renderings -what is our main purpose here-, we take the Available Renderings parent as location and use our branch template as Template - the one you created in the first step.

This will tell the SXA site creation script to create a new item based on the branch template at the set location. 

Data items

You can use the same AddItem to create other items as well, like a data folder (including data items if you want). The Page Content has examples on that using other branch templates. 

Rendering variants

If your rendering can make use of variants, you should also create the items for that. The Page Content has examples on empty variant folders (like Field Editor) or variant folders with a default variant (like Page List) where again a branch template is used to create all the necessary items.

Other instances

But what about other instances? Yes, indeed - we have been talking about SXA sites within the same instance here. That covers quite some scenarios, but if you want to have this in other instances with SXA as well you can easily package your stuff and tranfer it - after all, we did nothing more than manipulating items in Sitecore...

Conclusion

Adding your own components is quite powerful but still fairly easy if you know which steps to take. Just adding the renderings can be done with the steps provided here, but I'm sure they are more possibilities to discover by looking at the existing features (e.g. adding to the theme, which you can check in the search feature). And that is the best advice I can give you: take a look at the existing features and you'll discover the fancy world of SXA ;)

Sitecore SXA: PageList component with an Item Query

Sitecore Experience Accelerator (SXA) PageList component & Item Queries

Our requirement was simple: 

Display a set of fields from a list of items, based on a single template under a root item.

We checked the available components in SXA to see if we could do this in a decent way (and without any custom code) and found the PageList component:

Displays lists of pages by predefined or composed queries.

Item Queries as from SXA 1.3

We are using SXA 1.3 and in that version we can define Item Queries in the Settings of the site:

As you can see here we created an Item Query called "Speakers".
We used the "Build query" option on the Query field to create a query to select the desired template at a location. We could extend this with more clauses if needed.

The query build tool looks very familiar to editors who are used to work with the search tools in Sitecore and creates a search index query. You can see the resulting query in the Crawling log file.

Page List

The Page List component has a few options to determine the resulting items. 

Datasource

The "datasource" field also has a "Build query" option. Our first attempt was actually to use this to build our entire query but that failed as we did get multiple results and Sitecore does not like that in the Datasource field. So you have the options to simply select a single item as source or use a query to determine the datasource (but make sure that query does not return more than 1 item or the control will fail). You can combine the item datasource with a query (like the predefined "Children"). 

But in our case we didn't need a datasource as we had set everything on the query - not exactly sure how everything is handled behind the scenes, but as far as I could see they used a combination of the datasource and the query so a single index query seems a better option here.

Source Type

This is the option we did use - by creating our "item query" we added a new option to this dropdown (next to the standard ones):

We select our item query "Speakers" as source type. Save, publish, ..  and there is our list with the exact items we wanted.

Fields - Variants

In order to display the fields we want in the list, we can use Variants. How to create a variant is explained on the Sitecore doc site. In short:

1. Go to /sitecore/content/[tenant folder/tenant/site/...]/Presentation/Rendering Variants/Page List
2. Create a new Variant Definition
3. Add all the VariantFields you want (mark them as link if you want them to link to the underlying item - for a page list you probably want at least one of them to do so)
4. Select your newly created variant in the Styling properties of the control on your page

Credits

Thanks to Dawid (daru) & Adam (adamnaj) for the support on Sitecore Slack - the SXA channel there is a real good place to get help!  Next to Sitecore Stack Exchange of course, already having 58 questions on the SXA tag as we speak (and apparently even one where item queries are covered - d'oh).