- Writing custom properties: #1 Custom value type
- Writing custom properties: #2 Default value
- Writing custom properties: #3 Edit control
Features
Created control will have:
- Text input for Guid
- Button for creating new Guid
Controls render types
EPiServer properties can be rendered in one of the following modes (defined by EPiServer.Core.RenderType):
- Default – when viewing property in View Mode. It’s used e.g. when you display property using
- Edit – when editing page in Edit Mode or in Quick Edit Mode. In this mode CreateEditControls method is invoked.
- OnPageEdit – if PropertyDataControl.SupportsOnPageEdit returns true and <episerver:property PropertyName=”..”/> is used property is rendered in this mode. Otherwise uses default view. These mode will be covered in more details soon.
Basic server control implementation
All controls for editing custom properties in EPiServer must inherit from PropertyDataControl or derived class.
In simplest scenario when supporting only edit mode functionally CreateEditControls must create controls which are used in edit mode. Edited values should be saved in ApplyEditChanges method.
Additionaly SetupEditControls updates visual representation value based on data from PropertyData
public class GuidPropertyControl : PropertyDataControl
{
protected TextBox EditBox { get; set; }
public GuidProperty GuidProperty
{
get { return (GuidProperty)this.PropertyData; }
}
public override void CreateEditControls()
{
//create text box
this.EditBox = new TextBox { MaxLength = 0xff };
this.ApplyControlAttributes(this.EditBox);
this.Controls.Add(this.EditBox);
//button for generating new guid
//consider using LanguageManager for texts
var button = new Button { Text = "New" };
this.ApplyControlAttributes(button);
button.Click +=
(sender, e) => { this.EditBox.Text = FormatGuid(Guid.NewGuid()); };
this.Controls.Add(button);
this.SetupEditControls();
}
private static string FormatGuid(Guid guid)
{
return guid.ToString();
}
//Saves value in underlying PropertyData
public override void ApplyEditChanges()
{
Guid value;
if (string.IsNullOrEmpty(this.EditBox.Text))
{
value = Guid.Empty;
}
else
{
try
{
value = new Guid(this.EditBox.Text);
}
catch (FormatException e)
{
this.AddErrorValidator(e.Message);
return;
}
}
this.SetValue(value);
}
protected override void SetupEditControls()
{
this.EditBox.Text = FormatGuid(this.GuidProperty.Guid);
} //representation in View Mode
public override void CreateDefaultControls()
{
Label target = new Label();
target.Text = FormatGuid(GuidProperty.Guid);
this.CopyWebAttributes(target);
this.Controls.Add(target);
}
}Post back support
If you would try to click “New button” in edit mode you would notice strange behavior: Message box warning about leaving page and loosing unsaved value.
The reason for this is that Javascipt OnBeforeUnload event is raised and EPiServer warns you that pages is going to be left with possible data loss.
There are two solutions for this:
- Use ToolButton from EPiServer namespace instead of regular ASP Button and set DisablePageLeaveCheck to true
public override void CreateEditControls()
{
//same code creating TextBox
var button = new ToolButton
{
Text = "New",
DisablePageLeaveCheck = true
};
//same code using button
SetupEditControls()
}- Use ScriptDisablePageLeaveEvent to disable checking specific event raised from our control. This approach is more flexible because not only button is supported and it’s possible to specify which event should suppress checking.
public override void CreateEditControls()
{
//same code creating TextBox
//same code creating Button
ScriptDisablePageLeaveEvent scriptDisablePageLeaveEvent =
new ScriptDisablePageLeaveEvent
{
EventTarget = button,
EventType = EventType.Click
};
this.Controls.Add(scriptDisablePageLeaveEvent);
SetupEditControls()
}Page leave check considerations
You may wonder how it happed that without writing any code EPiServer can discover that value of Guid property has changed and warn about it. In fact EPiServer PageLeaveCheck attach to each html’s input event onchange and whenever this event is raise IsPageChanged is set to true. No magic!
This approach is working really well in most scenarios, since it’s common to store value in text boxes (sometimes in read-only mode like for Page Reference property). However, if you go into scenario where values are stored only in hidden field and displayed to user directly (without textbox) you will notice that Page Leave Check does not work anymore.
In that case you may manually mark page as changed using following Javascript
savePropetyValue: function (value) {
//change hidden field value
$("#hidden_field").val("...") ;
//mark page as changed
if (EPi.PageLeaveCheck.enabled) {
EPi.PageLeaveCheck.SetPageChanged(true);
}
};Please be patient: more advanced Javascript usage in custom controls will be covered in future posts. It will include using JQuery, packaging javacripts, AJAX support, etc.
