DNN Introduction

This is the first of three blog entries that make up a full introduction to DotNetNuke (DNN) from a developer's point of view, with the following pieces covering Skins and then Writing Custom Modules. A concise version of the complete article first appeared on 1 July 2008 in UK programming magazine VSJ.

Overview

DotNetNuke is not a good name for software, but don't let that put you off. Call it DNN, and think of it as a programmable content management system that's open source and runs on ASP.NET 2+ servers. Ie it lets you create and maintain a web site easily.

Although you may be familiar with the basic idea of a CMS, this first article will introduce you to DNN features, terminology and usage before getting stuck into new skins and programmable modules next time.

If you want to use Microsoft technology, DNN lets you deliver a working site with relative ease - it can be handed over to a non-technical site administrator who can do all the regular site updating, eg adding pages, editing text, making announcements etc. Web space at our preferred host Crystaltech starts at US$35 per year for a small site. At that price everyone can have a web site: I set up a badminton club site for a friend and he's now running it with no intervention from me.

There are some problems running DNN in Windows Server 2008 in Medium Trust.

When trying to decide between various systems, you will want to know:

• Is it reliable? We are now running a number of DNN sites with many thousands of users and they seem solid.
• Is it maintained? There are regular fixes and improvements for DNN, eg it now uses AJAX in places.
• Does it have the features you want? DNN handles users well, has a good framework to add functionality, and there are lots of add-on modules available.
• Can I learn it easily? It will always take a while to get in-depth understanding of a new system. With DNN you can set up a basic site on day one, but it might take months to get fully to grips with writing modules. DNN was a bit easier for us as we are used to ASP, ASP.NET and Microsoft hosting. To handle development, staging, production and backup servers, make sure you are able to copy all content and users to another site.

DNN is not perfect. The Text/HTML Editor is not good enough for serious use. Cute Editor and other plug-in editors may be better. They all suffer from not being clever enough at handling complex reformatting - what you see is seldom what you get. Note that users must have cookies enabled to be able to register and login at DNN.

Extensibility

Supplied Modules
Account login
Banner adverts
Feed explorer
Google Adsense
Links
Search Input
Search Results
Text/HTML
User Account
Announcements
Blog
Documents
Events
FAQs
Feedback
Forum
Help
IFrame
Media
NewsFeeds
Reports
Repository
Store
Survey
UserDefinedTable
UsersOnline
Wiki
XML

DNN serves most content using modules, eg a text module comes as standard, along with the others listed below. There's a thriving third-party market for modules, some for free but largely at low cost - usually listed and bought at SnowCovered.com. At phdcc, it is crucial that we can develop custom modules to provide the unique functionality that some web sites need. We have also released some freeware and commercial modules. Custom modules are written as a set of standard ASP.NET user controls, using extra DNN APIs as needed, with the end result bundled into a ZIP for distribution. Custom modules are usually written in Visual Basic like DNN itself, but C# is possible.

If you like to hedge your bets, code in a DNN module could be written to run on a plain ASP.NET system. Or perhaps do it the other way round: for example, the YetAnotherForum.net open source software will run as a standalone web app, but they have added some code and packaged it as a DNN module.

DNN's presentation is determined by skins which define the appearance of the whole site and each module container. Various skins are provided for free, while others are available for purchase at SnowCovered - you can write your own relatively easily. DNN skins tend to use fixed point size CSS definitions so it doesn't scale in Internet Explorer as you change text size - more on this next time and in these previous blog entries: DotNetNuke Internet Explorer fixed size fonts and DotNetNuke Internet Explorer font scaling.

Technology

It is worth saying right now that DNN is almost entirely database and ASP.NET driven. All DNN output is generated from a single ASP.NET page that dynamically loads whatever content needs to be shown, using many levels of ASP.NET .ascx user controls. So the site will not be as fast as from static content, but this is an acceptable price.

Although all DNN requests are run through the root default.aspx, it has a friendly-URL HttpModule that shows a unique URL with pertinent text for each page. Note that the standard menu system is implemented in JavaScript so it does not provide hard links. So make sure that you provide hard links somewhere so that search engines can trundle through your site.

The database can be in SQL Server Express or the full SQL Server. Strictly speaking, the code has been written in a generic way using a provider pattern that allows other database types to be used, but in practice I have only ever seen the Microsoft databases supported.

Doing backups in DNN can be complicated. There are facilities to export and import your site as a template in XML - but I am not confident that this gets a whole site design – and does not store the users. Doing a database backup will probably get most data. However to be certain, you will also need to backup the entire file system as some modules store their data in files.

DNN uses standard ASP.NET forms authentication to handle its users (recently, Windows LiveID as well). After a fresh install, the 'host' account lets you configure the entire site, while the 'admin' account has a reduced set of permissions that is suitable to give to a non-technical site administrator. One "host" DNN instance can have one or more "portals" (one for each site/domain name), so there is one admin account for each portal. We wouldn't recommend having more than one portal - it's not worth the fuss when web space is so cheap. Things go wrong if you attempt to run DNN from a sub-directory, so always make sure that it runs at the root of a domain name - one approach is to set up a sub-domain such as dnn.phdcc.com. On our shared host, we did this by adding an extra DNS Host Record (A) for "dnn" that points to the IP address of a separate hosted web space.

