Module Settings - A Developer Convenience

Often you will need to store configuration properties for your custom feature. For example the Contact Form Feature has a setting for the email address to send the message to when the form is posted. This is an instance level setting because I could have more than one Contact Form with different email addresses, so each instance of the Contact Form needs to store the instance specific setting somewhere.

You get to the Module Settings page for a feature instance by clicking the gears icon next to the title. There you will see a few core module properties defined in the SiteModuleControl base class and then you will see any custom feature specific module settings.

You could implement your own system for managing settings in your feature, and for very elaborate features that may be the best way to go. However, for simple scenarios, you can save some development effort by using the Module Settings system included in mojoPortal, which allows you to store arbitrary properties that can be serialized as strings. You can define your settings as using either TextBox or CheckBox. When you use TextBox, you can also specify a Regular Expression used to validate values entered for the setting.

Implementation

It is possible to define new module settings using the Site Administrative Features under Admin Menu > Feature Definitions > Feature Definition Settings, but typically its easier to just specify them in the FeatureDefinition file and then visit the Setup/Default.aspx page to run setup. It will add any missing Module Settings to the database based on your configuration file. Typically you put the FeatureDefinition files beneath Setup
 Applications
   YourApplicationName
     FeatureDefinitions

See the examples for the included features under Setup/applications/[feature-name]/FeatureDefinitions

There is also more information about feature definition files in the article Using the Installation System.

Deleting Unused Module Settings

Note that the setup page can process your feature definition file to add or update module settings but it does not delete settings that you may later remove from your feature definition file. To do that you would need to use a sql upgrade script with syntax like this example:

DELETE FROM [dbo].mp_ModuleSettings
WHERE
ModuleID IN (SELECT ModuleID FROM [dbo].mp_Modules WHERE FeatureGuid = 'yourfeatureguid')
AND SettingName = 'yoursettingname'

DELETE FROM [dbo].mp_ModuleDefinitionSettings
WHERE FeatureGuid = 'yourfeatureguid'
AND SettingName = 'yoursettingname'

GO

Using Module Settings from Code

In the code for your ModuleControl (which must inherit from SiteModuleControl, not UserControl), add a using statement for mojoPortal.Web (if not present):

using mojoPortal.Web;

Then, you can access settings from the intrinsic hashtable named Settings like this:

Settings["ContactFormEmailSetting"].ToString();

or

UseSpamBlocking = WebUtils.ParseBoolFromHashtable(
Settings, "ContactFormUseCommentSpamBlocker", false);

If your feature has supporting pages like the Blog and Forums do, you may need to be able to look up these settings from there too. Add a using statement for mojoPortal.Business (if not present):

using mojoPortal.Business;

Then you can get them like this:

Hashtable moduleSettings = ModuleSettings.GetModuleSettings(ModuleID);
ShowCategories = WebUtils.ParseBoolFromHashtable(
moduleSettings, "BlogShowCategoriesSetting", false);

For more complex settings, you can implement a UserControl (ie .ascx) and implement ISettingControl. An example implementation is  /Controls/GMapTypeSetting.ascx, which is used for choosing the map type in features that have Google maps. You can look at /Setup/applications/googlemap/FeatureDefinitions/50020_GoogleMapModule.config for an example configuration.

Updated 2011-07-21 Jamie Eubanks
Updated 2011-12-27 Kerry Doan

Created: Sep 04, 2007