This guide covers creating modules for the DotNetNuke framework.
In order to understand what a DotNetNuke module is, it is important to first understand what DotNetNuke is.
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 (PortalModuleBaseorModuleSettingsBase)
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.
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.
While logged into the DotNetNuke installation as the Host account, selectModule Definitions from theHost menu.
Then selectInstall New Module.
From theFile Uploadpage, navigate to the ".zip" file that you downloaded and click theUpload 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 theAdd link under thePage Functions section.
Enter details for the page, ensuring thatAll Users are selected under theView Page column. When you have entered the information, click the Update link.
Next, from the Administrator control panel, selectSurvey from theModule drop-down list and click theAdd link.
The Survey Module will now appear.
Click theAdd 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 theUpdate button.
The module will now display.
When you go toHost >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:
If you look at theDesktopModules/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.
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 theDesktopModules/Survey/Survey.ascxcontrol you see that it'sType is set toView. This is important because it indicates thesecurity group that the control will be in. The portal administrator will be able to configure access to each user control based on theType. This control does not have a setting forKey. The DotNetNuke framework will therefore display this user control as the default user control.
TheDesktopModules/Survey/EditSurvey.ascxcontrol has aType set toEdit. This will allow the portal administrator to configure this user control with a different security access than the previous user control. It also has theKey configured toEdit.
DesktopModules/Survey/Survey.ascx)DesktopModules/Survey/EditSurvey.ascx)
When you look at the details for theSettings control(DesktopModules/Survey/Settings.ascx), you can see that it'sType is set toEdit like theEdit control, but it'sKey is set toSettings.
This setting together with inheriting fromPortalSettingsBaseandoverridingthe LoadSettings() and UpdateSettings()methods,will instruct the DotNetNuke framework to insert this user control in theSettings page for the module. You access thisSettings 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 theSettings page. Here you will be able to configure the security settings for theView andEdit controls.
To see the contents of theSettings 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 theSettings user control(DesktopModules/Survey/Settings.ascx).
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 theModuleID. You usually would not want the data from one instance of the module to appear in another instance. For theSurvey module, theModuleID 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 currentModuleId in a user control that inherits fromPortalModuleBase:
intModuleId As
intModuleId = ModuleId
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 eitherPortalModuleBase orPortalSettingsBase.
To develop your own DotNetNuke modules, it is recommended that you start with one of these tutorials:
DotNetNuke® Module Tutorial Series:DotNetNuke is a registered trademark of Perpetual Motion Interactive Systems Inc.