Wednesday, 18 July 2007

Using CustomAction to modify system pages

In the last post, I covered 2 examples of how to safely modify functionality in 'system' areas of SharePoint, such as Central Admin and the Site Settings area. The first example was a tweaked Recycle Bin (which listed only items deleted by the current user), and the second was a custom 'Create Site Collection' admin page. In both cases, the technique was to copy the original page which shipped with SharePoint, make the customization to the copy, and then redirect the link in SharePoint to use our new page. The customization is then fairly transparent to users - depending on your implementation, they could simply be clicking the same link in the same place in SharePoint, yet going to somewhere different which is offering your modified functionality.

This last part (of redirecting the link in SharePoint) is accomplished via a Feature which makes use of the CustomAction element. However, this idea of changing an existing link somewhere in SharePoint is not necessarily the type of customization you might regularly make. So it's useful to know the CustomAction element can also be used to add a link somewhere in SharePoint. This opens up many opportunities for customization, and this post aims to detail some of the options.

The CustomAction element is used like this:

<CustomAction Id="MyDeletedItems"

              GroupId="SiteCollectionAdmin"

              Location="Microsoft.SharePoint.SiteSettings"

              Sequence="10"

              Title="My recycle bin items"

              Rights="ManageWeb,BrowseUserInfo">

  <UrlAction Url="_layouts/custom/MyRecycleBinItems.aspx" />

</CustomAction>



I covered most of the values in details in the previous post, but what I want to focus on here is the Location attribute - this essentially specifies where in SharePoint your link will be added to. Some of the common potential values are:

  • Microsoft.SharePoint.SiteSettings (as in the example XML above)
  • Microsoft.SharePoint.Administration.Operations
  • Microsoft.SharePoint.Administration.ApplicationManagement

If you've worked with SharePoint for a while you can probably work out where these values refer to - the first is the Site Settings area, whilst the last two are the 'Operations' and 'Application Management' pages in the Central Admin area respectively. When using a CustomAction to add links in these areas, you can also specify the group your link should appear in. This value refers to an existing 'category' of links within the Location, e.g. the locations listed above. Note that new groups can be created by using a CustomActionGroup element, but the GroupID value of a CustomAction must always specify a group which exists already. The following groups exist by default in the SiteSettings area:

  • UsersAndPermissions
  • Customization
  • QuickLaunch
  • Galleries
  • SiteAdministration
  • SiteCollectionAdmin

These correspond to the columns in the Site Settings area as shown below:




In the Central Admin pages, examples for the 'Operations' page are:

  • Topology
  • GlobalConfiguration
  • Security
  • BackupRestore
  • LoggingAndReporting
  • DataConfiguration
  • Upgrade

And for the 'Application Management' page:

  • WebApplicationConfiguration
  • SiteManagement
  • ApplicationSecurity
  • ExternalService
  • WorkflowManagement

By examining these pages, it's fairly simple to work out where the values refer to.

I mentioned earlier that new groups of links can be created using the CustomActionGroup element. An example of this would be:

<CustomActionGroup

    Id="CustomSiteSettingsGroup"

    Location="Microsoft.SharePoint.SiteSettings"

    Title="New custom group"

    Sequence="100"

    Description="My description" />



This will then create a new group of links on the page with your custom title - SharePoint will take care of the rendering such that your new group will wrap onto another row of groups. Of course if this isn't what you want you'll probably have an interesting time customizing this.

Using CustomAction elsewhere

So having covered how to add links into the admin areas, I'll wrap up by listing some other valid values for the 'Location' attribute. This hopefully illustrates some of the options you have for customizing SharePoint in this way:
  • Microsoft.SharePoint.ContentTypeTemplateSettings
  • Microsoft.SharePoint.ContentTypeSettings
  • Microsoft.SharePoint.Administration.ApplicationCreated
  • Office.Server.ServiceProvider.Administration (Shared Services/SSP links)
  • Microsoft.SharePoint.ListEdit.DocumentLibrary
  • Microsoft.SharePoint.Workflows
  • NewFormToolbar
  • DisplayFormToolbar
  • EditFormToolbar
  • Microsoft.SharePoint.StandardMenu (SiteActions menu)
  • Mcrosoft.SharePoint.Create (_layouts/create.aspx - the screen used to specify what you want to create on your site)
  • Microsoft.SharePoint.ListEdit (the screen used to edit the properties of a list item)
  • EditControlBlock (image below)
I've put the last few in bold and added a description as I think they're particularly interesting. Of course, if you have other customizations in mind one or two of the others might have caught your eye! In particular being able to add custom actions to the EditControlBlock is interesting:




