The DotNetNuke Property Editors

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 47 class or enum files that make up the Property Editor suite of controls. Part 1 of this series introduced the Profile Editor. This article introduces the 14 EditControls included with the core distribution. Future articles in this series will describe how to create your own EditControl.

The Abstract EditControl

Figure 1: The Abstract EditControl Base Class

Figure 1 shows the definition of the abstract base class EditControl. Every EditControl used by the Property Editors is derived from this base class.

Lets take a look at this abstract class. There are 9 Properties in this class and one abstract Property (StringValue).

• CustomAttributes - An array of Attributes that can be used by the derived classes to add customisation (for instance the DNNListEditControl uses the Attributes collection to determine which list to display).
• EditMode - Determines whether the control is in Edit or View mode.
• LocalResourceFile - This property is used by the EditControl to reference the current LocalResourceFile.
• Name - The name of the property being edited.
• OldValue - the old value of the property.
• Required - whether the property is required (used by drop-down lists to determine whether to add a < None Specified > option).
• StringValue - the Value expressed as a String , each derived class must override this property.
• SystemType - the underlying System.Type of the value of this control.
• Value - the value of the property.

The abstract class also defines a number of protected methods. Three methods control the rendering process.

• Render - the Render method is called by the .NET Framework at Render time and this method calls RenderEditMode or RenderViewMode to render the control, based on the value of the EditMode property.
• RenderViewMode - this method renders the control when the EditMode is set to View, as is the case in "View Profile" .
• RenderEditMode - this method renders the control when the EditMode is set to Edit, as is the case when editing a Profile. This method is shown in Listing 1 below.

   1:  Protected Overridable Sub RenderEditMode(ByVal writer As HtmlTextWriter)

   2:      Dim propValue As String = CType(Me.Value, String)

   3:      ControlStyle.AddAttributesToRender(writer)

   4:      writer.AddAttribute(HtmlTextWriterAttribute.Type, "text")

   5:      writer.AddAttribute(HtmlTextWriterAttribute.Value, propValue)

   6:      writer.AddAttribute(HtmlTextWriterAttribute.Name, Me.UniqueID)

   7:      writer.RenderBeginTag(HtmlTextWriterTag.Input)

   8:      writer.RenderEndTag()

   9:  End Sub

These methods provide a default implementation that is called if the derived class does not provide its own rendering methods. Later in this article we will show how a derived EditControl overrides these methods. In the abstract base class a text box is rendered (an XHTML <input /> tag), the value is set to the value of the property, and the name is set to the UniqueID of the control. This last value is very important, as it is used by the .NET Framework to identify the control on PostBack.

IPostBackDataHandler Interface

If you look at Figure 1 you will see that the EditControl class implements the IPostBackDataHandler Interface. This interface provides two methods that are called automatically by the .NET Framework LoadPostData (see Listing 2) and RaisePostDataChangedEvent (see Listing 3)

   1:  Public Overridable Function LoadPostData(ByVal postDataKey As String, _ 
                  ByVal postCollection As NameValueCollection) As Boolean

   2:      Dim dataChanged As Boolean = False

   3:      Dim presentValue As String = CStr(Value)

   4:      Dim postedValue As String = postCollection(postDataKey)

   5:      If Not presentValue.Equals(postedValue) Then

   6:          Value = postedValue

   7:          dataChanged = True

   8:      End If

   9:      Return dataChanged

  10:  End Function

The LoadPostData method is called by the .NET Framework for any Control that implements IPostBackDataHandler. It is called just after the View State is loaded (LoadViewState) and just before the Load phase of the Control Life Cycle. The postCollection represents all the name/value pairs returned to the Server by the PostBack, and the postDataKey is the key for the current control. (Remember earlier when I said the UniqueID was rendered to the Name attribute of the <input/> tag). The LoadPostData method returns a boolean that lets the Framework know whether the data was changed since it was rendered.

   1:  Public Sub RaisePostDataChangedEvent()

   2:      'Raise the DataChanged Event

   3:      OnDataChanged(System.EventArgs.Empty)

   4:  End Sub

Once the Load phase is complete, the .NET Framework then calls the RaisePostDataChangedEvent for every control that had previously reported that their data had changed. This allows the control to raise an event indicating its value has changed, In our case the RaisePostDataChangedEvent method calls the abstract OnDataChanged method. An abstract must be implemented in the derived class, and when the RaisePostDataChangedEvent calls the OnDataChanged method it actually calls the derived classes version, so the derived class can determine what to do next.

The base class also provides the ValueChanged event and associated OnValueChanged method (see Listing 4)

   1:  Public Event ValueChanged As PropertyChangedEventHandler

   2:   

   3:  Protected Overridable Sub OnValueChanged(ByVal e As PropertyEditorEventArgs)

   4:      RaiseEvent ValueChanged(Me, e)

   5:  End Sub

Figure 2: PropertyEditorEventArgs class

A derived class can use these events to indicated to the Editors that their values have been changed, passing the relevant infomration in a custom PropertyEditorEventArgs object.

EditControls included with DotNetNuke 4.3

As mentioned in the Introduction 14 EditControls are included with DotNetNuke (1 abstract base class and 13 derived classes). Figure 3 shows how 9 of the controls derive from the abstract base class. In general the controls can be divided into 4 groups:

• Text controls - which derive from the TextEditControl
• Integer controls - which derive from the IntegerEditControl
• True False controls - either True/False (using radio buttons) or a check Edit Control
• Lists - derived from DNNListEditControl

Figure 3: Some of the EditControls included in DotNetNuke v4.3.

