Using Web Part Verbs to Shortcut Web Part Property Configuration

Web part verbs are a pretty useful yet seemingly under-utilised feature of SharePoint web parts. Over my years in SharePoint I’ve seen and created more web parts than I care to remember, yet in that time can never remember seeing one which made use of the handy functionality web part verbs provide. I’m not sure whether it’s through lack of knowledge or lack of necessity, but I thought it would be useful to highlight one scenario where harnessing web part verbs would be valid – a more efficient method of setting web part property configuration.

First though, the obligatory background information. It would be remiss of me to assume that everyone reading this knows what web part verbs are. Most however, including those who think they don’t, probably already do. They’re simply the menu items available when you click the downward arrow in the top right-hand corner of the web part chrome.

Not as many however would know that it is quite easy to get your own items into that menu. This is done by creating custom WebPartVerb objects using one of 3 constructors – one which specifies a client-side function to run in the event the action item is clicked, one which specifies a server-side function to run in the event the action item is clicked and one which specifies both a client-side and server-side function to run – and adding them to a WebPartVerbCollection. You can read about the WebPartVerb class for more information.

Now this opens up a number of possibilities – you can essentially run any code client-side or server-side from these web part verbs, however being in an environment where i’ve worked on so many public facing websites for some time now and the fact that those web parts would rarely if ever expose the web part chrome, this functionality tends to only be available when the page is in edit mode, hence lends itself to configuration actions rather than functional actions.

As such, i’ve decided to slant this post in that direction – showing how web part verbs can be used to simplify the action of configuring a web part’s properties.

Most would be familiar with the concept of web part properties. When you click the ‘Edit Web Part’ verb shown above, you make visible a tool pane in which you can set a number of web part properties. When creating a web part, you can also define custom properties which will also appear in that tool pane. Without wanting to delve into custom ToolParts or EditorParts generally web part properties are displayed based on their type – for instance a string will appear as a textbox and a boolean as a checkbox. So if I wanted to toggle a switch on my web part to enable one display type over another I would create a custom property as a boolean value and conditionally render the web part based on that value.

This is a pretty common pattern when creating generic reusable web parts and trying to minimise the sprawl of custom web parts. The example i’ll show in this post is a visual web part used for searching. The web part will have two views – a simple view and an advanced view, configurable by the user who places the web part on the page.

When simply using a custom property to achieve this, the user must click the downward arrow in the web part chrome, select Edit Web Part, expand out the relevant category, check the checkbox and click OK. It’s not ridiculously painful in SP2010 but it is a little more frustrating in SP2007. I think everyone would agree that such a simple display toggle would be better served with an option that can be selected directly from the menu which is what web part verbs enable. The example can be seen below.

Search in Simple Mode

Search in Advanced Mode

Toggling Display via the ToolPane

Toggling Display via a Web Part Verb

The code required to get this up and running is fairly simple and requires modifications to 3 files:

WebPart.cs

using Microsoft.SharePoint.WebPartPages;

namespace WebPartVerbsExample.SearchWebPart
{
    [ToolboxItemAttribute(false)]
    public class SearchWebPart : System.Web.UI.WebControls.WebParts.WebPart
    {
        // Visual Studio might automatically update this path when you change the Visual Web Part project item.
        private const string _ascxPath = @"~/_CONTROLTEMPLATES/WebPartVerbsExample/SearchWebPart/SearchWebPartUserControl.ascx";

        [WebBrowsable(true),
        WebDisplayName("Advanced Search"),
        WebDescription("Click to show advanced options for search"),
        Personalizable(PersonalizationScope.Shared),
        Category("Custom Properties"),
        DefaultValue("")]
        public bool IsAdvancedSearch { get; set; }

        protected override void CreateChildControls()
        {
            SearchWebPartUserControl control = (SearchWebPartUserControl)Page.LoadControl(_ascxPath);
            control.IsAdvancedSearch = IsAdvancedSearch;
            Controls.Add(control);
        }

