CommandUIHandler element

Applies to: SharePoint 2016 | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

Defines the handler for a command.

Definition

<CommandUIHandler
  Command = "Text"
  CommandAction = "Text"
  EnabledScript = "Text"
 />

Elements and attributes

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

**Command**

Required. The name of a command. The value of this attribute matches the value of a **Command** attribute on an element that defines a control.

**CommandAction**

Required. A script statement to execute when this handler is invoked. Microsoft SharePoint Foundation calls the **eval** method, passing in the value of this attribute.

The value of the attribute can contain substitution tokens that are transformed at rendering. The following tokens are recognized:

  • `{ItemId}` - ID (GUID) taken from the list view.

  • `{ItemUrl}` - Web-relative URL of the list item (Url).

  • `{RecurrenceId}` - ID of a recurrent item (RecurrenceID).

  • `{SiteUrl}` - The fully qualified URL to the site (Url).

  • `{ListId}` - ID (GUID) of the list (ID).

  • `{ListUrlDir}` - Server-relative URL of the site plus the list's folder.

  • `{Source}` - Fully qualified request URL.

  • `{SelectedListId}` - ID (GUID) of the list that is currently selected from a list view.

  • `{SelectedItemId}` - ID of the item that is currently selected from the list view.

**EnabledScript**

Optional.

**Note**: The **EnabledScript** attribute doesn't work on custom actions deployed to the host web by an SharePoint Add-in.

A script statement that is executed to determine whether the command is enabled or disabled. The script expression should return a **Boolean** value, **true** if the command is enabled and **false** if not. If the ribbon is disabled, commands are grayed out and are not clickable.

As with the **CommandAction** attribute, the **eval** method is called with the value of this attribute as an argument. The **EnabledScript** attribute does not support the substitution tokens that are described for the **CommandAction** attribute.

Child elements

None

Parent elements

CommandUIHandlers

Occurrences

Minimum: 1

Maximum: unbounded

Example

The following example defines a button command and a corresponding handler.

    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <CustomAction
       Id="EmailContacts"
       RegistrationType="List"
       RegistrationId="105"
       Location="CommandUI.Ribbon">
        <CommandUIExtension>
          <CommandUIDefinitions>
            <CommandUIDefinition
             Location="Ribbon.ListItem.Actions.Controls._children">
              <Button
                Id="Ribbon.ListItem.Actions.Email"
                Alt="$Resources:core,E-Mail;"
                Sequence="55"
                Command="emailContacts"
                LabelText="$Resources:core,E-Mail;"
                Description="$Resources:core,E-Mail;"
                TemplateAlias="o1"/>
            </CommandUIDefinition>
          </CommandUIDefinitions>
          <CommandUIHandlers>
            <CommandUIHandler
             Command="emailContacts"
             CommandAction="javascript:
               function getItemIds()
               {
                 var itemIds = '';
                 var items = SP.ListOperation.Selection.getSelectedItems();
                 var item;
                 for(var i in items)
                 {
                   item = items[i];
                   if(itemIds != '')
                   {
                     itemIds = itemIds + ',';
                   }
                   itemIds = itemIds + item.id;
                 }
                 return itemIds;
               }
               function handleReadyStateChange()
               {
                 if (client.readyState == 4)
                 {
                   if (client.status == 200) 
                   {
                     // client.responseText is mailto string
                     window.location = ('mailto:' + client.responseText);
                   }
                 }
               }
               function invokeEmailContacts()
               {
                 var params = 'itemids=' + getItemIds(); 
                 // Posting to EmailContacts.ashx to get the mailto string
                 var site='{SiteUrl}'; 
                 var url = site + '/_layouts/emailcontacts.ashx?listId={ListId}';
                 client = null;
                 client = new XMLHttpRequest();
                 client.onreadystatechange =  handleReadyStateChange;
                 client.open('POST', url, true);         
                 client.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
                 client.setRequestHeader('Content-length', params.length);
                 client.send(params);
               }      
               invokeEmailContacts();"
             
          EnabledScript="javascript:
               function enableEmailContacts()
               {
                 var items = SP.ListOperation.Selection.getSelectedItems();
                 return (items.length > 0);
               }
               enableEmailContacts();"/>
          </CommandUIHandlers>
        </CommandUIExtension>
      </CustomAction>
    </Elements>