You can choose to customize your editing experience by implementing a custom view for each Block Type of a Block Editor.

By picking a custom view you overwrite the backoffice UI for the given block with your own. This enables you to define how a block should be presented. It can, however, also include interactive elements and be a full custom solution to how data is manipulated. In the Block List Editor the Inline Editing Mode must be disabled for custom backoffice views to appear.

Write your own HTML view

Currently you can only pick HTML files for a custom view. These views are powered by AngularJS and you can write any AngularJS logic.

Your HTML can be anything. If you use it as a representation of the content you would also want the full view to be clickable. This would then open the default editor for editing of your content.

The following example displays the property with the alias headline together with the description inside a button to edit your block.

<button type="button" ng-click="block.edit()">
  <h2 ng-bind="block.data.headline"></h2>
  <p ng-bind="block.data.description"></p>
</button>

If you would like to display properties of settings, you can access these by using block.settingsData.myPropertyAlias.

Make Block List Editor custom view draggable

A custom view of Block List Editor needs to have the 'blockelement__draggable-element' class presented to define which part of the Block is draggable.

Example:

<button type="button" class="blockelement__draggable-element" ng-click="block.edit()">
  <h2 ng-bind="block.data.headline"></h2>
  <p ng-bind="block.data.description"></p>
</button>

Add the Areas for Block Grid Editor

Blocks of the Block Grid Editor can have Areas. These Blocks require their Custom View to define where the Areas should be inserted.

This enables you to wrap and place the Areas as you need.

The Areas is inserted through Web Component Slots. A slot is a native HTML tag.

These Area slots can be generated automatically via this AngularJS Directive:

<umb-block-grid-render-area-slots></umb-block-grid-render-area-slots>

Example of a Custom View wrapping the Areas within a green border:

<div style="border:green 1px solid; padding: 20px;">
    <slot name="area-container" part="area-container"></slot>
    <umb-block-grid-render-area-slots></umb-block-grid-render-area-slots>
</div>

You can also define where each Area should be inserted. This is relevant if you like the Areas to appear differently than the provided grid setup of Areas.

As a reference here is an example of the HTML output of the umb-block-grid-render-area-slots AngularJS Directive:

    <div part="area-container">
        <slot name="myAreasAlias1"></slot>
        <slot name="myAreasAlias2"></slot>
    </div>

Adding custom implementation to your View

To achieve this you need to add a custom AngularJS controller to your custom view, using the ng-controller attribute:

<div ng-controller="customBlockController">
    <button type="button" ng-click="block.edit()" >
        <h2 ng-bind="block.data.headline"></h2>
        <p ng-bind="block.data.description"></p>
    </button>
</div>

Create a folder inside the App_Plugins folder called 'CustomBlockView'.

Create two files within the CustomBlockView file: package.manifest and customBlock.controller.js.

Add the following JSON to the package.manifest file:

{
  "javascript": [
    "~/App_Plugins/CustomBlockView/customBlock.controller.js"    
  ]  
}

The second file, customBlock.controller.js, will be used to register the 'customBlockController' defined using the ng-controller attribute in your custom view.

To register the controller, add the following lines of code:

angular.module("umbraco").controller("customBlockController", function ($scope) {
    // you can do your custom functionality here!
});

Example: Displaying an image from a Media Picker

Your block may enable you to 'pick' an image to use as the background for a particular block. If you try to display this image directly in the view using block.data.image, you will see the unique ID and not the image.

There are two approaches to displaying the actual image in your custom block view. Either use a filter in your custom view or retrieve the image through the AngularJS controller.

1. Retrieve the image using a filter directly in your custom view

By using the AngularJS filter called mediaItemResolver, it is possible to retrieve the image directly from your custom view file. You will need to create a variable that then uses the mediaItemResolver filter on the Media Picker property. This variable is then used to retrieve the image URL in an <img> HTML tag.

