Customizing the user experience of SharePoint: Modifying the default experience (Part 2 of 6)

Hey, we’re back, and it’s time to get our show on the road once again. This is the second part of a six part series on customizing the user of SharePoint.

The Customizing the User Experience of SharePoint series aims to explain how the user experience works, from how the interface is built down to details on how columns of lists  get created.

The series is also an exclusive preview of the topics from my upcoming book, “Building the SharePoint User Experience”, which, in my completely non-biased view of the world, will be the best SharePoint book ever written. To back up that claim I will refer to a recent study showing that a massive 100% of the people to which I am married thinks this will be the best SharePoint developer book ever written. Can’t beat statistics and surveys.

This article will be shorter than the previous one, and we will focus most of our attention on some simple things we can do to modify the built-in experience.

In this article our focus will be on some of the options available to us for customizing the default out-of-the-box experience. We will address multiple options and pay particular attention to what will break our support from Microsoft.

Oh, and if you didn’t read the last article, do so, and pay particular attention to the disclaimer. You break it, you buy it.

Customizing menus

If you look at a Basic Meeting Workspace and check out the Site actions menu you will find that it looks a bit different from the regular Site actions of, say, a team site. Specifically you will notice that there are two links on the bottom to add and manage pages that are not present in the team site menu.

Now, we know that the site definitions that come with WSS, such as team site and all the meeting templates, are built using tools that are available to everyone. There is not cheating involved, meaning we should be able to find out how the extra menu items are created, and we should be able to do the same thing without too much problem. So, let’s go hunting again…

There are actually several ways to add menu items to a menu in SharePoint and we will look at a few options here.

ASPX method

Our first clue comes if we look at how the site actions is actually created in the master page. Open the mwsdefault.master file located in [12]\TEMPLATE\Global folder. Remember that the [12] notation means the 12-hive, usually located in “c:\Program Files\Common files\Microsoft Shared\web server extension\12″ folder. This file, as we learned in the last article, is the master page used for the Basic Meeting Workspace as well as several other meeting site definitions. Thus, it stands to reason that the site actions menu, which is present in every page, should be located in the master file.

Sure enough, if you scroll down about 145 lines (Visual Studio gives you line numbers) to line 146 you will see the start of the Site Actions menu. It begins with a TD like this:

Inside that TD is a lot of ASP code, but our primary focus is on a component tag called SharePoint:SiteActions. Before we get there, though, I would just like to point out two tags located just before the SiteActions tag, namely the Meetings:CustomToolPaneManager and the Meetings:PropertyBag tags. I will explain what these do in a moment, but for now, just remember that they are there.

The SiteActions tag contain a FeatureMenuTemplate tag which in turn contain a lot of MenuItemTemplate. These look strangely related to the options available on the Site Actions menu. If you examine them closer, for instance the MenuItemTemplate with an id of MenuItem_Create you will certainly find that it links to the Create.aspx application page. Same thing for the remaining MenuItemTempate tags, they all match the choices available to us in the Site Actions menu. We have found it!

MenuItemTemplate tags are incredibly powerful and flexible, and you can use them to create a very rich but still user focused experience. You can customize them to do whatever you want, show different items to different users,

There are a few things worth noticing about the MenuItemTemplate tags. First of all, notice the MenuGroupId of 100 of the first three items and a MenuGroupId of 200 for the last two items. Do you remember in our site actions, there there was a line break between the first three and the last two? Hm… Make a guess as to what this means.

The Sequence attribute tells SharePoint the sequence for rendering the items, going from low to high. This sequence is scoped locally to a MenuGroupId so that even if the sequence of Add pages and Manage pages are lower than that of Site Settings they are still rendered after Site Settings.

There is also a ClientOnClickXXXXXX for each item, with XXXXXX being either Script of NavigateUrl. These should be self explanatory, but note that the last two MenuItemTemplate tags refer to a javascript function called MtgTlPart_ShowToolPane. That function is not part of any normal master page. Remember that Meetings:CustomToolPaneManager tag we saw earlier? That tag generates the javascript function used to show the custom toolpane that we use to add a new page to our meeting workspace. You can find this out by using .Net reflector on the function CustomToolPaneManager. It is located in the Microsoft.SharePoint.dll, in the namespace Microsoft.SharePoint.Meetings. What can we learn from this? We can, if we want, create our own toolpane that we can use to modify our site. We won’t be covering that in this series, however, but perhaps in another show. Just thought you should know that it is possible.

