In this article we go over the architecture of a DNN 2.x module, specifically the Survey module example included within the DotNetNuke distribution. In part one, we cover setting up a development project, and the user interface for our module.

If you're not familiar with DotNetNuke, be sure you visit http://www.dotnetnuke.com to learn more about this fast growing open source portal that you can use and develop against absolutely free.

DotNetNuke (DNN) has been out now for a little over a year and has really seen a tremendous amount of growth. The community is a very active and large community, which can easily be demonstrated by viewing the activity in the ASP.Net forums. In this article we will cover module creation for DotNetNuke, and specifically look at the Data Provider Model of DNN 2.x. We will not get into a step by procedural method of developing modules, but rather provide you with an overview of the architecture and starting point for developing your own custom modules for DNN.

What Are Modules?

Modules provide developers with the ability to extend the functionality of DotNetNuke. DotNetNuke provides a pluggable framework that can be expanded by the development of modules. A module container is provided by DotNetNuke to host a custom module. Modules can be developed in any .NET language, even though DNN is developed in VB.NET, a C# developer can still create a module that plugs into the core framework provided by DNN. This pluggable framework is accomplished by creating compiled private assemblies that expose and utilize interfaces specific to DNN. Once you compile the assembly, then just create a UI in the form of ascx files that allow your user to interact with your module.

Module Containers

Module containers provide several features for you as a developer. Besides being your way of interfacing with the DNN core framework, module containers also provide the following:

• Security mechanisms: You can define view and edit permissions for your modules. DNN will then handle the security checking for your module. You do not need to write your own security mechanism, rather use the role based security provided by the framework.
• Look and feel: Module containers can be customized with various looks, in addition the module container and DNN provide you with the ability to place the module within the DNN page. In addition, it also allows your users to customize the appearance of the module as well, for example minimize and maximize modes.
• Caching: As a performance mechanism you can define caching at the container level. This allows modules that do not need to be updated on every request to have their contents cached thus providing a performance improvement.

Configuring Your Development Environment

Now that we covered what modules actually are, lets go on and create a development project for our module. There are various methods for creating modules for DNN, but we prefer to configure a separate project for module creation and then compile the assemblies within the DNN bin folder. The following procedure  provides a method for configuring a portal module project in Visual Studio.NET.

1. Create a new class project, be sure to use a logical naming structure. For example: CompanyName.ModuleName.
2. When creating the new project folder, create a folder off of the DotNetNuke Root\DesktopModules\ directory.
3. Clear any namespace from the project properties. Right click on properties of the project, under general clear the root namespace box.
4. Add a reference to the DotNetNuke project in your new module project.

That's it for the base module assembly project. Now if you want to add a data provider assembly to your project you would follow the same procedure above except name your project CompanyName.ModuleName.SQLDataProvider (or Access depending on which database you're supporting). In addition to creating a reference to the DotNetNuke project, create a reference to your main module project and also the Microsoft.ApplicationBlocks.Data assembly. This is going to aid in the data abstraction.

Once you're project is done, it should look like the following in the solution explorer in Visual Studio.NET:

Figure 1.1 Solution Explorer View

Now let's first cover a little architecture for DNN. The following diagram is taken from the DotNetNuke documentation. This provides a look into how DNN is architected. First with the ascx controls which provide our user interface. The interface then communicates with the Business Logic Layer (BLL), as in the diagram this BLL is contained with the SurveyDB.vb class, and provides all data for our user interface. Below the BLL we have the Abstract Data Provider, we'll get more into this later, but this class provides an abstraction layer for our application. This provider is not database specific, rather our data provider class will provide methods that override the abstraction class and interaction with our specific database. The abstraction provider in this example is the DataProvider.vb class within the main survey module project. Below the abstraction layer we have our Data Access Layer, this class is specific to a vendor database and is unique based on what database we want our module to interact with. This class is the SQLDataProvider project as in the image above. Finally there is the Microsoft.ApplicationBlocks.Data which provides functions for our specific database interaction, and frees a developer from having to write specific SQL Server code.

Figure 1.2 DotNetNuke Architecture

Now that we covered project creation and architecture, let's get started writing some code. All code referenced in this article is the survey module example provided with DotNetNuke, so you can try it out for yourself.

Create Your Controls

First we need to create some controls for our user to interact with. In this example we have a Survey.ascx control, this control is the primary survey control that is public ally viewable for the user. The other controls are for managing the survey, these are the EditSurvey.ascx, and EditSurveyOptions.ascx controls.

View Control

In the view control, this is the main Survey.ascx control, open the code behind file. In this class you'll notice the following: 

Imports DotNetNuke
Namespace YourCompanyName.Survey
    Public MustInherit Class Survey
        Inherits PortalModuleControl
        ::
        ::
End Class

You'll notice instead of inheriting from the WebControls class, the module inherits from the PortalModuleControl provided by DNN. The PortalModuleControl, located in the /components/desktopcontrols.vb class, provides some very important properties and methods exposed by DNN, for example:

