DotNetNuke 5 module development tutorial - part 6: The settings control

25. February 2010 23:49

To Visual Basic version

The settings control is used a bit differently from the view and edit controls. On the module settings page the standard settings are always shown. If you create and register a settings control it will be appended to the end of the standard settings and show up at the bottom of the page.
While the edit page is used to edit the content of the module, the settings page handles the behavior of the module.

In our scenario we will create a settings control where you can configure if the product description will be displayed or not. And yes, I know it’s a pretty lame example but at least it doesn’t clutter up what I am trying to show: the basics for creating a settings control.
‘Nuff said, let’s get to work.

Since the configuration of whether to show the product description or not is basically an on/off selection we will use a checkbox control. Open Settings.ascx and make the contents look like this:

<%@ Control Language="C#" AutoEventWireup="false" Inherits="SipidCode.Modules.Products.Settings" Codebehind="Settings.ascx.cs" %>
<%@ Register TagPrefix="dnn" TagName="Label" Src="~/controls/LabelControl.ascx" %>
<table cellspacing="0" cellpadding="2" border="0">
        <td width="150"><dnn:Label ID="ShowDescriptionLabel" runat="server" ControlName="ShowDescription" Suffix=":"></dnn:Label></td>
        <td><asp:CheckBox id="ShowDescription" runat="server" /></td>

Now open Settings.ascx.cs. As you might remember from previous parts the view and edit controls inherit from PortalModuleBase. An important difference with the settings control is that it inherits from ModuleSettingsBase. If you are going to create your controls from scratch, don’t forget this.
ModuleSettingsBase inherits from PortalModuleBase and gives us members necessary for loading and updating settings for the module instance.
As you can see the templates have supplied us with overrides of the ModuleSettingsBase methods LoadSettings and UpdateSettings. Change them so they look like the following:

public override void LoadSettings()
  if (!IsPostBack)
   if ((string)TabModuleSettings["ShowDescription"] != string.Empty)
    bool show;
    if (!bool.TryParse((string)TabModuleSettings["ShowDescription"], out show))
     show = true; // Default to showing the description.
    ShowDescription.Checked = show;
 catch (Exception ex)
  Exceptions.ProcessModuleLoadException(this, ex);

public override void UpdateSettings()
  ModuleController controller = new ModuleController();
  controller.UpdateTabModuleSetting(TabModuleId, "ShowDescription", ShowDescription.Checked.ToString());
 catch (Exception ex)
  Exceptions.ProcessModuleLoadException(this, ex);

No black magic here either. In LoadSettings we get the settings from the settings store and populate our controls (in our scenario we only have one checkbox).
In UpdateSettings we get the settings from the controls and stuff them back into the settings store.
Note that settings are only stored in string form, so you have to convert them to and from strings if they are other types (as our show description setting is a bool).

With the logic in place, let’s look at the resources for this control. Open Settings.ascx.resx in the App_LocalResources folder. Make it look something like this:

Settings control resource file

Here is what the different keys are used for:

ControlTitle_settings.Text: This is the section header text for your settings control.
ShowDescriptionLabel.Help: Tooltip text for the question mark icon by the Show description label.
ShowDescriptionLabel.Text: Text of the Show description label.
ModuleHelp.Text: When the Help link is clicked, this text is displayed.

And this is how your settings control will look in a moment:

Settings custom section

Just a couple of steps left until you can see it for yourself...
Now compile your project so we can go ahead and register the control.
In DotNetNuke, go to Host > Module Definitions. Locate Products in the list and click the edit icon. Scroll down to the Module Controls section and click Add Module Control.
Make the following settings, then click Update:

Settings control definition

Now go to the page where you added the Products module and click the settings icon. At the bottom of the settings page you should now see your settings control as the section with the header Product Settings.
If you play around with the Show description setting you will notice that the product list shows the description regardless of what you set. This, of course, is because we have not yet implemented any functionality in the view control that takes this setting into account.

To correct this, open up ViewProducts.ascx.cs. Locate the ProductList_ItemDataBound event handler and make it look like this (the green section of code is added):

