Creating a new DotNetNuke module in Visual Basic

Before we start - let's get something in place: In this guide I do use Microsoft Visual Studio 2003, Visual Basic.NET, and Microsoft SQL server. Even if you don't have Visual Studio and do all your code in J#, you are able to learn from this guide as it will explain a lot of things about the layout, state, database, and DotNetNuke API.

If you code in C#, there are another guide on this site using this programming language.

So, you want to write a new DotNetNuke module, and don't know where to start… Do start by setting up a development environment by using the description here on this site. In this step by step guide I will use this framework to create a full working DotNetNuke module. I will show how to debug and package your module for easy end user installation.

First we must decide what to build, and why not build something usefully, that I need on my site. Text on this site is now a standard html/text module from the DotNetNuke core, but I would really like it to be shown at controlled random so that the page is dynamically changed for each request, to give an impression of a dynamic web site and loose some of the static look.

Okay, the steps we need to do are:

• Design a data model to hold the Text Page list information.
• Create a DotNetNuke version 2 data access layer (DAL) and SQL script files
• Make a view control, which is the primary presentation layer
• Make an edit control, which is use to manage the page list
• Test and debug the module
• Create the DNN deployment script file
• Create the module install archive

Wow - many task to complete, but it looks worse than it is...

An installable version and the full source code, including Visual Studio projects are available in the Random Page description under the Modules menu at this site.

Now it's time to create a new Visual Studio projects. Open Visual Studio and the DotNetNuke solution - I do expect that you are using the development environment setup as explained in another guide on this site.

First we create the Module project:

In the solution explorer, right click the DotNetNuke solution and select Add | New Project, select Visual Basic Projects and Empty Web Project. Type the Location:

http://localhost/DotNetNuke/DesktopModules/BonosoftRandomText

We are creating the module in the DesktopModules folder to allow us easy manual installation and debug facilities.

The new project is called BonosoftRandomText, right click it and rename it to Bonosoft.DNN.Modules.RandomText which will be the name of the Assembly.

We now want to set the project properties, right click the RandomImage project and select properties. In the Common properties General folder, set the Assembly Name to Bonosoft.DNN.Modules.RandomText, then clear the rootnamespace (delete the module name so the field is blank) and press OK.

To use the DotNetNuke API we need to add a reference to the DotNetNuke project, right click the RandomText projects references folder, select Add Reference and in the dialog box, select Projects, select DotNetNuke and press Select and OK.

Now we create a Data Provider project:

In this sample I create a Microsoft SQL server data provider, but repeat the steps for any other provider you would like to provide. The SQL provider uses Microsoft Application Blocks so to make a provider for another database, exchange this reference to the appropriate assembly like OleDataBlocks.

Right click the DotNetNuke Solution and select Add | New Project, select Visual Basic Projects and select Class Library, name it SqlDataProvider and place it at the location C:\Inetpub\DnnFramework\ DotNetNuke\DesktopModules\BonosoftRandomText\Providers

Rename the new project to Bonosoft.DNN.Modules.RandomText.SqlDataProvider and delete the Class1.vb that was auto create for us.

Set the project property Assembly Name to: Bonosoft.DNN.Modules.RandomText.SqlDataProvider
Set the project property Root Namespace to (blank) :

Add references to the Projects: DotNetNuke and Bonosoft.DNN.Modules.RandomText
Add reference to the file (use the browse option) C:\Inetpub\DnnFramework\
DotNetNuke\controls\DataAccessBlock\bin\Microsoft.ApplicationBlocks.Data.dll

In your DnnFramework project Add references to both our new projects, Bonosoft.DNN.Modules.RandomText and Bonosoft.DNN.Modules.RandomText.SqlDataProvider

Now we make all the files we need for the project, so we are able to build and register our module inside DotNetNuke.