• IsEditable: Property determines whether or not the current user has edit permissions for the module.
• UserId – id of the current user
• Help File path – file path to help
• Portal alias – the alias or name.
• Portal ID – the current portal id
• Tab ID – id of the current tab within DotNetNuke
• Module ID – id of current module
• Settings hash – similar to a registry for storing module specific values.

In this specific example, we have a some basic interaction with a database via the BLL. Remember the entire code for this module is available in the DotNetNuke download as example of custom module development. Use this as a template for your own projects.

Edit Control

Now that we went over the view control, most modules have at a minimum of two ascx controls, one for the view which the user sees, and another control for editing certain features of a module. This edit control provides you with a way of customizing a module for each instance within your DotNetNuke portal. For example, in the survey module you may want to create multiple surveys for your portal. You can do this by passing specific values to the module via the edit control. The DNN framework provides this by keying off of the ModuleID provided by the PortalModuleControl, as well as a Settings hash table, which is similar to a registry for storing module specific information.

Let's take a look at storing and retrieving values to the settings hash:

Private Sub cmdUpdate_Click(ByVal sender As Object, _
 ByVal e As System.EventArgs) Handles cmdUpdate.Click
   Dim objModules As New DotNetNuke.ModuleController
   objModules.UpdateModuleSetting(ModuleId, "surveyclosingdate", txtClosingDate.Text)
   objModules.UpdateModuleSetting(ModuleId, "surveygraphwidth", txtGraphWidth.Text)
   ' Redirect back to the portal home page
   Response.Redirect(NavigateURL())
End Sub

You'll notice in the Click handler above, we write some values to the settings hash for this specific module. We specify the ModuleID, which is provided by the PortalModuleControl, and then store the text field values within the hash. It's a pretty easy thing to do, only a couple lines of code. Retrieving information from the hash table is just as painless:

txtClosingDate.Text = CType(Settings("surveyclosingdate"), String)
txtGraphWidth.Text = CType(Settings("surveygraphwidth"), String)

Above we do the opposite of the above and retrieve the values from the hash table and populate our text controls.

Letting DotNetNuke Know About Your Modules

Many of you may be familiar with Private Assembly installation files, here you just upload a zip file to DNN and everything is installed automatically. When you're developing modules you usually have to do this process manually, and let DNN know where your ascx controls are. Your compiled assemblies are already being compiled and placed in the DNN bin folder so DNN can access them when needed, but you still need to let DNN know about your new module. You can manually define your modules using the following procedure:

1. Under Host Settings menu, go to Module Definitions
2. In Module Definitions Select Add New Definition from the module menu in the upper left hand corner.
3. You will then be presented with the Edit Module Definitions screen.
4. From here add a new definition.
5. Once your definition is created, then add your user controls to your module. For the survey module you will need to add the following:
   • Survey.ascx - Type of View
   • EditSurvey.ascx - Type Edit, Key is Edit.
   • EditSurveyOptions.ascx - Type is Edit, Key is Options.

Creating the Database Structure

Now that DNN knows about the Survey module example, you will want to create the database structure. If this is a private assembly install you could just install the assembly, but to play it safe for a development project it is best to run the SQL script manually. I prefer to run the script in Query Analyzer in the SQL Server tools menu. First you need to open the script which is located in the SQLDataProvider folder for the Survey module. Then remove the {databaseowner} and {objectqualifier} directives from the script; a simple search and replace in notepad will take care of this. These directives are for DNN when installing your module as an assembly file. Once you remove these directives, execute the script to generate your database manually.

Referring to Your Module Keys

On a final note of this part in the module creation series, we will cover referring to your control's keys within the code. Open the survey example, and expand the initialize method in the code behind of the survey.ascx control. You'll notice here where the module creates the menu options for each of the controls:

' PortalModuleControl base class settings for this module
MyBase.HelpFile = "help.txt" ' a local document stored in the same folder as the user control
MyBase.HelpURL = "http://www.dotnetnuke.com" ' a URL for support on the module
' action menu items
MyBase.Actions.Add(GetNextActionID, "View Options", "", URL:=EditURL(, , "Options"), _
  secure:=SecurityAccessLevel.Edit, Visible:=True)
MyBase.Actions.Add(GetNextActionID, "Add Survey", "", URL:=EditURL(), _
 secure:=SecurityAccessLevel.Edit, Visible:=True)

Here we create the menu options, and then refer to them by their key. For example, look at the MyBase.Actions.Add method, we add our menu options and refer to them by Key in the final value sent to he EditURL. You can see "Options" being passed. This is the key we defined earlier in our module definitions. We also specify security information for the menus as well.

Hopefully this article will provide you with an informative overview of the architecture of the Survey module that comes packaged with DNN. Use this example to build your own modules with. In the next series of module architecture we will discuss the data provider model of DotNetNuke and how you develop against it.

By: Patrick Santry, Microsoft MVP (ASP/ASP.NET), developer of this site, author of books on Web technologies, and member of the DotNetNuke core development team. If you're interested in the services provided by Patrick, visit his company Website at Santry.com.