Blocks

By Optimizely Education
Published: Feb 5, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Concept: Blocks as atomic UI building blocks.
Architecture: Shared vs. Local (Property) blocks.
Rendering: Partial Views and ViewComponents in ASP.NET Core.

Introduction

In Optimizely CMS 12, blocks represent the atomic, reusable building blocks of a digital experience. Unlike pages, which correspond to a specific URL and location in the site hierarchy, blocks are designed to be embedded within other content types. This modularity allows developers to create a library of consistent UI components—such as hero banners, sliders, or call-to-action sections—that editors can use to assemble complex layouts dynamically.

This module explores the technical architecture of blocks, the distinction between shared and local instances, and the modern rendering patterns available in ASP.NET Core.

Defining Block Types

A block type is defined as a .NET class inheriting from EPiServer.Core.BlockData. Just like page types, these are decorated with the [ContentType] attribute to define identity and metadata.

Standard Block Definition

using EPiServer.Core;
using EPiServer.DataAnnotations;
using System.ComponentModel.DataAnnotations;

namespace MyProject.Models.Blocks
{
    [ContentType(
        DisplayName = "Hero Banner Block",
        GUID = "f7a123bc-5567-4567-8901-abcdef123456",
        Description = "A modular banner component with text and image properties.",
        GroupName = "Standard Components")]
    public class HeroBannerBlock : BlockData
    {
        [CultureSpecific]
        [Display(Name = "Heading", Order = 10)]
        public virtual string Heading { get; set; }

        [CultureSpecific]
        [Display(Name = "Lead Text", Order = 20)]
        [UIHint(UIHint.Textarea)]
        public virtual string LeadText { get; set; }

        [UIHint(UIHint.Image)]
        [Display(Name = "Background Image", Order = 30)]
        public virtual ContentReference Background { get; set; }
    }
}
    

Shared Blocks vs. Local (Property) Blocks

Architecturally, blocks can be used in two distinct ways:

1. Shared Blocks

Shared blocks exist as standalone content items in the Optimizely database. They are located in the Assets pane (under "Global" or "This Site" folders).

Reusability: A single instance of a shared block can be referenced by multiple pages.
Storage: They are IContent items, meaning they have their own lifecycle (Published, Draft, Versioning).
Usage: Typically placed within a ContentArea property.

2. Local Blocks (Blocks as Properties)

Local blocks are "property blocks" where the data belongs strictly to the parent page or block.

Encapsulation: The content is stored as part of the parent's data and does not appear in the Assets pane.
Storage: They are serialized into the parent content instance and do not have an independent content lifecycle.
Usage: Defined as a direct property on a page or block model.

[Display(Name = "Contextual Call to Action")]
public virtual CallToActionBlock InlineCta { get; set; }
    

Content Areas and AllowedTypes

The ContentArea is the primary property type for creating dynamic layouts. It allows editors to drag and drop multiple shared blocks into a specific region. To maintain design integrity, developers should use the [AllowedTypes] attribute to restrict what can be placed in a specific area.

using MyProject.Models.Blocks;

[Display(Name = "Main Components", Order = 100)]
[AllowedTypes(typeof(HeroBannerBlock), typeof(TeaserBlock))]
public virtual ContentArea MainContentArea { get; set; }
    

Rendering Patterns in CMS 12

Optimizely CMS 12 utilizes the ASP.NET Core rendering engine. Blocks are rendered either via Partial Views or ViewComponents.

1. Partial Views (Fast Rendering)

Partial views are the most efficient method for blocks that require no substantial server-side logic beyond property access.

Naming Convention: Create a view with the same name as the block class.
Location: /Views/Shared/Blocks/HeroBannerBlock.cshtml.

@model MyProject.Models.Blocks.HeroBannerBlock

<section class="hero-banner">
    <h1>@Model.Heading</h1>
    <p>@Model.LeadText</p>
</section>
    

2. ViewComponents (Logic-Driven Rendering)

If a block requires data from an external API, custom business logic, or complex processing before rendering, a ViewComponent is the correct approach.

The Component Class:

using Microsoft.AspNetCore.Mvc;
using EPiServer.Web.Mvc;
using MyProject.Models.Blocks;

namespace MyProject.Components
{
    public class HeroBannerBlockViewComponent : BlockComponent<HeroBannerBlock>
    {
        protected override IViewComponentResult InvokeComponent(HeroBannerBlock currentContent)
        {
            // Logic: e.g., perform a lookup or transform data
            var viewModel = new HeroViewModel(currentContent);
            return View(viewModel);
        }
    }
}
    

Preview and Templates

By default, blocks are not standalone pages and do not have an independent URL. To allow editors to see what a block looks like during On-Page Editing (OPE), developers must implement a Preview Controller. This controller renders the block within a "preview page" context.

The TemplateResolver logic determines the correct template to use based on tags, display channels, and the TemplateDescriptor attribute.

Best Practices

Assign GUIDs: Always include a unique GUID in the class attribute to prevent data loss during refactoring.
Leverage Interfaces: If multiple blocks share common properties (e.g., SEO or Analytics), use shared interfaces or abstract base classes.
Optimize Property Access: Ensure all properties are marked as virtual to enable the CMS proxying system.
Use GroupNames: Categorize block types in the "New Block" dialog to help editors find components easily.
Limit Shared Blocks: Use shared blocks only when the content actually needs to be reused across pages. For content unique to a single page, use property blocks to minimize database bloat.

Conclusion

Blocks are the fundamental building blocks of a component-driven architecture in Optimizely CMS 12. By mastering the distinction between shared and property blocks and selecting the appropriate rendering pattern (Partial View vs. ViewComponent), developers can provide a flexible, performant, and editor-friendly content management experience.