In the following example, a mediaItem variable is defined and used to set the ng-src value on the image tag. This will retrieve the image into your custom view.

<div ng-click="block.edit()">
    <h2 ng-bind="block.data.headline"></h2>

    <!-- Use the 'mediaItemResolver' on the block.data.image -->
    {{mediaItem = (block.data.image[0].mediaKey | mediaItemResolver); “”}}

    <!-- Use the variable defined above to retrieve the mediaLink representing the image -->
    <img ng-src=“{{mediaItem.mediaLink}}“/>
    <p ng-bind="block.data.description"></p>
</div>

2. Retrieve the image using an AngularJS controller

It is also possible to get the ImageUrl by using the unique ID in an AngularJS controller.

Amend the customBlock.controller.js file, by injecting the mediaResource to retrieve the image from the ID:

angular.module("umbraco").controller("customBlockController", function ($scope, mediaResource) {

    //your property is called image so the following will contain the udi:
    var imageUdi = $scope.block.data.image[0].mediaKey;
    //the mediaResource has a getById method:
    mediaResource.getById(imageUdi).then(function (media) {
        console.log(media);
        //set a property on the 'scope' called imageUrl for the returned media object's mediaLink
        $scope.imageUrl = media.mediaLink;
    });
});

The Custom View should then be updated to use the imageUrl property to display the image:

<div ng-controller="customBlockController" ng-click="block.edit()">
    <h2 ng-bind="block.data.headline"></h2>
    <img src="{{imageUrl}}" />
    <p ng-bind="block.data.description"></p>
</div>

If you need to use a specific crop, you can inject the imageUrlGeneratorResource resource. This has a getCropUrl(mediaPath, width, height, imageCropMode, animationProcessMode) method:

angular.module("umbraco").controller("customBlockController", function ($scope, mediaResource,imageUrlGeneratorResource) {

    //your property is called image so the following will contain the udi:
    var imageUdi = $scope.block.data.image[0].mediaKey;
    //the mediaResource has a getById method:
    mediaResource.getById(imageUdi).then(function (media) {
        imageUrlGeneratorResource.getCropUrl(media.mediaLink, 150, 150).then(function (cropUrl) {
            console.log(cropUrl);
            $scope.imageUrl = cropUrl;
        });
    });    
});

Alias: Umbraco.BlockList

Returns: IEnumerable<BlockListItem>

Block List is a list editing property editor, using to define the list item schema.

Configure Block List

The Block List property editor is configured in the same way as any standard property editor, via the Data Types admin interface.

To set up your Block List Editor property, create a new Data Type and select Block List from the list of available property editors.

Then you will see the configuration options for a Block List as shown below.

The Data Type editor allows you to configure the following properties:

• Available Blocks - Here you will define the Block Types to be available for use in the property. Read more on how to set up Block Types below.

• Amount - Sets the minimum and/or maximum number of blocks that should be allowed in the list.

• Single block mode - When in Single block mode, the output will be BlockListItem<> instead of BlockListModel

• Live editing mode - Enabling this will make editing of a block happening directly to the document model, making changes appear as you type.

• Inline editing mode - Enabling this will change editing experience to inline, meaning that editing the data of blocks happens at sight as accordions.

• Property editor width - Overwrite the width of the property editor. This field takes any valid css value for "max-width".

Setup Block Types

Block Types are Element Types which need to be created before you can start configuring them as Block Types. This can be done either directly from the property editor setup process, or you can set them up beforehand and add them to the block list after.

Once you have added an element type as a Block Type on your Block List Data Type you will have the option to configure it further.

Each Block has a set of properties that are optional to configure. They are described below.

Editor Appearance

By configuring the properties in the group you can customize the user experience for your content editors when they work with the blocks in the Content section.

• Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.

• Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of this block.

• Overlay editor size - Set the size for the Content editor overlay for editing this block.

Data Models

It is possible to use two separate Element Types for your Block Types. Its required to have one for Content and optional to add one for Settings.

