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. This article describes how to create your own simple EditControl, and how you go about registering your control in your DotNetNuke site.

The FolderEditControl

As an example of building your very own EditControl, this article will take you step-by-step through building a Folder EditControl. While this is a somewhat arbitrary choice, we can envisage a Use Case for this control.

A module developer wishes to build a Gallery module where the images are saved to a specific folder for each user. The module developer decides that the obvious place to assign this folder is in the User's profile. The administrator of the site would assign the User a folder in the Profile Editor. By setting the Profile Properties Visible property to visible, the user cannot edit the property themselves, but Administrators can still see it, and edit it.

In the module's code the module developer would just determine the current user's folder using the following C# code:

string userFolder = UserInfo.Profile.GetPropertyValue("UserFolder")

The first step in creating your own custom EditControl, is deciding which existing EditControl to start from as your base class. In the case of the FolderEditControl, we will be saving the data (in the Profile) as a relative path. We could save the data as an integer by using the FolderID of the folder in question, but this would require a second call to detemine the folderPath.

   1:  int userFolderID = UserInfo.Profile.GetPropertyValue("UserFolder");

   2:  FolderController controller = new FolderController();

   3:  FolderInfo folder = controller.GetFolderInfo(PortalId, userFolderID);

   4:  string userFolder = folder.FolderPath;

As we have decided to store the data as text, the obvious base class candidate is the TextEditControl.

Figure 1: The FolderEditControl

Figure 1 shows the definition of the FolderEditControl. The control has three properties and one method. All the other aspects of the controls behaviour are handled either by the abstract base class (EditControl) or by the immediate base class (TextEditControl).

Thus, the abstract base class (EditControl) provides

• all the standard properties (Name, Value, OldValue etc) that the Property Editor Framework expects
• the RenderViewMode method to render the value of the control in View mode (as in View Profile)
• the IPostBackDataHandler Interface implementation, to manage post backs, and determine whether the value has changed
• and the ValueChanged event and OnValueChnaged method to inform the Property Editors that the value of the control has changed.

The TextEditControl meanwhile provides

• two extra helper properties (StringValue and OldStringValue) that provide strongly-typed versions of Value and OldValue,
• and the OnDataChanged method (see Listing 1), which we can use, since while we will be displaying a list of folders to the user, we are still just working with text

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

   2:      Dim args As New PropertyEditorEventArgs(Name)

   3:      args.Value = StringValue

   4:      args.OldValue = OldStringValue

   5:      args.StringValue = StringValue

   6:      MyBase.OnValueChanged(args)

   7:  End Sub

Those of you that have read the Part 2 of this series will note the similarity between this method and the same method in the TrueFalseEditControl (see Listing 7 in An Introduction to Edit Controls) .

Creating the FolderEditControl

The first thing we will need to do to create our FolderEditControl is to create a new class file (see Listing 2).. While the specific namespace used is not important, it is important to use a namespace that should be unique.

   1:  namespace Keydance.DotNetNuke.Controls

   2:  {

   3:      public class FolderEditControl : TextEditControl

   4:      {

   5:      }

   6:  }

The three properties in the FolderEditControl are provided as "helper" properties. They are all protected read-only properties (see Listing 3).

   1:  protected bool IsHost

   2:  {

   3:      get

   4:      {

   5:          bool _IsHost = Null.NullBoolean;

   6:          if (PortalSettings.ActiveTab.ParentId == PortalSettings.SuperTabId)

   7:              _IsHost = true;

   8:          return _IsHost;

   9:      }

  10:  }

  11:   

  12:  protected int PortalId

  13:  {

  14:      get

  15:      {

  16:          int _PortalId = Null.NullInteger;

  17:          if (!IsHost)

  18:              _PortalId = PortalSettings.PortalId;

  19:          return _PortalId;

  20:      }

  21:  }

  22:   

  23:  protected PortalSettings PortalSettings

  24:  {

  25:      get

  26:      {

  27:          return PortalController.GetCurrentPortalSettings();

  28:      }

  29:  }

The IsHost property determines whether we are dealing with Portal folders or Host folders. While this code is C# code it is clearly similar to code used in the URLControl and FileManager to determine whether we should be using Portal or Host folders. The PortalId returns either Null.NullInteger when IsHost is true or the Id of the current Portal if IsHost is false, and the PortalSettings returns the the current Portal's settings. There is nothing really different in these last two properties from the code found in the PortalModuleBase base class.

In reality the only property that we will use in the RenderEditMode method is the PortalId - the other properties just provide a convenient way to factorise out the code needed.

