How to: Work with User Custom Actions
Applies to: SharePoint Foundation 2010
Available in SharePoint Online
You can use the client object model to add custom actions to the user interface. The UserCustomActions property returns the collection of custom actions for a site collection, Web site, or list. To create a custom action in one of these collections, call the Add() method of the UserCustomActionCollection class. Set properties for the new action on the returned UserCustomAction object, and then call the Update() method before you execute the query by calling the ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) methods. The placement of a user custom action can be determined by its namespace location, custom action group, and sequence in relation to other user custom actions. For a table that lists possible values for custom action locations and groups, see Default Custom Action Locations and IDs.
Adding a user custom action for list items
The following example adds a user custom action to the drop-down menu that is displayed for list items. To place the new action on the menu, the Location property specifies EditControlBlock, Sequence specifies an order of placement in relation to other user custom actions, and Url specifies an absolute path to a page that defines the action. The example assumes the existence of a .aspx file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class CreateUserCustomActionList
{
static void Main()
{
string urlWebsite = "http://MyServer/sites/MySiteCollection";
ClientContext clientContext = new ClientContext(urlWebsite);
Web oWebsite = clientContext.Web;
List oList = oWebsite.Lists.GetByTitle("My List");
UserCustomActionCollection collUserCustomAction = oList.UserCustomActions;
UserCustomAction oUserCustomAction = collUserCustomAction.Add();
oUserCustomAction.Location = "EditControlBlock";
oUserCustomAction.Sequence = 100;
oUserCustomAction.Title = "My First User Custom Action";
oUserCustomAction.Url = urlWebsite + @"/_layouts/MyPage.aspx";
oUserCustomAction.Update();
clientContext.Load(oList,
list => list.UserCustomActions);
clientContext.ExecuteQuery();
}
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class CreateUserCustomActionList
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim clientContext As New ClientContext(siteUrl)
Dim oWebsite As Web = clientContext.Web
Dim oList As List = oWebsite.Lists.GetByTitle("My List")
Dim collUserCustomAction As UserCustomActionCollection = oList.UserCustomActions
Dim oUserCustomAction As UserCustomAction = collUserCustomAction.Add()
oUserCustomAction.Location = "EditControlBlock"
oUserCustomAction.Sequence = 100
oUserCustomAction.Title = "My First User Custom Action"
oUserCustomAction.Url = siteUrl + "/_layouts/MyPage.aspx"
oUserCustomAction.Update()
clientContext.Load(oList, Function(list) list.UserCustomActions)
clientContext.ExecuteQuery()
End Sub
End Class
End Namespace
Modifying a user custom action
The following example retrieves an action from the collection of user custom actions for the drop-down menu of items in a list, and updates the custom action to include an icon that represents the action on the menu. The example assumes the existence of an icon image file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\IMAGES.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class ModifyUserCustomAction
{
static void Main()
{
string urlWebsite = "http://MyServer/sites/SiteCollection";
ClientContext clientContext = new ClientContext(urlWebsite);
Web oWebsite = clientContext.Web;
List oList = oWebsite.Lists.GetByTitle("My List");
UserCustomActionCollection collUserCustomAction = oList.UserCustomActions;
clientContext.Load(collUserCustomAction,
userCustomActions => userCustomActions.Include(
userCustomAction => userCustomAction.Title));
clientContext.ExecuteQuery();
foreach (UserCustomAction oUserCustomAction in collUserCustomAction)
{
if (oUserCustomAction.Title == "My First User Custom Action")
{
oUserCustomAction.ImageUrl = "http://MyServer/_layouts/images/MyIcon.png";
oUserCustomAction.Update();
clientContext.ExecuteQuery();
}
}
}
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class ModifyUserCustomAction
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim clientContext As New ClientContext(siteUrl)
Dim oWebsite As Web = clientContext.Web
Dim oList As List = oWebsite.Lists.GetByTitle("My List")
Dim collUserCustomAction As UserCustomActionCollection = oList.UserCustomActions
clientContext.Load(collUserCustomAction, _
Function(userCustomActions) userCustomActions.Include( _
Function(userCustomAction) userCustomAction.Title))
clientContext.ExecuteQuery()
Dim oUserCustomAction As UserCustomAction
For Each oUserCustomAction In collUserCustomAction
If oUserCustomAction.Title = "My First User Custom Action" Then
oUserCustomAction.ImageUrl = "http://MyServer/_layouts/images/MyIcon.png"
oUserCustomAction.Update()
clientContext.ExecuteQuery()
End If
Next oUserCustomAction
End Sub
End Class
End Namespace
Adding a user custom action to the site actions of a Web site
Creating a user custom action on the Site Actions menu of a Web site is similar to creating an action for list items: You call the Add() method, set properties for the action, and then call Update(). The following example specifies Microsoft.SharePoint.StandardMenu for Location, and SiteActions for Group, to place the new action on the Site Actions menu. The value of Sequence specifies 101 so that the action will appear below an action whose sequence number is 100. The example assumes the existence of a .aspx file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class CreateUserCustomActionSite
{
static void Main()
{
string urlWebsite = "http://MyServer/sites/MySiteCollection";
ClientContext clientContext = new ClientContext(urlWebsite);
Web oWebsite = clientContext.Web;
UserCustomActionCollection collUserCustomAction = oWebsite.UserCustomActions;
UserCustomAction oUserCustomAction = collUserCustomAction.Add();
oUserCustomAction.Location = "Microsoft.SharePoint.StandardMenu";
oUserCustomAction.Group = "SiteActions";
oUserCustomAction.Sequence = 101;
oUserCustomAction.Title = "Website User Custom Action";
oUserCustomAction.Description = "This description appears on the Site Actions menu.";
oUserCustomAction.Url = urlWebsite + @"/_layouts/MyPage.aspx";
oUserCustomAction.Update();
clientContext.Load(oWebsite,
webSite => webSite.UserCustomActions);
clientContext.ExecuteQuery();
}
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class ModifyUserCustomAction
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim clientContext As New ClientContext(siteUrl)
Dim oWebsite As Web = clientContext.Web
Dim collUserCustomAction As UserCustomActionCollection = oWebsite.UserCustomActions
Dim oUserCustomAction As UserCustomAction = collUserCustomAction.Add()
oUserCustomAction.Location = "Microsoft.SharePoint.StandardMenu"
oUserCustomAction.Group = "SiteActions"
oUserCustomAction.Sequence = 101
oUserCustomAction.Title = "Website User Custom Action"
oUserCustomAction.Description = "This description appears on the Site Actions menu."
oUserCustomAction.Url = siteUrl + "/_layouts/MyPage.aspx"
oUserCustomAction.Update()
clientContext.Load(oWebsite, Function(webSite) webSite.UserCustomActions)
clientContext.ExecuteQuery()
End Sub
End Class
End Namespace
For information and examples about working with client objects within the context of the Microsoft SharePoint Foundation 2010 Silverlight object model, see Using the Silverlight Object Model.
See Also
Concepts
Default Custom Action Locations and IDs
SharePoint Client Object Creation
SharePoint 2010 Client Object Model Guidelines
Common Programming Tasks in the Managed Client Object Model