Introducing SXA data modeling

Current version: 1.9

SXA enables you to model your data in JSON (JavaScript Object Notation). For example, if you want to build a mobile app and feed it with SXA content, you can edit the JSON content on the page and have output content in JSON instead of HTML.

The JSON feature provides a JSON API to access the SXA content. The content for the site is accessible via a web-service API in JSON format.

Enable SXA data modeling

By default, JSON functionality is added to your tenants and sites. Both the Create a tenant and Create a new Experience Accelerator site wizards have the JSON feature selected.

Before you can start working with the JSON renderings, you must switch to the JSON device.

JSON layout

The SXA JSON device uses a separate layout that is stored in the JSON Layout folder (sitecore/Layout/Feature/Experience Accelerator/JSON Layout). When you switch to JSON device in the Experience Editor, you can see that it is using the JSON layout.

JSON renderings

There are special renderings that you can use to build JSON layout. These renderings are stored in sitecore/Tenant/Site/Presentation/Available Renderings/JSON. Out of the box, there are three JSON renderings available:

  • JSON Content – displays fields of a page using JSON renderings and JSON variants.

  • JSON List – displays lists of pages by predefined or composed queries.

  • JSON Results – displays the results of a search query.

JSON variants

To support additional fields for JSON renderings, you can create JSON variants. JSON variants are stored in the grouping items of the JSON renderings (for example, sitecore/Tenant/Site/Presentation/ Rendering Variants/JSON content).

To define the fields to display, you can add child items to the rendering variant. To do this, you right-click the variant, click Insert, and then click the relevant item.

You can add the following child items to a JSON variant:

  • JSON Checkbox– special JSON variant field that renders the values of the fields of type Checkbox in different modes.

  • JSON Date – renders date and time in a custom format.

  • JSON Field – renders field in HTML.

  • JSON File – JSON rendition of a File field that outputs link to a file.

  • JSON Image – specialized JSON variant field that renders the value of fields of type Image in different modes.

  • JSON Multilist Reference – special JSON field value that provides an enumeration over references defined in a Multilist derived fields. Uses child items to determine what to render. For example, lists all pages with their titles.

  • JSON Placeholder – provides a placeholder, for example, to load a JSON list within a JSON content rendering.

  • JSON Reference – allows to render content from a linked item. Define the field you want to use as the reference in the PassThroughField field. You can use this variant field for the following fields: LinkField (GeneralLink, DropLink), FileField (File), ImageField (Image), and ReferenceField (Droptree). The reference item needs to contain other JSON rendering items as its child items. This can be convenient when you have item linked from the rendered item and want to display fields from that item. By adding a name in the Variant details section, you can create an additional JSON object.

  • JSON Section – used for grouping of fields. This renderer contains fields such as Name (to create a wrapping element for the children renderers underneath). You can nest Section items to create a more complex variant structure.

  • JSON Template – lets you define the NVelocity template used to render part of the JSON. The getVelocityTemplateRenderers pipeline is used to add a custom renderer that later on can be used in the NVelocity template.

    Note

    NVelocity is a .Net-based template engine. It permits developers to use the simple yet powerful template language to reference objects defined in .Net code.

  • JSON Text – displays text and is used to render a custom string, of for example, a description. You can use the following fields: Name (define property name for the text), Text (containing the text to be rendered).

  • JSON Token – SXA supports the following tokens: $id (renders the id of the item); $size (formats the size of the attached asset); $name (renders the name of the item); and $FileTypeIcon (renders a span with the CSS class equal to the file extension). The custom resolveVariantTokens pipeline is used to extend the set of variant tokens.

  • JSON Rich Text – displays Rich Text field in your JSON component. Field can be rendered using one of the provided modes (for example, can be cleaned up before output to strip HTML tags from it).

Depending on the item you add, you can set different fields:

Field

Description

Mode

Depending on the rendering variant child item, the mode field can be set to different views:

  • Raw – renders a raw Sitecore value, unformatted data.

  • Text – renders text.

  • Rendered – renders the value using the field renderer.

  • Plain – renders the item as plain text.

  • Path – renders the path of the item.

  • Guid – renders the globally unique identifiers of the item in Sitecore.

Value for True

Determines the value that is rendered for true.

Value for False

Determines the value that is rendered for false.

Name

Overrides the JSON property name. By adding a name for the JSON Reference field, you can create an additional object.

Field name

Name of the field current item.

PassThroughField

Defines the name of the field that stores the link to a different item. For example, a simple reference, such as a link, or a multi-reference field, such as a Tree list.

Date format

Select the date format from the drop-down list.

Template

Define the NVelocity template that renders part of the component variant HTML. You can use the following objects:

  • $item – access to the current item (the $item.Name object displays the current item name).

  • $dateTool.Format(date, format) – formats date and time values.

  • $numberTool.Format(number, format) – formats numbers.

  • $geospatial.Distance – displays distance to points of interest in geospatial searches.

Text

The text to render.

Token

Use special tokens to format certain field values. The following tokens are supported:

  • $Size – displays the size of a file depending on the size unit.

  • $FileTypeIcon – displays an icon depending on the file extension.

Do you have some feedback for us?

If you have suggestions for improving this article,