DNN has built-in support for internationalisation, so you can download language packs for DNN itself so that all DNN management will be done in your preferred language, including email templates. Well written modules will use the same techniques but will usually only have English text provided. As I understand it, there is no direct support for showing a particular module (eg French intro text) if the user's browser setting or preferred locale is French.

It is helpful to understand a little of the DNN directory structure. As well as /bin/ and /App_Code/ directories, each supported site has a directory, so the first site portal (with a programmer PortalID of zero) has its file store at /Portals/0/. [Admin][File Manager] opens at this directory. If, with your super powers, you FTP a new file into this directory, then some of the DNN code may not initially see it. There is an option in File Manager to synchronize with the actual files present - don't forget to tick the Recursive box to sync all the sub-directories. You can also synchronise programmatically using the DNN FileSystemUtils.Synchronize method. Finally, the directory /Portals/_default/ contains definitions that are available for all portal sites, eg skins and containers.

DNN has a basic search built in, using the search information provided by each module. However the search will not index file documents such as PDFs.

Downloads

You can get the latest version of DNN, now 4.8.4, from http://www.dotnetnuke.com/ once you have registered. The "Install" package is for production use. Get the "Starter Kit" and "Documentation" packages if you are doing module development - there is a full "Source" release as well. For installation, your primary requirement is a connection string for a database, and you will need to make sure that DNN ASP.NET has full read, write and delete access to the file system. An installation wizard will take you through these options and set up the host and admin accounts. There's also an "Upgrade" package - but make sure that you have done a full backup before using this. When upgrading, you must carefully merge the existing DNN Web.Config file with the new one supplied in Release.Config, in particular keeping the existing ‘machineKey’ element, ‘SiteSqlServer’ connection strings and ‘objectQualifier’ value.

I have one of the standard books, 'Professional DotNetNuke ASP.NET Portals' for old DNN 3. This aims to cover setting up and administering a site, as well as writing skins and modules. I didn't find it very helpful and it is hopeless as a programmer reference as the index does not list the things I looked for. The "Documentation" download has various useful documents, but I seem to have missed a trick somewhere as I haven't found or generated a full DNN API help file. That said, it is great having the full DNN source available so you can look up methods and see how they work.

I haven't ever wanted to alter the main DNN code which is just as well if you want to track upgrades. There's a large developer community at work in the DNN help forums. I made one paltry contribution to sorting out one bug. I have however updated the wiki module to send me an email whenever a wiki entry is updated; I was pleased to be able to compile the wiki project, understand the code, and make my changes with relative ease.

Using DNN

Here's a simple overview of how to use DNN, without endless screen shots. A DNN page is typically laid out as shown below. The current skin defines various panes on the screen where you can place one or more modules. After you have added a module, it appears in a container, a rectangle with a title bar in a style determined by the container skin. DNN is generally very configurable, eg you can switch off the title bar for each container.
When logged in as 'host' or 'admin' you get a Control Panel at the top of the page as shown below - most functions are pretty obvious.
DNN supports various roles that determine which users can do what. Roles can be assigned to the view and edit visibility permissions for each page and module; the File Manager can set up view and write permissions for portal directories. Users who have the "Administrators" role can access everything. The other standard roles are 'All Users', 'Registered Users', 'Subscribers' and 'Unauthenticated Users'. You can set up new roles, for example, a fee-paying role that might be used to allow access to privileged content for say 3 months. DNN has built in support for several payment providers, including PayPal.

Below is an amalgamated screen shot that shows the menu options available to admin and all-powerful host users. Below is a typical Text/HTML module shown with its container title - and a module menu visible to admin users with edit permissions. When you write a module, you can add functionality to the module Settings page, and also add items to the menu itself - in the same way as "Edit Text" as shown.

DNN maintains a profile for each registered user, ie a set of properties of various types. As well as the basic profile properties of Username, FirstName, LastName, DisplayName and Email, DNN has many default properties for your Address, Contact Info, Biography, Time Zone and Preferred Locale. You can delete or add properties and mark individual properties as being required if desired. At program level, each user has a unique UserID; if a user joins with Username 'chris' then unregisters and subsequently someone else joins with the same Username 'chris', then these two users will have different UserIDs.
DNN has a rather fixed user interface for registration and setting your profile. For this reason, our phdcc.Data module has a form generator that lets you build custom alternatives to these facilities.

In conclusion, DNN provides a useful set of CMS/multi-user facilities for Microsoft-technology web sites. Any limitations can often be overcome using one of the many modules available. Everything DNN outputs is code and database driven which makes it harder to backup and understand what is going on. Next time, we'll look in detail at how to set up new skins and program modules.