How to Manually Install a DotNetNuke Module

These instructions cover setting up a dynamic DotNetNuke module in Visual Studio 2010 and manually installing the module in DotNetNuke.  While these instructions are based on DotNetNuke 05.06.03 they are applicable to all of DotNetNuke 5 versions.

These instructions do not cover in detail how to program each piece of the module, but does detail what files are need for a basic dynamic module and how to install them.

For the sake of clarity we’re going to create and install a module called “Widget World” and our company will be “iWidgets”.

If you’ve already install the Visual Studio Starter Kit follow steps A-D, skip steps 1-3 and continue at step 4.

A. In Visual Studio, with your project loaded, right click on the project root and select “Add New Item”

B. In the dialogue select “DotNetNuke Dynamic Module”.  Dynamic Module includes a database backend.  If you do not need a database backend select “DotNetNuke Simple Dynamic Module”.  Clear all text in the “Name” entry box at the bottom of the dialogue, enter “WidgetWorld” and click “Add”.

C. The Starter Kit will automatically add a folder called ModuleName to both the App_Code and DesktopModule folders.  Rename the ModuleName folder to WidgetWorld in both cases.  In the DesktopModulesWidgetWorld folder you can delete the Documentation folder.  You won’t need it.

D. This is the most tedious part.  Open all of the files that were generated by the VSSK.  Find and Replace all instances of “YourCompany” with “iWidgets”.

Skip steps 1-3 if you used the Visual Studio Starter Kit.  Otherwise start here.

1. In your Project create the following folders on the root of your project:

App_CodeWidgetWorld
DesktopModulesWidgetWorld

2. A dynamic module has a database backend, so you will need several database connecting files in the App_CodeWidgetWorld folder:

WidgetWorldController.vb (entry point to the functionality)
WidgetWorldInfo.vb (maps fields to properties)
DataProvider.vb
SQLDataProvider.vb (makes the actual calls to the database)

To get started the only file that needs code in it is the WidgetWorldController.vb.  Copy the following lines into it:

Namespace CUIM.Modules.CUIM_BusinessDir
Public Class CUIM_BusinessDirController
End Class

End Namespace

3. The Desktop Modules file is a bit more complicated and will have several files and folders

01.00.00.SqlDataProvider (build the sql components for auto install)
WidgetWorld.dnn (base manifest file for auto install)
EditWidgetWorld.ascx and .vb (add/edit control)
Settings.ascx and .vb (special settings for the module)
Uninstall.SqlDataProvider (uninstalls sql components for auto uninstall)
ViewWidgetWorld.ascx and .vb

App_LocalResourcesEditWidgetWorld.ascx.resx
App_LocalResourcesSettings.ascx.resx
App_LocalResourcesViewWidgetWorld.ascx.resx

*You don’t actually need any code in these files to install the module, although without any code when you place it on a page in DotNetNuke it will be totally anti-climatic.  🙂

4. Log in to your DotNetNuke site as “Host” and click on: “Extensions” in host menu

At the bottom of the page click the “Create New Extension” Link.

5. In the Create New Extension page select “Module” from the drop down and wait for the page to refresh.  The “Name” field must match the folder name in the file system.  “Friendly Name” should be a user-friendly title.  Description is a general overview of the module.  In our case this is version one, but in subsequent updates you have the flexibility of using build, major revision, and minor revision settings.  Click “Next”.

6. In Module Specific Details the “Folder Name” will be filled in for you.  The “Business Controller Class” entry can be pulled from the WidgetWorldController.vb file.  The general format can be seen in the figure below.

If the module will be exported from one site to another, check “Is Portable”
If the module contains searchable data, check “is Searchable”
If the module will be upgraded at a future date, check “is Upgradable”
If you are the host for the site and will allow users to select modules, but certain modules require payment first, check “is Premium module”

Click “Next”.

7. General info, just fill in these fields with your information.  Click “Next”.

8. DotNetNuke returns you to the Extensions list and you should see the Widget World module listed near the bottom of the module section.  Click the pencil icon.

7. The configure extension settings screen shows all of the information you’ve entered in the install process.  If you’re planning on selling the module, or distributing the module you’ll want to fill in the “License” and “Release Notes” sections.  To complete the setup click on the “Add Definition” link.

This will bring up the “Create Definition” link. The “Default Cache Time” is typically for content that will not change often.  Since our module is databased we expect the content to change regularly so it’s better to leave the cache time at 0 so we always get a fresh copy.  If the content doesn’t change often, setting the cache will decrease load time.

Enter “Widget World” in the friendly name and click “Create Definition”

Click “Add Module Control”

8. Add the View control which is the default control.  Leave the “Key” field blank for this control.  By leaving the “Key” field blank the module will default to this control when the page containing the module is loaded.  The fields left blank and unchecked are not necessary for a basic install, but you can click on the “?” icons to learn more about them.

The “Source” is the View control itself.  Scroll through the drop down list until you find the control “ViewWidgetWorld.ascx”.

Set “Type” to “View” and click “Update”

9. Add the “Edit” and “Setting” controls by clicking “Add Module Control” again and following the layouts below.  Notice that while “Edit” and “Settings” have different key fields, they have the same “Type” setting.

Your “Module Controls” list should now look like this

10. Assign the module to a page by returning to the home page of your site and select “Add’ from the Edit mode Page Functions menu.

 

 

11. On the new page select the module in the “Add New Module” mode and set the Title, Visibility, Pane, and Insert settings as you need them.

And that should do it!

 

Leave a Reply