The DotNetNuke Property Editors - Part 1, Introduction

This article is based on material originally published on DNN Developer Zone (www.dnndevzone.com).  This version has been edited slightly.

Introduction

Version 4.3 of the DotNetNuke Web Application Framework introduced a suite of Property Editors. These Property Editors dynamically inject the appropriate Edit Control depending on the Data Type to be edited. There are 5 types of editor and 53 class or enum files that make up the Property Editor suite of controls.

This first article in a series of articles I intend to write on this topic provides an introductory overview to these Property Editors.

The Editors

There are five top-level Editors

• FieldEditorControl - This editor represents a single row in an Editor. It is used to edit a single "property".
   
  While it can be used on its own, it is usually used as a building block in one of the other four editors.
  
• PropertyEditorControl - This editor combines many FieldEditors to form an Editor for an instance of a Class. A Fields collection can be used to define the properties of the class that are part of the editor, or if this Fields collection is not provided then the Property Editor will automaticaly generate the fields it needs from the public properties of the Class.
  
  Attributes can be used to decorate the properties to control the editor . eg.
  • Browsable - is the property included
  • SortOrder - the order of property in the Editor
  • Required - whether the property is required
  • Editor - defines the Assembly Qualified Name of the editor that will be used to edit this property. If this is not defined the Editor determines the control to use based on its System.Type.
    
• CollectionEditorControl - This editor combines many FieldEditors to form an editor for a collection. Rather than attributes controlling the editor, properties of the objects in the collection determine the behavior of the Editor. Thus the CollectionEditorControl has a number of properties that define which object property to use, eg
  • VisibleDataField - the property of the object that determines the objects visibility
  • RequiredDataField - the property of the object that determines if the objects is required
  • EditorDataField - the property of the object that determines the editor to use for the object
  • ValueDataField - the property of the object that holds the objects "value"
    
• ProfileEditorControl - This editor is a customised version of the CollectionEditor, and is used to edit a collection of ProfilePropertyDefinition objects (Profile properties) . Properties of the ProfilePropertyDefinition object determine the behaviour of the editor (and are bound to the various "DataField"s described above).
  
• Settings Editor - This editor combines many FieldEditors to form an editor for a Hashtable of settings.

The PropertyEditorControl

While a lot more attention has been focused on the use of the Profile Editor, this control is much more flexible and can be used by 3rd party developers in their own modules. This control can be used to edit some or all of the properties of an instance of a class.

The beauty of this control is that the code required to set up an "Edit Page" for an object becomes much simpler. This doesn't mean that the editor is less flexible than the traditional way of creating an Edit Page, in fact the new PropertyEditorControl provides a lot more flexibility, as it can take advantage of the full suite of Edit Controls, provided in the DotNetNuke core, as well as custom Edit Controls created by 3rd parties.

Figure 1: Adding a new Profile Property

We will describe how this control can be used by discussing a real example that is found in the DotNetNuke core - the "Edit Profile Definition " page (see Figure 1).  It is important to note here that there are 9 properties managed on this page of three different types - text, combo/list, boolean/checkbox.

The ASCX File

   1:  <%@ Control Inherits="DotNetNuke.Modules.Admin.Users.EditProfileDefinition" 

             CodeFile="EditProfileDefinition.ascx.vb" language="vb" AutoEventWireup="false" 

             Explicit="True" %>

   2:  <%@ Register TagPrefix="dnn" Assembly="DotNetNuke" Namespace="DotNetNuke.UI.WebControls"%>

   3:   

   4:  <dnn:propertyeditorcontrol id="Properties" runat="Server"

   5:      SortMode="SortOrderAttribute"

   6:      labelstyle-cssclass="SubHead" 

   7:      helpstyle-cssclass="Help" 

   8:      editcontrolstyle-cssclass="NormalTextBox" 

   9:      labelwidth="200px" 

  10:      editcontrolwidth="250px" 

  11:      width="450px"/>

  12:  <p>

  13:      <dnn:commandbutton class="CommandButton" id="cmdUpdate" 
               imageUrl="~/images/save.gif" resourcekey="cmdUpdate" 
               runat="server" text="Update"/>&nbsp;

  14:      <dnn:commandbutton class="CommandButton" id="cmdCancel" 
               imageUrl="~/images/lt.gif" resourcekey="cmdCancel" 
               runat="server" text="Cancel" causesvalidation="False" />&nbsp;

  15:      <dnn:commandbutton class="CommandButton" id="cmdDelete" 
               imageUrl="~/images/delete.gif" resourcekey="cmdDelete" 
               runat="server" text="Delete" causesvalidation="False" />

  16:  </p>

   4:  <dnn:propertyeditorcontrol id="Properties" runat="Server"

   5:      SortMode="SortOrderAttribute"

   6:      labelstyle-cssclass="SubHead" 

   7:      helpstyle-cssclass="Help" 

   8:      editcontrolstyle-cssclass="NormalTextBox" 

   9:      labelwidth="200px" 

  10:      editcontrolwidth="250px" 

  11:      width="450px"/>

   1:  Private Sub Page_Load(ByVal sender As System.Object, _

   2:           ByVal e As System.EventArgs) Handles MyBase.Load

   3:      Try

   4:          'Declare Property Definition object

   5:          Dim propertyDefinition As ProfilePropertyDefinition

   6:   

   7:          If PropertyDefinitionId <> Null.NullInteger Then

   8:              'Get Property Definition from Data Store

   9:              propertyDefinition = ProfileController._

  10:              GetPropertyDefinition(PropertyDefinitionId)

  11:          Else

  12:              'Create New Property Definition

  13:              propertyDefinition = New ProfilePropertyDefinition

  14:              propertyDefinition.PortalId = PortalId

  15:          End If

  16:   

  17:          cmdDelete.Visible = True

  18:          ClientAPI.AddButtonConfirm(cmdDelete, _

  19:              Localization.GetString("DeleteItem"))

  20:   

  21:          'Bind Property Definition to Data Store

  22:          Properties.LocalResourceFile = Me.LocalResourceFile

  23:          Properties.DataSource = propertyDefinition

  24:          Properties.DataBind()

  25:   

  26:      Catch exc As Exception    'Module failed to load

  27:          ProcessModuleLoadException(Me, exc)

  28:      End Try

  29:  End Sub

   1:  'Check if Property Editor has been updated by user

   2:  If Properties.IsDirty And Properties.IsValid Then

   3:      'Declare Definition and "retrieve" it from the Property Editor

   4:      Dim propertyDefinition As ProfilePropertyDefinition

   5:      propertyDefinition = DirectCast(Properties.DataSource, ProfilePropertyDefinition)

   6:   

   7:      If PropertyDefinitionID = Null.NullInteger Then

   8:          'Add the Property Definition

   9:          PropertyDefinitionID = ProfileController.AddPropertyDefinition(propertyDefinition)

  10:      Else

  11:          'Update the Property Definition

  12:          ProfileController.UpdatePropertyDefinition(propertyDefinition)

  13:      End If

  14:  End If