How to create custom properties in EPiServer CMS 5
|Number of votes:||3|
This article describes how to create custom properties in EPiServer CMS 5. The article is based on the EPiServer CMS SDK documentation, EPiServer CMS knowledge base, EPiServer CMS 5 source code and forum postings.
What is a property?
A single page in EPiServer CMS 5 contains properties. A property is a part of the page which contains data of specific types. There are several predefined properties in the EPiServer CMS 5 core, for example PropertyString, PropertyDate, and PropertyNumber. It is also possible to create your own properties.
Customized properties can be implemented in two ways:
- Use an existing property as a base and change its behavior
- Create a custom property from scratch
The first approach is easier and only requires that you change parts of the base property logic. Here we will focus on the second approach and discuss how to create a property from the beginning.
Representation modes of properties
A property has three representation modes:
- Default (view)
- On Page Edit
Default mode is a common mode used when the page is being viewed in a browser.
Edit mode is used when a page is being edited in Edit mode.
On Page Edit mode is used when the page is being edited directly from the View mode.
A property can be edited either in Edit or in On Page Edit mode. So to allow a property to be edited, we should implement methods which will create the corresponding controls for edit mode. For example, for a PropertyString control text box, a control will be created in order to give the user possibility to edit the string. We will discuss this in the following.
Custom property definition
A property is represented by two classes:
- A class for storing the data of the property
- A class for representing the property on the page
The class for storing property data is derived from the PropertyData class. It is defined as follows:
MyCustomProperty overrides some of the base class methods and properties to customize the page property behavior. PageDefinitionTypePlugInAttribute marks the class as a property, and allows the property to be automatically registered by EPiServer CMS (you will see your property in the list of properties when adding the property to a page type).
The class for representing a property on the page is derived from the PropertyDataControl class. It is defined as follows:
To create a new custom property class, you can use the Visual Studio template for Custom property. What you will do is to add a new class item to the project. Please refer to SDK documentation for details: http://sdk.episerver.com/library/cms5/Developers Guide/How To/Create a Custom Property.htm
Below is an example of a custom property with string type data. To read and write string type values, instead of object a string property is defined. The CreatePropertyControl method returns an instance of rendering control of MyCustomPropertyControl type.
The PropertyDataControl base class provides default implementation of the CreateDefaultControls and CreateOnPageEditControls methods, which are responsible for the rendering in view and edit on page modes respectively. This default implementation allows for displaying and editing string values. We will rely on the base methods because our property’s data type is string. In the property control class implementation, these methods are commented and provided for reference. If you want to change how the property is displayed and edited, uncomment these methods and provide your own implementation.
Adding the property to the page type
In order to display the property on the page, we need to perform two steps:
- Add the property to the page type for the page in Admin mode.
- Add the property to the .aspx file for this page type.
To perform the first step, log in to the EPiServer CMS in Admin mode. Go to “Page Type” tab. From the Page Types list, click the one you want to edit. Click the “Add Property” button to create a new property.
The “Create New Property” form will be displayed. Enter the name of the property (you will specify this name when you will add the property to the page type file). For property Type, choose MyCustomProperty from the list of available types. If MyCustomProperty type is not in the list, then you probably forgot to apply the attribute to the property class. Specify the other values and click the “Save” button.
Adding the property to the page type file
In order to see a new property on the page, we need to add the property to the page type file. Find the .aspx file of the page type and open it in Visual Studio (to determine the file for the page type, go to the settings of the page type and check the File field). Switch to HTML view and add the next string at the place where you want your property to be shown:
<EPiServer:Property PropertyName="MyCustomProperty" runat="server" EnableViewState="false" />
Checking the result of your work
To check the result of your work, create a new page using the page type where the property was added. In the Edit mode, go to Edit tab. You should see the property title and text box (the type of control depends of the CreateEditControls method of MyCustomPropertyControl) as follows:
Enter a value into the text box and click the “Save and Publish” button. You will be returned to the View tab and you will see your page with the text you entered, similar to this:
Now we will check the editing of the page in View mode. Select your page in the tree structure, and switch to the View mode. Open the context menu with a right click and select Edit. The property’s text will be displayed in the editable box (again, depends of the control you created in the CreateOnPageEditControls method of MyCustomPropertyControl).
Right-click, select Save and enjoy the result!