How To Use

Learn how to use the Block Farm Editor for Umbraco. This guide covers initial setup, backoffice configuration, building your first block, and defining block properties.

Initial setup
Backoffice setup
Building your first block
Defining Block Properties

Initial setup.

Setup is comprised of the following steps:

Install the Block Farm Editor nuget package

dotnet add package BlockFarmEditor.Umbraco

Initial setup in your Umbraco project:

Add AddBlockFarmEditor() to your builder.CreateUmbracoBuilder()

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .AddBlockFarmEditor() // Added BlockFarmEditor
    .Build();

Add the tag helper import to your _ViewImports.cshtml file.

@addTagHelper *, BlockFarmEditor.RCL

Add the register tag helper <register-block-farm></register-block-farm> to your umbraco layout’s head section. This tag helper registers the front end javascript needed when in edit mode.

<html>
   <head>
       <register-block-farm></register-block-farm>
   </head>
   <body>
   </body>
</html>

The javascript will not be loaded in live mode only in edit mode.

Backoffice setup:

License the Block Farm Editor in the Umbraco backoffice

Go to the Settings section, then Block Farm Editor.
Select your domain and click (Re)Validate.

Create your first Block Area

Block Areas are used to define where blocks can be placed in your templates. Use the <block-area> tag helper to define block areas in your templates.

Example:

@using Umbraco.Cms.Web.Common.PublishedModels;
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
	Layout = "layout.cshtml";
}

<block-area identifier="banner"></block-area>

<div class="container-fluid">
    <div class="row mb-3">
        <div class="col-12 col-md-3">
            <block-area identifier="sidebar-widgets"></block-area>
        </div>

        <div class="col-12 col-md-9">
            <block-area identifier="main"></block-area>
        </div>
    </div>
    <block-area identifier="full-page"></block-area>
</div>

Build your first block.

Blocks are reusable components geared towards easily place content in different areas in your templates. They can be used to create anything from simple text blocks to complex components with multiple properties and behaviors.

Built using razor syntax, you have full control on what you would like to create.

Register Block Definitions

Use assembly attributes to register your available blocks and containers. The difference between a container and a block is purely syntactic, allowing for categorization on the front end. Either a view component type or a partial view can be used to render your block. There is also a PropertiesType which can be used to define the properties of the block. The icon list can use any of the icons specified in the essential icon registry. Icon Registry Essential

Example:

// Blocks
[assembly: BlockFarmEditorBlock("my.text.block", "Text Block", 
    PropertiesType = typeof(TextBlockProperties), 
    ViewPath = "~/Views/Blocks/TextBlock.cshtml", 
    Icon = "icon-text")]

[assembly: BlockFarmEditorBlock("my.image.block", "Image Block", 
    PropertiesType = typeof(ImageBlockProperties), 
    ViewComponentType = typeof(ImageBlockViewComponent), 
    Icon = "icon-picture")]

// Containers
[assembly: BlockFarmEditorContainer("my.section.container", "Section Container", 
    PropertiesType = typeof(SectionContainerProperties), 
    ViewPath = "~/Views/Containers/Section.cshtml", 
    Icon = "icon-grid")]

[assembly: BlockFarmEditorContainer("my.complex.section.container", "Complex Section Container", 
    PropertiesType = typeof(ComplexSectionContainerProperties), 
    ViewComponentType = typeof(ComplexSectionContainerViewComponent), 
    Icon = "icon-grid")]

Defining Block Properties.

Properties classes inherit from IBuilderProperties and are made up of Properties decorated with attributes.

You have two options for decorating the properties:

Use the BlockFarmEditorDataType attribute to define the Data Type name (or id as a string) and label.
Use the BlockFarmEditorPropertyEditor attribute to define the Property editor and label.

Using Data Types

Using a BlockFarmEditorDataType allows you to control the property editor’s config in the backoffice.

public class TextBlockProperties : IBuilderProperties
{
    [BlockFarmEditorDataType("Textstring", "Heading")]
    public string? Heading { get; set; }
    
    [BlockFarmEditorDataType("Richtext editor", "Content")]
    public RichTextEditorValue? Content { get; set; }
}

Adding a custom config to a BlockFarmEditorDataType

Use a BlockFarmEditorDataTypeConfig to specify the property editor’s config on the backend.

public class AdvancedTextProperties : IBuilderProperties
{
    [BlockFarmEditorDataType("Textstring", "Heading")]
    [BlockFarmEditorDataTypeConfig(typeof(TextBoxConfig))]
    public string? Title { get; set; }
}

public class TextBoxConfig : IBlockFarmEditorConfig
{
    public IEnumerable<BlockFarmEditorConfigItem> GetItems()
    {
        return new[]
        {
            new BlockFarmEditorConfigItem { Alias = "maxChars", Value = 100 },
            new BlockFarmEditorConfigItem { Alias = "minChars", Value = 5 }
        };
    }
}

Use the Umbraco element typee

For multiple selection of content, make use of the element types in umbraco and then use the block list or block grid components.

See Bootstrap Row Block for an example of an element type being used with a block list data type.