The Permission related attributes do warrant a bit of explaining. First of all there are two properties in our MenuItemTemplate tags, PermissionString and PermissionMode. PermissionString is the permissions that the current user should have in order to see the MenuItemTemplate. The string is made up of one or more SPBasePermissions strings, the complete list of which you can see in the SDK at http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.spbasepermissions.aspx. The PermissionMode is either Any or All and defines whether or not the user should have all the listed permissions or just any one of them.

MenuItemTemplate is a very powerful method of adding and customizing menus. You are not limited to modifying the Site Actions menu, a lot of other menus uses this tag as well, and you can see a list of most group Id in the SDK. I will give you the link in a few moments. I do advice you to take a look in the SDK to see all the different properties you can set for the MenuItemTemplate: http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.webcontrols.menuitemtemplate_members.aspx

For now, however, we need to move on. Because while this is a useful feature for creating our own pages, masterpage or otherwise, it is not what we want. Editing the mwsdefault.master will break our supportability so that is out of the question. If we want to edit that menu, there must be another way.

CustomActions via features

The second method of altering menus is to use features to deploy what are called custom actions. Using a standard feature we can add or hide custom actions from virtually any menu in SharePoint, such as the site actions, the toolbar on new items, Central administration link groups, and the context menu in lists of items.

CustomActions are basically feature elements that can be configured to do most of what we do in ASPX code in the master page. A notable exception is that where MenuItemTemplate has a PermissionMode attribute, custom actions do not. You have a custom actions attribute called Rights that accepts SPBasePermissions to list the properties required to see the custom action, but there is no option to use an Any permission mode. A user must have all the permissions listed in the Rights attribute in order to see the action.

I will show you some examples of how CustomActions can work. A prerequisite for this article series is that you are able to write a feature from scratch, so I will not be covering that, but rather focus on the element code. And, as we want to explore the way the SharePoint interface is built, let us look first at how the Site Settings page is created. You know, the page that gives you Users and Permissions, Look and Feel, etc. Usually located in _layouts/settings.aspx.

In you [12]\TEMPLATE\Features folder there is a feature called SiteSettings containing an element file called SiteSettings.xml. Open that now.

The entire SiteSettings.xml file is made up of two different elements, CustomActionGroup and CustomAction, with its child UrlAction. The first thing you should notice is that the CustomActionGroup elements match the columns on the site settings page. If we then examine the CustomAction elements we get some revelations. Each CustomAction element matches a link on the site settings page. Granted, all the titles are in resource files, but the Id attribute should give you a hint as to what each CustomAction creates. Each CustomActionGroup has an Id and each CustomAction matches one of those Ids in the GroupId attribute. That is how each link is sorted into each column.

Notice also that each CustomAction has a Rights attribute. That is where you set the permissions required to see any action, and that is how SharePoint is able to security trim the SiteSettings page to only display links to settings you can modify.

Clever? I think so…

Still, this does not give us anything, because we are not able to simply modify the SiteSettings.xml to add items here. We could, but Microsoft support will probably rip our heads off. So, we need to create our own feature.

Start with a plain vanilla feature.xml and an elements.xml. Call your feature whatever you like and scope it however you like. Add the following code to your elements.xml:

<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>
<CustomActionGroup Id=”CustomColumn”
Location=”Microsoft.SharePoint.SiteSettings”
Title=”My custom actions” Sequence=”5″/>
<CustomAction Title=”My first action” GroupId=”CustomColumn” Location=”Microsoft.SharePoint.SiteSettings” Id=”FirstAction” Sequence=”5″ Rights=”EnumeratePermissions,BrowseUserInfo” >
<UrlAction Url=”http://www.sharepointmagazine.net/”/>
</CustomAction>
</Elements>

Now install and activate your feature and go to the site settings file. You should see something like this:

Now we are getting somewhere. And no breaking of our supportability.

Remember that you can add custom actions to a whole range of menus by changing the Location value of our custom action. I promised to provide you with a link to a list of such places, and the list provided by Microsoft is indeed full of interesting Location values. You can find it here: http://msdn.microsoft.com/en-us/library/bb802730.aspx.

However, even Microsoft’s list is not exhaustive, not even for the built-in menus and lists. Not just that, but for each location there is also a potential range of GroupId values that modify where in the menu, or if at all, the CustomAction should be placed. For instance in our Custom column above we had a location of Microsoft.SharePoint.SiteSettings, but there were several different GroupIds that we used to customize placement. Another example is the Microsoft.SharePoint.StandardMenu, used for the Settings menu in lists, the Site Actions menu, the Welcome <UserName> menu, and several others.

So, if even Microsoft does not know  about all their Locations, or at least haven’t documented them, how can we know how we can add actions to the proper menus? Well, we need to do some reverse engineering but we will soon find familiar ground, and even the beginnings of a whole new section of this article.

