How to develop DotnetNuke Module - Implementation of module

Download Module Project

In previous post Develop DotnetNuke Module - Setting up environment, I described how you will go about setting up your development environment. Now I will start discussion on developing a DNN custom module as stand alone assembly using C#. I have named this module as ByteBlocks: AmazonProducts. The module displays products from Amazon.com store based on product category and search keywords. For this to use in your web site, you will need to have an associate account with Amazon.com. This is totally free and you can get started by clicking here.

Click here to see this module in action

New Project

Select File > New > Project menu option to create new project. In my case, I named it AmazonProducts. This will create a new C# project for you. The project template adds lot of boiler plate code for you to get started. In this post I will explain the files that are absolutely basic to get started with module development. Before you start doing anything, run NANT build tool to make sure that your project compiles. And check that there is a folder named package under the project folder. And this folder should contain four ZIP files in it. If this step goes smoothly, that means you have your development set up correctly and you are ready to rock with module development.

Lets look at some of the files that got added to your project.

.dnn file

This is the file that defines metadata for your module. What this means is that this where you specify how your module is structured, files it contains and other settings. Open this file. This is a XML file. All the node names are very intuitive and very quickly you will figure out what these means. If you are building a single view and single assembly module then you will not have to make any changes under Controls and Files node. For more complex modules that require more files to be included and other things then you will be made to define those settings in these sections. For now, leave it the way it is. Make sure that you have name of the module specified that is relevant to functionality of your module.

View{projectname}.ascx

This is the file where you will implement VIEW of your module. What this means is that this is the control that gets loaded in DNN framework when users come to your site. If you open {projectname}.dnn file you will find a node under controls that looks as below.

<control>
 <src>DesktopModules/AmazonProducts/ViewAmazonProducts.ascx</src>
 <type>View</type>
 <helpurl></helpurl>
</control>

This is the node where you indicate to DNN framework what all controls are going to be used a view for the data. If you have multiple views for your module then you will need to add entries for those views in {projectname}.dnn file. I will explain in another post how you will deal with multiple views and how you will load them at run time based on their IDs and things like that. In this sample module I only have one view.

Settings{projectname}.ascx

This is the control that gets loaded when you invoke settings of a module. DNN framework loads your implementation combined with the base implementation provided by the framework to show settings for the module. If you do not have any custom settings for your module then you do not have to add any content to it. Also open {projectname}.dnn and notice that you have a node like below in there.

<control>
 <key>Settings</key>
 <title>AmazonProducts Settings</title>
 <src>DesktopModules/AmazonProducts/Settings.ascx</src>
 <type>Edit</type>
 <helpurl></helpurl>
</control>

Edit{projectname}.ascx

This is a very important control implementation in your module. If your control requires some input to configure it to run it, then you can use this control to implement gathering of those settings. For example in the sample module, you need to gather 2 very important pieces of information to get data from Amazon.com web service. The images below shows you how a new link Amazon Account Set up appears when you are logged in as an admin and clicking on it brings up a view where you can specify the settings for the module.

Open {projectname}.dnn file you will find a node as shown below.

<control>
 <key<Edit</key<
 <title<Edit Content</title<
 <src<DesktopModules/AmazonProducts/EditAmazonProducts.ascx</src<
 <type<Edit</type<
 <helpurl<</helpurl<
</control<

There are some very important points about how you indicate to DNN framework that this is the control that is going to be used for EDIT. One you have noticed in the DNN file that type has been set to Edit. Second is in your implementation. You have to implement IActionable interface in View{projectname}.ascx control. In that implement you indicate to DNN framework what all other actions can be performed by this module. The project template does not add boiler plate code for this interface in your module. You will have to add it yourself. For example, in the sample project the implementation of the class looks as below.

public partial class ViewAmazonProducts : 
   AmazonProductsModuleBase, IActionable
{....}

Add implementation

Now that you have set up the boiler plate code for your module, it is time to fill it with implementation. You will just go about the implementation as you are doing regular ASP.Net user control implementation. The sample project contains complete implementation of rendering product lists from amazon.com. This code was implemented during .Net1.1 days so lot of code may be obsolete and not optimized according to recent changes. But it will give you get started with your DNN module development.

Compile It

Now that you have finished adding implementation of your module, it is time to see it in action. You can use your Visual Studio to a build of the project and resolve any compile errors. Once all errors have been taken care of, fire up NANT build to create package for your module. You will notice four ZIP files created in package folder.

Install It

Once you have created package for your module, you are ready to install it in your DNN framework. Fire up DNN site and login with HOST account. Yes, you will need to log in as HOST. Once logged in, under HOST menu option, select Module Definitions option. This will bring up list of all modules installed in your installation. On that page at the top you will see a dropdown icon next to Module Definitions. Hover mouse on it and it will bring up menu options. Select Install module option as show below.

In the first step you will be asked to select location of your module package. Point to package folder under your project or wherever you copied the ZIP files created for your module. After that follow the instructions and you will have your module loaded and ready to use on any page in your site.

Use It

Once you are done with installation of module package, it shall be visible in list of modules available for your site. Just follow your usual steps of adding a module on any page on your site and you are good to go.

Debugging

In the next post, I will explain how you can go about debugging a DNN module.