How to add ribbon button in SharePoint list and library

Test Your Skill

Q. Which class is required to retrieve data from selected lists or from all lists in the current site collection?
SPQuerySPWebDataQuerySPListDataQuerySPSiteDataQuery

View all questions...

The premise behind the ribbon is that it provides a more results-driven interface. Users focus on what they are doing, and commands are presented only for those things they can do at a specific time.

Those who think that ribbon concept is completely new in SharePoint 2010 are wrong. It was also in SharePoint 2007 to add button in that menu bar etc. Actually in SharePoint 2007, users face difficult to find actions button. So in SharePoint 2010, Microsoft added the Server ribbon to SharePoint to address this problem and added additional things to make it more powerful. Let me get in to more detail in ribbon button show that we can create our custom ribbon button.

Adding custom ribbon button in SharePoint list and library to provide various actions can make user life very easy. Let me take an out box ribbon button example to make you realize importance of ribbon button. If you are familiar with SharePoint 2010, you must aware about "Delete" ribbon button. Refer Mentioned below screenshot; user has options to delete multiple items at a time using delete ribbon button. But in SharePoint 2007 user will have to delete items one by one. So one of the best use of ribbon button to provide bulk operation in the SharePoint and you can use this architecture to provide various functionalities in the ribbon button to make good user experience.

Now we know the importance of ribbon button, so it is right time to get our hand dirty with custom ribbon button (Download sample code).

Steps to add ribbon button:
1. Create a "Empty SharePoint Project" > Add New Item > Click Empty Element
SharePoint-Empty-Element

2. Copy following XML file into Empty Element file

<?xml version="1.0" encoding="utf-8"?>

<CustomAction

Id="ShowHelloWorldButton"

RegistrationType="List"

RegistrationId="100"

Location="CommandUI.Ribbon.ListView"

Rights="EditListItems">

<CommandUIDefinition

Location="Ribbon.ListItem.Actions.Controls._children">

<Button

Id="Ribbon.ListItem.Actions.Controls.ShowHelloWorldButton"

Alt="Show HelloWorld Alert"

Sequence="1"

Image32by32="/_layouts/DemoSharePointRibbon/HelloWorld.jpg"

Command="ShowHelloWorldCommand"

LabelText="Hello World"

TemplateAlias="o1"

CommandType="General"/>

</CommandUIDefinition>

</CommandUIDefinitions>

<CommandUIHandler

Command="ShowHelloWorldCommand"

CommandAction="javascript:alert('Hello World');" />

</CommandUIHandlers>

</CommandUIExtension>

</CustomAction>

</Elements>

3. Deploy this solution, a hello world button will appear in all the custom list

Our first "Hello World" ribbon button is ready. Now I will walk you through important configurable properties of "Element .xml" file.

Property	Description
RegistrationType	None, List, ContentType, ProgId or FileType E.g. To show ribbon button on SharePoint list set List
RegistrationId	It is identifier of the list or item content type that this action is associated with. E.g. 100 RegistrationId is used to attach action with the custom list.
Location	Location of this custom action. Few important locations are mentioned below: · Microsoft.SharePoint.SiteSettings · If the custom action is a menu item or toolbar button, the possible options include EditControlBlock, NewFormToolbar, DisplayFormToolbar, and EditFormToolbar. · If the CustomAction element contains a CommandUIExtension child element, the Location must start with "CommandUI.Ribbon". E.g. In the "Hello World" sample we used CommandUI.Ribbon.ListView.
Rights	· If it is not specified, the action always appears in the list of actions. · Specifies a set of rights, so that it will visible only if user has all specified rights (logical AND will be applied if we assign multiple permission comma separated). Few important values for "Rights" property are mentioned below: ViewListItems, AddListItems, EditListItems, OpenItems, ViewVersions, ManagePersonalViews, ViewFormPages, Open, ViewPages, CreateSSCSite, BrowseDirectories, BrowseUserInfo, AddDelPrivateWebParts, UpdatePersonalWebParts, UseRemoteAPIs, CreateAlerts, EditMyUserInfo E.g. Specified "EditListItems" right to visible this button to the user who has edit item permission.
Sequence	Specifies the ordering priority for actions

Button properties:

Property	Description
Sequence	Order of placement if there are multiple ribbon buttons
Command	The name of the command to execute when the control is clicked. Note: Command attribute of the control should be the same as the value of the Command attribute of a corresponding CommandUIHandler element. E.g. "ShowHelloWorldCommand" is used in our sample.
CommandType	General \| OptionSelect \| IgnoredByMenu

Above mentioned information is enough to create ribbon button, but I wanted to highlight few challenges you are going to face when you actually started using it to solve real time requirement in your application:

1. Show ribbon button in the specific group: In our "Hello World" ribbon button appear in the "Actions" group. What if, we want appear in the other group like Manage, "Share & Track", "Workflows" etc. If you see element file of our sample carefully, we have specified location (Ribbon.ListItem.Actions.Controls._children) in the "CommandUIDefinition". So using this attribute we can change the group of ribbon button.

