8.SharePoint 2007 Deployment: Custom Action Features

Package Structure

As I mentioned previously in the post SharePoint 2007 Deployment: Creating and Using Features, to build a feature you need to create the following files:

• The feature manifest file (which must be named feature.xml)
• One or more element manifest files

The feature manifest file contains the generic information about the feature package, and the element manifest files contain the information about each specific type of element that makes up the feature. Since I already explained all the possible contents of the feature manifest file in the above mentioned post, I will focus this one the element manifest that allows the creation of custom actions in a SharePoint site.
You can then place these two files inside a Solution following the instructions in the post SharePoint 2007 Deployment: Creating Solutions, to provide an easy way to deploy the feature (or upgrade it).

Custom Actions

Custom actions are links, toolbar buttons and menu items that you can add to or hide from the SharePoint's user interface. Each custom action exists in a specific location, and depending on that location, can be a part of a group of actions.
With a custom action feature, you can:

• Add a new Custom Action Group which can be used to group custom actions in a specific options screen;
• Add a new Custom Action which can be a new option in a settings screen, a new menu item, or a new toolbar button;
• Hide an existing Custom Action whether that action is the result of custom action feature or it belongs to SharePoint's out-of-the-box features.

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with custom action elements can be deployed to all the scopes, that is, Farm, Web Application, Site Collection and Web Site.
The correct scope must be chosen according to the group and location of the custom action being added or hidden. Note that you can't mix feature elements with different scopes on the same feature.

Feature Manifest

I will only present a simple feature manifest, since the additional options were presented in the above mentioned post.

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Id="5DFD12AF-D0AA-4c63-8FB8-C49DB1191083"
         Title="My Custom Action Feature"
         Description="Adds Custom Actions to the Web Site."
         Scope="Web"
         Version="1.0.0.0">
    <ElementManifests>
        <ElementManifest Location="CustomActions.xml"/>
    </ElementManifests>
</Feature>

Notes about this feature manifest:

• The title of the feature is My Custom Actions Feature.
• It will be deployed as a Web Site feature, since it's Scope value is Web.
• It references a single element manifest file: CustomActions.xml.

Element Manifest