First, the RandomText.SqlDataProvider project contains a class file called AssemblyInfo.vb, please edit this to meet your copyright and version requrements. Then create a new class in the RandomText project ( right click the project, select Add | Add Class... and specify AssemblyInfo.vb as the name. Copy and Paste the content of the sql provider assembly info file to the new file created in the RandomText project. This will ensure that your assembly files (dll) is not having a version number of 0.0.0.0 - please do not copy the GUID information.

In the Bonosoft.DNN.Modules.RandomText project:

Create two new classes (Add | Add class) named DataProvider.vb and RandomTextDB.vb, leave the content as it is created by Visual Studio. We will use these files for linking to the DAL and for making a Business logic layer (BLL).

Create two new web user controls (Add | Add Web User Control...)  and name these: ViewRandomText and EditRandomText.

In both user control files, select View Code and find the class definition, change it so the class will extend  from DotNetNuke.PortalModuleControl instead of System.Web.UI.UserControl. The class definition should look like this:

Public Class ViewRandomText
  Inherits DotNetNuke.PortalModuleControl

This is verry important, as this is required for DotNetNuke to load your controls. If you forget the skin class in DotNetNuke will throw a Class Cast Exception in the Load Module method.

In the ViewRandomText control, find and expand the Web Form Designer generated code section and edit the Page_Init method to look like this:

  InitializeComponent()
  MyBase.Actions.Add(GetNextActionID, "Edit Page List", "", _
     Url:=EditURL(), Secure:=SecurityAccessLevel.Edit)

Lets explain what this is... well when your module is placed on a page in the portal, the view control is displaied, and with these commands we are adding the option for users with the security access level edit to have menu items to navigate to the edit control. The EditURL is a DotNetNuke global method to build the correct links to the controls.

In both controls we need to import the DotNetNuke namespace and define a namespace for the module, this is done by wrapping the code for the two controls with these statements:

Imports DotNetNuke
Namespace Bonosoft.DNN.Modules.RandomText
...
End Namespace

Now that we have added a namespace to the module, we need to correct the ascx files to reflect this. The two web controls contains a single line of information a <%@ line with control information. in this line there are a Inherits attribute that needs to include the namespace, so add the namespace to the name like

Inherits="Bonosoft.DNN.Modules.RandomText.ViewRandomText" 

Inherits="Bonosoft.DNN.Modules.RandomText.EditRandomText"

If this has not been done you will get a anonymous error message like "Module not loaded".

In the Bonosoft.DNN.Modules.RandomText.SqlDataProvider project:

Add a class (Add | Add class) named SqlDataProvider.vb

Add two text files (Add | Add new Item... | Text File) named 02.00.00.SqlDataProvider and Uninstall.SqlDataProvider

The version number in the text file starts with 02 because we already made a version 1 for the DotNetNuke 1.0.10 of the RandomText module. When creating your own module use your own version numbers.

Now we have a mock-up of the final module with all the files except for the dnn installation file. If you done it correcly you are now able to rebuild the full DotNetNuke solution and have an empty workin module

Rebuild the DotNetNuke Solution and press Debug Run (F5) and wait for the DotNetNuke portal to be loaded in your browser.

Login as the Host account, select the host menu and Module Definitions. Find the Edit icon at the upper left corner and select Add New Module Definition from the drop down menu. Fill in module name as Bonosoft Random Text, and a description. Then press the Update link.

In the New Definition field enter Bonosoft Random Text and press the Add Definition link.

Press the Add Control Link, find the ViewRandomText.ascx in the source dropdown, and change the type to View. Then press update.

Press the Add Control Link, enter edit in the key field, find the EditRandomText.ascx in the source dropdown, and change the type to Edit. Then press update.

Now click on the Home menu item and the home page is shown, in the top tab admin click on the Add link and create a new tab which we will use for testing the module. Name and place it where you like.

When on the new tab, find the Bonosoft Random Text from the Modules dropdown list, and click add.

Now you see your empty module... and in the edit menu you have a link to the also empty edit control. If you write Hello World in the ViewRandomText web control - you just made the classical Hello World application.

If you get Error loading module, please check that the two assemblies (DLL) files Bonosoft.DNN.Modules.RandomText and RandomText.Sqlprovider are located in the DotNetNuke/bin folder. If they are not - you have forgot to add a reference in the DnnFramework project, or you havent rebuild the complete solution yet.

Now we are only missing the functionality, data layer access and the packaging of the module...

Now we need to make the Data Access Layer, in your DotNetNuke installation there are a folder that has a document explaining the DotNetNuke data access layer in depth, but the verry short version is that we make a business layer which is used in the web user controls. The Business layer uses an abstract base data provider class, which at runtime is overloaded with the actual implementation connecting you to the correct database.

Normal database operation like Create, Retrieve, Update and Delete (CRUD) are very basic thus is an easy target for a code generator, so why code all this basic data access by hand... I have two code generators that is able to produce all these files - so lets use one of these... The professional version fetches the information directly from the database, and it even checks your datamodel for foreign keys and make appropriate methods to navigate between the tables using these references. The free (only requires site registration) version uses a simple web form, where you describe the table you want to use in your module.

When you create SQL script files, DotNetNuke expects the file to be in Unicode format - not ASCII. So when saving the 0x.00.00.xxxDataProvider file - select Advanced Save Options in the File Menu, and select to save the sql script file in Unicode - Codepage 1200.

Free Bonosoft Dal Builder
The free version can be found on this site under Information | Build Data Providers, and it is able to generate source code in both Visual Basic and Visual C#. All the generated source code is roalty free and you can use it in any way you like. Please follow the instructions in the builder module when creating modules of you own, for this sample I will set the company name to Bonosoft, the module name to RandomText, select the Visual Basic language for the source code, and select that each instance of the module will be able to store multiple items (text pages in this case). I fill in the attribute I need (HtmlText as Text) and after selecting the Generate button, a result page is shown with links to all the generated files. You should now go through all the files you need in the project and copy the content and paste it into the mock-up files we generated in a previous step.

Try to rebuild your DotNetNuke solution to verify the generated code.

Development database
When you have copy pasted the files, we need to build the database information on our development installation. Open the SQL Query Analyzer and connect to the development database. Select the database which is used for your development DotNetNuke in the dropdown box, and copy the sql install script from Visual Studio to the edit area. Before you execute the script, do press ctrl H (replace) and replace all {databaseOwner} with dbo. and replace all {objectQualifier} with and empty string (or your selected qualifier).