2. Button should be visible to user having specific permission: We have already discussed about the "Rights"attribute of button element, by specifying "Rights" attribute we can handle this scenario.

3. External JavaScript file: In our "Hello World" sample we need write just online line of JavaScript code. But to solve real world problem we need to write a lots of JavaScript code. So it is not a good idea to write JavaScript code in element file. In this case, we need an external JavaScript file to maintain code. There are two ways to achieve the same. Either create a JavaScript file and put reference in your mater page or follow the mentioned below steps to associate external JavaScript file:

a. Add this mentioned below custom action in your element file and put your JavaScript in the JavaScript file (e.g. HelloWorld.js).

<CustomAction

Id="ShowHelloWorldCommand.Script"

Location="ScriptLink"

ScriptSrc ="/_layouts/DemoSharePointRibbon/js/HelloWorld.js"/>

b. Call JavaScript method from "CommandAction" instead of writing inline JavaScript.

4. How to get selected items when user clicks on ribbon button: Put mentioned below code to get selected items:

//Using JavaScript client object model, we can get the selected items id

function GetSelectedItemsId() {

var ctx = SP.ClientContext.get_current();

var items = SP.ListOperation.Selection.getSelectedItems(ctx);

var selectedItems = '';

for (index in items) {

selectedItems = selectedItems + ',' + items[index].id;

}

return selectedItems;

}

5. Button should be disable if no item selected in the list view: Just check the behavior of out of box "Delete" ribbon button, If there is no item select, this button will be disable. Follow mentioned below steps to achieve this functionality:

a. Add following attribute in the element file under "CommandUIHandler" section:

<CommandUIHandler

Command="ExternalFileShowHelloWorldCommand"

EnabledScript="javascript:EnableButton();"

CommandAction="javascript:ShowAlert();" />

</CommandUIHandlers>

b. Add following JavaScript code in the external file:

function EnableButton() {

var ctx = SP.ClientContext.get_current();

var items = SP.ListOperation.Selection.getSelectedItems(ctx);

return items.length > 0;

}

6. How to perform server site operation using ribbon button:
There are three ways to do server site operation. They are mentioned below:

a. Put following code for postback and server side using the request id we can identify the button, and then perform action accordingly:

<CommandUIHandler

Command="ExternalFileShowHelloWorldCommand"

EnabledScript="javascript:EnableButton();"

CommandAction="__doPostBack('ShowHelloWorldPostback','');" />

</CommandUIHandlers>

//On page load check for request id

if (this.Page.Request["__EVENTTARGET"] == "ShowHelloWorldPostback")

{

//Call your method

}

Note: Selected items collection will be available in the server side. If you want selected items server side, before calling _doPostBack method save selected items id in the hidden variable.

b. Use JavaScript client side object model to perform action like add, edit, delete.

For example, suppose we have to provide functionality to change status of selected items to approve. So we can use following client side code to achieve the same:

function ApproveSelectedItems() {

var ctx = SP.ClientContext.get_current();

var items = SP.ListOperation.Selection.getSelectedItems(ctx);

var web = ctx.get_web();

var crList = web.get_lists().getById (SP.ListOperation.Selection.getSelectedList(ctx));

var index;

for (index in items) {

var selectedItem = crList.getItemById(items[index].id);

selectedItem.set_item(columnName, columnValue);

if ('' != currentList && changeRequestListName == currentList) {

selectedItem.set_item('Status', 'Approve');

}

selectedItem.update();

}

ctx.executeQueryAsync(Function.createDelegate(this, this.onsccess),

Function.createDelegate(this, this.onFail));

}

