CommandUIHandler Element

Applies to: SharePoint Foundation 2010

Defines the handler for a command.

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

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. 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="https://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>