Block types and templates

Terminology:

• A block is an instance of the .NET class that defined the block type and can exist at runtime as either a property on a page or as a global block.
• A block type defines a set of properties.
• When you create a global block, or edit 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 system uses the renderer (a user control or a web control) associated with the block type to generate output.

Block type

During initialization, EPiServer CMS scans binaries in the bin folder for .NET classes that inherits BlockData as show in the following example. For each of the classes found, the system creates a block type and creates a corresponding property on the block type for public properties on the .NET class.

[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

The system uses a block template to generate output for blocks of a given type, often as an .ascx type of file or a web control. You can use a block template for more than one block type but a one-to-one connection is typical. The following example shows 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 block template accesses the property values of the block to integrate the values into the output by using base classes and User Controls within the EPiServer CMS API; base classes from which your web control can inherit; BlockControlBase<T> is the most common selection for usercontrols and implementing IBlockControl<T> is the common approach for web controls.

When you write User Controls for an EPiServer CMS project, you get access to the CurrentBlock property by inheriting from BlockControlBase<T> (or IBlockControl<T> for web controls). 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 that contains the properties defined in your .NET class. The value of CurrentBlock is automatically set to the BlockData object that is requested by the clients so you do not have to find out from which page you should be fetching property values; you only need to consume the property values from the CurrentBlock object.

Shared blocks

A block is a .NET type inheriting EPiServer.Core.BlockData. A block instance is either part of a page instance (if a PageType or BlockType contains a property of the block type) or it is a shared instance.

• A page instance with a block is stored, loaded, versions (and so on), as part of the page.
• A shared block is stored, loaded, versioned, (and so on) individually as an own entity. You can reference a shared block from several pages or blocks.

Shared blocks structure

Shared blocks are structured by using folders. A folder in the shared blocks structure can have other folders or Shared Blocks as children. A Shared Block cannot have any children. You set editorial access on folders to specify which folders that are available for an editor. The global folder root EPiServer.Core.SiteSettings.Current.GlobalBlocksRoot is the root folder for Shared Blocks that are available for sites in an enterprise scenario. There can be a site-specific folder EPiServer.Core.SiteSettings.Current.SiteBlocksRoot that contains the folder structure for shared blocks. In a single site scenario, GlobalBlocksRoot and SiteBlocksRoot typically point to the same folder.

A Folder is an instance of EPiServer.Core.ContentFolder and it structures content. A content folder does not have an associated  WebForm or MVC controller and therefore does not have a visual appearance on the site.

Related topic

• Creating page templates and block controls