Add/Remove Custom Ribbon Items on SharePoint List Using CSOM PowerShell

Introduction

In this article, you will learn how to add or remove custom ribbon items (user actions) on SharePoint list using CSOM Powershell on SharePoint 2013 / SharePoint online sites.

Steps Involved

The following prerequisites need to be executed before going for any operations using CSOM PowerShell on SharePoint sites.

1. Add the references using the Add-Type command with the necessary reference paths. The necessary references are Client.dll, Client.Runtime.dll and publishing.dll.
   

   Add-Type -Path
   
   "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
   
   Add-Type -Path
   
   "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
   
   Add-Type -Path
   
   "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Publishing.dll"

2. Initialize client context object with the site URL.
   

   $siteURL = ""
   $ctx = New-Object Microsoft.SharePoint.Client.ClientContext($siteURL)

3. If you are trying to access SharePoint Online site then you need to setup the site credentials with credentials parameter and load it to the client context. 
   

   #Not required for on premise site - Start
   $userId = ""
   $pwd = Read-Host -Prompt "Enter password" -AsSecureString
   $creds = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($userId, $pwd)
   $ctx.credentials = $creds
   #Not required for on premise site - End

4. If you are trying to access the SharePoint on premise site then the credentials parameter is not required to be set to the context but you need to run the code on the respective SharePoint Server or you need to pass the network credentials and set the context.
   

   #Credentials for on premise site - Start
   $pwd = Read-Host -Prompt "Enter password" -AsSecureString
   $creds = New-Object System.Net.NetworkCredential("domain\userid", $pwd)
   $ctx.Credentials = $creds
   #Credentials for on premise site - End

Add Custom Ribbon Items (User Actions) to List

We will see how we can add the custom ribbon items (actions) to the SharePoint list. 

• Get the existing user action collection. Access the web and get the existing user actions using UserCustomActions property. Load and execute the property.
  

  $web = $ctx.Site.RootWeb
  $userActions = $web.UserCustomActions
  $ctx.Load($userActions)
  $ctx.ExecuteQuery()

• Then to the user actions collection, add new custom action. The necessary parameters for new action are registration id, title, registration type and location.
  
  
• Registration Id - Corresponding List template id to add the user action. For example, here 100 denotes the custom list templates.
• Registration Type -  Denotes association type.
• location - Custom Action location.
  

  $newRibbonItem = $userActions.Add()
  $newRibbonItem.RegistrationId = "100"
  $newRibbonItem.Title = "Custom Ribbon"
  $newRibbonItem.RegistrationType = [Microsoft.SharePoint.Client.UserCustomActionRegistrationType]::List
  $newRibbonItem.Location = "CommandUI.Ribbon"

• Build the xml for the new definition with correspoding handler. In this case, I have considered button as a custom action and associated alert box to the action. You can build your own logic on command action parameter. Location in the xml denotes the place where item will be placed.
  
  
• Update and execute the query.
  

  $ribbonUI = '<CommandUIExtension>
                      <CommandUIDefinitions>
                          <CommandUIDefinition Location="Ribbon.List.Actions.Controls._children">
                              <Button Id="Ribbon.List.Actions.ShowAlert" Alt="Show Alert" Sequence="100"
                                   Command="ShowRibbonAlert"
                                   LabelText="Custom Alert"
                                   TemplateAlias="o1"
                                   Image32by32="_layouts/15/images/alertme.png"
                                   Image16by16="_layouts/15/images/alertme.png" />
                         </CommandUIDefinition>
                      </CommandUIDefinitions>
                      <CommandUIHandlers>
                          <CommandUIHandler Command="ShowRibbonAlert"
                               CommandAction="javascript:alert(''hi'');"/>
                      </CommandUIHandlers>
                  </CommandUIExtension >'
  
  $newRibbonItem.CommandUIExtension = $ribbonUI
  $newRibbonItem.Update()
  $ctx.Load($newRibbonItem)
  $ctx.ExecuteQuery()

After executing the above steps you can find the new ribbon item on the sharepoint custom list (list tab). The following snapshot depicts the custom ribbon action.

Remove Custom Ribbon Items (User Actions) from List

We will see how we can remove the custom ribbon items (actions) from the SharePoint list.

• Get the existing user action collection. Access the web and get the existing user actions using UserCustomActions property. Load and execute the property.
  

  $web = $ctx.Site.RootWeb
  $userActions = $web.UserCustomActions
  $ctx.Load($userActions)
  $ctx.ExecuteQuery()

• Delete items
  
  
• If items exists, use filter conditions and filter the ribbon items and assign items in to an array to delete. (Multiple items can not be deleted from the result variable, since the items are present in the enumeration variable. So we are assigning it to array and deleting the items or actions)
  
  
• From the array, delete the items and finally execute the query.
  

  $itemsToDelete = @()
  if($userActions.Count -le 0){
      Write-Host "No Ribbon Items found to delete"
  }
  else{
      foreach($userAction in $userActions){
          $itemsToDelete += $userAction
      }
      foreach($item in $itemsToDelete){
          Write-Host "Deleting Ribbon Item : " $item.Title
          $item.DeleteObject()
      }
      $ctx.ExecuteQuery()
  }

The above operation deletes all the custom ribbon items from the site. You can filter out to the exact ribbon item from the for each loop and delete the item(s).

 

Summary

Thus, you have learned how to add or remove custom ribbon items to/from the SharePoint lists using CSOM PowerShell on SharePoint 2013 / SharePoint online sites.