diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 611b8839ac9..9148c41a2be 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -83,6 +83,7 @@ * [Dropdown](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/dropdown/README.md) * [Rich Text Editor](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md) * [Configuration](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md) + * [Blocks](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md) * [Custom CSS properties](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/css-properties.md) * [Extensions](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md) * [Style Menu](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/style-menu.md) diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md index 894b2567311..50563f97834 100644 --- a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md +++ b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md @@ -20,7 +20,7 @@ Customize everything from toolbar options to editor size to where pasted images Define a cascading text formatting and style menu for the Rich Text Editor toolbar. -## [Blocks](broken-reference) +## [Blocks](blocks.md) Use Blocks to define specific parts that can be added as part of the markup of the Rich Text Editor. diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md new file mode 100644 index 00000000000..1835d3c3e6c --- /dev/null +++ b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md @@ -0,0 +1,217 @@ +# Blocks + +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. + +Blocks can be added to the Rich Text Editor when: + +* Available Blocks are specified as part of the Rich Text Editor Data Type configuration. +* The **Insert Block** toolbar option is enabled in the Rich Text Editor. + +![RTE Insert Block Toolbar Button](images/rte-blocks-toolbar-insert-button.png) + +## Configure Blocks + +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 + +Blocks functionality can then be configured through the Rich Text Editor Data Type configuration as follows. + +1. Navigate to **Settings** > **Data Types**. +2. Select your Rich Text Editor Data Type or create a new one. +3. Locate the **Available Blocks** section. +4. Add the Element Types you want to make available as blocks. +5. Configure each Block Type with the options described below. + +![RTE Blocks Data Type Configuration](images/rte-blocks-datatype-configuration.png) + +### Editor Appearance + +Configure how blocks appear and behave in the Content section: + +* **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). +* **Display Inline** - When enabled, blocks remain inline with surrounding text. When disabled, blocks appear on separate lines. +* **Overlay size** - Set the size of the editing overlay when editors work with the block content. + +![RTE Blocks Editor Appearance Settings](images/rte-blocks-editor-appearance-settings.png) + +### Data Models + +Configure the content structure for your blocks: + +* **Content model** - The Element Type that defines the main content properties for the block (required). +* **Settings model** - Optional Element Type that defines additional settings or configuration options for the block. + +![RTE Blocks Data Models Settings](images/rte-blocks-data-models-settings.png) + +### Catalogue Appearance + +Control how blocks appear in the block picker: + +* **Background color** - Background color displayed behind the block icon or thumbnail. +* **Icon Color** - Color of the Element Type icon. +* **Thumbnail** - Custom image to replace the default Element Type icon. + +## Working with Blocks + +### Adding Blocks to Content + +Editors can add blocks to rich text content using the **Insert Block** toolbar button: + +1. Position the cursor where you want to insert the block + +2. Click the **Insert Block** button in the Rich Text Editor toolbar + + ![Adding Blocks to Content - Step 1](images/rte-blocks-adding-to-content-1.png) + +3. Select the desired Block from the available options + + ![Adding Blocks to Content - Step 2](images/rte-blocks-adding-to-content-2.png) + +4. Configure the block content (and settings, if provided) + + ![Adding Blocks to Content - Step 3](images/rte-blocks-adding-to-content-3.png) + +The block appears in the editor as a structured element. + +## Rendering Blocks + +To display blocks on the frontend, create Partial Views for each Block. + +{% hint style="info" %} +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/`. +{% endhint %} + +### File Structure + +* **Location**: `Views/Partials/RichText/Components/`. +* **Naming**: Use the exact Element Type alias as the filename (e.g., `quoteBlock.cshtml` for alias `quoteBlock`). +* **Model**: `Umbraco.Cms.Core.Models.Blocks.RichTextBlockItem`. + +The different folder structure ensures that RTE blocks and Block List blocks can have separate rendering implementations, even when using the same Element Types. + +{% hint style="warning" %} +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. +{% endhint %} + +### Example Partial View + +For a Block Type with Element Type alias `quoteBlock`: + +```csharp +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage + +@{ + var quoteText = Model.Content.Value("quoteText")?.ToString(); + var citation = Model.Content.Value("citation")?.ToString(); +} + +
+ @if (!string.IsNullOrEmpty(quoteText)) + { +

@Html.Raw(quoteText)

+ } + + @if (!string.IsNullOrEmpty(citation)) + { + @citation + } +
+``` + +### Example with Settings Model + +For a Call To Action block with Element Type alias `callToActionBlock` and settings model `callToActionBlockSettings`: + +```csharp +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage +@using Umbraco.Cms.Core.Models + +@{ + // Get link from Multi URL Picker + var linkPicker = Model.Content.Value>("link"); + var link = linkPicker?.FirstOrDefault(); + + // Get style from settings (if settings model exists) + var style = "primary"; // Default style + if (Model.Settings != null) + { + var settingsStyle = Model.Settings.Value("style")?.ToString(); + if (!string.IsNullOrEmpty(settingsStyle)) + { + style = settingsStyle.ToLower(); + } + } + + // CSS class based on style setting + var cssClass = $"cta-button cta-button--{style}"; +} + +@if (link != null && !string.IsNullOrEmpty(link.Url)) +{ +
+ + @(!string.IsNullOrEmpty(link.Name) ? link.Name : "Learn More") + +
+} +``` + +### Type-Safe Rendering with Models Builder + +When using Models Builder, specify the Content and Settings models for type-safe access: + +```csharp +@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage> +@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels; + +@{ + var style = ""; + if (Model.Settings?.Color != null) + { + style = $"style=\"border-left-color: {Model.Settings.Color};\""; + } +} + +
+ @if (!string.IsNullOrEmpty(Model.Content.QuoteText)) + { +

@Html.Raw(Model.Content.QuoteText)

+ } + + @if (!string.IsNullOrEmpty(Model.Content.Citation)) + { + @Model.Content.Citation + } +
+``` + +## Build a Custom Backoffice View + +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). + +## Best Practices + +### Content Design + +* Design blocks for reusable content patterns. +* Keep block content focused on a single purpose. +* Use descriptive labels that help editors understand the block's function. + +### Performance + +* Avoid creating too many Blocks - this can overwhelm content editors. +* Use appropriate caching strategies for block rendering. +* Consider the impact of complex blocks on editor performance. + +### Accessibility + +* Ensure block markup follows accessibility guidelines. +* Provide meaningful labels and descriptions. +* Test block rendering with screen readers. + +## Related Articles + +* [Element Types](../../../../data/defining-content/default-document-types.md#element-type) +* [Rich Text Editor Configuration](configuration.md) +* [Rich Text Editor Extensions](extensions.md) diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md index 973a10bc252..48405ffe71d 100644 --- a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md +++ b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md @@ -45,7 +45,7 @@ Select the width of the link picker overlay. The overlay size comes in three siz ## Available Blocks -Blocks can be added as elements in the Rich Text Editor. Configuration and rendering of Blocks are described in the [Blocks in Rich Text Editor](broken-reference) article. +Blocks can be added as elements in the Rich Text Editor. Configuration and rendering of Blocks are described in the [Blocks in Rich Text Editor](blocks.md) article. ## Image Upload Folder diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-1.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-1.png new file mode 100644 index 00000000000..47ff9a7eb13 Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-1.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-2.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-2.png new file mode 100644 index 00000000000..9294e8bed0c Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-2.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-3.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-3.png new file mode 100644 index 00000000000..a204f47163d Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-adding-to-content-3.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-data-models-settings.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-data-models-settings.png new file mode 100644 index 00000000000..f85d58fa82b Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-data-models-settings.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-datatype-configuration.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-datatype-configuration.png new file mode 100644 index 00000000000..6aa7845022f Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-datatype-configuration.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-editor-appearance-settings.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-editor-appearance-settings.png new file mode 100644 index 00000000000..9e5ebcc88e5 Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-editor-appearance-settings.png differ diff --git a/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-toolbar-insert-button.png b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-toolbar-insert-button.png new file mode 100644 index 00000000000..3339e299477 Binary files /dev/null and b/16/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-blocks-toolbar-insert-button.png differ diff --git a/16/umbraco-cms/reference/templating/macros.md b/16/umbraco-cms/reference/templating/macros.md index f6f5501de9e..19ea54855d6 100644 --- a/16/umbraco-cms/reference/templating/macros.md +++ b/16/umbraco-cms/reference/templating/macros.md @@ -5,7 +5,7 @@ Macros and Partial View Macros have been removed with the release of Umbraco 14. -We recommend using using [Partial Views](../../fundamentals/design/partial-views.md) or [Blocks in the Rich Text Editor](broken-reference) as a replacement. +We recommend using [Partial Views](../../fundamentals/design/partial-views.md) or [Blocks in the Rich Text Editor](../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md) as a replacement. Learn more about the decision for remove Macros in the official announcement: [Breaking change: Macros will be removed in Umbraco 14](https://github.com/umbraco/Announcements/issues/14). {% endhint %}