How to: Add and Modify User Custom Actions Using JavaScript

Artikel
09/24/2014

Letzte Änderung: Montag, 20. Juni 2011

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
Adding a User Custom Action for List Items Using ECMAScript (JavaScript, JScript)
Modifying a User Custom Action Using JavaScript
Adding a User Custom Action to the Site Actions of a Website

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, website, or list. To create a custom action in one of these collections, call the add() function of the UserCustomActionCollection object. Set properties for the new action on the returned UserCustomAction, and then call the update() function before you execute the query by calling executeQueryAsync(succeededCallback, failedCallback). 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 Benutzerdefinierte Standardaktionsspeicherorte und IDs.

Adding a User Custom Action for List Items Using ECMAScript (JavaScript, JScript)

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 an .aspx file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.

var siteUrl = '/sites/MySiteCollection';

function createUserCustomActionList() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.oList = oWebsite.get_lists().getByTitle('My List');
    var collUserCustomAction = oList.get_userCustomActions();
        
    var oUserCustomAction = collUserCustomAction.add();
    oUserCustomAction.set_location('EditControlBlock');
    oUserCustomAction.set_sequence(100);
    oUserCustomAction.set_title('My First User Custom Action');
    oUserCustomAction.set_url(siteUrl + '/_layouts/MyPage.aspx');
    oUserCustomAction.update();
        
    clientContext.load(oList, 'Title' ,'UserCustomActions');
    
    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    alert('Custom action created for ' + this.oList.get_title());}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Modifying a User Custom Action Using JavaScript

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.

var siteUrl = '/sites/MySiteCollection';

function modifyUserCustomAction() {

    this.clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.oList = oWebsite.get_lists().getByTitle('My List');
    this.collUserCustomAction = oList.get_userCustomActions();
        
    clientContext.load(oList,'UserCustomActions','Title');

    clientContext.executeQueryAsync(Function.createDelegate(this, this.SetImage), Function.createDelegate(this, this.onQueryFailed));
}

function SetImage() {

    var customActionEnumerator = collUserCustomAction.getEnumerator();

    while (customActionEnumerator.moveNext()) 
    {
        var oUserCustomAction = customActionEnumerator.get_current();
            
        if (oUserCustomAction.get_title() == 'My First User Custom Action') 
        {
            oUserCustomAction.set_imageUrl('http://MyServer/_layouts/images/MyIcon.png');
            oUserCustomAction.update();
                
            clientContext.load(oUserCustomAction);

            clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
        }
    }
}

function onQuerySucceeded() {

    alert('Custom action changed for ' + this.oList.get_title());
}

function onQueryFailed(sender, args) {

        alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Adding a User Custom Action to the Site Actions of a Website

Creating a user custom action on the Site Actions menu of a website is similar to creating an action for list items: You call the add() function, 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 an .aspx file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.

var siteUrl = '/sites/MySiteCollection';

function createUserCustomActionSite() {

    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();
    var collUserCustomAction = oWebsite.get_userCustomActions();
        
    var oUserCustomAction = collUserCustomAction.add();
    oUserCustomAction.set_location('Microsoft.SharePoint.StandardMenu');
    oUserCustomAction.set_group('SiteActions');
    oUserCustomAction.set_sequence(101);
    oUserCustomAction.set_title('ECMA Website User Custom Action ECMA');
    oUserCustomAction.set_description('This description appears on the Site Actions menu.');
    oUserCustomAction.set_url(siteUrl + '/_layouts/jstest2.aspx');
    oUserCustomAction.update();
        
    clientContext.load(oWebsite, 'Title', 'UserCustomActions');
    
    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {

    alert('Custom action created for ' + this.oWebsite.get_title());
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}