` | Root wrapper. Renders the entire experience composition. | | `` | `

` | Renders a section node with grid layout. | | `` | `

` | Renders a row inside a grid. | | `` | `

` | Renders a column inside a row. | | `` | `

``` The `experience` attribute accepts a model expression pointing to your `ExperienceData`. If the model is `null`, the tag helper renders nothing. **How the rendering works:** 1. `` converts the `ExperienceData` into a `Composition` tree and iterates over top-level nodes. 2. For each **section** node, it tries to resolve a Razor partial view (display template) for the section. - If the framework finds none, the renderer falls back to the tag helper template declared inside `` (the `` block). - If no inline template exists, the framework renders the default grid layout. 3. For each **component** node, it renders the component using the standard Optimizely template resolution, honoring the `DisplayTemplateKey` from the composition node. 4. In edit mode, `data-epi-block-id` attributes are automatically added to enable Visual Builder editing. No additional markup is needed. ### Customize the HTML tag All composition node tag helpers render as `

` by default. Use the `tag-name` attribute to change the output element: ```html

``` ## Display templates The rendering engine uses the standard Optimizely template resolution to find views for sections and components. When a node has a `DisplayTemplateKey`, the framework tries to find an MVC partial view tagged with that key. For a detailed explanation of how the `TemplateResolver` selects templates based on content type, tags, and inheritance, see [Select templates](docId\:X6jWKJqMhlD1rFhW_y6u6). ### Section templates 1. The renderer checks if the section's `DisplayTemplateKey` is set. 2. If set, it resolves a partial view registered with that tag (for example, via `[TemplateDescriptor]`). 3. If a matching view is found, it renders that view with the section's `SectionData` as the model. 4. If no matching view is found, it falls back to the inline tag helper template (`` block inside ``). 5. If no inline template is declared, the framework renders a built-in default grid layout.. To create a section display template, add a Razor partial view for your `SectionData` type. ```csharp [ContentType] public class MySection : SectionData { [Display(GroupName = SystemTabNames.Content)] [CultureSpecific] public virtual string Title { get; set; } [Display(Name = "Short description", GroupName = SystemTabNames.Content)] public virtual string Description { get; set; } } ``` Then create the corresponding Razor view: ```csharp @* Views/Shared/MySection.cshtml *@ @model MySection

@Model.Title

@Model.Description

``` The framework resolves the view automatically by convention (matching the content type name). You can also register additional section templates explicitly using `IViewTemplateModelRegistrator` (see [Component templates](docId:2rCTqetHmi7zDZvAJqLwj) below). ### View file naming convention for display tags In addition to the default view (`{ContentTypeName}.cshtml`), you can create tag-specific views by appending the display tag name to the content type name with a dot separator: ```javascript {ContentTypeName}.{DisplayTag}.cshtml ``` When the framework renders a component or section, it checks for a display tag (from the `DisplayTemplateKey` or the view context). If a tag is present, the renderer first looks for a view named `{ContentTypeName}.{DisplayTag}.cshtml`. If no matching view is found, it falls back to the default `{ContentTypeName}.cshtml` view. For example, given a `BlankSection` content type and a display tag `CardSection`, create a view file named `BlankSection.CardSection.cshtml`: ```csharp @* Views/Shared/BlankSection.CardSection.cshtml *@ @model BlankSection

``` This view renders when a `BlankSection` is assigned the display template key `"CardSection"` in the Visual Builder, while the default `BlankSection.cshtml` renders when no display tag is set. You can create multiple tagged views for the same content type without any code registration: ```javascript Views/Shared/ ├── BlankSection.cshtml ← default (no tag) ├── BlankSection.CardSection.cshtml ← tag "CardSection" └── BlankSection.FullWidth.cshtml ← tag "FullWidth" ``` :::hint{type="info"} **Note** This naming convention works alongside `IViewTemplateModelRegistrator`. If you need additional control (such as setting `AvailableWithoutTag` or specifying multiple tags for the same view), use the programmatic registration approach described in the [Component templates](docId:2rCTqetHmi7zDZvAJqLwj) section. ::: ### Component templates Components follow the same template resolution pattern. Each `ComponentNode` has a `Component` property (the actual `IContentData` block) and an optional `DisplayTemplateKey`. 1. If `DisplayTemplateKey` is set, the framework resolves a partial view tagged with that key for the component's content type. 2. The matched view is rendered with the block as the model. 3. If no tagged view is found, the framework uses the standard default view. The default view is resolved by convention from its filename matching the content type name: ```csharp @* Views/Shared/Blocks/TeaserBlock.cshtml (default template) *@ @model TeaserBlock

@Model.Heading

@Model.Text

``` A wide variant is defined in a separate view file: ```csharp @* Views/Shared/Blocks/TeaserBlockWide.cshtml (wide template) *@ @model TeaserBlock

