70-541: Create an Action to Add an Option to the Site Settings Menu May 19, 2009

Short & Sweet

Actions in SharePoint are links that you can add at various areas of a site. They are deployed using features and allow you to add hyperlink entries to areas such as: The Site Actions drop-down, the Site Settings page, a list’s toolbar menu and a list item’s ECB menu.

Define a custom action by using the CustomAction element within an elements manifest file. The Title attribute is the only required attribute. To define the Url add a child element named UrlAction and set its Url attribute.

Detailed Information

This use of the word ‘action’ might seem a bit misleading at first. Action evokes images of events firing or of changes occuring. In this case all we’re doing with the action is adding a hyperlink to the Site Setting page. What sets this link apart, though, is that it’s deployed (and activated) via SharePoint’s Feature framework. Actions can be deployed to many areas within SharePoint and without them it’d be much more difficult to modify sections, such as: List and Library toolbar entries, list item edit control block menus and the Site Actions drop-down.

The action itself is defined using the CustomAction element within the feature’s element manifest. Here’s an example of an elements.xml file for deploying a custom action:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Id="1111-11111-1111-11111-1111"
    Location="Microsoft.SharePoint.SiteSettings"
    GroupId="Galleries"
    Sequence="100"
    Title="SharePoint Gear Blog"
    >

 

    <UrlAction Url="http://www.sharepointgear.wordpress.com" />

 

  </CustomAction>
</Elements>

So, let’s examine this code, line-by-line:

• Line 1: Open the Elements xml tag and specify the xml namespace. Apart from being good practise, specifying the namespace also provides you with intellisense in Visual Studio.
• Line 2: Open the CustomAction xml tag. The CustomAction element holds all the information about the action.
• Line 3: The Id attribute can hold any unique text. I like to use a GUID to help ensure uniqueness, but you can use any string, or even ommit it.
• Line 4: The location describes the parent element that the action will be installed to. In this case we reference the Site Settings page, but other options could be a list item’s ECB or its toolbar. For a link to the full list of locations, see the references at the end of this article.
• Line 5: The group, within the location (see line 4), to install the action to. Microsoft’s full list of groups will be linked in the references section of this article. In this example we’re adding an entry to the Galleries group on the Site Settings page.
• Line 6: Sequence allows for altering the order of actions on a menu or toolbar. I recommend using a high number for your custom actions, so they don’t interfere with future Microsoft patches. An item’s sequence is relative to the sequence value of its siblings. For a given group, the custom actions might have sequence numbers: 1, 2, 100, 150, 200, 201, 202. This is valid and the numbers needn’t be sequential.
• Line 7: Title is the only required field in the CustomAction element. This is the text people will see when they view your action.
• Line 9: Whitespace. You wouldn’t think this was necessary, but I received and error without it. The error was: “invalid XML: Root element is missing.”. You might not get this error; who knows?
• Line 10: The UrlAction element is the Url that people will be redirected to when then activate (click on) the action.
• Line 11: More whitespace: See line 9.
• Lines 12 & 13: Close the xml tags.

There’s many more CustomAction elements that might be useful depending on the type of action you’re creating. They’re referenced at the end of this article. Although creating a feature is beyond the scope of this guide, I’ve included one for you to download and install for testing. To use the feature:

1. Download the zip file from my Windows Live SkyDrive. Link’s in References section below.
2. Extract the zip file to the following folder on the SharePoint server:

   C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES

   . This will create a SharePointGearCustomActions folder which contains two files, feature.xml and elements.xml.

3. Open command prompt and change to the following directory:

   C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin

   .

4. Run: stsadm -o installfeature -name SharePointGearCustomActions
5. The feature is scope to a (web) site. Open a SharePoint site and from the site settings page, click on Site Features (not Site Collection Features).
6. Activate the feature named: SharePoint Gear Custom Action.
7. To test this action, browse to the Site Settings page again. You should have a new entry in the Galleries group.

References

• SharePoint Gear Custom Action. Download the example feature that accompanies this guide.
  http://cid-ba333a1e7a3f182a.skydrive.live.com/self.aspx/.Public/SharePoint%20Gear/Custom%20Action/SharePointGearCustomAction.zip
• CustomAction Element (Custom Action)
  http://msdn.microsoft.com/en-us/library/ms460194.aspx
• Default Custom Action Locations and IDs
  http://msdn.microsoft.com/en-us/library/bb802730.aspx