Block types and templates

This section contains information about a central concept of an EPiServer CMS project, namely that of blocks, block types and block templates.

This is how it works:

• A block type defines a set of properties.
• A block is an instance of the .NET class that defined the block type.
• At runtime a block can exist either as a property on a page or as a global block.
• When creating a global block or editing a page that contains a block the editor assigns values to the properties defined by the block type.
• When a page that contains a block is requested by a visitor, the renderer (can be a user control or a web control) associated with the block type is used to generate output.

Block type

During initialization EPiServer CMS will scan all binaries in the bin folder for .NET classes that inherits BlockData as example below. For each of the found classes a block type is created and for all public properties on the .NET class a corresponding property on the block type will be created.

[ContentType]
public class PageList : BlockData
{
    public virtual PageReference Root { get; set; }
    public virtual int Count { get; set; }
    public virtual string Heading { get; set; }
}

Blocks can be reused on several pages as in the following example where PageList is a defined block.

[ContentType]
public class NewsPage : PageData
{
    public virtual PageList Archive { get; set; }
}

[ContentType]
public class EventPage : PageData
{
    public virtual PageList Archive { get; set; }
}

Block template

A block template is used to generate output for blocks of a given type, often as an .ascx type of file or a web control. A block template can be used for more than one block type but a one-to-one connection is the most common approach. Below is an example of a template for a block.

[TemplateDescriptor(Name = "My block control", Description = "My first block control", Path = "~/templates/MyBlockControl.ascx", Default = true)]
public partial class MyBlockControl : BlockControlBase<PageList>
{
    protected TextBox HeadingControl;
    protected override void OnLoad(System.EventArgs e)
    {
        base.OnLoad(e);
        HeadingControl.Text = CurrentBlock.Heading;
    }
}

A central function of any block template is to access the property values of the block so that they can be integrated into the output, so how do you accomplish that? This is where the base classes and User Controls come into play. In the following you will find an example based on a web form block template.

Within the EPiServer CMS API there are some base classes that your web control can inherit from, but BlockControlBase<T> is the most common selection for usercontrols and implementing IBlockControl<T> is the common approach for web controls.

Access to the CurrentBlock property is probably the most important benefit you get from inheriting from BlockControlBase<T> (or IBlockControl<T> for web controls). You will find yourself accessing this property many times when you are writing User Controls for an EPiServer CMS project. So what is it? The type of the CurrentBlock property is an instance of your .NET class that inherits EPiServer.Core.BlockData. A BlockData object is the programmatic representation of a block in EPiServer, it contains the properties defined in your .NET class. The value of CurrentBlock is automatically set to the BlockData object that is requested by the client. This means that you don't have to find out what page you should be fetching property values from yourself, all you need to do is consume the property values from the CurrentBlock object.

Shared blocks

A block is a .NET type inheriting EPiServer.Core.BlockData. A block instance can either be part of a page instance (in case a PageType or BlockType contains a property of the block type) or it can be a shared instance. A block that is part of a page instance is stored, versioned, loaded etc, as part of the page. A shared block on the other hand is stored, versioned, loaded individually as an own entity. A shared block can be referenced from several pages or blocks.

Shared blocks structure

Shared blocks are structured with use of folders. A folder in the shared blocks structure can have other folders or Shared Blocks as children. A Shared Block can not have any children. The editorial access is set on the folders to specify which folders that should be available for the editor. There is a global folder root given by EPiServer.Core.SiteSettings.Current.GlobalBlocksRoot that is the root folder for Shared Blocks that should be available for all sites in an enterprise scenario. There might also exist a site specific folder EPiServer.Core.SiteSettings.Current.SiteBlocksRoot that contains the folder structure for shared blocks that are site specific. In a single site scenario typically the GlobalBlocksRoot and SiteBlocksRoot points to the same folder.

A Folder is an instance of EPiServer.Core.ContentFolder and is used to structure content. A content folder does not have any WebForm or MVC controller associated and hence it does not have any visual appearance on the site.

See also

• Creating page templates and block controls