@Model.Heading

@Model.Text

``` Register the wide template with tags using `IViewTemplateModelRegistrator` in a `TemplateCoordinator`: ```csharp [ServiceConfiguration(typeof(IViewTemplateModelRegistrator))] public class TemplateCoordinator : IViewTemplateModelRegistrator { public void Register(TemplateModelCollection viewTemplateModelRegistrator) { viewTemplateModelRegistrator.Add(typeof(TeaserBlock), new TemplateModel { Name = "TeaserBlockWide", Tags = ["wide", "full"], AvailableWithoutTag = false, }); } } ``` When a component in the Visual Builder is assigned the display template key `"wide"`, the `TeaserBlockWide` partial is rendered instead of the default. ## Style display settings with CSS classes Display settings are key-value pairs configured in the Visual Builder (for example, `margin=top`, `padding=large`). The style tag helpers let you map these values to CSS classes declaratively. ### Declare a style section with `` Use `` inside `` (or any composition tag helper) to declare CSS classes and display setting mappings. It produces no HTML output. It only configures styling for the composition nodes. | Attribute | Required | Description | | --------- | -------- | ---------------------------------------------------------------------------------------------------- | | `name` | No | The `DisplayTemplateKey` this style section applies to. If omitted, applies as the default fallback. | | `class` | No | CSS classes to always add to nodes matching this template. | ```csharp

``` **Fallback behavior:** When a composition node has a `DisplayTemplateKey` of `"dark"`, the `` section is used. If a node has no template key, or its key does not match any named ``, the unnamed (default) section is used as a fallback. ### Map display settings with `` Use `` inside `` to map specific display setting values to CSS classes. You can use self-closing syntax for single mappings: ```csharp

``` | Attribute | Required | Description | | --------- | ----------------------- | ------------------------------------------------------------- | | `name` | Yes | The display setting name to match (for example, `"padding"`). | | `value` | Yes (self-closing mode) | The display setting value to match (for example, `"small"`). | | `class` | Yes (self-closing mode) | Space-separated CSS classes to apply when matched. | ### Group mappings with `` For grouping multiple value mappings under a single display setting name, use `` in normal (non-self-closing) mode with `` children: ```csharp

``` Both syntaxes produce identical results. ### Per-template style mappings You can define different CSS mappings for different display templates: ```csharp

``` When a node has `DisplayTemplateKey = "dark"`, the framework applies the CSS classes from the `name="dark"` styles section. For nodes without a matching template key, the unnamed default section is used. If the same `name` appears in multiple `` blocks, the framework merges their mapping rules. ## Render an experience with HTML helpers For full control over the markup, you can bypass tag helpers and render the composition tree manually. This approach uses `ICompositionMapper` to convert `ExperienceData` to `Composition` model to access the composition tree. :::hint{type="info"} **Note** You should use the [tag helper](docId:2rCTqetHmi7zDZvAJqLwj) approach for most scenarios because it handles edit mode attributes, template resolution, and style mapping automatically. Use the manual approach when you need complete control over the HTML structure. ::: ### Manual rendering example The following example demonstrates manual rendering: ```csharp @using EPiServer.Cms.VisualBuilder.Rendering @using EPiServer.VisualBuilder.Compositions @model ExperienceViewModel @{ var marginMap = new Dictionary { { "top", "mt-3" }, { "bottom", "mb-3" }, { "both", "mt-3 mb-3" } }; } @if (Model.Composition != null) {

@foreach (var section in Model.Composition.Nodes) {

@if (section is SectionNode sectionNode) { foreach (var row in sectionNode.Nodes) {

@if (row is StructureNode rowNode) { foreach (var column in rowNode.Nodes) {

@if (column is StructureNode columnNode) { foreach (var component in columnNode.Nodes) {

@if (component is ComponentNode componentNode) { await Html.RenderContentDataAsync( componentNode.Component, false, [componentNode.DisplayTemplateKey], new { Node = componentNode }); }

} }

} } else if (section is ComponentNode componentNode) { await Html.RenderContentDataAsync( componentNode.Component, false, [componentNode.DisplayTemplateKey], new { Node = componentNode }); }

}

} ``` ```csharp public static string GetTheme(this CompositionNode model) { if (model.DisplayTemplateKey == "MyExperience") { return "cool-experience"; } return ""; } public static string? GetCss(this CompositionNode node, string key, Dictionary map, string? defaultCss = null) { if (node.DisplaySettings.TryGetValue(key, out var setting)) { if (map.TryGetValue(setting, out var css)) { return css; } } return defaultCss; } ``` ### Key points for manual rendering - Use `@Html.EditAttributes(node)` on every container element to support Visual Builder editing. - Use `Html.RenderContentDataAsync()` to render individual components, passing the `DisplayTemplateKey` as a tag.