19 May 2008

DNN module and tab-module settings

If you write a custom DotNetNuke (DNN) module, be careful with your use of the two types of settings that can be associated with an instance of a custom module - there are Module settings and Tab-Module settings. The difference becomes important (a) when you use Add Existing Module on another page and (b) when you Export Content from a module. In general, it makes sense to use the Module settings.

The Module settings are associated with all instances of a module on several pages, while the Tab-Module settings are only associated with one instance (on a single page).

When you copy a module instance to a new page with Add Existing Module, only the Module settings are available on the new page. So, if you want settings to be available after a module has been copied, then use Module settings, not Tab-Module settings.

When a module's content is exported using Export Content, the module controller is called with the ModuleId only (ie without the TabModuleId). This only provides easy access to the Module settings.

Implementation:

Most of the following implementation examples require the use of the DNN ModuleController, obtained as follows in C#:
ModuleController objModules = new ModuleController();

Most custom modules have a Settings user control that appears as a part of the module's main Settings page. When the user clicks on Update, the module setting's UpdateSettings() method is called. To save a Module setting, eg for a CssFile text box, use the following:
objModules.UpdateModuleSetting(ModuleId, "CssFile", txtCssFile.Text);
If instead, you want to save a Tab-Module setting, use the following:
objModules.UpdateTabModuleSetting(TabModuleId, "CssFile", txtCssFile.Text);

The Settings user control is initialised using its LoadSettings() method. The ModuleSettingsBase Settings[] property provides access to the current settings, eg:
txtCssClass.Text = Settings["CssClass"] as string;
Settings[] contains both the Module and Tab-Module settings, with the Tab-Module settings taking precedence.

Within your View control, the PortalModuleBase Settings[] property is the same.

Other methods available are objModules.DeleteModuleSetting() and objModules.DeleteTabModuleSetting().

To implement Export Content, your module controller must implement IPortable. You must then write an ExportContent() method that might start as follows:
public string ExportModule(int ModuleID)
{
ModuleController objModules = new ModuleController();
Hashtable Settings = objModules.GetModuleSettings(ModuleID);
string CssFile = Settings["CssFile"] as string;


Several of my existing modules used Tab-Module settings. I have converted them to use Module settings. I was careful to transfer any existing settings from Tab-Module to Module. I used a "SettingsInModule" module setting set to "done" to indicate that the settings had been transferred. My conversion method was careful to work for brand new modules where no settings exist at all.