Downloads
The Custom configuration feature
Written by: Margriet Bruggeman, Nikander Bruggeman.
February 19, 2009
Thanks to the sharp eyes of Tony Yin (thx Tony!) we were able to improve the custom configuration feature (aka the custom application configuration, the name under which it is known at codeplex). The custom configuration at the list level was only targeted towards document libraries (because the Location property of the <CustomAction> element was targeted towards Microsoft.SharePoint.ListEdit.DocumentLibrary). We've changed this so it targets to other types of lists as well (by targeting the Location property of the <CustomAction> element towards Microsoft.SharePoint.ListEdit). You can download version 1.1 of the custom configuration feature here, and we'll post an update to codeplex as well.
December 8, 2008
When it comes to storing application configuration settings there are lots of options available to you. Currently, we favour storing app config settings in SharePoint itself and allow administrators to control those settings via the user interface at various levels.
If you choose to store app config settings in SharePoint two options jump out as being particularly interesting: the hierarchical object store and the various SharePoint property bags. For a discussion of the hierarchical object store versus SharePoint property bags, please refer to a previous blog post we’ve written about this topic called "Hierarchical object store vs. Property bag".
In the past, Scot Hillier has blogged about using the hierarchical object store to hold web application settings in an article called "Managing the Hierarchical Data Store" and he has taken the effort to create the Manage Hierarchical Object Store feature (to be downloaded at http://www.codeplex.com/features) which adds a nice UI that allows you to manage those web app settings.
In addition to having the ability to store app settings at the web application level we find we generally need to store app settings at other levels as well, at least at the site collection, site, list and web part level. Storing web part app settings is easy, out of the box there’s a nice way to interact with web part properties, so there’s no need to address that. To add the possibility to control site collection, site and list app settings via the user interface, we’ve written a feature that adds those capabilities.
To create this feature, which we’ll call the Custom configuration feature, we’ve taken the liberty of taking the code written by Scot Hillier from the Manage Hierarchical Object Store feature and changed it so it suits our needs. There are two major differences:
- Our custom configuration feature allows you to specify app settings at the site collection, site and list level (and not the web application level).
- Our custom configuration feature uses the site and list root folder property bags to store app settings (and not the hierarchical object store). We prefer to use property bags instead of the hierarchical object store for performance and stability reasons.
Later on, we’ll try and see if Scot Hillier wants to add the Custom configuration feature to his Features project on Codeplex, but for now you can only download the Custom configuration feature here.
Installing the Custom configuration feature is pretty simple. Just download the SharePoint solution file called Custom.Configuration.cab and store it somewhere on the server. Open a command prompt, navigate to the folder that contains this cab file and add it to the SharePoint solution store, then deploy it. To accomplish this, you need to type the following commands:
stsadm -o addsolution -filename CustomConfiguration.cab
stsadm -o deploysolution -immediate -name CustomConfiguration.cab
stsadm -o execadmsvcjobs
iisreset
At this point, SCA should display the custom configuration solution, as can be seen in the next figure:
If you want to uninstall the solution, you need to open a command prompt and type the following commands:
stsadm -o retractsolution -name CustomConfiguration.cab -immediate
stsadm -o execadmsvcjobs
stsadm -o deletesolution -name CustomConfiguration.cab -override
iisreset
After adding and deploying the solution, you need to activate a site collection feature called Custom configuration settings. You can do this via the user interface:
1. Go to the Site Settings page of a site collection.
2. Under section Site Collection Administration, click the Site collection features link. This opens the Site Collection Features page.
3. Locate the Custom configuration settings feature and click the Activate button.
This activates the feature. Alternatively, you can open a command prompt, navigate to the Features folder in the 12 hive and type the following command:
stsadm -o activatefeature -name CustomConfiguration -url [URL site collection]
iisreset
You can deactivate this feature via the user interface or via the following command:
stsadm -o deactivatefeature -name CustomConfiguration -url [URL site collection]
iisreset
The next figure shows the custom configuration settings site collection feature in deactivated state:
The following procedure explains how to use the Custom site config settings:
1. Open the Site settings page of any SharePoint site.
2. In the Custom site config settings page, click the Custom site config settings link. This link is shown in the next figure:
3. This opens the Custom site config settings page. This page provides all current site config settings, which is shown in the next figure:
4. If you press the New button, you’ll be taken to a page that allows you to add a new application setting at the site level. If you click on the Edit button, you‘ll be taken to a page that allows you to adjust an application setting. This is shown in the next figure:
The following procedure explains how to use the Custom list config settings:
1. Open the List settings page of any SharePoint list.
2. In the General Settings section, click the Custom list config settings link. This link is shown in the next figure:
3. This opens the Custom list config settings page. This page provides all current list config settings, which is shown in the next figure:
4. If you press the New button, you’ll be taken to a page that allows you to add a new application setting at the list level. If you click on the Edit button, you‘ll be taken to a page that allows you to adjust an application setting. Adding a new application settings is shown in the next figure:
Please note that the Custom configuration feature requires site admin rights, otherwise, you won’t be able to open the config management pages. If you don’t want this, you should comment out the following code in both .cs files that can be found in the CustomConfiguration folder of the LAYOUTS folder of the 12 hive:
protected override bool RequireSiteAdministrator
{
get
{
return true;
}
}
Reading application settings is pretty easy once you have a valid reference to a SharePoint site or list. For instance, if you’re able to access the SPContext object you could use the following line to read an app setting for the current SharePoint site: SPContext.Current.Web.Properties[strKey];
And you could use the following line to read an app setting for the current SharePoint list: SPContext.Current.List.RootFolder.Properties[strKey]
If you need to access SharePoint site collection settings, just read the properties of the root web site of a SharePoint site collection.
As a side note, since all our custom application pages make use of the application.master Master page file they have inherent support for breadcrumb navigation. In our development environment we’ve just added some nodes to the layouts.sitemap file in the App_bin folder of the SharePoint web application that hosts our custom configuration feature and added the appropriate navigation info.
To add navigation info for custom site app config settings, locate the <siteMapNode title="$Resources:wss,settings_pagetitle" url="/_layouts/settings.aspx"> node and add the following nodes right below it:
<siteMapNode title="Site configuration" url="/_layouts/CustomConfiguration/SiteConfig.aspx">
<siteMapNode title="Adding a site configuration setting" url="/_layouts/CustomConfiguration/AddSiteConfig.aspx" />
</siteMapNode>
To add navigation info for custom list app config settings, locate the <siteMapNode title="$Resources:wss,lstsetng_settings" url="/_layouts/listedit.aspx" requiredParameters="List"> node and add the following nodes right below it:
<siteMapNode title="List configuration" url="/_layouts/CustomConfiguration/ListConfig.aspx">
<siteMapNode title="Add list configuration setting" url="/_layouts/CustomConfiguration/AddListConfig.aspx" />
</siteMapNode>
As stated before, adding navigation info like this is okay on a development environment. You’d actually be better of configuring a custom sitemap provider in the web.config file of the SharePoint web application hosting the custom configuration feature, create a new site map file and create a new master page file that refers to your custom site map. The article "Implementing Consistent Navigation across Site Collections" written by Sahil Malik discusses how to do this.
As a final word, you’re welcome to use our custom configuration feature. It’s community software and it’s free, so we’re not providing official support for it and using it is at your own risk (although the source code is provided in the solution). Having said that, if you find a bug in it, please let us know (info@lcbridge.nl) and we’ll try to fix it.