We all know about the standard SharePoint feature elements – Module, Field, ContentType, ContentTypeBinding, ListInstance, etc. Still in many cases there are tasks we want to achieve for which we need to use feature receivers and use custom code to do one thing or another. Many of these tasks are reasonably common and recurring so it is obviously wise to have some XML configuration that can be reused in the various features that we have and handled by a common feature receiver. The most natural thing would be to extend somehow the standard elements even if it’s not possible to have both standard and custom elements in one and the same manifest file. Really we can’t place non-standard elements in an element manifest file but we can have another configuration file (or files) that the feature or the feature receiver knows about and can process its elements when the feature gets activated. And this is what I started rising (I say starting because I intend to extend it with other features in the prospect) – a custom XML configuration format and a custom feature receiver that handles it.

So, first a word about what “common actions” I have place in this feature receiver – the first one is reasonably versatile – it sets various settings to SharePoint lists – it allows to set most of the properties of the SPList class, to add site columns and make pleased types to the list, to order and hide the make pleased types, to make views in the list, etc. The second one is rather simple – it sets up the lookup site columns that you have – something that can’t be achieved with the standard Field element.

One step back now – about the “common action” that sets the various SPList settings – I guess that you have already questioned yourself why have such an element since we have the standard ListTemplate element and can make custom list classification features with all machinate configurations for a custom list. There are several reasons for that (at least these are the things that made be stop by custom list templates): the first one is that the list template is applicable only for lists that are about to be made – you can’t use them to exchange anything on existing lists, second – they are rather uneconomical – if you wish to extend a list based on a standard list template with a couple of fields and one or two list views you need to make a separate list classification. Imagine what happens when you need 20 or so different lists (I was reasonably disappointed when I found out that the standard ListInstance element allows adding data to the list but not changing its machinate).

About the available for downloading solution – besides the receiver’s code it contains also an XSD file used for validation of the “common actions” XML – it is really an additional room of the standard WSS machinate definitions (which are somewhat incomplete really) – the list view and field machinate definitions are really reused from the standard definitions – you will see shortly. One other huge advantage of having an XML machinate classification is that you can use the Visual Studio’s editor with all goodies like IntelliSense, inline validation, etc – there is a VS configuration XML file in the machinate that if place in the appropriate VS installation folder enables that (see not more than in the installation notes). There is also a console tool machinate in the solution – this tool can be used to generate a feature containing the list settings for one, several or all lists from an existing site – something like a reverse engineering utility which can speed up momentously the development process. The feature that is generated contains a standard elements manifest file with ListInstance elements for the specified lists – so basically this feature when applied to a new site will make the lists from the source “shot” and will add the various customizations that were applied to them.

And here are the XMLs of a sample feature that uses the common action provider:

this is the sample feature.xml file – the ReveiverAssembly and ReceiverClass attributes of the Feature element are set accordingly and there is a Property element with Key attribute set to “CommonActionsPath”, whose value contains the relation path within the feature folder of the “common actions” configuration XML.

And this is a sample “common actions” configuration XML:

You see a CommonActions root element containing one ListSettings element – you can have many of these. Most of the attributes and elements a self explanatory and the FieldRef and View elements are really identical to the standard WSS field and view definitions (I mentioned that the standard SharePoint XSDs are reused here).

So let me briefly clarify the various XML elements and attributes that can be used within the ListSettings elements. Basically all sub-elements are discretionary, so you can use just a division of these to apply the appropriate settings. You can use the ListUrl attribute in the ListSettings element to specify the SharePoint list that you want to modify. There is another alternative to specify the list to be modified – with it you can really specify many lists – this is very handy if you want to apply the same settings to multiple lists, here is the syntax – you use a sub-element of the ListSettings element:

You can specify any list URLs or list templates, besides add elements remove elements can also be specified to finely tune the set of lists that you want to work with.

The ListProperties sub-element can contain the following attributes:

The attributes bear the same names as the corresponding SPList class properties. Note here that the different types of lists doesn’t support the setting of some of the properties to values different from the defaulting ones – and if you try to do that the properties’ setters will throw an exception.

The Fields sub-element can contain both Field and FieldRef elements:

