Walkthrough: Creating a simple rendering with a data source

Version: 10.0

This walkthrough demonstrates the most common task of a Sitecore developer with the Rendering Engine SDK: creating a view that renders content from a data source item bound to a strongly-typed model object.

This process is done using the model-bound view view type.

Note

This walkthrough assumes you are using the Getting Started template with a project called MyProject.

In this example, the rendering host displays a few field types, including text, rich text, a link, a date, and an image.

This walkthrough describes how to:

Create the JSON rendering in Sitecore

To create the JSON rendering in Sitecore:

In the Content Editor, create a new template called DataSourceExample under /sitecore/templates/Project/MyProject.
Create a new template section (the name is unimportant) and add the following fields:
- Title: Single-line Text
- BodyText: Rich Text
- FeaturedImage: Image
- PromoLink: General Link
- ExampleDate: Date
On the Builder Options tab, click Standard Values and in the Title, BodyText, PromoLink, and ExampleDate fields enter default values.
Create a JSON rendering called DataSourceExample in /sitecore/layout/Renderings/Project/MyProject. Enter the following values:
- Datasource Location: ./
- Datasource Template: Select sitecore/Templates/Project/My Project/DataSourceExample
Add the DataSourceExample rendering to the Allowed Controls in the /sitecore/layout/Placeholder Settings/Project/MyProject/MyProject-main placeholder and click Save.
Open /sitecore/content/MyProject/Home in the Experience Editor and add your new rendering, including creating a data source item for it.

Note

Your rendering host page outputs Unknown component or a similar message, because you have not yet mapped a component to this JSON rendering in your rendering host.
Publish all your item changes:
- In Content Editor, on the Publish ribbon, click the small black arrow next to the Publish icon and click Publish site.
- In the Publish Site window, to publish your items from the Master database to the Web database, select the Smart publish radio button and click Publish.

You can now test the output of your new rendering:

In your rendering host, open the site home page.
Type the following command into a PowerShell terminal to get the rendering host logs: docker-compose logs -f <rendering-service-name>. Replace the <rendering-app-service-name> placeholder with the name of the rendering service.

Tip

If you use Docker Compose V2 or later, you can use the command docker compose logs -f <rendering-app-service-name>.

Alternatively, you can use the command docker logs -f <container-name>.

For more information about Docker commands, refer to the official Docker CLI documentation.

In the rendering host logs, view the debug output with the Layout Service response, including the component you just added:

RequestResponse

{
    "uid": "8654d7f9-6df3-4d32-835a-92d4d65e6efc",
    "componentName": "DataSourceExample",
    "dataSource": "{3BC54537-E31D-4C9B-A230-088F92F3A0EF}",
    "params": {},
    "fields": {
        "BodyText": {
            "value": "Default"
        },
        "FeaturedImage": {
            "value": {}
        },
        "Title": {
            "value": "Default"
        },
        "PromoLink": {
            "value": {
                "href": "/en/",
                "text": "",
                "anchor": "",
                "linktype": "internal",
                "class": "",
                "title": "",
                "querystring": "",
                "id": "{453C1C1A-7E24-4F2F-8069-84165C6130A3}"
            }
        },
        "ExampleDate": {
            "value": "2020-08-07T04:00:00Z"
        }
    }
}

Create a model for the view

To create a model for the view:

In the Models folder of your rendering host, create a new class called DataSourceExampleModel:

RequestResponse

using Sitecore.LayoutService.Client.Response.Model.Fields;

namespace MyProject.Models
{
    public class DataSourceExampleModel
    {
        public TextField Title { get; set; }
        public RichTextField BodyText { get; set; }
        public ImageField FeaturedImage { get; set; }
        public HyperLinkField PromoLink { get; set; }
        public DateField ExampleDate { get; set; }
    }
}

Note

This class contains five properties that are automatically data bound due to their types inheriting from IField.

Create the view

To create the view:

Create a new DataSourceExample.cshtml Razor view in your rendering host project under Views\Shared\Components\SitecoreComponent.

Note

This is the default search path for Model-bound views using the built-in Sitecore View Component. To simplify the registration of the view with the Rendering Engine, we recommend you name the view the same as the name of the Layout Service component (JSON rendering).
RequestResponse
```
@model MyProject.Models.DataSourceExampleModel

<h2>Simple Rendering Example</h2>
<h3 asp-for="Title"></h3>
<sc-text asp-for="BodyText"></sc-text>
<div>
    <sc-img asp-for="FeaturedImage"/>
</div>
<p>
    <a asp-for="PromoLink">My Link</a>
</p>
<p asp-for="ExampleDate" date-format="D"></p>
```

Register the model-bound view

To register the model-bound view:

In your rendering host project's Startup.cs class, find your AddSitecoreRenderingEngine call in ConfigureServices method, and register your model-bound view:

RequestResponse

services.AddSitecoreRenderingEngine(options =>
    {
        //Register your components here
        options
            .AddModelBoundView<ContentBlockModel>("ContentBlock")
            // Add our DataSourceExample model-bound view:
            .AddModelBoundView<DataSourceExampleModel>("DataSourceExample")
            .AddDefaultPartialView("_ComponentNotFound");
    })

Note

The extension method used here to register the model-bound view assumes the provided Layout Service component name matches the name of the Razor view file.

If you are using the Getting Started template, the dotnet watch process automatically compiles your changes, and you can refresh the Home page of your rendering host site to see your component output. The component header is now displayed, as well as your default content values.

Important

You must check your rendering host logs for any compilation errors.

Fill in values in the Experience Editor

To fill in the values:

In the Experience Editor, open /sitecore/content/MyProject/Home .
Fill in values for all fields.
Click Save and Publish.
Refresh the Home page and see the headers you populated.

Note

Be aware of the following when you use the solution:

A publish of the Platform project updates the running cm service.
The running rendering service uses dotnet watch and re-compiles automatically for any changes you make. You can also run the rendering project directly from Visual Studio.

Do you have some feedback for us?

If you have suggestions for improving this article,