|
| 1 | +# Blocks |
| 2 | + |
| 3 | +Blocks enable editors to insert structured content elements directly into the Rich Text Editor (RTE). Blocks are [Element Types](../../../../../../data/defining-content/default-document-types.md#element-type) and can be configured with custom properties, styling, and behavior. |
| 4 | + |
| 5 | +Blocks can be added to the Rich Text Editor when: |
| 6 | + |
| 7 | +* Available Blocks are specified as part of the Rich Text Editor Data Type configuration. |
| 8 | +* The **Insert Block** toolbar option is enabled in the Rich Text Editor. |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | +## Configure Blocks |
| 13 | + |
| 14 | +Blocks are Element Types that must be created before configuring them as blocks in the Rich Text Editor. You can create Element Types in the **Settings** > **Document Types** section |
| 15 | + |
| 16 | +Blocks functionality can then be configured through the Rich Text Editor Data Type configuration as follows. |
| 17 | + |
| 18 | +1. Navigate to **Settings** > **Data Types**. |
| 19 | +2. Select your Rich Text Editor Data Type or create a new one. |
| 20 | +3. Locate the **Available Blocks** section. |
| 21 | +4. Add the Element Types you want to make available as blocks. |
| 22 | +5. Configure each Block Type with the options described below. |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +### Editor Appearance |
| 27 | + |
| 28 | +Configure how blocks appear and behave in the Content section: |
| 29 | + |
| 30 | +* **Label** - Define how the block appears in the editor. Umbraco 16 uses [Umbraco Flavoured Markdown](../../../../../reference/umbraco-flavored-markdown.md) (UFM) syntax for dynamic labels. Use `{=propertyAlias}` to display property values (e.g., `{=author}` for a text property containing the name of an author, or `Written by: {=author}` for a label with static text and dynamic content). |
| 31 | +* **Display Inline** - When enabled, blocks remain inline with surrounding text. When disabled, blocks appear on separate lines. |
| 32 | +* **Overlay size** - Set the size of the editing overlay when editors work with the block content. |
| 33 | + |
| 34 | + |
| 35 | + |
| 36 | +### Data Models |
| 37 | + |
| 38 | +Configure the content structure for your blocks: |
| 39 | + |
| 40 | +* **Content model** - The Element Type that defines the main content properties for the block (required). |
| 41 | +* **Settings model** - Optional Element Type that defines additional settings or configuration options for the block. |
| 42 | + |
| 43 | + |
| 44 | + |
| 45 | +### Catalogue Appearance |
| 46 | + |
| 47 | +Control how blocks appear in the block picker: |
| 48 | + |
| 49 | +* **Background color** - Background color displayed behind the block icon or thumbnail. |
| 50 | +* **Icon Color** - Color of the Element Type icon. |
| 51 | +* **Thumbnail** - Custom image to replace the default Element Type icon. |
| 52 | + |
| 53 | +## Working with Blocks |
| 54 | + |
| 55 | +### Adding Blocks to Content |
| 56 | + |
| 57 | +Editors can add blocks to rich text content using the **Insert Block** toolbar button: |
| 58 | + |
| 59 | +1. Position the cursor where you want to insert the block |
| 60 | + |
| 61 | +2. Click the **Insert Block** button in the Rich Text Editor toolbar |
| 62 | + |
| 63 | +  |
| 64 | + |
| 65 | +3. Select the desired Block from the available options |
| 66 | + |
| 67 | +  |
| 68 | + |
| 69 | +4. Configure the block content (and settings, if provided) |
| 70 | + |
| 71 | +  |
| 72 | + |
| 73 | +The block appears in the editor as a structured element. |
| 74 | + |
| 75 | +## Rendering Blocks |
| 76 | + |
| 77 | +To display blocks on the frontend, create Partial Views for each Block. |
| 78 | + |
| 79 | +{% hint style="info" %} |
| 80 | +Rich Text Editor blocks use a different view location than Block List blocks. RTE blocks are placed in `Views/Partials/RichText/Components/`, while Block List blocks use `Views/Partials/BlockList/Components/`. |
| 81 | +{% endhint %} |
| 82 | + |
| 83 | +### File Structure |
| 84 | + |
| 85 | +* **Location**: `Views/Partials/RichText/Components/`. |
| 86 | +* **Naming**: Use the exact Element Type alias as the filename (e.g., `quoteBlock.cshtml` for alias `quoteBlock`). |
| 87 | +* **Model**: `Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem`. |
| 88 | + |
| 89 | +The different folder structure ensures that RTE blocks and Block List blocks can have separate rendering implementations, even when using the same Element Types. |
| 90 | + |
| 91 | +{% hint style="warning" %} |
| 92 | +The view filename must match the Element Type alias exactly. If you see the error `ArgumentException: ~/Views/Partials/richtext/Components/[filename].cshtml does not match any available view`, verify that your view filename matches your Element Type alias precisely. |
| 93 | +{% endhint %} |
| 94 | + |
| 95 | +### Example Partial View |
| 96 | + |
| 97 | +For a Block Type with Element Type alias `quoteBlock`: |
| 98 | + |
| 99 | +```csharp |
| 100 | +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem> |
| 101 | + |
| 102 | +@{ |
| 103 | + var quoteText = Model.Content.Value("quoteText")?.ToString(); |
| 104 | + var citation = Model.Content.Value("citation")?.ToString(); |
| 105 | +} |
| 106 | + |
| 107 | +<blockquote class="quote-block"> |
| 108 | + @if (!string.IsNullOrEmpty(quoteText)) |
| 109 | + { |
| 110 | + <p class="quote-text">@Html.Raw(quoteText)</p> |
| 111 | + } |
| 112 | + |
| 113 | + @if (!string.IsNullOrEmpty(citation)) |
| 114 | + { |
| 115 | + <cite class="quote-citation">@citation</cite> |
| 116 | + } |
| 117 | +</blockquote> |
| 118 | +``` |
| 119 | + |
| 120 | +### Example with Settings Model |
| 121 | + |
| 122 | +For a Call To Action block with Element Type alias `callToActionBlock` and settings model `callToActionBlockSettings`: |
| 123 | + |
| 124 | +```csharp |
| 125 | +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem> |
| 126 | +@using Umbraco.Cms.Core.Models |
| 127 | + |
| 128 | +@{ |
| 129 | + // Get link from Multi URL Picker |
| 130 | + var linkPicker = Model.Content.Value<IEnumerable<Link>>("link"); |
| 131 | + var link = linkPicker?.FirstOrDefault(); |
| 132 | + |
| 133 | + // Get style from settings (if settings model exists) |
| 134 | + var style = "primary"; // Default style |
| 135 | + if (Model.Settings != null) |
| 136 | + { |
| 137 | + var settingsStyle = Model.Settings.Value("style")?.ToString(); |
| 138 | + if (!string.IsNullOrEmpty(settingsStyle)) |
| 139 | + { |
| 140 | + style = settingsStyle.ToLower(); |
| 141 | + } |
| 142 | + } |
| 143 | + |
| 144 | + // CSS class based on style setting |
| 145 | + var cssClass = $"cta-button cta-button--{style}"; |
| 146 | +} |
| 147 | + |
| 148 | +@if (link != null && !string.IsNullOrEmpty(link.Url)) |
| 149 | +{ |
| 150 | + <div class="cta-block"> |
| 151 | + <a href="@link.Url" |
| 152 | + class="@cssClass" |
| 153 | + @(link.Target == "_blank" ? Html.Raw("target=\"_blank\" rel=\"noopener noreferrer\"") : Html.Raw(""))> |
| 154 | + @(!string.IsNullOrEmpty(link.Name) ? link.Name : "Learn More") |
| 155 | + </a> |
| 156 | + </div> |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +### Type-Safe Rendering with Models Builder |
| 161 | + |
| 162 | +When using Models Builder, specify the Content and Settings models for type-safe access: |
| 163 | + |
| 164 | +```csharp |
| 165 | +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem<QuoteBlock, QuoteBlockSettings>> |
| 166 | +@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels; |
| 167 | + |
| 168 | +@{ |
| 169 | + var style = ""; |
| 170 | + if (Model.Settings?.Color != null) |
| 171 | + { |
| 172 | + style = $"style=\"border-left-color: {Model.Settings.Color};\""; |
| 173 | + } |
| 174 | +} |
| 175 | + |
| 176 | +<blockquote class="quote-block" @Html.Raw(style)> |
| 177 | + @if (!string.IsNullOrEmpty(Model.Content.QuoteText)) |
| 178 | + { |
| 179 | + <p class="quote-text">@Html.Raw(Model.Content.QuoteText)</p> |
| 180 | + } |
| 181 | + |
| 182 | + @if (!string.IsNullOrEmpty(Model.Content.Citation)) |
| 183 | + { |
| 184 | + <cite class="quote-citation">@Model.Content.Citation</cite> |
| 185 | + } |
| 186 | +</blockquote> |
| 187 | +``` |
| 188 | + |
| 189 | +## Build a Custom Backoffice View |
| 190 | + |
| 191 | +Building Custom Views for Block representations in Backoffice is the same for all Block Editors. [Read about building a Custom View for Blocks here](../../../../../tutorials/creating-custom-views-for-blocklist.md). |
| 192 | + |
| 193 | +## Best Practices |
| 194 | + |
| 195 | +### Content Design |
| 196 | + |
| 197 | +* Design blocks for reusable content patterns. |
| 198 | +* Keep block content focused on a single purpose. |
| 199 | +* Use descriptive labels that help editors understand the block's function. |
| 200 | + |
| 201 | +### Performance |
| 202 | + |
| 203 | +* Avoid creating too many Blocks - this can overwhelm content editors. |
| 204 | +* Use appropriate caching strategies for block rendering. |
| 205 | +* Consider the impact of complex blocks on editor performance. |
| 206 | + |
| 207 | +### Accessibility |
| 208 | + |
| 209 | +* Ensure block markup follows accessibility guidelines. |
| 210 | +* Provide meaningful labels and descriptions. |
| 211 | +* Test block rendering with screen readers. |
| 212 | + |
| 213 | +## Related Articles |
| 214 | + |
| 215 | +* [Element Types](../../../../data/defining-content/default-document-types.md#element-type) |
| 216 | +* [Rich Text Editor Configuration](configuration.md) |
| 217 | +* [Rich Text Editor Extensions](extensions.md) |
0 commit comments