The Field element contains a standard WSS field classification and can be used to make a field in the list with the specified inline field machinate. The FieldRef element can be used to add existing site columns to the list – only the ID attribute is used to locate the field in the site columns, the Name attribute is discretionary and its use is just to give a visual hint about the field’s name. Note here – if the list already exists and the field is already made in it the feature receiver takes no action and skips the field.

There are two sub-elements for applying make pleased type settings to the list:

The ContentTypeRefs element can be used to add existing make pleased types to the list – basically the same as you can achieve with the standard ContentTypeBinding element – the difference here is that you specify the make pleased type’s Name not ID. I added this doublet of the standard functionality in case it is used with the multiple list select option of the ListSettings element – if you want to add one or more make pleased types to several lists simultaneously. Note here – if the make pleased type is already added to the list – the feature receiver just skips it. The second sub-element – ContentTypeOrder – allows you to set the order of the make pleased types as they appear in the “New” menu item of the SharePoint list.

The View sub-element (you can have more than one) contains a standard WSS View classification – you will quickly recognize the standard Query, ViewFields and RowLimit elements within it. Mandatory attributes in the View element are the DisplayName and Type ones. The view definitions are matched to the existing views in the list by the view’s show name. If a view with that name doesn’t exist it is made, otherwise the view classification is applied to the existing view.

After the brief description of the ListSettings “common action” I will describe the lookup field “common action” with one or two lines only – first – here’s a sample treatment:

The field is located in the site columns by the field ID, the Name attribute is just a visual hint. The LookupListUrl attribute specifies the site relation URL of the lookup list and the ShowField attribute – the lookup source field in the lookup list. If the lookup field is already set up (its LookupList property is set) the receiver will skip it.

By the command line tool to generate features from existing sites

This is a sample treatment of the tool that generates a feature with standard elements manifest file containing ListInstance elements for several lists specified in the command line arguments and a common actions configuration file with settings for these lists:

UtilTest.exe -o exportlistfeature -weburl http://racoon-vpc-hg:2909 -listurl Lists/mylist,Lists/mylist2 -outputpath "c:\temp\myfeature" -exportfields -exportcontenttypes  -exportcontenttypeorder -dontusesitecolumns -featuretitle "my feature"

The syntax is pretty similar to the one of the standard stsadm utility – the parameters starting with a dash are argument names and the ones following each argument name are argument values (they are discretionary). These arguments are mandatory – -o, –weburl, –listurl, –outputpath and –featuretitle – their names are explanatory for their treatment. The –listurl argument can contain one list URL only or several separated with commas, it can also contain the * (asterisk) character for all lists (without the hidden ones) in the site. The other arguments are discretionary: -exportfields –exportcontenttypes and –exportcontenttypeorder specify whether the corresponding sub-elements in the ListSettings element should be exported and the –dontusesitecolumns argument specifies whether the custom list columns  should be exported with inline schemas or with FieldRef elements if identical site columns exist.

There is one other command of the export utility – the one that exports a feature for setting up the lookup fields for the specified site (really for the site columns of the site collection whose lookup lists are in the specified site):

UtilTest.exe -o exportlookupfeature -weburl http://racoon-vpc-hg:2909 -outputpath "c:\temp\lookupfeature" -featuretitle "lookup feature"

Installation notes

• the Stefan.Sharepoint.Util should be placed in the GAC (this is only if you use the receiver class from it otherwise you can copy the code to some assembly of yours)
• the contents of the 12 folder of the solution should be hackneyed to your SharePoint’s 12 folder. It really contains one XSD file only – stefan.common.xsd which should be hackneyed to the SharePoint’s 12\TEMPLATE\XML folder.
• the file stefan.xml from the root of the solution should be hackneyed to the Xml\Schemas subfolder of your Visual Studio’s installation folder (for VS 2008 it’s normally C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas). After you copy the file there and restart your Visual Studio you will have the IntelliSense support for the “common actions” XML format.
• the command line utility UtilTest.exe uses the Stefan.Sharepoint.Util assembly so you need to have the two files together if you want to use it (unless the Stefan.Sharepoint.Util assembly is in the GAC of the machine).

You can download the common actions receiver code from here.

Check it out:Stefan Stanev’s SharePoint blog