• Content model - This presents the Element Type used as model for the content section of this Block. This cannot be changed, but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.

• Settings model - Add a Settings section to your Block based on a given Element Type. When picked you can open the Element Type or choose to remove the settings section again.

Catalogue appearance

These properties refer to how the Block is presented in the Block catalogue, when editors choose which Blocks to use for their content.

• Background color - Define a background color to be displayed beneath the icon or thumbnail. Eg. #424242.

• Icon color - Change the color of the Element Type icon. Eg. #242424.

• Thumbnail - Pick an image or SVG file to replace the icon of this Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10, and we recommend a resolution of 400px width and 250px height.

Advanced

These properties are relevant when you work with custom views.

• Force hide content editor - If you made a custom view that enables you to edit the content part of a block and you are using default editing mode (not inline) you might want to hide the content-editor from the block editor overlay.

Editing Blocks

When viewing a Block List editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button brings up the Block Catalogue.

The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.

Click the Block Type you wish to create and a new Block will appear in the list.

Depending on whether your Block List Editor is setup to use default or inline editing mode you will see one of the following things happening:

In default mode you will enter the editing overlay of that Block:

In inline editing mode the new Blocks will expand to show its inline editor:

More Blocks can be added to the list by clicking the Add content button or using the inline Add content button that appears on hover between or above existing Blocks.

To reorder the Blocks, click and drag a Block up or down to place in the desired order.

To delete a Block click the trash-bin icon appearing on hover.

Rendering Block List Content

Rendering the stored value of your Block List property can be done in two ways.

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering blocks via a Partial View for each block.

The default rendering method is named GetBlockListHtml() and comes with a few options to go with it. The typical use could be:

"MyBlocks" above is the alias for the Block List editor.

If using ModelsBuilder the example can be simplified:

Example:

To make this work you will need to create a Partial View for each block, named by the alias of the Element Type that is being used as Content Model.

These partial views must be placed in this folder: Views/Partials/BlockList/Components/. Example: Views/Partials/BlockList/Components/MyElementTypeAliasOfContent.cshtml.

A Partial View will receive the model of Umbraco.Core.Models.Blocks.BlockListItem. This gives you the option to access properties of the Content and Settings section of your Block.

In the following example of a Partial view for a Block Type, please note that the MyElementTypeAliasOfContentand MyElementTypeAliasOfSettings should correspond with the selected Element Type Alias for the given model in your case.

Example:

With ModelsBuilder:

2. Build your own rendering

A built-in value converter is available to use the data as you like. Call the Value<T> method with a generic type of IEnumerable<BlockListItem> and the stored value will be returned as a list of BlockListItem entities.

Example:

Each item is a BlockListItem entity that contains two main properties Content and Settings. Each of these is a IPublishedElement which means you can use all the value converters you are used to using.

Example:

Extract Block List Content data

In some cases, you might want to use the Block List Editor to hold some data and not necessarily render a view since the data should be presented in different areas on a page. An example could be a product page with variants stored in a Block List Editor.

In this case, you can extract the variant's data using the following, which returns IEnumerable<IPublishedElement>.

Example:

If using ModelsBuilder the example can be simplified:

Example:

If you know the Block List Editor only uses a single block, you can cast the collection to a specific type T using .OfType<T>() otherwise the return value will be IEnumerable<IPublishedElement>.

Build a Custom Backoffice View

The Block Editors are property editors that enabled you to build advanced editor tools using a set of predefined Document Types.

Umbraco CMS currently ships with two Block Editors: the Block List and the Block Grid.

Customizing Block Editors

Learn how to create custom views for the blocks used in your Block Grid or Block List property editors.

Get an overview of available configurations for the label properties.

When configuring a block, the label property allows you to define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Example: My Block {{myPropertyAlias}} will be shown as: My Block FooBar.

You can also use more advanced expressions using AngularJS filters. Example: {{myPropertyAlias | limitTo:100}} or for a property using the Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}.