So, lets now take a look at the RenderEditMode method. This method will render our list of folders as a drop-down list (ie an XHTML <select> tag. The code is shown in Listing 4.

   1:  protected override void RenderEditMode(HtmlTextWriter writer)

   2:  {

   3:      //Declare variables

   4:      string folderName;

   5:      string folderPath;

   6:      string viewRoles = Null.NullString;

   7:   

   8:      //Render the Style for the control

   9:      ControlStyle.AddAttributesToRender(writer);

  10:   

  11:      //Render the Select Tag

  12:      writer.AddAttribute(HtmlTextWriterAttribute.Name, this.UniqueID);

  13:      writer.RenderBeginTag(HtmlTextWriterTag.Select);

  14:   

  15:      //Get the folders

  16:      ArrayList folders = FileSystemUtils.GetFolders(PortalId);

  17:   

  18:      //Iterate through the folders

  19:      foreach (FolderInfo folder in folders)

  20:      {

  21:          if (folder.FolderPath == Null.NullString)

  22:          {

  23:              folderName = Localization.LocalizeString(this, "Root");

  24:              viewRoles = FileSystemUtils.GetRoles("", PortalId, "READ");

  25:          }

  26:          else

  27:          {

  28:              folderName = folder.FolderPath;

  29:              viewRoles = FileSystemUtils.GetRoles(folderName, PortalId, "READ");

  30:          }

  31:          folderPath = folder.FolderPath;

  32:   

  33:          //Check if the user has View access to this folder

  34:          if (PortalSecurity.IsInRoles(viewRoles) && 
                   (folder.StorageLocation == 
                   (int)FolderController.StorageLocationTypes.InsecureFileSystem))

  35:          {

  36:              //Add the Value Attribute

  37:              writer.AddAttribute(HtmlTextWriterAttribute.Value, folderPath);

  38:   

  39:              //Add the Selected Attribute if this folder is the currently

  40:              //selected folder

  41:              if (folderPath == StringValue)

  42:                  writer.AddAttribute(HtmlTextWriterAttribute.Selected, "selected");

  43:   

  44:              //Render Option Tag

  45:              writer.RenderBeginTag(HtmlTextWriterTag.Option);

  46:              writer.Write(folderName);

  47:              writer.RenderEndTag();

  48:          }

  49:      }

  50:   

  51:      //Close Select Tag

  52:      writer.RenderEndTag();

  53:  } 

Lines 4-6 declare the variables we will need in this method. Lines 9, 12 and 13 render the beginning of the XHTML <select> tag. As was discussed in Part 2 of this series, the name attribute of the <select> tag is set to the UniqueID of the control, so the .NET Framework can match up the control with the correct name/value pair returned from the client. Line 52 renders the closing part of the <select> tag.

The rest of the code (lines 16-49) detemine which folders to include and then renders each folder as an <option> tag, which represents a single row in the drop-down list. In line 16 we call the static (Shared in Visual Basic) GetFolders method of FileSystemUtils. This returns an ArrayList of FolderInfo items representing all the folders for a given portal (or the Host folders if PortalId is -1 (Null.NullInteger). We then iterate through the ArrayList of folders (line 19). Lines 21-31 determine the value of the folderName and the folderPath and build a ";" delimted list of roles with "READ" permission (viewRoles) .

Line 34 then checks whether the current user can "READ" the current folder. If the current user does have the appropriate permission the value attribute (of the <option> tag) is rendered (line 37). If the current folder's folderPath is the current Value of the property then the <option> tags selected value is set (lines 41 & 42). Finally, in lines 45-47 the <option> tag is rendered displaying the name of the foler (folderName)

Thats all there is to it. As I have emphasised a number of times, the important points to note are the the name attribute is set to the UniqueID property and the value part of the control is set to the Value of the property.

Registering the FolderEditControl

Now that we have our own FolderEditControl, we will need to register the control in our DotNetNuke site. Obviously the first step is to make sure that the control compiles. Next we need to figure out the Assembly Qualified Full Name for the Control. It is assumed here that the control was created in a Class Library.

Figure 2: Detmermining the AssemblyName

To determine the Assembly Qualified Full Name, we need to know the Assembly's name. To determine this name we right-click on the class Library project in Solution Explorer, and select the Properties menu item (its probably at the bottom of the list). The Assembly Name is on the Application Tab of the Properties page for the project (see Figure 2). So in this example the Assembly Name is "Keydance.DNNLibrary" which means that the executable created will be Keydance.DNNLibrary.dll.

The next thing we need to know is the Namespace. In Listing 2, we used the namespace Keydance.DotNetNuke.Controls. This means that our Assembly Qualified Full Name is "Keydance.DotNetNuke.Controls.FolderEditControl, Keydance.DNNLIbrary" ( or Namespace.ClassName, AssemblyName).

Now that we have determined what the Assembly Qualifed Full Name for the control is, we can use the List Editor in DotNetNuke to register this control as a new DataType. To do this we log in to the DotNetNuke site as Host, select the Lists menu item on the Host menu, and then click on DataType in the Lists Tree. The list of current DataTypes will be shown on the right (see Figure 3)

Figure 3: The DataTypes List

To add a new DataType we click on AddEntry, enter the Assembly Qualified Full Name in the Entry Text field and a short name (Folder) in the Value field. (see Figure 4)

Figure 4: Adding the new DataType

Figure 5: Creating the new UserFolder property

The short name we choose will be displayed in the DataType drop-down list in the Profile Property Editor.

After filling in both fields we click the Save button to save the new DataType. We can now use this new DataType in the Profile Property editor to create a new UserFolder property.

This process was described in more detail in Part 1 of this series, and is shown in Figure 5. Note that the new property is near the bottom of the List of DataTypes.

Once this property has been created we can now see it an action by viewing a User's profile. This is shown in Figure 6.

Figure 6: The new UserFolder Property

The administrator can now assign a folder to the User and the module developer of our fictitious Gallery module can determine the current user's assigned Folder, and use it to save all the current user's images.

This example was fairly straightforward. Not all EditControls are this simple. It does however illustrate the process required to develop your own EditControl.

In the next article in this series we tackle a slightly harder example - developing a DateEditControl.

Conclusion

This article describes how to create your own EditControl for use in the DotNetNuke PropertyEditors. It also describes, how you register the new control, so Administrators can use the control for editing a Profile Property.

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.