The element manifest file can have any name you wish (in this example it's called CustomActions.xml), but it's root element must be <Elements>. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of three feature elements:

• <CustomActionGroup> used to create new custom action groups;
• <CustomAction> used to create new custom actions;
• <HideCustomAction> used to hide existing actions.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <!-- Custom Action Group -->
    <CustomActionGroup
        Id="MyActionGroup"
        Description="This group contains all my custom actions."
        Title="My Action Group"
        Location="Microsoft.SharePoint.SiteSettings"
        Sequence="30" />
    <!-- Custom Action in Custom Action Group -->
    <CustomAction
        Id="MyCustomAction"
        Description="This link is a custom action."
        Title="My Custom Action"
        GroupId="MyActionGroup"
        Location="Microsoft.SharePoint.SiteSettings"
        Rights="ManageWeb"
        RequireSiteAdministrator="FALSE"
        Sequence="20">
        <UrlAction Url="~sitecollection/_layouts/MyCustomPage1.aspx" />
    </CustomAction>
    <!-- Custom Action in Site Actions Menu -->
    <CustomAction
        Id="MyNewCustomAction"
        Description="This menu item is a new custom action."
        Title="My New Custom Action"
        GroupId="SiteActions"
        Location="Microsoft.SharePoint.StandardMenu"
        ImageUrl="/_layouts/MyActionIcon.jpg"
        Sequence="10">
        <UrlAction Url="~sitecollection/_layouts/MyCustomPage2.aspx" />
    </CustomAction>
    <!-- Hide Custom Action -->
    <HideCustomAction
        Id="HideDeleteWeb"
        GroupId="SiteAdministration"
        Location="Microsoft.SharePoint.SiteSettings"
        HideActionId="DeleteWeb" />
</Elements>

The <CustomActionGroup> Element

The <CustomActionsGroup> element is used to create custom action groups that can contain custom actions. In the sample above, a new custom action group, named My Action Group, is added to the Site Settings screen.
The following attributes can be used with this element:

• Id - (optional) Specifies a unique identifier for this group. It can be a GUID or a unique term, for example "SiteManagement".
• Description - (optional) Description for the custom action group.
• Title - (required) Title of the custom action group, shown to the user in the UI.
• Location - (required) Specifies the place where the custom action group will be placed
  • Microsoft.SharePoint.SiteSettings - Site Settings screen
  • Microsoft.SharePoint.ContentTypeSettings - Content Type Settings screen
  • Microsoft.SharePoint.Administration.Operations - Operations screen in the Central Adminstration web site
  • Microsoft.SharePoint.Administration.ApplicationManagement - Application Management screen in the Central Administration
• Sequence - (optional) Order of the custom action group in the list of groups that exist in the specified location.

The <CustomAction> Element

The <CustomAction> element is used to create a new custom action in the UI. In the above samples, two custom actions are created:

• A custom action (named My Custom Action) in a custom action group (named My Action Group) in the Site Settings screen.
• A custom action (named My New Custom Action) in an existing action group (which is the Site Actions menu).

The following attributes can be used with this element:

• Id - (optional) Unique identifier to the custom action. The ID can be GUID or unique term, for example, "MyCustomAction".
• Description - (optional) Description for the custom action. It will be displayed as a tooltip or sub-description for the action, depending on its location.
• Title - (required) Title for the custom action.
• GroupId - (optional) Specifies an action group inside which to place the custom action. If this custom action is contained inside a custom action group, the value of this attribute must match the value of the Id attribute of the <CustomActionGroup> element.
• Location - (required) Specifies the location for this custom action. If this custom action is contained inside a custom action group, the value of this attribute must match the value of the Location attribute of the <CustomActionGroup> element. Check the possible values below, in the Locations and Group IDs section.
• ImageUrl - (optional) Address of the image to use as the icon for this custom action. Note that, in certain locations, the custom actions don't have an icon.
• Rights - (optional) Specifies a set of permissions that the user must have in order for the link to be visible. If omitted, the action always appears. To specify multiple values, separate them using commas (which means the user must have all the permissions specified). Check the possible values below, in the Action Rights section.
• RequireSiteAdministrator - (optional) TRUE to specifiy that the user must be a site administrator to see the custom action. The default value is FALSE. This attribute is not supported if the custom action is to be placed in the context menu for a list item.
• Sequence - (optional) Specifies the order of the custom action inside its action group.
• ContentTypeId - (optional) Specifies the ID of the content type to associate with the custom action.
• ShowInReadOnlyContentTypes - (optional) TRUE to specify that the action should only appear in the Manage Content Type screen, for Read Only Content Types. The default value is FALSE.
• ShowInSealedContentTypes - (optional) TRUE to specify that the action should only appear in the Manage Content Type screen, for Sealed Content Types. The default value is FALSE.
• ControlAssembly - (optional) Specifies the fully qualified name of the assembly of the control that supports the custom action. This attribute is used in conjunction with the next one.
• ControlClass - (optional) Specifies the name of the class of the control that supports the custom action. This attribute is used in conjunction with the previous one.
• ControlSrc - (optional)
• RegistrationType - (optional) Used to specify the type of attachment in per-item custom actions. The possible values are:
  • ContentType
  • FileType
  • List
  • ProgId
• RegistrationId - (optional) Depending on the RegistrationType value, this attribute can hold a Content Type ID, a File Type identifier, a List ID or a Program identifier.

The <UrlAction> Element

The <UrlAction> element is used inside the <CustomAction> element to specify what happens when the user clicks the link (or toolbar button, or menu item). It has a single attribute, Url, which is the address of the page to redirect the user to.
In this URL address you can use a few tokens that SharePoint will replace by the correct values when the user clicks it:

• ~site - relative address of the current web site.
• ~sitecollection - relative address of the root web site of the current site collection.
• {ItemId} - ID (Integer value) of the item being acted upon (if applicable).
• {ItemUrl} - URL of the item being acted upon (only works in document libraries).
• {ListId} - GUID of the list.
• {SiteUrl} - absolute URL of the current web site.
• {RecurrenceId} - Recurrence index (not supported in the context menu of list items).

The <HideCustomAction> Element

The <HideCustomAction> element is used to hide an existing custom action.
The following attributes can be used with this element:

• Id - (optional) Specifies the ID of this hide custom action element.
• GroupId - (optional) Identifies an action group that contains the action.
• Location - (required) Specifies the location of the custom action to hide. Check the possible values in the table below.
• HideActionId - (required) Specifies the ID of the action to hide.

Locations and Group IDs

The location and group ID values identify a specific place where the custom action must be created (or hidden). See below the possible combinations for both attributes.

Description	Location	Group ID
Display form toolbar	DisplayFormToolbar	N/A
Edit form toolbar	EditFormToolbar	N/A
New form toolbar	NewFormToolbar	N/A
List view toolbar	ViewToolbar	N/A
List item context menu	EditControlBlock	N/A
New menu for list and document library view toolbars	Microsoft.SharePoint.StandardMenu	NewMenu
Actions menu for list and document library view toolbars	Microsoft.SharePoint.StandardMenu	ActionsMenu
Settings menu for list and document library view toolbars	Microsoft.SharePoint.StandardMenu	SettingsMenu
Upload documents menu for document libraries	Microsoft.SharePoint.StandardMenu	UploadMenu
Site Actions menu	Microsoft.SharePoint.StandardMenu	SiteActions
Site Settings Site Collection Administration links	Microsoft.SharePoint.SiteSettings	SiteCollectionAdmin
Site Settings Site Administration links	Microsoft.SharePoint.SiteSettings	SiteAdministration
Site Settings Galleries Links	Microsoft.SharePoint.SiteSettings	Galleries
Site Settings Look and Feel links	Microsoft.SharePoint.SiteSettings	Customization
Site Settings Users and Permissions links	Microsoft.SharePoint.SiteSettings	UsersAndPermissions
Site Actions menu for surveys	Microsoft.SharePoint.StandardMenu	ActionsMenuForSurvey
Site Settings links for surveys	Microsoft.SharePoint.SiteSettings	SettingsMenuForSurvey
Content Type Settings links	Microsoft.SharePoint.ContentTypeSettings	N/A
Central Administration Operations page	Microsoft.SharePoint.Administration.Operations	N/A
Central Administration Application Management page	Microsoft.SharePoint.Administration.ApplicationManagement	N/A

Action Rights

Each custom action has its own set of permission requirements which are defined using the Rights attribute of the <CustomAction> element. The list below summarizes the possible values for this attribute.

• AddAndCustomizePages - Add, change, or delete HTML pages or Web Part Pages, and edit the Web site using a Windows SharePoint Services–compatible editor.
• AddDelPrivateWebParts - Add or remove personal Web Parts on a Web Part Page.
• AddListItems - Add items to lists, add documents to document libraries, and add Web discussion comments.
• ApplyStyleSheets - Apply a style sheet (.css file) to the Web site.
• ApplyThemeAndBorder - Apply a theme or borders to the entire Web site.
• ApproveItems - Approve a minor version of a list item or document.
• BrowseDirectories - Enumerate files and folders in a Web site using Microsoft Office SharePoint Designer 2007 and WebDAV interfaces.
• BrowseUserInfo - View information about users of the Web site.
• CancelCheckout - Discard or check in a document which is checked out to another user.
• CreateAlerts - Create e-mail alerts.
• CreateGroups - Create a group of users that can be used anywhere within the site collection.
• CreateSSCSite - Create a Web site using Self-Service Site Creation.
• DeleteListItems - Delete items from a list, documents from a document library, and Web discussion comments in documents.
• DeleteVersions - Delete past versions of a list item or document.
• EditListItems - Edit items in lists, edit documents in document libraries, edit Web discussion comments in documents, and customize Web Part Pages in document libraries.
• EditMyUserInfo - Allows a user to change his or her user information, such as adding a picture.
• EmptyMask - Has no permissions on the Web site. Not available through the user interface.
• EnumeratePermissions - Enumerate permissions on the Web site, list, folder, document, or list item.
• FullMask - Has all permissions on the Web site. Not available through the user interface.
• ManageAlerts - Manage alerts for all users of the Web site.
• ManageLists - Create and delete lists, add or remove columns in a list, and add or remove public views of a list.
• ManagePermissions - Create and change permission levels on the Web site and assign permissions to users and groups.
• ManagePersonalViews - Create, change, and delete personal views of lists.
• ManageSubwebs - Create subsites such as team sites, Meeting Workspace sites, and Document Workspace sites.
• ManageWeb - Grant the ability to perform all administration tasks for the Web site as well as manage content. Activate, deactivate, or edit properties of Web site scoped Features through the object model or through the user interface (UI). When granted on the root Web site of a site collection, activate, deactivate, or edit properties of site collection scoped Features through the object model. To browse to the Site Collection Features page and activate or deactivate site collection scoped Features through the UI, you must be a site collection administrator.
• Open - Allow users to open a Web site, list, or folder to access items inside that container.
• OpenItems - View the source of documents with server-side file handlers.
• UpdatePersonalWebParts - Update Web Parts to display personalized information.
• UseClientIntegration - Use features that launch client applications; otherwise, users must work on documents locally and upload changes.
• UseRemoteAPIs - Use SOAP, WebDAV, or Microsoft Office SharePoint Designer 2007 interfaces to access the Web site.
• ViewFormPages - View forms, views, and application pages, and enumerate lists.
• ViewListItems - View items in lists, documents in document libraries, and view Web discussion comments.
• ViewPages - View pages in a Web site.
• ViewUsageData - View reports on Web site usage.
• ViewVersions - View past versions of a list item or document.