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.
Subscribe