How to create a simple Block Type in EPiServer CMS 7

In EPiServer 7 you can defined block types in code. In this blog post we cover how to create your first block type in this way.

Updated to EPiServer 7 CMS on 15.01.2013

This blog post was originally written for a preview version of EPiServer 7 CMS, but is now updated to the final release version.

What is a block type?

Just like we have page types and pages we have block types and blocks. But what are blocks, and what are they used for? Here is where it gets a little confusing, but hang in there.

Group of properties

Think of blocks as a group of properties. E.g. you have an image url and an image description. With blocks you can add an image url property and an image description property to a new block type and call it image.

Group the image property and image description property together in a block type image.

You can now add this new block just like any other type of property to a page type. You can even add it multiple times to the same page type (think Image1, Image2 etc.) and multiple page types (think ArticleImage on the article page type and  NewsImage on the news page type).

Just like page types has a page type template (.aspx), block types has a block type template user control (.ascx) that renders the properties the way you want.

Shared blocks

And now to the confusing part: all blocks are also “shared blocks”. So you can create a new block (just like you create a new page) of the block type and add it to a content area on a page (note: page, not page type). This is similar to EPiServer Composer blocks. Also once you create a block (note: block, not block type) you can reuse it on other pages. This is similar to EPiServer global blocks. (Note: You can prevent a block from being used as a “shared block” by setting the AvailableInEditMode attribute to false)

The shared blocks widget shows up in the right hand side bar. Here you can create new blocks just like you can create new pages.

The blocks you create can be dragged into content areas on pages.

Lets create a simple block type

A block type in EPiServer 7 consists of two parts:

1. A block type class (.cs) that defines what properties the block should contain

2. A block template (.ascx) that renders the block and those properties.

Creating a block type class

Here is a simple block type class that defines our block type MyBlock. (Bonus sound track: On My Block – Scarface)

MyBlock.cs

using System.ComponentModel.DataAnnotations;

using EPiServer.Core;

using EPiServer.DataAbstraction;

using EPiServer.DataAnnotations;

using EPiServer.Web;

namespace EPiServer.Templates.Alloy.Models.Blocks

{

    [ContentType(DisplayName = "MyBlock", Description = "")]

    public class MyBlock : BlockData

    {

       [UIHint(UIHint.Image)]

       [Display(

           Name = "Image Url",

           Description = "",

           GroupName = SystemTabNames.Content,

           Order = 1)]

       public virtual Url ImageUrl { get; set; }

       [Display(

           Name = "Image Description",

           Description = "",

           GroupName = SystemTabNames.Content,

           Order = 2)]

       public virtual string ImageDescription { get; set; }

    }

}

MyBlock has two properties: Image url that contains the URL to the image we want to show and image description that describes the image. (Here is a quick reference on how to define the other property types in EPiServer 7, like XhtmlString, LinkCollection and Number)

Creating a block template

To display our new block type we create a user control.

MyBlockTemplate.ascx

<%@ Control Language="C#" AutoEventWireup="true" 

    CodeBehind="MyBlockTemplate.ascx.cs" 

    Inherits="EPiServer.Templates.Alloy.Views.Blocks.MyBlockTemplate" %>

<EPiServer:Property PropertyName="ImageUrl" runat="server" /><br/>

<EPiServer:Property PropertyName="ImageDescription" runat="server" />

In the code behind for the .ascx file we set the connection between the block type class and the block template by setting BlockControlBase<MyBlock> (where MyBlock is our block type class.)

MyBlockTemplate.ascx.cs

using System;

using EPiServer.Templates.Alloy.Models.Blocks;

using EPiServer.Web;

namespace EPiServer.Templates.Alloy.Views.Blocks

{

    public partial class MyBlockTemplate : BlockControlBase<MyBlock>

    {

        protected void Page_Load(object sender, EventArgs e)

        {

        }

    }

}

Using our new block type as a “shared block”

After building the project and starting our EPiServer 7 site we can use the new block type as a “shared block”. You can view the new block type in admin mode (under the “Block Type” tab).

You can now create and publish a new “shared block” of the type MyBlock in edit mode. (Click the + button on the top bar and choose “New Block”)

Add the block you just created to the content area of a page. (You can try a “Standard Page” in the Alloy demo. Drag your block from the “Shared Block” widget into the content area.)

You can use the block you created on multiple pages, and if you change and publish the block, all the pages will show the updated block. Neat!

Using our new block type as a property on a page type

The great thing about block types are that we can add them as properties to page type just like the built in properties. Lets modify the MyPage page type we created in the blog post “How to create a simple Page Type in code for EPiServer CMS 7” to contain a MyBlock.

Add a MyBlock property named Image to the MyPage page type class:

MyPage.cs

using System.ComponentModel.DataAnnotations;

using EPiServer.Core;

using EPiServer.DataAbstraction;

using EPiServer.DataAnnotations;

using EPiServer.Templates.Alloy.Models.Blocks;

namespace EPiServer.Templates.Alloy.Models.Pages

{

    [ContentType(DisplayName = "MyPage")]

    public class MyPage : PageData

    {

        [Display(

            Name = "My name",

            Description = "",

            GroupName = SystemTabNames.Content,

            Order = 1)]

        public virtual string MyName { get; set; }

        [Display(

            Name = "Image",

            Description = "",

            GroupName = SystemTabNames.Content,

            Order = 2)]

        public virtual MyBlock Image { get; set; }

    }

}

Add a EPiServer:Property to the page type template. This will render our block type template user control.

MyPageTemplate.aspx

<%@ Page Language="c#" 

    Inherits="EPiServer.Templates.Alloy.Views.Pages.MyPageTemplate" 

    CodeBehind="MyPageTemplate.aspx.cs" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head id="Head1" runat="server">

<title>My Page Template</title>

</head>

<body style="background-color: white;">

<form id="Form1" runat="server">

<div>

<h1>MyPage Template</h1>    

My name is

<EPiServer:Property runat="server" PropertyName="MyName" />

<br/><br/>

<EPiServer:Property runat="server" PropertyName="Image" />

</div>

</form>

</body>

</html>

After building the project and starting our EPiServer 7 site we can see the new MyBlock property on the MyPage type in admin mode.

When creating a new MyPage page we can edit our MyBlock properties.

If we click inside the green box the editor will open our MyBlock properties.

After we publish the page this is what the visitors will see:

That was how to create your first block type in EPiServer 7 from code.