Try our conversational search powered by Generative AI!
AI OnAI Off
| Views: | 24914 |
| Number of votes: | 2 |
| Average rating: |
How to create custom properties in EPiServer CMS 5
Feb 22, 2008
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)
- Edit
- 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:
[Serializable]
[PageDefinitionTypePlugIn]
public class MyCustomProperty : EPiServer.Core.PropertyData
{}
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:
public class MyCustomPropertyControl : EPiServer.Web.PropertyControls.PropertyDataControl
{}
MyCustomProperty class
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.
/// <summary>
/// MyCustomProperty implementation. Add this property to one of templates in Edit mode.
/// Also to display property on a page add the control to the aspx file of the template as follow:
/// <EPiServer:Property PropertyName="MyCustomProperty" runat="server" EnableViewState="false" />
/// </summary>
[Serializable]
[PageDefinitionTypePlugIn]
public class MyCustomProperty : EPiServer.Core.PropertyData
{
string _string;
/// <summary>
/// Inherited. Gets the Type of the property value.
/// </summary>
public override Type PropertyValueType
{
get
{
return this.GetType();
}
}
/// <summary>
/// Inherited. Gets the property type as defined by enum PropertyDataType.
/// </summary>
public override EPiServer.Core.PropertyDataType Type
{
get
{
return PropertyDataType.String;
}
}
/// <summary>
/// Inherited. Gets or sets the value of the String property.
/// </summary>
public override object Value
{
get
{
if (this.IsNull)
{
return null;
}
return this.String;
}
set
{
base.ThrowIfReadOnly();
base.SetPropertyValue(value,
delegate
{
this.String = value.ToString();
});
}
}
/// <summary>
/// Gets or sets the string value of this property.
/// </summary>
[System.Xml.Serialization.XmlIgnore]
protected virtual string String
{
get
{
return this._string;
}
set
{
base.ThrowIfReadOnly();
if (PropertyData.QualifyAsNullString(value))
{
base.Clear();
}
else if ((this._string != value) || this.IsNull)
{
this._string = value;
base.Modified();
}
}
}
/// <summary>
/// Inherited. Read property data from a string representation, ie reversed ToString().
/// </summary>
/// <param name="str"></param>
/// <returns></returns>
public override EPiServer.Core.PropertyData ParseToObject(string str)
{
MyCustomProperty prop = new MyCustomProperty();
prop.String = str;
return prop;
}
/// <summary>
/// Inherited. Read property data from string representation and set value of the invoking object based on this value.
/// </summary>
/// <param name="str"></param>
public override void ParseToSelf(string str)
{
String = str;
}
/// <summary>
/// Inherited. Set default value for this property.
/// </summary>
protected override void SetDefaultValue()
{
this.String = "default value";
}
/// <summary>
/// Inherited. Creates an IPropertyControl that is used to display a user interface for the property.
/// </summary>
/// <returns></returns>
public override EPiServer.Core.IPropertyControl CreatePropertyControl()
{
//Create an instance of MyCustomPropertyControl which is used for displaying the property.
return new MyCustomPropertyControl();
}
}
MyCustomPropertyControl class
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.
/// <summary>
/// MyCustomPropertyControl implementation. Used for rendering MyCustomProperty property.
/// </summary>
public class MyCustomPropertyControl : EPiServer.Web.PropertyControls.PropertyDataControl
{
TextBox tb;
/// <summary>
/// Gets the MyCustomProperty instance for this IPropertyControl.
/// </summary>
/// <value>The property that is to be displayed or edited.</value>
public MyCustomProperty MyCustomProperty
{
get
{
return PropertyData as MyCustomProperty;
}
}
/// <summary>
/// Get a value either this property supports On Page Edit mode or not.
/// </summary>
public override bool SupportsOnPageEdit
{
get
{
return true;
}
}
//This method is commented becuase base class PropertyDataControl contains default implementation
//which display strings on a page. Remove the comment if you want to provide your own implementation.
/// <summary>
/// Inherited. Create a controls for rendering the property in view mode.
/// </summary>
//public override void CreateDefaultControls()
//{
// System.Web.UI.WebControls.Label l = new System.Web.UI.WebControls.Label();
// l.Text = this.PropertyData.Value == null ? "[My custom property empty]" : this.PropertyData.Value as string;
// Controls.Add(l);
//}
/// <summary>
/// Inherited. Create a TextBox for rendering the property in edit mode.
/// </summary>
public override void CreateEditControls()
{
tb = new System.Web.UI.WebControls.TextBox();
this.ApplyControlAttributes(this.tb);
Controls.Add(tb);
this.SetupEditControls();
}
//This method is commented becuase base class PropertyDataControl contains default implementation
//which allows to edit strings on a page. Remove the comment if you want to provide your own implementation.
/// <summary>
/// Inherited. Create TextBox control for rendering the property in "On Page Edit" mode.
/// </summary>
//public override void CreateOnPageEditControls()
//{
// this.tb = new System.Web.UI.WebControls.TextBox();
// this.ApplyControlAttributes(this.tb);
// Controls.Add(tb);
// this.SetupEditControls();
//}
/// <summary>
/// Inherited. Initialize the value of the TextBox control.
/// </summary>
protected override void SetupEditControls()
{
this.tb.Text = this.ToString();
}
/// <summary>
/// Inherited. Applies changes for the posted data to the page's properties when the RenderType property
/// is set to Edit.
/// </summary>
public override void ApplyEditChanges()
{
base.SetValue(this.tb.Text);
}
/// <summary>
/// Inherited. Applies changes for the posted data to the page's properties when the RenderType property
/// is set to OnPageEdit.
/// </summary>
//public override void ApplyOnPageEditChanges()
//{
// base.SetValue(this.tb.Text);
//}
}
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!
Comments
Please login to comment.
Thank you, this has helped to get me started with custom properties.