Custom Actions - Simple Steps to Add Your Touch to Site Actions

Custom Actions - Simple Steps to Add Your Touch to Site Actions

WSS 3.0 and MOSS 2007 now have a supported extensibility mechanism allowing developers to easily add items to existing menus.  Custom Actions - most easily installed as a feature means no more hacking of JavaScript files and ASPX pages.

Custom Actions can be used to add new custom functionality to many places in WSS and MOSS. Depending on where the custom action is located determines the user interface of the custom action. For example if you create a custom action for the Site Actions menu the result is a menu item anchored in the control. If you create a Custom Action for the Site Settings page you will see a link.  Creating a custom action for a list's display form toolbar results in a toolbar button. As you can see just from this small list a Custom Action provides a lot of extensibility in WSS and MOSS.

 For this post I will walk you through creating, installing and activating custom actions that will be located on the Site Actions dropdown control.  If you are a developer working with features, like I do, you usually find yourself activating and deactivating features frequently.  If you use the feature management pages for activation and deactivation  you have more than a few clicks to get to either the site features management page or the site collection feature management page.  This example will create two custom actions for your Site Action control allowing you to quickly jump from a site page to either the site or site collection feature management page. The great thing about using a feature to install these links into the custom action control you will be able to activate or deactivate and thereby add or remove these links as needed.

To start with create a new folder to contain the custom actions feature. This folder must be located inside the Features folder located on the WSS or MOSS server.  I create a folder titled  "FeatureManagmentLinksFeature". Somewhat redundant name but I like adding Feature to the end of my feature folder.  This folder is located at:  C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. The Feature directory is where WSS and MOSS will look for new features.

We need a feature.xml file to describe our feature and place in our newly created folder.  A feature file is an Xml file that contains information about the feature including the location of the custom action definition we will be using.  For this example simply create a new text file using your favorite editor. Include the following Xml in the file

<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="Place your GUID here!"
    Title="Feature Management Links"
    Description="The Feature Management Links feature will create two links within the Site Actions menu control."
    Version="1.0.0.0"
    Scope="Site"
    xmlns="http://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementManifest Location="FeatureManagementLinks.xml" />
  </ElementManifests>
</Feature>

It is absolutely required that you replace the text "Place your GUID here!" with a  valid GUID!.  GuidGen comes to mind. Save the file with the name Feature.xml to the newly created folder within the feature directory.  Make sure that the file is saved as an Xml file and not a text file. 

The feature file provides us with the basic elements of our feature - id, descriptions, references to required files. It should be noted that the Scope of this feature is set to "Site". This means this feature will be activated at a site collection level. The ElementManfiest  element and it's Location attribute refers the feature to our next file "FeatureManagmentLinks.xml". It is this file which will contain our Custom Action definitions.

The "FeatureManagementLinks.xml" file will contains an  "Elments" Xml element as the top node.  This element contains one ore more feature elements that are well-known to WSS and MOSS. For our example we will need to use the CustomAction element so that WSS and MOSS will create the appropriate menu items in the Site Action control. This example will contain two custom actions. One will link the user to the site-level feature management aspx page and another action that will link the user to the site collection -level feature management aspx page.

Create a new text file using your favorite text editor and add the following Xml:

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
    GroupId = "SiteActions"
    Location="Microsoft.SharePoint.StandardMenu"
    Sequence="1000"
    Title="Site Features">
    <UrlAction Url=" ~site/_layouts/ManageFeatures.aspx"/>
  </CustomAction>
 
  <CustomAction
    GroupId="SiteActions"
    Location="Microsoft.SharePoint.StandardMenu"
    Sequence="1000"
    Title="Site Collection Features">
    <UrlAction Url="/_layouts/ManageFeatures.aspx?Scope=Site"/>
  </CustomAction>

</Elements>

Save this file to the newly created directory using the same name that is listed in the feature.xml's ElementManifest element. In this example we will save the file as FeatureManagementLinks.Xml in the  FeatureManagmentLinksFeature directory.

Before we install and activate this  lets look at the first of two CustomAction elements.  The CustomAction element has the basic attributes to allow us to define where the custom action should reside, the text displayed by the custom action as well as the action. In  these examples the custom action should reside in  the StandardMenu of SiteActions. The Sequence attribute allows us to provide a relitive position among the other actions.  In these examples the action we want is to navigate to a page. This is accomplished by the UrlAction element.

The first custom action has a UrlAction element that will direct us to the ManageFeatures.aspx page relative to the site we are located on. The ~site token provides us with a way to generically specify the site we are currently on. The second custom action will take us to the site collection feature management page.

The next step is to install and activate the feature.  STSAdm.exe is a command line tool for WSS and MOSS and can be found in the bin directory in the 12 hive.  Generally this is located at: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\.  Open a command prompt by clicking the Start button, then Run. Type in CMD and then click the Ok button.

The Command Prompt will open.  To install the feature type the following command:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM -o installfeature -filename  FeatureManagmentLinksFeature\feature.xml

Hit enter to run the command. Assuming you have no spelling errors STSADM will tell you it has installed the feature.  To activate the feature run the following command in the Command Prompt.

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM -o activatefeature -filename  FeatureManagmentLinksFeature\feature.xml -url http://{Servername}

Make sure you replace {Servername} with the server name and port. The url parameter should point to the site collection that the feature will be activated on.

After running this command your feature should be installed.  To test it go to any web (or subsite) within the site collection and click on the Site Action  menu control. You should she two additional links allowing you to easily move from a site page to either feature management page. If you are constantly activating or deactivating features this small feature will save you some time.

Custom Actions really provide us with a great mechanism to place our needed extensions into the menus of WSS and SPS. This post about Custom Actions is a very simple start to what you can do.  Normally I add this little feature to all site collections I am working on and disable it when the sites go "live". A slightly more advanced scenario would security trim these new actions by a user's rights.  I could easily require a set of rights before this custom action would be accessible.  

If your interested about more advanced Custom Action scenarios then check out Tony Bierman's posts on  Quick Site Settings: Adding Sub Menus to Site Actions in SharePoint .