Figure 4: The TrueFalseEditControl

The TrueFalseEditControl

As an example of a derived EditControl let's look at the TrueFalseEditControl. This control can be used to edit a boolean value using two radio buttons (True and False). As can be seen in Figure 4, this control has three properties and 2 methods.

The StringValue property is abstract in the base class so every derived class must implement this property.

The BooleanValue and OldBooleanValue properties are ReadOnly typed versions of the base classes Value and OldValue properties. They are not neccessary but are provided as helper properites that can be used in the methods of the class and any classes derived from it.

   1:  Protected ReadOnly Property BooleanValue() As Boolean

   2:      Get

   3:          Dim boolValue As Boolean = Null.NullBoolean

   4:          Try

   5:              'Try and cast the value to an Boolean

   6:              boolValue = CType(Value, Boolean)

   7:          Catch ex As Exception

   8:          End Try

   9:          Return boolValue

  10:      End Get

  11:  End Property

  12:   

  13:  Protected ReadOnly Property OldBooleanValue() As Boolean

  14:      Get

  15:          Dim boolValue As Boolean = Null.NullBoolean

  16:          Try

  17:              'Try and cast the value to an Boolean

  18:              boolValue = CType(OldValue, Boolean)

  19:          Catch ex As Exception

  20:          End Try

  21:          Return boolValue

  22:      End Get

  23:  End Property

  24:   

  25:  Protected Overrides Property StringValue() As String

  26:      Get

  27:          Return BooleanValue.ToString

  28:      End Get

  29:      Set(ByVal Value As String)

  30:          Dim setValue As Boolean = Boolean.Parse(Value)

  31:          Me.Value = setValue

  32:      End Set

  33:  End Property

The TrueFalseEditControl overrides the RenderEditMode method of the base class as we are using two radio buttons (rather than a text box) to edit the data. This method is shown in Listing 6.

   1:  Protected Overrides Sub RenderEditMode(ByVal writer As HtmlTextWriter)

   2:      writer.AddAttribute(HtmlTextWriterAttribute.Type, "radio")

   3:      If (BooleanValue) Then

   4:          writer.AddAttribute(HtmlTextWriterAttribute.Checked, "checked")

   5:      End If

   6:      writer.AddAttribute(HtmlTextWriterAttribute.Value, "True")

   7:      writer.AddAttribute(HtmlTextWriterAttribute.Name, Me.UniqueID)

   8:      writer.RenderBeginTag(HtmlTextWriterTag.Input)

   9:      writer.RenderEndTag()

  10:   

  11:      ControlStyle.AddAttributesToRender(writer)

  12:      writer.RenderBeginTag(HtmlTextWriterTag.Span)

  13:      writer.Write("True")

  14:      writer.RenderEndTag()

  15:   

  16:      writer.AddAttribute(HtmlTextWriterAttribute.Type, "radio")

  17:      If (Not BooleanValue) Then

  18:          writer.AddAttribute(HtmlTextWriterAttribute.Checked, "checked")

  19:      End If

  20:      writer.AddAttribute(HtmlTextWriterAttribute.Value, "False")

  21:      writer.AddAttribute(HtmlTextWriterAttribute.Name, Me.UniqueID)

  22:      writer.RenderBeginTag(HtmlTextWriterTag.Input)

  23:      writer.RenderEndTag()

  24:   

  25:      ControlStyle.AddAttributesToRender(writer)

  26:      writer.RenderBeginTag(HtmlTextWriterTag.Span)

  27:      writer.Write("False")

  28:      writer.RenderEndTag()

  29:  End Sub

This is a much more complicated method that the one in the base class (compare with Listing 1), as it needs to render two radio buttons, and make one of them selected (or "checked") depending on the vale of the BooleanValue property. It is important to note also that the name attribute for both buttons is given the same value, the UniqueID property of the EditControl, so that the .NET Framework can correctly identify the control.

As mentioned above the RaisePostDataChangedEvent method of the base class calls the abstract OnDataChanged method, so the TrueFalseEditControl has to provide an implementation of this method. This is shown in Listing 7.

   1:  Protected Overrides Sub OnDataChanged(ByVal e As EventArgs)

   2:      Dim args As New PropertyEditorEventArgs(Name)

   3:      args.Value = BooleanValue

   4:      args.OldValue = OldBooleanValue

   5:      args.StringValue = StringValue

   6:      MyBase.OnValueChanged(args)

   7:  End Sub

The OnDataChanged method creates a new PropertyEditorEventArgs object, and sets its Value, OldValue and StringValue properties - the Name property is created in the constructor, and the controls Name value is passed as a parameter of the constructor.

This PropertyEditorEventArgs object is then passed to the base classes OnValueChanged method, which raises the ValueChanged event.

As can be seen from this discussion, there really isn't very much to the derived EditControls. In future articles in this series we will show how to develop new Edit Controls, and how to register them in your DotNetNuke installation.

Conclusion

This article provides an introduction to the 14 EditControl provided as part of the Property Editor introduced in DotNetNuke v4.3. It describes the abstract EditControl in some detail, the provides an overview of the inheritance model, and concludes with a description of one derived control in some detail.

For More Information:

For more information on the Control Life Cycle, Events and Postback please see Chapter 9 of "Developing Microsoft ASP.NET Server Controls and Components", by Nikhil Kothari and Vandana Datye, Microsoft Press.

About the Author: Charles Nurse is the owner of Keydance Computer Services, the sponsor of this site, as well as being a Trustee and a Lead Developer in the DotNetNuke project.