        public override WebPartVerbCollection Verbs
        {
            get
            {
                //server-side verb
                WebPartVerb titleVerb = new WebPartVerb(this.ID + "_searchModeVerb", ToggleSearchMode);
                titleVerb.Text = "Toggle Search Mode";

                // return collection with new verbs
                WebPartVerb[] verbs = new WebPartVerb[] { titleVerb };
                return new WebPartVerbCollection(verbs);
            }
        }

        // event gets executed when the user invokes the server-side verb
        void ToggleSearchMode(object sender, WebPartEventArgs e)
        {

            SPWeb site = SPContext.Current.Web;
            SPFile page = site.GetFile(Context.Request.Url.AbsolutePath);
            SPLimitedWebPartManager wpm = page.GetLimitedWebPartManager(PersonalizationScope.Shared);
            SearchWebPart webpart = wpm.WebParts[this.ID] as SearchWebPart;

            //Toggle the search mode
            webpart.IsAdvancedSearch = !webpart.IsAdvancedSearch;
            wpm.SaveChanges(webpart);
        }
    }
}

WebPartUserControl.ascx.cs

namespace WebPartVerbsExample.SearchWebPart
{
    public partial class SearchWebPartUserControl : UserControl
    {
        public bool IsAdvancedSearch { get; set; }

        protected void Page_Load(object sender, EventArgs e)
        {
        }
    }
}

WebPartUserControl.ascx

<div>
    <% if (!IsAdvancedSearch) { %>
    <div>Search</div>
    <div>
        <!-- simple search fields -->
    </div>
    <% } else { %>
    <div>Advanced Search</div>
    <div>
        <!-- advanced search fields -->
    </div>
    <% } %>
</div>

So there you have it, a neat little way to leverage web part verbs to shortcut the need to edit the web part’s properties to set a simple configuration toggle. This makes the page editors life far easier and is definitely a more efficient way to handle such a requirement. Before I finish and on a slightly unrelated note, if you’re looking for an even more efficient way to set web part configuration values in SP2010 then check out Wictor Wilen’s post Improve the experience using Modal Dialogs when adding Web Parts in SharePoint 2010.

Application Settings in SharePoint

One of the most commonly neglected features in SharePoint I find across a number of different projects is the manner in which application settings are managed. Far too often it is left to manually modifying the <AppSettings> section of the web.config file for the relevant web application. Perhaps this is due to legacy behaviour of ASP.NET developers moving into the SharePoint sphere, perhaps its due to environments being small and the risks of manually modifying the file not being exposed. It may be due to organisational process or procedure, or (most likely) it may be because on face value it appears to be the most simple, quick and easy option to maintain some configuration values.

It’s ironic that in projects laced with features and solutions to deploy resources ‘the right way’ that configuration is overlooked and remains a manual process. Aside from wanting to avoid any manual modification of files directly on the server by principle, dangers exist in terms of ensuring the web.config files are the same on all web front end servers. Maintaining application settings this way also requires access to the web.config file (and hence server) itself which wouldn’t be considered best practice, and the act of changing a variable in the web.config directly would cause the application pool to refresh and cause the site to load slowly on the next hit.

I write this post with a tinge of regret – I too have been guilty on multiple occassions of maintaining the status quo and leaving (and even adding to) configuration values maintained manually in a web.config file. So not only should this post serve as a source of information regarding the best practice methods to maintain application settings, but it should also serve as a motivator to myself and others to practice what I/we preach on all future greenfield projects.

Anyone who has studied for or taken the application development exam (70-576) would have noticed that 4 main options consistently get presented for application configuration: web.config, lists, property bags and the hierarchical object store. I’ll discuss each option briefly and provide some situations where the method would be appropriate.

Web.config

Now it may seem like i’m beginning to contradict myself here – I previously mentioned that manually maintaining application settings in the web.config was a BAD idea. It is. The beauty of SharePoint though is that it provides a mechanism to maintain application settings in the web.config file automatically via the SPWebConfigModification class. If you’re wanting to store them in the web.config, then a feature should be created which on activation uses the SPWebConfigModification class to modify the web.config for you. This ensures that the same values are written to the web.config files on all front-end web servers and even ensures they’re consistent amongst new servers added to the farm.

