Starting with SXA – Part 1: Custom rendering and rendering variants

Let’s say that we have articles which look as the examples bellow. Normally, in Sitecore we would create different renderings, templates etc for each of these cases. With SXA, we can create all of this by using one template and manipulate different outcomes with Rendering Variants.

So, let’s start!

To create a Custom Rendering, there are several things to be done.

Sitecore:

• Template
• Rendering
• Link to the Available rendering in order for our feature to appear in the Toolbox
• Rendering Variants

Code wise:

• Controller
• Model
• Repository
• IRepository
• View

Template:

All these articles have some fields which are in common, some appear in one case but not in the other. Our template will have all of them.

The template was created on the following path: /sitecore/templates/Feature/Experience Accelerator/Page Content/Article

This was done for the purpose of this blog, but I would strongly recommend to keep your custom SXA features (templates, renderings, etc) in the separate folder /sitecore/templates/Feature/YOUR_WEB_SITE for the future Sitecore upgrades (keep it clean!).

Rendering

When creating a rendering, don’t forget to select Rendering Controller.
/sitecore/layout/Renderings/Feature/Experience Accelerator/Page Content/Article

You need to specify Controller and Controller Action as shown in the picture above.

In order to have rendering available in the Toolbox you must have checked Editable

Data Source Template and Datasource Location are specified in order for Sitecore to automatically create a proper content, it's type and the location in Sitecore tree for the user.

Available rendering

In order to enable your Rendering to be visible in the Toolbox, you need to add your rendering to the appropriate section. For this example, the rendering was added here /sitecore/content/HHog Site/hhog/Presentation/Available Renderings/Page Content

You need to click on Edit and to place your custom rendering in the list.

Rendering Variants

New Redering Variants are created under /sitecore/content/HHog Site/hhog/Presentation/Rendering Variants. It has 3 types:

• Full Article Text Only
• Article Preview
• Article Description Preview

Full Article Text Only has 4 fields: Headline, Subheadline, Synopsis and Description. For each of the fields you can specify HTML tag (div, p, h1,..) and a class name.

Desired output

Article Preview has 4 fields with a wrapper for the text (Image, Headline, Synopsis, Link). You can treat wrappers as a div section to manipulate the position of the content.

Desired output

For the Link type of fields you have to check Is Link box.


Article Description Preview has 4 fields with Text Wrapper around two of them: Headline, Image, Description, Link.

Desired output

Note: It doesn't matter how you call the field items BUT Field Name has to be the same as the field name in the template.

These Rendering Variants will appear in the dropdown list when you select Article item in Experience Editor.

Ok this is all nice but I get an error when I try to add rendering to the placeholder. What about the code? After looking into the features which were built within SXA, here’s what you need to do.

IRepository

public interface IArticleRepository :IVariantsRepository
{
}

Repository

 public class ArticleRepository : VariantsRepository, IArticleRepository
 {
    public override IRenderingModelBase GetModel()
    {         
        ArticleModel model = new ArticleModel ();
        FillBaseProperties(model);
        return model;
    }
}

Model

public class ArticleModel : VariantListsRenderingModel
{
    //Here you can place your template fields or leave it empty to render it through @Html.Sitecore() helpers
}

Controller

public class ArticleController: StandardController
{
    protected IArticleRepository ArticleRespository
    {   get; set;   }

    protected IVariantsRepository VariantsRespository
    {   get;  set;  }

    public ArticleController()
    {
        ArticleRespository = ServiceLocator.Current.Resolve<IArticleRepository>();
        VariantsRespository = ServiceLocator.Current.Resolve<IVariantsRepository>();
    }
    protected object GetVariantsModel()
    {
        return VariantsRespository.GetModel();
    }

View

@model Your_Website.Models.ArticleModel
@if (Model.DataSourceItem != null || Html.Sxa().IsEdit)
{
<div class="component article @Model.CssClasses.Aggregate()")>
    <div class="component-content">
        @if (Model.DataSourceItem == null)
        {
            @Model.MessageIsEmpty
        }
        else
        {
            foreach (VariantFieldBase variantField in Model.VariantFields)
            {
                @Html.RenderingVariants().RenderVariant(variantField, Model.Item, Model.RenderingWebEditingParams)
            }
        }
    </div>
</div>
}

And there it is, the simple use of Rendering Variants.

Keep in mind that many of the Controls, View and Models can be reused from the existing SXA renderings. The reason why all of them are mentioned here is to give you the bigger picture of what is needed if you need to create something more complex.

In Part 2, creating a standard model will be covered as an example for composite renderings.