function onsccess (sender, args) {

if (this.SuccessMsg != undefined || this.SuccessMsg != null) {

alert(this.SuccessMsg);

}

function onfailure (sender, args) {

alert(MsgOperationFailed);

}

Note: But in this approach we are not providing any option to enter the status. But ideally we should ask from you to select option or enter status of the item. Because user might approve or reject the selected items.

c. Using layout page we can provide user to input information before updating or performing any action on any item. Follow mention below steps to achieve the same:

i. Create a layout page say approve.aspx

ii. Write your server side code in the code behind of layout page

iii. When user click on ribbon button, open layout page in the popup using SharePoint modal dialog API

iv. Pass selected items id as a query string parameter to the layout page

v. Read query string parameter

vi. Perform whatever action you want to do it on selected items

Comments

zohrePosted on: 6/2/2012 4:57:38 AM

Thanks,it is so helpful
but when i deploy my project in site it dose not work.if you know the answer tell me.

SofthackerPosted on: 6/2/2012 2:42:59 PM

Hello Zohre,

I have created a thread in our forum to discuss your issue with all experts associate with a2zmenu. Below is the thread URL:
http://www.a2zmenu.com/Ribbon-button-deployment-issues-in-SharePoint-2010_t111.aspx?ftid=2&siteId=0&forumId=48

TonyPosted on: 8/20/2012 10:45:20 PM

What programme are you using in this tutorial?

Also I am adding the button so that a user can add a column to a list automatically with a particular name. Do you know if I can also add it to a view with a particular width also?

Thanks

KatePosted on: 9/5/2012 5:44:55 AM

?ow to make sure that the button is visible only on a particular page, not at all, for example, where there is work with a document library? please help

KatePosted on: 9/5/2012 11:27:15 AM

?ow to make sure that the button is visible only on a particular page, not at all, for example, where there is work with a document library? please help

SofthackerPosted on: 9/5/2012 1:58:29 PM

Hello Kate,

We need to configure Location, RegistrationType, and RegistrationID properties to associate a ribbon button with list or library. So please refer to explanation in the above blog. If you wish to associate a ribbon button with the particular document library, you will have to do it programmatically. In the List object you can get "CustomAction" property, using which you can achieve your requirement.

I know, above information is very high level. It might help you. Please let me know, if you are need some more input.

KatePosted on: 9/6/2012 6:16:02 AM

My code:
<CustomAction
Id = "MyActions.Ribbon.CustomButtons"
Location = "CommandUI.Ribbon"
RegistrationType = "List"
RegistrationId = "c17b2895-dcc4-4c97-8ec7-9abe806ce790">

where c17b2895-dcc4-4c97-8ec7-9abe806ce790 - id of list. May be my syntax is wrong...

SofthackerPosted on: 9/6/2012 1:55:19 PM

Hello Kate,
RegistrationId can not be list or library id. It is template id. e.g. for template id of "Document Library" is 101. So if you wish to associate ribbon button with all documnet libraries, you can use this approch.

But in your case you have to associate ribbon button with the particular document library. So in this scenario you will have to use object model. Please refer below sample code:
using (SPSite objSite = new SPSite(SPContext.Current.Site.Url))
{
using (SPWeb objWeb = objSite.OpenWeb())
{
SPList objList = web.Lists.TryGetList("<List/Library Name>");
SPUserCustomActionCollection objActionscollection = objList.UserCustomActions;

foreach (SPUserCustomAction currentAction in objActionscollection
{
if (currentAction.Name == "<Action Name>")
{
currentAction.Location = "<List/Library Name>";
currentAction.Update();
objList.Update();
break;
}
}

//custom action code

SPUserCustomAction myCustonAction = objActionscollection.Add();
myCustonAction.Title = "<Action Title>";
myCustonAction.Name = "Action Name";
myCustonAction.Sequence = 10;
myCustonAction.Location = "EditControlBlock";
myCustonAction.Update();
}
}

KatePosted on: 9/7/2012 9:11:18 AM

Thanks!) but how this will might affect the xml code?

SofthackerPosted on: 9/7/2012 11:46:07 AM

Hi Kate,

If you use above mention approach, no need to use XML in this case. You will have to create a feature for custom action and in the feature activate, your have to write above mentioned code to associate ribbon button with the library.

Chris RylePosted on: 9/9/2012 9:31:30 AM

I have struggled for hours trying to get your item 6.a. to work. Including much research on other sites. How to I attach the code behind to the list view page so that I can catch the onPageLoad event? I can't find any example of this.

SofthackerPosted on: 9/9/2012 5:44:11 PM

Hi Chris Ryle,

I have used this approach while creating custom site definition. I had full control in the list view and I was able to associate code behind with view. I have created a class which inherits webpartpage class available in SharePoint. Put this dll into GAC and changed the inheritance of view page.

But in case you don't have full control on view page and you have applied custom master page having code behind. You can use matser page "OnPageLoad" event to capture this postback. Do let me know, in case you need more help.

Chris RylePosted on: 9/11/2012 9:08:20 PM

I have now solved my problem using the info at the following link http://www.thorntontechnical.com/tech/sharepoint/sharepoint-2010-context-menu-item-with-custom-code
However your answer, as many I have looked up, assumes too much.
In visual studio I can easily create a new menu or ribbon item by creating an element as described above. You can put in a __doPostBack javascript call. But very few posts describe how to create whatever object is going to contain the code behind and how it is linked to the XML.
Even the example I found does not really explain why a class based on an SPLink button is used. And even its author seems unsure why a step to force Sharepoint to load the control appears to be necessary only in some cases. (I had to do this to make it work)

KatePosted on: 9/28/2012 7:32:28 AM

Hi! The answer for my problem I have found here http://markeev.com/sharepoint/ribbon/?topic=html/ribbonCustomAction.htm
It's very good article! )))

ehazePosted on: 10/12/2012 8:09:55 PM

@Softhacker
The code you posted on 9/6/2012 1:55:19 PM, where does it belong in the VS project?

SofthackerPosted on: 10/12/2012 9:13:35 PM

Hi Ehaze,

Create an empty SharePoint Project and create a feature and put the above code on feature activation.

ehazePosted on: 11/2/2012 2:33:29 PM

What if you want to export all the items in the view, not just the selected items?

Add Comment

Comment

Name
(Required)

E-mail (Privacy assured)
(Required)

Subscribe to this site by email

Test Your Skill

Add Comment

Poll of the Day

Related Contents

Online Test Papers

Related Tutorials

Fun @ Work

Top Blogs