You’re likely to want to use this option if you just can’t pull yourself away from the web.config for variable configuration. At least its a safer method. There are some valid reasons however – it’s reasonably simple to incorporate this functionality and then easy to program with seeing you’re probably used to it already. It ensures values are consistent across all front-end web servers and are available and consistent across the entire web application. It’s also fairly useful for ‘set and forget’ the values – if you’re unlikely to need to change them in the future, then you won’t run into the application pool refresh issue I mentioned previously and will get the performance benefits of the cached settings.

Before running off and using this method however, be warned that the web is littered with issues and problems with using SPWebConfigModification. I’d probably want to avoid making any ‘unnecessary’ changes to the web.config especially for the purposes of setting configuration values considering there are other options available.

SharePoint lists

It almost seems too easy and obvious. SharePoint provides us with these useful things called lists. Most of us would be familiar with or have used database-driven variable configuration mechanisms before. Lists, on face value, are reasonably similar to database tables. Why don’t we use lists for variable configuration? It’s not actually that silly a proposition and is in fact one of the more reasonable options. One of the beauties of using lists is that you get all that SharePoint listy goodness. Versioning, security and an out-of-the-box UI for example. You’re likely already familiar with list-based programming, so that isn’t too much of an inconvenience.

Using SharePoint lists is definitely one of the preferred methods. It’s probably easier to outline some of the reasons why you may not want to use it; a site with lax security restrictions would probably be wise to avoid this method – you wouldn’t want any user being able to modify or delete configuration items or the list itself. If you wanted the application settings to be available to multiple site collections/web applications then you’d potentially end up duplicating the list values across these sites.

There’s another huge advantage to choosing this method. An MVP named Chris O’Brien has written a Config store framework available on Codeplex which makes the option even more attractive and erases some of the drawbacks from choosing it. I’d definitely recommend reading a bit about it in his post A better Config Store for SharePoint sites.

Property bags

This option is perhaps a little less obvious but similarly powerful. A number of SharePoint objects contain a Properties property which stores a collection of key/value pairs. These obviously lend themselves towards being used for storing application settings.

This option is possibly the best one to harness when scope is an important consideration for configuration. It lends itself to being able to maintain numerous variables with different values on a per-scope basis (per web, per web application and so forth).

Like the SharePoint list option, this also benefits from addons which improve the usability and effectiveness of the option. The SharePoint Guidance Library provides the Application Setting Manager which is an API to read and write application settings. Codeplex also has the SharePoint Property Bag Settings project which provides a GUI in Central Administration to manage the settings.

Hierarchical Object Store

This is a farm-scoped store similar to a property bag. It requires custom code to create and is far more complex than the other options, however has the benefit of being able to store more complex types if that’s neccessary. Generally for the purpose of variable configuration though, in my opinion i’d go for one of the other options.

You’d possibly choose this option if you were looking for a global storage option for values or required complex values to be stored. If the values are simple key/value pairs however a farm-scoped property bag would probably be easier to use and do the trick.

WebPart properties

I know I said before there were 4 main options, but I wanted to briefly cover this one too. In the event that your custom web parts require configuration values specific to the web part then it will often make sense to include custom properties editable in the web part itself – they are then able to be set by modifying the settings of the web part.

My initial concept for this post was to include an array of advantages, disadvantages and code samples on each option to more completely highlight where each could be used and how they’re used, however during my research for this post came across an MSDN article written by David Mann titled Managing Custom Configuration Options for a SharePoint Application – it essentially covers in reasonable detail those points and I would strongly recommend reading.

Overall I’d have to say I prefer the SharePoint list method the best. I’m somewhat surprised, I remember thinking a while ago that using lists for application settings would be a bit primitive and that surely the other options which have been provided (obviously for the purpose of variable configuration?) like SPWebConfigModification, SPPersistedObject and the Properties collections would be the best practice method to use. I guess sometimes the easy option actually is the best, and it’s sandbox-friendly to boot.