protected void ProductList_ItemDataBound(object sender, ListViewItemEventArgs e)
 if (e.Item.ItemType == ListViewItemType.DataItem)
  ProductsInfo prod = (ProductsInfo)((ListViewDataItem)e.Item).DataItem;
  if (this.PortalSettings.UserMode == DotNetNuke.Entities.Portals.PortalSettings.Mode.Edit)
   Panel prodContainer = (Panel)e.Item.FindControl("ProductContainer");
   System.Web.UI.HtmlControls.HtmlAnchor editLink = new System.Web.UI.HtmlControls.HtmlAnchor();
   editLink.HRef = EditUrl("ItemId", prod.ItemId.ToString(), "EditItem");
   editLink.Style.Add("width", "16px");
   editLink.Style.Add("height", "16px");
   editLink.Style.Add("display", "inline-block");
   editLink.Style.Add("background-image", "url(/images/edit.gif)");
   editLink.Title = "Edit product";
   prodContainer.Controls.AddAt(0, editLink);

  // Show description according to setting.
  Label productDescription = (Label)e.Item.FindControl("ProductDescription");
  bool showDescription;
  if(!bool.TryParse(Settings["ShowDescription"] as string, out showDescription))
   showDescription = true;
  productDescription.Visible = showDescription;


Compile the project again, the go and play with the setting again. The list should now display the description text only if the Show description checkbox is checked.

Tags: , ,

DotNetNuke | Modules | Tutorials


4/20/2010 2:54:44 PM #

Leland Dischinger

Intresting post, i really enjoyed reading it. Smile

Leland Dischinger United States |

5/4/2010 8:29:42 PM #

Phil Stricker

Great stuff.  That helped me out a ton.  Thanks!

Phil Stricker United States |

5/5/2010 1:38:33 PM #


You're welcome! Couldn't make me happier!

Johan Sweden |

5/17/2010 9:29:57 PM #

Rodrigo BDHiv Orellana

Nice text !!
i really learn about module developing with your post
regards from Chile

Rodrigo BDHiv Orellana Chile |

5/17/2010 10:01:54 PM #


That's great! Keep on coding!

Johan Sweden |

5/20/2010 5:47:42 PM #

Thomas Flückiger

Many thousend thanks for this very useful tutorial! I tried starting module development by reading a wrox book on dnn 5, but was disappointed when module development was only described for dnn 4.
Im afraid I would have had to read many hundred pages to get an equal level of information as you provided in this few simple steps!
You saved me days!
Cheers Thomas

Thomas Flückiger Switzerland |

5/21/2010 9:31:32 AM #


That's what I'm here for ;)
Glad I saved you some reading time. Coders want to code, not read! Right? =)

Johan Sweden |

5/21/2010 9:47:28 AM #

Thomas Flückiger

You hit the nail on the head Johan!

Thomas Flückiger Switzerland |

5/30/2010 9:02:51 PM #


Thank you! This tutorial really helped me out a lot.

Urbain Austria |

9/29/2010 11:41:25 PM #

Roberto Barrantes

Exelente paso a paso.

muchas gracias...

Roberto Barrantes Costa Rica |

2/26/2011 3:42:42 PM #

More link for title

hi thanks for the step by step explanation it helps us a lot.

but i have one question if i want to give the link to title which will redirect to the detailed page how can i do can any body expalin me


More link for title India |

11/12/2011 10:09:52 AM #


Thanks for this post.

i am following the same steps ,that you mentioned in this post ,still it produces exception of module action null or module action nothing .....
please help us ....

once again thanks for this post.

Rohan India |

5/11/2012 5:02:28 AM #


Pingback from

HÆ°á»›ng dẫn viết module DNN 5 – DotNetNuke 5 module development tutorial  « Phạm Duy Anh |

6/12/2012 11:09:50 PM #


Clear and nice help!!!!... thanks


9/14/2012 11:54:11 AM #


Thank's for this tutorial!
I'm sorry for my ignorance, but I have a problem:

When I'm in edit mode page it's work perfectly, but when I'm in online mode it doesn't read setting... HashTable Settings is empty... Have You any ideas?

Paola Italy |

9/14/2012 12:39:31 PM #


It's because TabModuleId is different about module in edit mode tab and module in online mode tab... It's possible? How I can solve this problem?


Paola Italy |

10/9/2013 8:01:17 AM #

Chitra Srinivas


I would like to where is the TabModuleSettings "ShowDescription" defined.

Thanks in advance.

Chitra Srinivas India |

Comments are closed

About the addict

Johan Seppäläinen lives in Uppsala, Sweden. He spends most of his days working as a systems architect/developer, specialized in solutions built on Microsoft platforms.
Occasionally there is time for some recreational coding, when he pursues optimal solutions and code zen, mainly in C#. When he is not writing in this blog, that is.