Create components for Sitecore Page Editor

This quick tutorial will guide you trough your first Sitecore Page Editable Component.

The Sitecore Page Editor is build around the concept of components. A component is a reusable piece of data that is parred with a sublayout and placed in a placeholder.

Sitecore Page Editor’

This tutorial will create a very simple component: Adding an Image.

To create components you must go through a series of steps.

STEP 1: CREATE THE TEMPLATE

First you need a Sitecore Template where you store the data. My component must show an image, so all my template contains is an image field called “DocumentImage”:

Document Image Template

STEP 2: FIND A HOME FOR TEMPLATES OF THIS TYPE

Next step is to define a place in your web site structure where you will store templates of this type. Templates of different types can share a folder, or you can create a folder specifically for this type.

You will need the folder in a few steps.

STEP 3: CREATE A SUBLAYOUT

Now you need a sublayout that will present the data from the template.

Document Image Sublayout

When creating the sublayout you must determine the contents of these fields:

• Editable: Check this box. If unchecked, the sublayout is not editable and cannot be used in the Page Edittor as a component.
• Datasource location: Select the folder you chose in STEP 2. When the component is added to a page, this is where the data will be stored.
• Datasource template: Select the template you created in STEP 1. When the component is added to a page, this is the template that is created.

STEP 4: ASSIGN THE SUBLAYOUT TO A PACEHOLDER SETTING

Each placeholder that is capable of having controls added must be defined in the folder /sitecore/layout/Placeholder Settings.

Select the placeholder setting where you would like to allow your control to be added and add it to the “Allowed controls” field:

Placeholder setting

Read more about placeholder settings here.

STEP 5: CODE THE CONTENTS OF THE SUBLAYOUT

When a component is added to a page it is parred to a item through the “datasource” parameter on the layout. This means that you cannot get the data for your component with Sitecore.Context.Item. Sitecore.Content.Item will point to the actual page where the component is added, not the item assigned to the component.

The following method will get the item from the “datasource”, with a fallback to the current item. The fallback is a safety mechanism that ensures that the item returned is never null, as this will crash the entire web page.

protected Item CurrentContextItem
{
  get
  {
    Sublayout thisSublayout = (Parent as Sublayout);
    if (thisSublayout == null)
      return Sitecore.Context.Item;
    if (string.IsNullOrEmpty(thisSublayout.DataSource))
      return Sitecore.Context.Item;
    string dataSource = thisSublayout.DataSource;
    Item dataSourceItem = Sitecore.Context.Database.GetItem(dataSource) ??
                          Sitecore.Context.ContentDatabase.GetItem(dataSource);
    if (dataSourceItem == null)
      return Sitecore.Context.Item;
    return dataSourceItem;
  }
}

(This method of getting the datasource has not changed the last 5 years).

You now assign the Item parameter of the sc:Image webcontrol to CurrentContextItem, and the control will take its data from that item:

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="DocumentImage.ascx.cs" Inherits="PT.Document.DocumentImage" %>
<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>

<div class="Image">
  <sc:Image field="DocumentImage" id="Image" runat="server" Item="<%# CurrentContextItem %>" MaxHeight="200" />
</div>

If your component uses an EditFrame you need to get the actual value from the datasource, not the item it points to. In this case you need another method:

protected string DataSourceValue()
{
  Sublayout sublayout = (Parent as Sublayout);
  return (((sublayout == null) || string.IsNullOrEmpty(sublayout.DataSource)) ? string.Empty : sublayout.DataSource);
}

You can now use this method to ensure your EditFrame uses the correct item:

<sc:EditFrame runat="server" ID="editFrame" Buttons="???" DataSource="<%# DataSourceValue %>">
  ...
  ...
</sc:EditFrame>

That’s all there is to it. Happy coding.

More reading:

• Sitecore Recommended Practices – part 6 (Presentation,Page Editor, and Solution Code) by Dan Brown.
• Presentation component reference (PDF Document by Sitecore)