In this previous article, we explored the new Sitecore ASP.NET Core SDK and it companion, the ASP.NET Core Starter Kit. That article will help you get started, but now we’re ready to actually begin building components. The starter kit gives us a few examples of simple Model-Bound Views, which will be the highlight of this article. However, there are other ways of creating components as well.

Model-Bound Views: Ideal for simple views which derive their content from XM Cloud without any logic. This the default view type and the primary example shown in the starter kit.

View Components: (Article coming soon). This type of component is great for views with more complexity, such as those requiring complex logic, or interactions with 3rd party systems.

Partial Views: These are good for separating your views into smaller, more manageable sub-components.

Before we create a view, it’s important to understand the different aspects of a good component. A good, editor-friendly components contains the following:

  • A rendering definition – an item in Sitecore which defines the properties of your view. The rendering definition hold the values for the other items listed below.
  • A datasource template – The type of data template that is used to populate the values needed by the view
  • A datasource location – A location where the datasource can be saved.
  • View File – a physical file which drives the component markup
  • Rendering Parameters – an optional set of parameters that can manipulate the behavior or look and feel of a specific instance of the component. For example, you can expose parameters to change the background color.

Sitecore Items

Let’s create a rendering definition first. There are a couple ways we can do this. One is to create the definition, the datasource template, the rendering parameters all separately. The other way is that we can use an existing rendering definition and clone it, which will create the necessary pieces for us. We’ll do the latter in this example.

Begin by finding an existing view definition that most closely resembles the new on that you’re trying to build. In the ASP.NET Core Starter Kit, there is a Promo component, which we’ll use as the basis for our new Image Banner component. To clone the existing rendering , navigate to it’s rendering definition, which, in this case, is located at:
/sitecore/layout/Renderings/Feature/JSS Experience Accelerator/Page Content/Promo

Right click on Promo, then click Scripts -> Clone Rendering

This brings up the Create Derivative Rendering dialog. On the General tab, give your new component a name. We’ve named it ImageBanner in this example, and Add to Module field, select an appropriate path for your rendering definition. I recommend saving your rendering definitions in your project module under Renderings/Project/<your project>. This ensures a clean helix-compliant structure and avoids risk of losing your work in case a future upgrade replaces the out of the box Headless folder.

On the Parameters tab, select the Make a copy of the original rendering parameters. This ensure you have a unique and independent rendering parameters template for your component.

Similarly, choose Make a copy of original datasource in your Datasource tab.

When the script is completed, your new rendering definition is created at the location you specified. If we navigate to our new rendering definition, we’ll need to make note of some important fields. The primary field to inspect is the Component Name. This name will later map to our physical file and model binding code.

Scrolling down further also reveals the location for our new datasource and rendering parameters templates

If we need to make changes to our templates or parameters, we can navigate to these templates to do so. In this example, let’s add a FeaturedImage field to our data template. Begin by navigating to our new template (in this example, at /sitecore/templates/Project/dotnetcore/ImageBanner), and add the field name that wish to add:

Don’t forget to set an appropriate icon for your template.

We won’t delve too much into the concepts of template inheritance and best practices when creating template, but I highly recommend learning about proper inheritance methodologies to ensure you have a clean and efficient template structure. Here are some references and official documentation:

Once we have configured our templates to our liking, let’s make this new component available to your site. Navigate to your site’s Presentation -> Available Renderings folder and select the appropriate bucket to show your new component. In our case, we’ll select Media, and click on Edit in the renderings field. Then navigate to the rendering definition we create above and add it to your list of available renderings.

We now have everything we need in Sitecore, but are still missing the actual view file, so let’s go ahead and create that in our solution.

Create the code

We’ll first need to create Model which represents our data and can be passed into our view. Create a new class for your model’s data that matches the fields in our template. Here is an example of our model. Please note that it inherits from BaseModel which is a class found in the starter kit that gives us access to some of the basic Sitecore fields, like ID and such.

using Sitecore.AspNetCore.SDK.LayoutService.Client.Response.Model.Fields;
using Sitecore.AspNetCore.SDK.RenderingEngine.Binding.Attributes;

namespace Sitecore.AspNetCore.Starter.Models;

public class ImageBanner : BaseModel
{
    [SitecoreComponentField]
    public ImageField? FeaturedImage { get; set; }

    [SitecoreComponentField]
    public TextField? Title { get; set; }

}

Now, let’s create our view. Model-bound views exist under the Views/Shared/Components/SitecoreComponent folder, so create our new ImageBanner view in the same folder. 

@model Sitecore.AspNetCore.Starter.Models.ImageBanner

<div class="component promo @Model.Styles @Model.GridParameters" id="@Model.Id">
    <div class="component-content">
        <div class="field-image">
            <sc-img asp-for="@Model.FeaturedImage" />
        </div>
        <div class="banner-text">            
            <div>
                <div class="field-promotext">
                    <sc-text class="banner-title" asp-for="@Model.Title"></sc-text>
                </div>
            </div>            
        </div>
    </div>
</div>

As you can see, we put our HTML markup in the view and bind our data using the SDK’s Tag Helpers. As you can see, we are using a <sc-img> tag for our image and a <sc-text> tag for our text. Utilizing these tags allows the content to be edited in XM Cloud’s pages WYSIWYG editor. Read more about tag helpers here.

You can also use the asp-for attribute on standard HTML tags, for example, for our title, we could also do something like this:

<h1 asp-for=@Model.Title></h1>

For our final step, we need to register our new model and view, so that Sitecore knows how to bind our rendering to the code we just created. In the starter kit, an example of how to do this is shown under the Extensions/ServiceCollectionExtensions.cs class. Here, we’ll simply bind our Model to the Component Name we defined when we created our rendering definition:

renderingEngineOptions.AddModelBoundView<ImageBanner>("ImageBanner");

If we build our solution now to test locally (see getting started article), or if we deploy our solution to XM Cloud, and switch to our components list in Pages, we should see our new component. Simply drag it to the page and populate the fields.

That’s all there is to it. We’ll explore the more complicated View Components in a future article.