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.


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.


Palmer Eldritch said...

Hi, thanks for explanation.
I have one question though...
I'm developing module with three tabs. Each tab may be placed on any page. (through copying same instance to another page)
One tab has it's own properties, like items amount on page.
What should I use in this scenario? Tab-Module Settings or Module Settings?

Chris Cant said...

The crucial decision is what your users expect to happen when they copy the module from one page to another.

If you use Module Settings, then when an administrator copies a module from one page to another, the module works instantly on the new page. However, as the settings are common to both instances, any change on one page will instantly change the other page instance; the administrator may not realise this is happening.

If you only use Tab-Module Settings, then copying a module to a new page is effectively equivalent to putting a new instance of the module on the new page.

I can see merits in either approach. If you are only ever using your module yourself, then you should work with whatever you feel happiest with. If distributing to others, then tell them what happens when they copy a module.

Anonymous said...

Hi Chris,
Good to know i'm not the only DNN developer in the UK!, it feels like it some times! Anyway, I need to update tabmodulesettings from a multi-select listbox, any ideas to help me?

Thanks in advance


Chris Cant said...

Hi Andy - good to meet you.
I think you need to iterate through the ListBox Items, testing each ListItem's Selected property.
That make sense? Chris

Parag Nair said...

Hi Chris, Thanks for the explanation. I have seen people handle settings for modules in a really bad way and wanted to know how can I leverage the power of DotNetNuke to manage settings for a custom module which is dropped on different pages. Your article maeks a lot of sense and has been of great help.

iRohan said...

Hi all ,

Please help me on following point.
I want some information about the module setting option .
I have two requirement .
First – when page have “View” Permission I want to define the module setting can accessed by actor.
Second – When the page have “Edit” Permission I want to define the module setting can’t accessed by actor.

Chris Cant said...


In the settings for a page and module, you can set access permissions for different roles in View and Edit mode.

Or: in your code, check the EditMode flag (in PortalModuleBase) and act accordingly.