Here, a special attribute called 'RegistrationType' can be added to the CustomAction element, allowing you to control exactly the circumstances where your action should appear. Valid options include 'List', 'ContentType', 'FileType' and 'ProgId'. Vince (aka TheKid) has some good examples of this over on his blog.

Hopefully this has given you some ideas on how you can add or amend the SharePoint UI in this way. Happy customizing!

14 comments:

Robin Meuré said...

Check out the following page on MSDN to check out all the possible locations : http://msdn2.microsoft.com/en-us/library/ms473643.aspx

Found your awesome post while googling for all the possible locations :)

Robin Meuré said...

N/m my last post. You defined more in total. Maybe you can help me out, im searching for the location of the globallinks (mysite/mylinks)

Chris O'Brien said...

Hi Robin,

In fact the links you mention aren't provisioned using CustomAction. These are actually Delegate Controls with the following IDs:

MySite link: GlobalSiteLink1
My links link: GlobalSiteLink2

You might find some useful information in my article on Using the Delegate Control.

HTH,

Chris.

Robin Meuré said...

Hi Chris,

well I found a groupid to add my link in the personal links ('Welcome User' linkssection)
Check out the solution on my blog at http://glorix.blogspot.com/2007/08/custom-action-locations-and-groupid.html

btw if you want I will delete the information which i copied from your post and make a reference to your post.

Jeff said...

Hi Chris:

Thanks for your post. I need to do something a little different. The ECB normally displays associated with the Title column in a list. But, I am not using the title in my view. How can I associate the ECB with another column in my views?

Chris O'Brien said...

@Jeff,

Apologies for the delay in replying, I've been on holiday.

I don't _think_ there is a way to associate the ECB with a different column. I might be wrong though - did you find a way?

Chris.

cjuenck said...

Hi there,

does anyone have an idea how to add customactions to the "Send To" dialog?

Christian

Chris O'Brien said...

Christian,

I _think_ this can only be done by using JavaScript, since this menu is built in core.js and isn't exposed as a CustomAction location.

HTH,

Chris.

Carsten said...

You have a very nice translation of the SiteSettings page but, how do I find the match for _layouts/create.aspx and eks. the Web Pages section, i want to replace Web Pages> Sites and Workspaces Action with a custom

Chris O'Brien said...

Hi Carsten,

The best thing I can suggest is to search through the feature files which ship with SharePoint. Many of the links are added in this way, so you may find the ID of the particular link you are looking to modify.

HTH,

Chris.

Anonymous said...

Hi Chris!
I created a new listtemplate with new menu buttons for the manager with new views for new items, display and edit items. and i created a new list and the buttons are visible only in this list. til now it was great, but now my boss want me to hide the original buttons 'new', 'edit' and 'display item' in the ECB , DisplayFormToolbar and EditFormToolbar, but only when he is the current user. My problems: 1. I can't do it with HideCustomAction, because the changes for ECB must have done in the Core.js. but how else can I do it for DisplayFormToolbar or EditFormToolbar? The changes in Core.js only affect the ECB.. 2. when I will find how it works in any time in future, what do I have to change in the code to differentiate between Manager and normal workers? does it work with 'if (HasRights())'?
Please apologize my english!
Thank You in advance!
Claudia

Chris O'Brien said...

Hi Claudia,

Yes, making customizations like this often requires making changes in several areas. Remember however, that modifying the original SharePoint system files is not supported by Microsoft, so where possible you should consider if there's a way to implement the change without modifying supplied files. I suggest techniques for doing this for each of the changes I think you need below:

- modify JavaScript provided by core.js for the ECB items (override JavaScript by specifying an override JS file)
- modify toolbar used on list (provide a custom list form which uses a modified version of the toolbar) - this article has some good info on actually modifying the toolbar - http://www.sharepointblogs.com/tanujashares/archive/2008/01/11/customize-the-oob-list-menus-in-sharepoint-2007-lists.aspx

HTH,

Chris.

Rajni said...

Hi Chris,

When stuck I look into your blog for a way out.
The issue I am facing is that we need to deploy an application as solution on Sharepoint 2007 where all the webparts are deployed as a single feature.

Now I need to specify all these webparts under a new custom section group that comes when you have this window to add new webparts to your page.

I have tried to put entries in the Elements.xml, but this does not work. May be you could think of a reason....

Looking forward to a reply.

Rajni

Chris O'Brien said...

Rajni,

There are a couple of elements to this:

- ensure the web parts go in a certain group
- specify a value for the QuickAdd property on the WebPartZone in your HTML markup

HTH,

Chris.