EPiServer property settings in the Help text field

August 24, 2009

In one of my previous posts I listed a number of suggested improvements to the EPiServer property system. My number 1 wish (Just after wish 0) was that there would be a settings property on page definitions. While being nothing like a native solution with a dedicated interface would be, I thought I would show you a simple way to use the help text field to store settings for your EPiServer page properties. I’ve seen this approach being mentioned before around the web but I never got around to use it myself as I always found it somewhat tedious to manage these settings in the admin mode. Since starting to use the PageTypeBuilder by Joel Abrahamsson this has somewhat changed and now there is a possibility to define help texts through attributes in your code, making them much easier to manage.

Therefore I thought that I would share with you how I have implemented EPiServer property settings through the help text field.

Rationale

Being able to store settings for a page property enables a whole range of new possibilities. Property input can be limited to certain size, ranges or patterns without writing one custom property for each item. Custom length strings, email address input, integers within a given range or categories from a sub level are just examples of every day (site) properties.
Property settings could also serve as an input on how a property should be rendered in view mode although I personally recommend to separate the presentation logic from the property control as much as possible.

Settings format

I chose to save my page definition settings in an name-value collection format where I separate name and value with : (colon) and each pair with | (pipe). I feel that using the same format even if you just want a single settings value is good for consistency.

Property settings resolver

I have moved the code for retrieving the settings for a property to a class that I called PropertySettingsResolver. It only has a single method that returns a dictionary with the setting values.

public IDictionary<string, string> GetSettings(PropertyData property)
{
  PageDefinition definition = PageDefinition.Load(property.PageDefinitionID);
  Dictionary<string, string> settings =
    new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
  var segments = definition.HelpText.Split(
    new char[] { '|' }, StringSplitOptions.RemoveEmptyEntries);
  foreach (string segment in segments)
  {
    string[] keyValuePair = segment.Split(':');
    if (keyValuePair.Length == 2)
    {
      settings.Add(keyValuePair[0], keyValuePair[1]);
    }
  }
  return settings;
}

Retrieving values

I would recommend storing the dictionary locally to avoid re-parsing of values and using the TryGetValue of the IDictionary to retrieve the settings value.
Also I personally like to keep my PropertyData minimal, so I would normally place this code in the property control and not in the property itself. Example code below is cut from a category type property that lists all categories below a root category that is passed in as a property setting.

private IDictionary<string, string> _propertySettings;
protected virtual IDictionary<string, string> PropertySettings
{
  get
  {
    return _propertySettings ??
      (_propertySettings = PropertySettingsResolver.Instance.GetSettings(this.PropertyData));
  }
}

protected override void SetupEditControls()
{
  // Code removed for brevity...
  string rootCategoryName;
  Category rootCategory = null;
  if (this.PropertySettings.TryGetValue("Root", out rootCategoryName))
  {
    rootCategory = Category.Find(rootCategoryName);
  }
  // Code removed for brevity...
}

What about the help texts?

Since help texts can be defined using EPiServers language files, you can still have help texts for your properties by adding some elements to your language file(s):

<pagetypes>
  <common>
    <property name="MyProperty">
      <help>This will display as the help text for properties
            with name MyProperty on all page types.</help>
    </property>
  </common>
  <pagetype name="My Page Type">
    <property name="MyProperty">
      <help>This will display as the help text for properties
            with name MyProperty on pages of type 'My Page Type'.</help>
    </property>
  </pagetype>
</pagetypes>

Also since we are not storing help texts in the help text field anymore I though it would be appropriate to change the label for the admin field as well. Either change the field in each of the EPiServer language[XX].xml or add a new file to the language folder with a name that ensures that it gets loaded after the standard files. I would recommend the latter since this will ensure that your language file isn’t overwritten during an upgrade.

<admin>
  <editpagetypefield>
    <helpcaption>Settings</helpcaption>
  </editpagetypefield>
</admin>

PageTypeBuilder configuration

I thought I would also show how you would specify your settings if you are using PageTypeBuilder. Below is an example of an Integer property that has a maximum and a minimum value for the input.

[PageTypeProperty(Type = typeof(PropertyInteger),
    EditCaption = "Integer between 0 and 10",
    HelpText = "MinValue:0|MaxValue:10",
    Tab = typeof(Tabs.InformationTab))]
public virtual int MyIntegerProperty
{
  get { return this.GetPropertyValue(p => p.MyIntegerProperty); }
  set { this.SetPropertyValue(p => p.MyIntegerProperty, value); }
}

Finally

If you want to take this even further you could replace the page property editing page, EditPageTypeField.aspx, with a file that lets you replace the HelpText/Settings field with an individual settings control for each property type. However replacing standard EPiServer files is nothing that I’m specifically fond of for maintenance and upgrading reasons. I’ll leave this for EPiServer to implement themselves.

Advertisements

4 Responses to “EPiServer property settings in the Help text field”

  1. EPiDave Says:

    Nice solution. I mentioned this issue in my latest blog post. We must have been blogging at the same time. :)

  2. EPiDave Says:

    Sorry, forgot the link: http://bit.ly/LnD44

  3. hn Says:

    Yeah, property settings can be used for so many use cases it need to be included in the future. I think I would prefer your solution if I didn’t use the PageTypeBuilder.

    Oh, and that’s a nice and clean property, have done a few Key/Value properties during my EPiServer days :)

  4. Emil Says:

    Really nice post with a simple and clean solution. Thank you very much for sharing.


Comments are closed.

%d bloggers like this: