Introduction We will create the famous Hello World! application as a module for DotNetNuke. It will show a hello message that will be stored in the HelloWorld table in the database. (This tutorial will use SqlServer but it's very similar for other databases) Note: In this tutorial we'll use the templates descrived here. So if you plan to follow the tutorial you'll need them. This will be a very simple module, but will show you the foundations of DotNetNuke module creation. When you finish this tutorial you should have something similar to this: 
To create this module we will use Microsoft Visual Studio.NET 2003 and CodeSmith.  
Keep in mind that this is not a tutorial about VS.NET nor CodeSmith nor SqlServer. It is supposed you have a minimum understanding of VB.NET, CodeSmith and SqlServer. Please if something doesn't work for you read again the instructions and repeat them before emailing me immediately. I'm not going to solve all your problems, but try to show you how things work.
Database First of all we need a table to store the data. So let's create a table on the SqlServer database like this one: 
Things to note: itemID is an Identity column. ModuleID should have a relation to ModuleId in Modules table. Make sure you check "Cascade Delete Related Records", so when a HelloWorld module instance is deleted all data related to this instance is also deleted. Also note that I called the table VMasanas_HelloWorld. It's always a good practice to prefix your objects with a CompanyName noun to avoid possible conficts with other module's tables. We'll do the same for every object in the database.
Imagine another developer builds an extended HelloWorld module with the same table name. Upon installing this module it will drop our HelloWorld table and we will loose all information. This not a great problem in this case, but how about deleting all information on a Customer table?  Now let's create the stored procedures for this table.
Open CodeSmith and find the template StoredProcedures.cst. Doble click on it and you'll see the window below. CodeSmith is a code generation tool based on tables so first thing to do is select the table we just created ("VMasanas_HelloWorld"). You can play with this window looking a the generated code for each option on the left. Note the table prefix (ObjectQualifier). With the same options as below click the Generate button and save the resulting code. 
Now we should create all this stored procedures on the database. Open QueryAnalyzer, connect to your database and copy the generated code here. For this to work you'll need to replace "{databaseOwner}{objectQualifier}" with "". Run the code but DON'T SAVE THE CHANGES TO THE FILE! We'll need the original generated code later.
Project Setup Ok, now we have the database and all related code prepared. Let's start with the module project. Open DotNetNuke solution in VS.NET and add a new project. Make sure you don't select to close the solution but add to it. 
 We'll create this module on the DesktopModules folder and set it's name to HelloWorld. If all goes well your solution should look like the picture on the left.
The project template has created a number of files and folders which we will use in the next steps. Now we need the project to access the database so let's add a new project to build the module data layer. This kind of project is called a data provider. All providers should be build in the Providers folder under \DesktopModules\HelloWorld\. It is important that you use this folder so the templates can find the relative path to your main \bin folder. Navigate to this folder and name the project as HelloWorldSqlDataProvider. The name is very important because the template will use the first part of the name to build the code. 
Data Providers Up to this point the template has built some generic code that in most cases will need some corrections. As you can imagine this template does not have any idea of what tables and databases you're using, so all database related code should be refined. Now we'll build the SqlDataProvider code. Open CodeSmith and use the template Vb SqlDataProvider.cst. Enter the same options as you did in the stored procedures and generate the code. Copy this new code to the file SqlDataProvider.vb. Just replace the last part of the code, where all HelloWorld related methods are defined. Save the file and close. We have finished with it! Wasn't so dificult!
Data Provider Abstract Layer The next required step is to build the Data provider Abstract Layer (DAL). This part will abstract our module from the real database used. If you want to add support for Access or another database, you'll only need to create the related DataProviders (as in the last step) and the specific code for the database (tables and stored procedures). Go to CodeSmith and find the template Vb DataProvider.cst. Execute using the same options as previous steps and copy the generated code to DataProvider.vb. Again, just replace the last part of the code, where the abstract methods are defined. Done!
Business Layer DotNetNuke 2.0.x uses business objects as a way to communciate to the data layer, so we need to build these objects. Open CodeSmith as execute the template named Vb BusinessObject.cst. Here you will see apart from the usual options two new properties: NameSpace and NameSpaceData. Here you should replace the 'PA' part with your actual project name, in this case HelloWorld. Generate the code, copy and replace ALL code in the file HelloWorldBLL.vb. If you used Get as your "SelectPrefix" you should put the Get method between [ ] as Get is a reserved keyword in Vb.NET. We have finished with CodeSmith so say thanks and close it.
View Control We'll start for the easy part: just create a view control and test if it works. Open HelloWorld.ascx and add a label (Label1) with this text "HelloWorld says hello to:" and a datagrid (DataGrid1). To make things more interesting add a hyperlink control in a template column. Your code should be like this one: <asp:Label id="Label1" runat="server">
HelloWorld says hello to:
</asp:Label>
<asp:DataGrid id="DataGrid1" runat="server">
<Columns>
<asp:TemplateColumn>
<ItemTemplate>
<asp:HyperLink id="Hyperlink1" runat="server"
Visible='<%# IsEditable %>' NavigateUrl='<%# EditUrl("itemid",
DataBinder.Eval(Container.DataItem,"ItemID"),"Edit") %>'>
<asp:Image id="Image3" ImageUrl="~/images/edit.gif"
AlternateText="Edit"
Visible="<%# IsEditable %>" Runat="server" />
</asp:HyperLink>
</ItemTemplate>
</asp:TemplateColumn>
</Columns>
</asp:DataGrid>
Add the following code to the Page_Load: Private Sub Page_Load(....) Handles MyBase.Load
Try
Dim objHelloWorld As New HelloWorldController
Dim list As ArrayList
If Not Page.IsPostBack Then
list = objHelloWorld.GetByModules(ModuleId)
Label1.ControlStyle.Font.Bold = _
CType(Settings("HelloBold"), Boolean)
DataGrid1.DataSource = list
DataBind()
End If
Catch exc As Exception
ProcessModuleLoadException(Me, exc)
End Try
End Sub There is a piece of code hiden in the "Web Form Designer Generated Code" you should be aware of. In Page_Init this code declares the options that will show on the actions menu: MyBase.Actions.Add(GetNextActionID, "Add HelloWorld", "", _
URL:=EditURL(), secure:=SecurityAccessLevel.Edit, Visible:=True)
MyBase.Actions.Add(GetNextActionID, "View Options", "", _
URL:=EditURL(, , "Settings"), secure:=SecurityAccessLevel.Edit, Visible:=True)
EditURL function takes 3 parameters: - KeyName and KeyValue. These two parameters can be used to pass a value to the edit page. The value will be passed in the QueryString as "&keyname=keyvalue". You can find an example in the .ascx html.
- ControlKey. This is the same value used when defining this control on the Module Definitions page. As we just want to try the view part of the HelloWorld, delete HelloWorldEdit.ascx and HelloWorldOptions.ascx (if you don't the project will not compile). Now compile HelloWorld and HelloWorldSqlDataProvider projects. If you didn't make any mistake it should compile without errors. Now we will install this module in your DotNetNuke portal, so logon as Host, go to Module Definitions. Add a new module and define it like this: 
Just enter the first control, we don't have the others. And now, add this module to a tab a see what happens. If all went ok you should only see the message "HelloWorld says hello to:". At this moment Edit and Options don't work.
Edit Control Let's add the edit control so we can add and modify some data. To add a new DNN control to a project select Add New. Now choose DNN Module Edit and name this control HelloWorldEdit.ascx. 
Add a textbox control to the control and name it txtMessage. Now for the code: - In Page_Load change the if itemid<>-1 then ... end if to If itemId <> -1 Then
objHelloWorld = objCtlHelloWorld.Get(itemId, ModuleId)
If Not objHelloWorld Is Nothing Then
'Load data
txtMessage.Text = objHelloWorld.message
cmdDelete.Visible = True
Else
Response.Redirect(NavigateURL(), True)
End If
End If - In cmdUpdate_Click put this inside the if page.isvalid then .... end if Dim objHelloWorld As New HelloWorldInfo
objHelloWorld = CType(CBO.InitializeObject(objHelloWorld, _
GetType(HelloWorldInfo)), HelloWorldInfo)
objHelloWorld.ItemId = itemId
objHelloWorld.moduleId = ModuleId
objHelloWorld.message = txtMessage.Text Dim objCtlHelloWorld As New HelloWorldController
If Null.IsNull(itemId) Then
objCtlHelloWorld.Add(objHelloWorld)
Else
objCtlHelloWorld.Update(objHelloWorld)
End If
Response.Redirect(NavigateURL(), True) - In cmdDelete_Click put this code inside the Try ... Catch block If Not Null.IsNull(itemId) Then
Dim objCtlHelloWorld As New HelloWorldController
objCtlHelloWorld.Delete(itemId)
End If
' Redirect back to the portal home page
Response.Redirect(NavigateURL(), True) Depending on how you named the methods you should change the HelloWorldController methods here accordingly. Rebuild the project, go to you Portal, add this control definition (as showed in the previous step) with Edit controlkey and try it. Now you should be able to add and edit messages.
Options Control To complete this tutorial we'll build an options page. Add a new control as you did in the previous step but now choose DNN Module Options and name it HelloWorldOptions.ascx. Add a CheckBox control (Checkbox1) and set the text property to "Header in bold". In Page_Load add this code: ' Load settings
CheckBox1.Checked = CType(Settings("HelloBold"), Boolean) And in cmdUpdate_Click this one 'Update(Settings)
objModules.UpdateModuleSetting(ModuleId, "HelloBold", _
CheckBox1.Checked.ToString) Now you can rebuild the project, add this new control definition (with Settings controlkey) and test how it works.
And That's All Folks! You have now a wonderfull HelloWorld module for DotNetNuke!
Packaging If you want to distribute this module as a PA you should package all required files in the provided zip. If you did follow my instructions you shouldn't have to change the HelloWorld.dnn file too much. To be sure it is correct, check the files listed inside to see if are same you created. The zip file should include the following files: - HelloWorld.ascx
- HelloWorldEdit.ascx
- HelloWorldOptions.ascx
- VMasanas.DNN.Modules.HelloWorld.dll (dll for the module project)
- VMasanas.DNN.Modules.HelloWorld.SqlDataProvider.dll (dll for the dataprovider)
- HelloWorld.dnn (install file)
- icon_HelloWorld_32px.gif
- module.css
There are two more files which need to be included: - 01.00.00.SqlDataProvider. This file will contain the code generated in step 2 (Database). Remember we saved the code to a file? Copy the code generated to this file and include it into the zip. The first part of the name should be the same number that's on the dnn file (<version>01.00.00</version>). This file will be executed when this PA is installed in DotNetNuke.
- uninstall.SqlDataProvider. Here you need to put all the code needed to cleanup database when the module is uninstalled. In our case it should include drop statements for stored procedures and HelloWorld table.
You'll will find these two files in the HelloWorldSqlDataProvider folder. Now make sure HelloWorld.dnn contains a section <file>
<name> .... </name>
</file> for each file included in the zip, except for itself. To test the PA install package you'll need a clean DotNetNuke portal, where HelloWorld is not already installed. | 
