Introduction to DotNetNuke® Module Development

Introduction to DotNetNuke® Module Development

This guide covers creating modules for the DotNetNuke framework.

What is a DotNetNuke Module?

In order to understand what a DotNetNuke module is, it is important to first understand what DotNetNuke is.

DotNetNuke is a Framework

DotNetNuke is a program that runs on Microsoft ASP.NET. It is also a framework, meaning, it is a program that is designed to be extended. One of the ways you extend the framework is to create modules. These modules are installed inside a DotNetNuke installation and when they run in that DotNetNuke installation they extend the framework to create a DotNetNuke website also called a portal.

A single DotNetNuke installation will allow the creation of thousands of individual portals (as much as the server hardware can handle). DotNetNuke portals are configured to display pages and the pages are configured to display modules.

The portal is accessed by users via a web browser (this can be over the internet or a intranet). These users can be either anonymous visitors or users with accounts and passwords. The modules that are installed and configured in the DotNetNuke installation provide the functionality that the users can perform.

For example, the Survey module allows visitors to participate in a survey and possibly see the tabulated results.

The DotNetNuke framework provides the various functions such as determining if a user is logged in, displaying the look and feel, determining what is on a page and who can see it. The Survey module extends the framework and allows users to participate in the survey.

The developer of the Survey module needs only to create the survey functionality. The DotNetNuke framework handles all the required elements to access the module including the installation  of the module. The Survey module developer does this by writing code that interfaces with the DotNetNuke API (Application Programming Interface). This is done by creating user controls that inherit from the DotNetNuke base classes (PortalModuleBase or ModuleSettingsBase)

DotNetNuke Host and Administrator Accounts

A Host account is the administrator of all portals of a DotNetNuke installation. The Host account is also used for installing modules in the installation. In addition, the Host account creates and configures Administrator accounts. Administrator accounts only administer a particular portal.  An Administrator account cannot install (or uninstall) modules but is able to configure the modules that the Host account has made available. The Administrator also indicates what pages the module will be on and which users can access it.

Installing A Module

To better understand how DotNetNuke and modules work, you can examine the installation and configuration of the Survey module.

First you obtain an installation file. You can obtain the installation file for the Survey module from the Survey project page on DotNetNuke.com.

When you download the file you can see that it is in the form of a ".zip" file.

When you open up the ".zip" file you can see that it contains all the elements it needs as well as a ".dnn" configuration file.

When you open the ".dnn" configuration file you can see that it contains the configuration settings for all the module elements.

Upload The Survey Module

While logged into the DotNetNuke installation as the Host account, select Module Definitions from the Host menu.

Then select Install New Module.

From the File Upload page, navigate to the ".zip" file that you downloaded and click the Upload New File link.

The module will upload...

When you view the installed modules list (Host > Module Definitions), you will now see the Survey module.

Next you will create a page to place the module on. On the Administrator control panel, click the Add link under the Page Functions section.

Enter details for the page, ensuring that All Users are selected under the View Page column. When you have entered the information, click the Update link.

Next, from the Administrator control panel, select Survey from the Module drop-down list and click the Add link.

The Survey Module will now appear.

Click the Add Question link to configure the module. This link and the functionality that follows is the result of the code contained in the ".zip" package. The preceding functionality is provided by the DotNetNuke Framework.

Create a question and click the Update button.

The module will now display.

A Look Into the DotNetNuke Module Definition

When you go to Host > Module Definitions and click on the Survey module definition, you can see that there are 3 user controls configured at the bottom of the Module definition:

• DesktopModules/Survey/Survey.ascx
• DesktopModules/Survey/EditSurvey.ascx
• DesktopModules/Survey/Settings.ascx

If you look at the DesktopModules/Survey directory that was created when you uploaded the Survey module you can see the user controls (and all the other module elements) reside in that directory.

View Control

You can click on the pencil icon next to each user control in the module definition to see it's details. When you click the pencil icon next to the DesktopModules/Survey/Survey.ascx control you see that it's Type is set to View. This is important because it indicates the security group that the control will be in. The portal administrator will be able to configure access to each user control based on the Type. This control does not have a setting for Key. The DotNetNuke framework will therefore display this user control as the default user control.

Edit Control

The DesktopModules/Survey/EditSurvey.ascx control has a Type set to Edit. This will allow the portal administrator to configure this user control with a different security access than the previous user control. It also has the Keyconfigured to Edit.

The Key is important because it allows the module developer to to navigate from the View control(DesktopModules/Survey/Survey.ascx) to the Edit control (DesktopModules/Survey/EditSurvey.ascx) using code such as this:

Response.Redirect(EditUrl())

To navigate from the Edit control to the View control you can use code such as this:

Response.Redirect(Globals.NavigateURL(), true)

(see How to make A DotNetNuke® link for more information)

Settings Control

When you look at the details for the Settings control (DesktopModules/Survey/Settings.ascx), you can see that it'sType is set to Edit like the Edit control, but it's Key is set to Settings.

This setting together with inheriting from PortalSettingsBase and overriding the LoadSettings() and UpdateSettings()methods, will instruct the DotNetNuke framework to insert this user control in the Settings page for the module. You access this Settings page on the module's configuration menu. You access this menu by logging is as the portal administrator (or Host account) and placing the module on a page (if you haven't already done so). Then click the menu link on the module (in the example below it is the small black downward pointing arrow in the upper left hand corner of the module).

This will bring up the Settings page. Here you will be able to configure the security settings for the View and Editcontrols.

To see the contents of the Settings user control (DesktopModules/Survey/Settings.ascx), click the plus icon next toSurvey Settings at the bottom of the settings page.

This will allow you to see the contents of the Settings user control (DesktopModules/Survey/Settings.ascx).

A Module Can Have Multiple Instances

A portal administrator can add multiple instances of a module to a page. In the picture below, two separate instances of the Survey module have been added to the page.

Therefore, in module development it is important to store the ModuleID. You usually would not want the data from one instance of the module to appear in another instance. For the Survey module, the ModuleID is stored in the Surveys table to properly segment the data.

ModuleID is a unique value across all portals in a DotNetNuke installation.  The following code shows how to obtain the current ModuleId in a user control that inherits from PortalModuleBase:

Dim intModuleId As Integer
intModuleId = ModuleId

Summary

DotNetNuke is a framework. You implement this framework by extending it's classes and implementing it's interfaces. One way to do this is by creating modules.

For most DotNetNuke is a solution because they use modules that already extend the classes and implement the interfaces. However, in those instances where you are unable to find an existing module that provides the functionality you desire, you can easily create your own modules.

Essentially, a DotNetNuke module is a collection of user controls that are configured to work together. These user controls inherit from either PortalModuleBase or PortalSettingsBase.

Developing Your Own DotNetNuke Module

To develop your own DotNetNuke modules, it is recommended that you start with one of these tutorials:

DotNetNuke® 4 Module Tutorial Series:

• Creating a DotNetNuke Module using LINQ to SQL (Start here!)
• Super-Simple Module (DAL+)
• Super-Fast Super-Easy Module (DAL+)
• Create a full complete Module

[Back to: The ADefWebserver DotNetNuke HELP WebSite]

DotNetNuke® is a registered trademark of Perpetual Motion Interactive Systems Inc.