First, we go back to our mwsdefault.master where we look for the tag that creates the Welcome <UserName> menu. I will assume that you have read the pre-requisites for this series and are thus able to find that tag yourself. If not, it is located in line 56 as wssuc:Welcome. That tag is in turn mapped to the “~/controltemplates/Welcome.ascx” file, which you can probably figure out. And, being as bright as you are, you can probably also guess that the ~/controltemplates refer to the ControlTemplates folder in the [12]\TEMPLATE folder.

Inside that folder are numerous files and we shall explore some of these later in the article, but for now, open only the Welcome.ascx file.

Notice the GroupId, as well as the use of MenuItemTemplate again. That GroupId is not in the list from Microsoft, so how are we supposed to find all these GroupIds for our customization? Again we would need to reverse engineer the individual files to find out how the menus are created and what Location and GroupId values we would need to set to add or modify actions.

There is a problem with that, at least one that I have. If I try to use explorer search for GroupId in the TEMPLATE folder I get no hits even if I know that there are files there containing that term. I suspect this has something to do with the file formats or encoding, but in any case, a simple fix is to copy the folder to a visual studio solution and use the search feature there.

More on features

Still, we want more. It seems hard work to add a new feature to just expand something that is already there. Not to mention we would have to create a new site definition to have the feature activated automatically when creating a new site.

Luckily, SharePoint now has a feature called feature stapling. Basically this allows up to create a feature that piggy-backs on another feature while not modifying the original feature at all. And even better, there is a series by Paul Liebrand right here on SharePoint Magazine that covers feature stapling: Permalink to- Introduction to SharePoint Feature Stapling – Part 1. you can explore that series for complete coverage of Feature stapling.

Controltemplates

For a brief moment there I thought we were lost in the realm of menu customization, but it is time to move on. For the sake of keeping this article too below a full day’s worth of reading I will cover only a couple more topics. First is the control templates we touched briefly a few paragraphs back.

You see, the [12]\TEMPLATE\CONTROLTEMPLATES folder, besides revealing some intricate details on the workings of several user interface elements, holds a real gem to anyone who wants to customize the user experience of SharePoint. I am talking about the DefaultTemplates.ascx control file. Open that file now.

The first thing you should notice is that the entire file is made up of SharePoint:RenderingTemplate tags, all with different ID values. You might guess how some of these are used based on the ID value alone. For instance, you may recognize, if you read the last article, the name ListForm in a rendering template starting in line 104.

So, how is this important?

Well, Microsoft has been kind enough to include the ability to override these templates, simply by creating our own ascx file with a SharePoint:RenderingTemplate tag with the same ID as the one we want to override.

Before we look at an example of this, please note that there are some quirks with this method. First of all, you can have only one overriding control. That is, if you make a MyCustomListForm.ascx that overrides the ListForm rendering template then that is the only override you can do on the ListForm template. Second, once you override a template you override the template for everything. The only way to go back is to remove the custom template completely.

In the next article I will show you how to override forms on a per list basis by creating new templates rather than overriding.

So, how is this cool?

The net effect of the override functionality is that we can basically modify the behavior of any of the templates in the DefaultTemplates.ascx control without messing up our supportability. Want to have all text fields use an Ajax autocomplete feature? Create your own ascx file and include a SharePoint:RenderingTemplate with an ID of TextField. Want to change the star (*) that is displayed for a required field? That rendering template has an ID of FieldLabelRequired. Made or bought a nice rich text editor? Put it in a rendering template with an ID of RichTextField.

Suddenly you can control the exact behavior or every list form element without breaking supportability. Combine this with what you will learn next week when we cover list customization and you can suddenly create an incredibly rich editing experience tailored exactly as you want.

We want more, we want more…

Masterpages, CSS, and themes

Really, people, this is about the User Experience, not user interface. I should mention these, though, but only briefly.

Master pages are powerful and incredibly useful for modifying the entire user interface. However, there is already a series by Greg Galipeau here on SharePoint Magazine that covers Master Pages: Introduction to Master Pages. I recommend you read that series to get more details than I could possibly fit here.

For CSS, well, this is a user experience series, not an interface or designer series. I don’t know much about CSS, at least not by far enough to try to explain it to anyone. The queen of SharePoint branding, which is the term used for visual design in SharePoint, is Heather Solomon. Her web site at http://www.heathersolomon.com/ has a great deal of detail for those of you who are into the ‘make it pretty, please’ scene.

