With your development decisions made, it's time to begin developing your module. In this example, you are going to work with the Events module that is included in the DotNetNuke distribution. This chapter and the next three chapters provide an in-depth study of this module.
At the time of this writing, the DotNetNuke 4.x source code download does not include the module source code for all the modules. This is because the module structure is essentially the same as the 3.2.x version. To obtain the source code for the Events module, download the source for 3.2.x.
DotNetNuke is broken down into several solutions. The primary solution, located in the root directory of the distribution file, contains all the projects that make up the entire core. This includes controls, web forms, class files, and any other files required for the core application. With the release of DNN 4, the solution organization is restructured into more manageable pieces for each specific section of DotNetNuke. The module code is not included in the source download for DotNetNuke 4.x, as mentioned earlier in this chapter. For module developers, there is the module solution located within the <approot>\Solutions\DotNetNuke.DesktopModules directory of the 3.x source download.
Open the DotNetNuke.DesktopModules.sln file in Visual Studio .NET. You will see a solution containing approximately 30 projects, which are the individual modules that make up DotNetNuke. This part of the chapter shows you how to work with a module using Visual Studio 2003, which is essentially the same method you use if you are targeting your module for the ASP.NET 1.1 version of the framework. Later you'll see how to create a module using Visual Studio 2005 and the DotNetNuke starter project.
When you open the solution, you should see the project listings in the upper-right pane (Solution Explorer), as shown in Figure 12-1.
To begin module development, first create a module project within the DesktopModules solution. Several projects are already included in the solution, and in this example you will be using the Events module. To create your own project, step through the following process:
With the Visual Studio .NET DotNetNuke.DesktopModules solution open, right-click the solution at the top of the Solution Explorer. Select Add ð New Project from the context menu. The Add New Project dialog opens.
Select Class Library from the Templates section, provide a name for your module in the Name text box, and click Browse to pick a location for the project files. For module development, select <approot>\DesktopModules\ for the project directory (see Figure 12-2). Your module should now be listed at the bottom of the Solution Explorer.
Notice the BuildSupport project within the solution. This ensures that when you compile your project, your assemblies will be copied to the bin directory of the main DotNetNuke core project; then, any time you make a change in your development code and compile, those changes are displayed in your module when you view it within your portal in a web browser. This eliminates the need to manually copy the DLL file to the bin directory every time you make a change and recompile. To accomplish this, add a reference to your module project to the BuildSupport project as shown in Figure 12-3.
As you can see in the figure, a reference is created to each of the module projects in DNN. For the example used in this and the next three chapters, you can see a reference to the Events module — SQLDataProvider (more about this in the next chapter).
After your module project has been created, follow the same procedure to create your SQLDataProvider project. The only difference for the Data Provider project is the name, which will be ModuleName .SQLDataProvider (depending on your physical provider — if you were using Access, it would be AccessDataProvider). It is generally acceptable to place the Data Provider project in a subdirectory off of your module, so the full path would be <approot>\DesktopModules\ModuleName\Providers\DataProviders\SQLDataProvider\. You then create a directory for each physical database you plan on supporting for your module.
Now that your project has been created, you need to add some controls for your users to interface with and some classes for data operations.
There is a limitation with Visual Studio .NET in adding user controls in class projects: you can't do it. In many cases, developers copy an existing ASCX control from another module project and paste it into their newly created project.
For most modules you need to create three controls:
View control (Events.ascx): The default view users will see when they first access your module.
Edit control (EditEvents.ascx): For updating the data contained in the module's tables within the database.
Settings control (Settings.ascx): For specifying unique values for a particular instance of a module.
The Events module example has all three of these controls.
A member of the DNN Core Team created templates that you can use to install into your Visual Studio .NET application to ease the process of creating controls, as well as project files. They can be freely downloaded from http://dnnjungle.vmasanas.net. In addition, you can download Code Smith templates that will reduce the amount of code needed to create a data provider for your module. You also can download the AtGen SDK module development project at http://projects.apptheory.com — it will generate much of the code necessary for module development.
You also need to create the supporting classes within the module. Generally, you'll have three classes contained in your main module project:
DataProvider class: Contains methods that provide your abstraction layer with the database. These methods will be overridden by your data provider class in the Data Provider project (see Chapter 14).
Controller class: Contains the methods for manipulating and obtaining data from the abstraction layer (see Chapter 14).
Info class: Contains properties that define your objects (see Chapter 14).
The Data Provider project has one class, the DataProvider class, which holds the actual methods for obtaining and updating the data contained within a specific vendor's database (see Chapter 11).
In the Events module, the classes are DataProvider.vb, EventsController.vb, EventsInfo.vb, and SQLDataProvider.vb. We'll get into more detail on what these classes do in subsequent chapters, but for now we just want to cover what files need to be created to begin a module development project.
Now that you have your Visual Studio .NET 2003 projects configured, you need to let DotNetNuke know about your module so you can test your development within your portal. DotNetNuke needs to know the location and type (view, edit, or settings) of your user controls to display them within the portal.
To manually configure your modules in DotNetNuke, log in as the host account. Then follow these steps:
Select Host ð Module Definitions.
In the Module Definitions page, select Add New Module Definition from the menu options (see Figure 12-4).
Enter a Name and Description for your module. Select the check box for Premium if this module requires an additional payment for each portal admin to use the module.
Click the Update link button. Additional text boxes appear for you to enter a definition for the Desktop module (see Figure 12-5).
Provide a name for your module definition. The controls listing appears below the Definitions text box (see Figure 12-6).
Define the location and type of control that you created in Visual Studio .NET 2003. Click the Add Control link button to bring up the Edit Module Control page (see Figure 12-7).
Define a key. For a default view control, leave the Key field empty; for an edit control, use Edit; and for a settings control, use Settings for your key. Keys they provide you with a mechanism to define which control to load at a point in your logic (discussed in more detail in Chapter 15). You can have as many controls as you want within your module — you just need to define a unique key to refer to each one in your code.
Provide a title for your control. It is displayed in the module container when viewing the control in DotNetNuke.
Select a source for the module — this is the actual filename and path to your ASCX control located in the DesktopModules directory. DotNetNuke will iterate through the directory structure and find all controls that are located in module projects under the DesktopModules directory. This is why you want to ensure you are creating your projects using the proper directory paths as described earlier in this chapter.
Select the type of control: Skin Object, Anonymous, View, Edit, Admin, or Host (more on this in Chapter 15).
You can enter in an optional View Order for the control. This is used to manage the order in which your controls are displayed on your module's action menu.
You can select an optional icon to be displayed next to your control. You must first upload the image file to your portal for it to be displayed in the drop-down menu.
Finally, there is an option for the Help URL, which enables you to provide online help for your module.
Click Update. Go through each control that makes up your module project and add a definition. Figure 12-8 shows an example of the definition for the Events module.
Another option on the Module Definitions screen is the capability to create a private assembly. A private assembly enables you to distribute your module to other portals using an automated setup. This is covered in more detail in Chapter 16.
After you define your module, place an instance within a page in your development DotNetNuke. You should see the initial view control after placing the module in the page, enabling you to view and debug your module within a live portal installation. Any changes that you make and then compile are instantly seen in this development page.