Rapid Module Development for DotNetNuke
- Copyright 2006 Mark Hoskins
Before there were web parts, DotNetNuke created installable private assemblies nicknamed Modules to encapulate the functionality desired within a modular environment. It doesn't take much experience developing Modules for DotNetNuke before you start asking the age old questions. I know its powerful, but where do I start? I know this is handled in dnn, but how? How do I structure the module and create the installable package? At this point you are most likely starting to think instinctively about how to utilize a combination of existing tools and reusable code or templates to streamline development time.
In the DotNetNuke community one of the most commonly asked questions is how to integrate CodeSmith or MyGeneration templates to create the Data Abstraction Layer (DAL). This article will hopefully open new paths of development by discussing a complete set of methods and tools to rapidly create modules for DotNetNuke. Although creating a series of templates that will cover the variety of elements required for even the simplest module seems like a daunting task in itself that requires learning a new variety of languages, there are a few packages that have been circulated that consist of all the rudimentary elements to use CodeSmith to auto-generate the data access methods and database scripts. The actual coding and creation of the business objects, the user interfaces and the construction of the project itself remains entirely manual when using CodeSmith to generate the CRUD.
The DAL Builder Pro tool by BonoSoft enhanced this functionality by generating a fairly complete module from the tables of a database, but still the actual coding and creation of the user interfaces and the construction of the project itself remains entirely manual. With the release of the DNN SDK from AppTheory, all this has changed.
Understanding Custom Business Objects
When DotNetNuke adopted the provider pattern for its datalayer, many developers who were familiar with creating methods using hardcoded Sql queries, Sql helper functions, or DotNetNuke's own SqlCommandGenerator class were left with a new process shrouded in mystery. A very common question is how the DataProvider and SqlDataProvider combine to supply the dataaccess functionality. The relationship exists as a type of contract held between the two parties, enforced by the methods, their parameters and return types. When something is changed in the DataProvider, those changes must be reflected in the SqlDataProvider and visa versa. Because the SqlDataProvider, as a separate project, contains a reference to the module project which houses the DataProvider class, any changes to the DataProvider will show up as errors in the SqlDataProvider, because the signature of the methods, parameters or return types do not constitute a match for the MustOverride methods provided by the DataProvider. Likewise, those same changes in the DataProvider will show as errors in any code that invokes those methods until the contract is restored. It is very helpful to complete these changes in a common fashion tailored to your development tastes, so that when changes occur it is fairly transparent to the developer which code was changed, and which is showing errors because it requires changes, or you could find yourself undoing necessary work to attempt to restore that contract. As always, it is best to have a prescribed development protocol to follow.
One of the nicest features of he DNN SDK is how you can regenerate specific parts of your module code to update only what is necessary after changes to the database,which saves all that hassle but leaves your sensitive business logic intact. In other cases you need to regenerate vast portions of the module, possibly adding new controls to handle the data entry for a new table or columns, but still need to leave the business logic intact. Thos too is handled by using an inherited stub class as the generated business layer, so all of your custom changes can exist side by side without fear of losing the code when regenerating.
Central to understanding the DataProvider pattern is the way that DotNetNuke uses a Custom Business Object (CBO) to supply a strongly typed class for each object. This class exists solely to house the public properties and the private variables which represent the results of the DataReader. This type of classes are called info classes and for best results in a wide variety of use cases, should be stored in a separate assembly or project than the rest of the module. By storing these property classes in their own assembly you guarantee the utilization of these classes without requiring a reference to the business or presentation classes. In the DNN SDK module structure, the info classes are actually contained within the central project for simplicity, which is suitable for most modules.
The CBO serializes these info classes into their respective types, passing the classes through the DataProvider to the selected SqlDataProvider, or Access/Oracle/MySql provider. Until recently, there was no definitive tool to aid in the creation of these info classes, their accompanying logic classes, or their DataProvider methods which remained a cumbersome and time consumptive burden for developers who were sure there was a better way to spend their time.
The DAL Builder from BonoSoft is a popular application which takes a defined data structure and produces the data layer for you, and has become a popular and timesaving utility with a low pricetag. The DNN SDK from AppTheory takes all of this to a new level by adding not only complete generation of the stored procedures, dal, cbo and info classes, but as well creates the module project in its entirety. In fact, the module itself can be compiled with the open source tool nAnt using the accompanying build file included in any DNN SDK generated module package.
To those who are already familiar to auto code generation tools, this may not seem like a revolutionary accomplishment, but the best part about DNN SDK is that it is completely free, and it is tightly integrated with MyGeneration (which is also free). Overall, the ease of use and the lack of a learning curve to use the tool could allow someone without any technical or development skills to quickly generate a complete, ready to install module in under ten minutes from any existing database tables!
Although this article is not intended to be a tutorial on how to use any of these tools, it is essential to understand the available products that can dramatically increase your productivity. For a complete tutorial on the AppTheory DNN SDK click here. The remainder of the article will show the steps required to plan, create and implement a module for DotNetNuke, and demonstrate how incredibly easy these tools can make your development cycle.
1. Designing the Database Tables
Because the database is such a centerpoint of code generation, the tables must be created with a few things in mind to produce the most effective, complete result when the module is generated.
A) Each table that will be used in the generation process must have a single primary key field, which is set to Auto-Increment. DNN SDK has a few problems with tables with multiple primary keys where it does not generate the corresponding components correctly so a single primary key should be considered a requirement when designing these tables for code-generation.
B) Foreign Key Constraints should be enforced between the related tables directly corresponding to your module. These Foreign Keys are essential to the generation of a complete module that follows the rules set forth in your database. With foreign keys fields, there is auto-generation of the stored procedures that filter the results to the foreign keys, which saves considerably on coding later. For example, if you have a table named Pages with the three columns PageID (primary), PageName, and ChapterID (foreign key from the table Chapters), the DNN SDK will automatically create the stored procedures and business methods to return the results by PageID or ChapterID.
2. Understanding the DotNetNuke Module Structure
There are many articles found at popular resource websites that are devoted to explaining the Why of the Module File Structure, and explain the necessary dependencies with other assemblies in order to maximise your modules integration with dotnetnuke, so in this part of the article I will focus only on the structure that is produced by DNNSDK so you have a complete understanding of the pattern.
3. Using DNN SDK to create your module
First, we will open the DNN SDK Master Template in MyGeneration by clicking on the desktop icon, or the start menu.
<image 1>
Now we need to Run the template within MyGeneration by clicking on the Play button. This loads the DNN SDK program and begins the setup of your custom module.
<image 2>
The CRUD tab contains the elements for configuring the Data Abstraction Layer for your module, including the CRUD Stored Procedures. After selecting a database to use, select the related tables pertaining to this module. It is essential to follow the steps defined in Designing the Database Tables for complete CRUD generation during this step. In most cases you can leave the defaults for the prefixes of the different CRUD actions, but it is very important to properly name your module project now by choosing a unique, case sensitive name for the Project Name field, which corresponds to the naming convention of your other modules.
Now you are ready to save the settings you have defined, so you can regenerate the DAL for this module later if something changes in the database design down the road. I generally just name the template the same as my project name, like Initials_ProjectName_DAL. Once the template is saved, click on the Generate button to create the SQL scripts and add the stored procedures to your database.
There are a couple quirks in the database script creation that still need some fleshing out, but overall this works extremely well.
<image 3>
Now that the CRUD is created, you are ready to create the rest of the module. On the Module Code tab, you need to define a few properties to define this module. The Project Name should be the same as the one you defined when creating the CRUD template, and is case sensitive. Select the database to use for this module, generally the same one as you used in the CRUD generation, then click View Objects to confirm the generated objects are what you desire. This will show a list of the Stored Procedures and Tables in your database that were created using the CRUD template.
Fill in the Company Name, which is generally the initials of your company. Then fill in the Schema Prefix, which is usually the same as the project name. In most cases, I suggest you leave the Object Qualifier field empty.
Now just the final settings and your module will be ready to generate. There are two types of project references you can choose for your private assembly, which determines if the reference to the DotNetNuke assembly is a Class Project, or a Web Project. I suggest to use a Class Project as the reference type for your modules, as this choice allows for easier project management later, and decreases the build time.
The GUIDs that are generated for your module must be unique to this project, and are preset. You should not need to change these settings. Now select "Everything" in the Code Generation drop down list to create the complete module project. As in the CRUD step, you should save these settings prior to code generation, so that you can regenerate the module code later if anything changes in the database. Now just kick back, and click the Generate button to watch the magic happen.
<image 4>
Now we can run Nant to build the module and package it for installation into your portal. There is one quirk that must be dealt with prior to building in nant. First, open up the dnn manifest file, which was created in the module folder, using notepad.
Find the line: <businesscontrollerclass>CompanyName.ProjectName.ProjectName.BusinessController, CompanyName.ProjectName</businesscontrollerclass>
And change it to read: <businesscontrollerclass>CompanyName.ProjectName.ProjectNameBusinessController, CompanyName.ProjectName</businesscontrollerclass> (remove the extra period before BusinessController)
Now you can go to the command prompt in windows, and type "Nant -buildfile:" , then open up a new window and browse to the folder that you just generated, and drag the file named CompanyName.ProjectName.build into the command prompt window. Just click enter and Nant should produce a complete, compiled and packaged module for you with the Source and Install packages placed into the same folder as your module code.
4. Designing the view and edit controls
Dotnetnuke modules consist of a View screen which represents the public or outward facing UI element of your module. All privately accessable edit screens, or administrative screens are accessable by a variety of ways. The first and most common is through the admin menu within the module container which appears once you are logged into a role within your portal that has edit access for this module, this is called the module actions menu. When you generate the module using the dnnsdk, these screens are determined by the tables you selected during the CRUD creation phase. The Create, retrieve, update, and delete functionality is visibly displayed through the use of a generic, yet quite powerful series of screens for each table in the schema.
The Add screen is shown in the module actions menu as well as the bottom of the container. Some containers may not expose this control, so if this functionality is desired then ensure your selected container for the module admin container includes the links token.
The list screens show a datagrid of the entries for that particular table, with ability to edit, delete or add to the table. A few really handy features of this screen are that you can select numerous items and delete them, and this list includes full integration of the dotnetnuke pager control for simplified paging and sorting of the results.
The links on the listed items in each table can be selected and display a detailed edit screen, allowing you to alter the selected item. The edit and add screens are actually comprised from the same usercontrol, so the bulk of your development work for the administration screens lies within this area.
Out of the box, although this module can be installed and placed onto a page, there are several areas that need further customization. The admin screens are created using only textboxes for the corresponding data entry areas for each table. You will need to define some of these as dropdownlists if they represent a foreign key or a series of values, or as a checkbox for boolean fields. This part will generally consume a fair amount of the development time required to create your module.
You will notice that the default View screen that is visible when you first place the module on a page is blank. You will need to specify what to show to Viewers of this module. Because the entire administration, data and business layers are already created, you can leverage these elements to substantially create the View screen which is presented. Other than customizing the admin screens, this is essentially the only major part of the module that will need to be created by a developer. In this screen there is no definitive example because the display essentially comprises the outward facing elements of your module. This screen could be an advanced calendar as the central part of a detailed booking system, or a complete human resources system, this is really where you, as the developer, become empowered.
5 . Deploying the module
If you have Nant installed and created your module using dnnsdk, you can easily build a deployment package for your module by using the build scripts provided. If not, the other method is a bit more laborious, but is important to understand. The folder structure of dotnetnuke is designed to place all installed modules in their own folder under the desktopmodules folder in your website root. Your deployment package requires a .dnn manifest file to be included so that the module installer can determine what to do with the package. The .dnn manifest file defines the folder name for the module, the files, the control definitons for view, settings and edit controls, as well as the interfaces this module implements. If you are making changes to the .dnn file, it is imperative to preserve the integity of the xml schema. You can find an explanation of this schema in the dnn source or install packages.
as you can see from the above steps, the creation and deployment of the fabric of your new custom module can be dramatically improved by utilizing the dnnsdk, leaving your precious development time better spent doing more productive things like playing games on your xbox.
Happy coding. Mark Hoskins - December 2006