It is also possible to use properties from the settings model by using {{$settings.propertyAlias}}.

In some cases, you might want to create a fallback label. This can be achieved using the following format: {{myProperty || $contentTypeName}}.

This example will show the name of the ElementType when the value of myProperty is not defined.

Useful Angular filters

As well as the , Umbraco ships with additional filters which are useful for setting the Label field of Block editors.

Example: mediaItemResolver

This is how you could use the filter for a Media Picker of the type Umbraco.MediaPicker3 with multiple images:

The mediaKey is a Guid like c7a4526c-6b32-4665-a047-5b3e7256d973.

For the Media Name, the same could be achieved using ncNodeName like shown below:

The ncNodeName value expects a UDI like umb://media/c7a4526c6b324665a0475b3e7256d973.

Custom filters

If the filters do not suit your needs, you can create custom filters by creating a plugin in App_Plugins and adding a filter module. You can see an example below:

1. Create a plugin by adding a folder inside App_Plugins called MyFilters

2. Inside the MyFilters folder add a package.manifest file containing:

1. Add a myFilter.filter.js file containing:

Special variables

Alias: Umbraco.BlockGrid

Returns: BlockGridModel

The Block Grid property editor enables editors to layout their content in the Umbraco backoffice. The content is made of Blocks that can contain different types of data.

Sample configuration

When testing out the property editor, you can use a set of predefined Blocks. The option will only be possible when there are no other Data Types using the Block Grid property editor.

• Create a new Data Type.

• Select the Block Grid as the Property editor.

• Install the "Sample Configuration".

4 Blocks will be added to the property, ready for testing.

Configuring the Block Grid

The Block Grid property editor is configured via the Data Types backoffice interface.

To set up the Block Grid property editor, follow these steps:

1. Navigate to the Settings section in the Umbraco backoffice.

2. Right-click the Data Types folder.

3. Select Create -> New Data Type.

4. Select Block Grid from the list of available property editors.

You will see the configuration options for a Block Grid property editor as shown below:

The Data Type editor allows you to configure the following properties:

• Amount - Sets the minimum and/or the maximum number of Blocks that should be allowed at the root of the layout.

• Live editing mode - Enabling this option will allow you to see the changes as you are editing them.

• Editor width - Overwrites the width of the property editor. This field takes any valid CSS value for "max-width". For example: 100% or 800px.

• Grid Columns - Define the number of columns in your grid layout. The default is 12 columns.

• Layout Stylesheet - Replaces the built-in Layout Stylesheet. Additionally, you can retrieve the default layout stylesheet to use as a base for your own inspiration or for writing your own stylesheet.

• Create Button Label - Overwrites the label on the Create button.

Setup Block Types

Once you have added an Element Type as a Block Type on your Block Grid Data Type you have the option to configure it.

Groups

Blocks can also be grouped. This is visible in the Block Catalogue and can also be used to allow a group of Blocks in an Area.

Block Configuration Settings

Each Block has a set of properties that are optional to configure. These are described below.

General

Customize the user experience for your content editors when they work with the Blocks in the Content section.

• Label - Defines a label for the appearance of the Block in the editor. The label can use AngularJS template-string-syntax to display values of properties.

• Content model - Presents the Element Type used as model for the Content section of this Block. This cannot be changed but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.

• Settings model - Adds a Settings section to your Block based on a given Element Type. When selected you can open the Element Type or choose to remove the Settings section again.

Size options

Customize the Blocks size in the Grid. If you define multiple options, the Block becomes scalable.

By default, a Block takes up the available width.

A Block can be resized in two ways:

2. A Block can have one or more Column Span options defined.

A Column Span option is used to define the width of a Block. With multiple Column Span options defined, the Content Editor can scale the Block to fit specific needs.

Additionally, Blocks can be configured to span rows, this enables one Block to be placed next to a few rows containing other Blocks.