Themes are also in the ‘made for the eyes’ category and outside the scope here. I don’t know, I think themes can be useful, but there are quite a few issues with getting them working. SharePoint Magazine author Paul Culmsee has more on the issues of getting themes to work, and a bit on why they don’t work, in his offsite branding series: http://www.cleverworkarounds.com/2007/10/13/sharepoint-branding-%e2%80%93-how-css-works-with-master-pages-%e2%80%93-part-3/

Application pages and other pages

The term application pages is used for pages residing in the _layouts virtual folder, such as list and site settings, create content, user information, and others. Application pages follow their own rules when it comes to customization. First of all they do not use the master pages of the site at all, they have their own master pages. That file, in turn, is shared for all application pages across the entire farm.

Creating new pages for a solution will in no way void your supportability. You can use this fact to greatly change the default user experience by substituting links to the out-of-the-box pages for links to your own pages. For instance, if you want a more sexy site settings page, simply copy the one that ships with SharePoint and save it in the [12]\TEMPLATE\LAYOUTS folder. Then you can write your own master page and modify the SharePoint:SiteActions’ FeatureMenuTemplate to change the menu link to go to your own site settings page instead, and then configure your new page to use that master page. When deploy your own custom master page in your site definition your site actions menu will point to the new page with your state-of-the-art management experience.

Which is fine and dandy, but doesn’t really prevent other links to the old site settings page. Anyone who knows the original _layouts/settings.aspx address will also be able to see the old page. That may or may not be what you want, after all, having the old version may still be desirable.

You may be tempted, then, to customize the application.master page or even the application pages themselves. But boom, goes Microsoft supportability. They reserve the right to mess up all your wonderful crafting any time they issue a service pack or update that you install. No dice with editing the built-in pages.

It turns out that there really is no supported way of customizing the application pages. Short of creating your own, which has serious drawbacks, you are at a loss. Sridhar Raghunathan’s blog has some more information about this, including a work-around that really does not make things a whole lot better and introduces security and stability risks into the equation.

Another work-around, which again is unsupported, is to create a custom HTTPHandler to override the PreInit method of the page to substitute the application.master for your own. While this method may work it does break supportability, so no dice there either. If you do not care about that, Liam Cleary wants to talk to you about how to accomplish this and some problems: http://www.sharepointblogs.com/helloitsliam/archive/2007/05/09/moss2007-quot-httphandler-quot-investigation.aspx

Sorry, folks. We just have to hope for something better in Office 14 or someone in Redmond to notice the smell of burning tires from the ‘We want application.master customization’ riot outside.

Oh, one thing… Themes work on application.master. Remember I said that themes can be useful? This is the only place I can think of where themes may be your best bet. It is actually your only bet, but hey, we take what we can get.

…we want more, we want more…

Still not satisfied? Good! There is plenty more to learn, and online resources are abundant.

First, read the next articles in this series. The next article will cover Lists, with the subsequent articles covering content types and fields. In the final article there will be some tools, tricks, and tips for speeding up development. And, by all means, feel free to visit the first article in the “Customizing the User Experience” series as well, in case you missed that part.

Second, feel free to read the other great articles and series here on SharePoint Magazine. I have mentioned two already, the master pages series by Greg Galipeau and Paul Liebrand’s series on feature stapling.

Third, use the SDK, online or offline, and update it to make sure you have the most recent version if using offline. http://msdn.microsoft.com/en-us/library/ms441339.aspx

Fourth, you may want to drop by my blog from time to time, or subscribe to the feed there. If requested I often write deeper articles on any particular topic, or cover completely new topics. http://furuknap.blogspot.com/ and http://feeds.feedburner.com/furuknap for the feed.

Fifth, grab yourself a front-row seat for the upcoming book, called “Building the SharePoint User Experience”, by visiting the book blog. This article is but the tip of the ice berg of what will be covered there. If you sign up for the mailing list on the book blog you will get the fastest updates, the most exclusive excerpts, invitations to the best competitions, and a ton of me talking about how fabulous I am. There is also a section on recommended SharePoint books you might like, in addition to my own book, of course.

Conclusion

I hate writing these conclusions. I do love writing, and exploring the deep depths of a particular topic, but I have never gotten along with conclusions. First, it means that I should be finished, no more content to add, no new knowledge to gain. Second, I mean, if you have come this far and have no idea what this article is about then I must be a terrible writer. It shouldn’t need a conclusion. Third, this really isn’t a conclusion in any case, just the end of the article. There is plenty more to explore, Google will never run out of material on any of these topics.

I don’t like conclusions.

So, I won’t write one. I am an adult, I can decide for myself.

There.

No conclusion.

The end.