Create a rendering variant

Abstract

Learn how to dynamically render fields in renderings.

SXA comes with a set of default renderings and rendering variants. Rendering variants are configurable adaptations of the default renderings. To further encourage reusability, designers and front-end developers can also create new rendering variants. This gives authors more options in the way they present their content.

You can create your own variation of a rendering by adding a variant in the Content Editor.

To create a rendering variant:

In the Content Editor, click the site and open the Presentation/Rendering Variants folder. This folder lists all the renderings that allow variants.
Note
To add a rendering to the folder, contact your Administrator.
Right-click the rendering that you want to add the variant to, and then click Insert, Variant Definition.
Enter a name and click OK.
In the Variant Details section, specify information in the following fields:
- Css Class: specify the class name for the variant in the HTML.
- Item CSS class: specify the CSS class for list items. For example, for variants of PageList, LinkList, FileList, and Navigation renderings.
- Field used as link target: provide the field name of the target item. This class is added to the list and navigation items markup (li HTML element). This link is used to override all links when the Is link, Is prefix link, or Is suffix link check boxes are selected.
- Allowed in templates: specify the pages that the variant is available for. Click the relevant page template, click the right arrow to move it to the list of selected items, and then click Save. If there are no templates selected, the variant is available for all pages.

To define the fields that will be displayed, you can add child items to the rendering variant, right-click the variant, click Insert, and then click the relevant item.

These are the child items available for a rendering variant:

Date: displays data and time in custom format. To be able to display date and time in custom format you have to use Date item. This item is similar to the Field item but has an additional field: "Date format" that allows you to choose a date and time format. Like the Field item, the Date item can be used as fallback item and can have its own fall back items defined.
Note
The fields and variant details are described in a table below.
Field: displays field name and other field values.
Query: allows to specify a query that will be will be run on current context item. This enables you to query child items. For example, if you want the rendering variant to display only for the child items of a certain template.
Placeholder: allows to render an empty placeholder.
Reference: displays field from referenced item. If you want to display a field from a referenced item, you can define this field in the PassThroughField. You can use this variant field for the following fields: LinkField (GeneralLink, DropLink), FileField (File), ImageField (Image), and ReferenceField (Droptree). Reference items can contain have another reference item as its child item. This can be convenient when you want to create a tree of reference items and display fields from items which are referenced in referenced items.
Section: used to create groups. Section contains fields such as Tag (to create wrapping element for the section, for example "div") and CssClass (to add a css class to the wrapping tag). You can nest Section items to create more complex variant structure.
Template: allows user to define NVelocity template which will be used to render part of the HTML. The getVelocityTemplateRenderers pipeline can be 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.
Text: displays text. Used to render custom string of for example a description. You can use the following fields: Text, Tag (define additional tag that will wrap text), CssClass (the css class that will be added to the tag), IsLink (if selected then custom text will be additionally wrapped by hyper link to the current item).
Token: SXA supports tokens $id (renders id of the item), $size (formats size of attached asset), $name (renders name if the item), and $FileTypeIcon (renders span with css classed equal to the file extension). The custom pipeline resolveVariantTokens can be used to extend the set of variant tokens.

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

Field	Variant details
Tag	HTML tag in which the field content will be rendered. For example: `div` If left empty field content will remain unwrapped.
Field name	Name of the field current item.
Prefix	Adds string value as a prefix.
Suffix	Adds string value as a suffix.
Is link	Select to have hyperlinks that wrap the field content.
Is prefix link	Select to wrap prefix in the same link which you use for the field content.
Is suffix link	Select to wrap the suffix with a hyperlink.
Is download link	Select to have a hyperlink with a download attribute.
Css Class	Adds Css class to the tag.
Is editable	Select to edit rendered field.
Date format	Determines the date format.
Render if empty	Select to render empty element when the field is empty.
Pass through field	Defines the name of the field from the nested item.
Text	The text to render.
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 (`$item.Name` displays current item name). `$dateTool.Format(date, format):` formats date and time values. `$numberTool.Format(number, format)`: formats numbers. `$geospatial`: in case of geospatial search (`$geospatial.Distance`) will show distance to certain point of interest).
Token	Use special tokens to format certain field values. Supported tokens are: `$Size`: displays size of a file depending on size unit. `$FileTypeIcon`: displays icon depending on file extension.

Create a rendering variant

Note

Note

Note