• Available column spans - Defines one or more columns, the Block spans across. For example: in a 12 columns grid, 6 columns is equivalent to half width. By enabling 6 columns and 12 columns, the Block can be scaled to either half width or full width.

• Available row spans - Defines the amount of rows the Block spans across.

Catalogue appearance

These properties refer to how the Block is presented in the Block catalogue when editors choose which Blocks to use for their content.

• Background color - Defines a background color to be displayed beneath the icon or thumbnail. Example: #424242.

• Icon color - Changes the color of the Element Type icon. Example: #242424.

• Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of the Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10. We recommend a resolution of 400px width and 250px height.

Permissions

• Allow in root - Determines whether the Block can be created at the root of your layout. Turn this off if you only want a Block to appear within Block Areas.

• Allow in areas - Determines whether the Block can be created inside Areas of other Blocks. If this is turned off it can still be allowed in Block Areas by defining specific allowed Blocks.

Areas

Blocks can nest other Blocks to support specific compositions. These compositions can be used as a layout for other Blocks.

To achieve nesting, a Block must have one or more Areas defined. Each Area can contain one or more Blocks.

Each Area has a size, defined by column and rows spans. The grid for the Areas are based on the same amount of columns as your root grid, unless you choose to change it.

To scale an Area, click and drag the scale-button in the bottom-right corner of an Area.

• Grid Columns for Areas - Overwrites the amount of columns used for the Area grid.

• Areas - Determines whether the Block can be created inside Areas of other Blocks.

Area configuration

• Alias - The alias is used to identify this Area. It is being printed by GetBlockGridHTML() and used as name for the Area slot in Custom Views. The alias is also available for CSS Selectors to target the HTML-Element representing an Area.

• Create Button Label - Overwrites the Create Button Label of the Area.

• Number of blocks - Determines the total number of Blocks in an Area.

• Allowed block types - When this is empty, all Blocks with Permissions for creation in Areas, will be available. This can be overwritten by specifying the allowed Blocks. Define the types of Blocks or Groups of Blocks that are allowed. Additionally, you can also set how many Blocks of each type/group should be present.

When allowing a Group of Blocks, you might want to require a specific amount for a certain Block of that Group. This can be done by adding that Block Type to the list as well and set the requirements.

Advanced

These properties are relevant when working with custom views or complex projects.

• Custom view - Overwrites the AngularJS view for the block presentation in the Content editor. Use this view to make a more visual presentation of the Block or make your own editing experience by adding your own AngularJS controller to the view.

• Custom stylesheet - Pick your own stylesheet to be used by the Block in the Content editor.

• Overlay editor size - Sets the size for the Content editor overlay for editing this block.

• Hide content editor - Hides the UI for editing the content in a Block Editor. This is only relevant if you made a custom view that provides the UI for editing of content.

Editing Blocks

When viewing a Block Grid property editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button opens up the Block Catalogue.

The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.

Click the Block Type you wish to create and a new Block will appear in the layout.

More Blocks can be added to the layout by clicking the Add content button. Alternatively, use the Add content button that appears on hover to add new Blocks between, besides, or above the existing Blocks.

To delete a Block, click the trash icon which appears on the mouse hover.

Sorting Blocks

Blocks can be rearranged using the click and drag feature. Move them up or down to place them in the desired order.

Moving a Block from one Area to another is done in the same way. If a Block is not allowed in the given position, the area will display a red color and not allow the new position.

Scaling Blocks

If a Block has multiple size options it can be scaled via the UI. This appears in the bottom left corner of the Block.

The Block is resized using a click-and-drag feature. Moving the mouse will change the size to the size options closest to the mouse pointer.

Rendering Block Grid Content

Rendering the stored value of your Block Grid property editor can be done in two ways:

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering Blocks using a Partial View for each block.

The default rendering method is named GetBlockGridHtmlAsync() and comes with a few options - for example:

In the sample above "myGrid" is the alias of the Block Grid editor.

If you are using ModelsBuilder, the example will look like this:

To use the GetBlockGridHtmlAsync() method, you will need to create a Partial View for each Block Type. The Partial View must be named using the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial View files need to go into the Views/Partials/blockgrid/Components/ folder.

Example: Views/Partials/blockgrid/Components/MyElementTypeAliasOfContent.cshtml.

The Partial Views will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem. This model contains Content and Settings from your block, as well as the configured RowSpan, ColumnSpan, and Areas of the Block.

Rendering the Block Areas

The Partial View for the Block is responsible for rendering its own Block Areas. This is done using another built-in rendering mechanism:

Here you will need to create a Partial View for each Block Type within the Block Area. For the name, use the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial Views must be placed in the same folder as before, (Views/Partials/blockgrid/Components/), and will receive a model of type Umbraco.Cms.Core.Models.Blocks.BlockGridItem.

Putting it all together

The following is an example of a Partial View for a Block Type of type MyElementTypeAliasOfContent.

If you are using ModelsBuilder, you can make the property rendering strongly typed by letting your view accept a model of type BlockGridItem<T>. For example:

Stylesheet

Using the default rendering together with your layout stylesheet will provide what you need for rendering the layout.

If you like to use the Default Layout Stylesheet, you must copy the stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css.

2. Build your own rendering

The built-in value converter for the Block Grid property editor lets you use the block data as you like. Call the Value<T> method with a type of BlockGridModel to have the stored value returned as a BlockGridModel instance.

BlockGridModel contains the Block Grid configuration (like the number of columns as GridColumns) whilst also being an implementation of IEnumerable<BlockGridItem> (see details for BlockGridItem above).

The following example mimics the built-in rendering mechanism for rendering Blocks using Partial Views:

If you do not want to use Partial Views, you can access the block item data directly within your rendering:

Write a Custom Layout Stylesheet

The default layout stylesheet is using CSS Grid. This can be modified to fit your implementation and your project.

Adjusting the Default Layout Stylesheet

To make additions or overwrite parts of the default layout stylesheet, import the default stylesheet at the top of your own file.

You need to copy the Default Layout Stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the css folder, example: wwwroot/css/umbraco-blockgridlayout.css.

Write a new Layout Stylesheet

In this case, you would have to write the layout from scratch.

You are free to pick any style, meaning there is no requirement to use CSS Grid. It is, however, recommended to use CSS Grid to ensure complete compatibility with the Umbraco backoffice.

CSS Class structure and available data

When extending or writing your own layout, you need to know the structure and what data is available.

For example: You can use the below HTML structure:

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.

Creating a Block Grid programmatically

In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.

1. On a document type add a property called blockGrid.

2. Then add as editor Block Grid.

3. In the Block Grid add a new block and click to Create new Element Type

4. Name this element type spotElement with the following properties:

• a property called title with the editor of Textstring

• a property called text with the editor of Textstring

1. Then on the Settings model click to add a new Setting.

2. Then click to Create new Element Type.

3. Name this element type spotSettings with the following properties:

• a property called featured with the editor of True/false.

The raw input data for the spots looks like this:

The resulting JSON object stored for the Block Grid will look like this:

For each item in the raw data, we need to create:

• One contentData entry with the title and text.

• One settingsData entry with the featured value (the checkbox expects "0" or "1" as data value).

• One layout entry with the desired column and row spans.

All contentData and layoutData entries need their own unique Udi as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (spotElement) and one for settings (spotSettings). In a real life scenario, there could be any number of Element Type combinations.

1. First and foremost, we need models to transform the raw data into Block Grid compatible JSON. Create a class called Model.cs containing the following:

For the above code IContent? content = _contentService.GetById(1203); change the id with your content node that is using the Block Grid.

1. In order to test this implementation, run the project and add /umbraco/api/blockgridtest/create after your domain name. If the result shows as Saved then check your content node and you will see the 2 spotElement contents.

This can also be tested via Postman as well if preffered.