Add custom SharePoint 2010, 2013 ribbon group,
tab, button and other controls: VB.NET, C#

Ribbon Designer
for Microsoft® SharePoint® and and Office 365

Add-in Express Home > Ribbon Designer for SharePoint and Office 365 > Online Guide > Creating a custom SharePoint ribbon tab

Creating a custom SharePoint ribbon tab

The sample project below demonstrates how you create the Ribbon UI of your SharePoint 2010, 2013 or SharePoint Online solution in Visual Studio 2010.

A bit of theory

In SharePoint Foundation terms, the Ribbon Designer is a feature. It provides a True RAD way for developing a custom Ribbon UI of your SharePoint solution. Using information provided at design-time, the Ribbon Designer creates a well-formed XML markup, which complies with the Server Ribbon scheme. Then, at a proper moment, the Ribbon Designer sends the XML to the server. Basing on the markup, the server creates the required Ribbon UI and connects it to the events - both server and client.

Developing SharePoint projects requires that you have administrative permissions. In addition, if you have Windows Vista, Windows 7, or Windows 2008, it is imperative that you start Visual Studio 2010 via Run as Administrator.

Adding the Ribbon Designer

You have two options:

• Create a new SharePoint project
• Add the Ribbon Designer to an existing SharePoint project

Create a new SharePoint project:

In Visual Studio, open the New Project dialog and navigate to the SharePoint folder in the Visual Basic or Visual C# branch depending on your preferred programming language.

Select the Add-in Express SharePoint Ribbon item and click OK. This starts a one-step project wizard shown in the screenshot below:

The project wizard requires that you specify a local site for debugging your solution. It allows you to choose the name of the feature enclosing the Ribbon Designer's functionality. Also, you must specify whether the solution will deploy to a server farm (default) or it will be a sandboxed solution. Clicking Finish creates and opens a new solution in the IDE. The solution contains just one project, a SharePoint project. We discuss it in Ribbon Designer basics.

See also: Differences between sandboxed and farm solutions and Sandboxed solution considerations.

Add the Ribbon Designer to an existing SharePoint project:

You can add a Ribbon designer to an application page, user control or Visual Web part: just right-click the corresponding node in the Solution Explorer and choose the Add Ribbon Designer item. See also Integrating with existing SharePoint solutions.

In the dialog, select ADX SharePoint Ribbon, enter a name in the Name text box and click Add.

Ribbon Designer basics

Following the instructions above opens the Ribbon Designer in your project. The designer provides access to four areas:

• Ribbon Toolbox - (#1 in the screenshot below) it contains commands; clicking a command adds a corresponding Ribbon component to the designer surface.
• Ribbon designer - (#2) it is a usual designer.
• In-place designer - (#3) if there's a visual designer for the currently selected Add-in Express component, then it is shown in this area.
• Help panel - see #4 in the screenshot below.

Before we start looking at how to use these areas, let us find the Ribbon Designer files in your project.

Ribbon Designer files

The Ribbon Designer is a feature (in SharePoint Foundation terms). You specify the feature's name in the Add New Item dialog (see Adding the Ribbon Designer).

The main file is called {feature name}.feature. In this sample, we name the feature SPRibbon, the resulting file name is SPRibbon.feature (see the screenshot).

The feature provides three sections: designer, code and JavaScript code. To access them, you use the corresponding items of the context menu – just right-click the feature as shown in the screenshot.

Ribbon tabs and controls

To add a new tab to the Ribbon, you use the ADXSPRibbonTab command on the Ribbon Toolbox to add an AddinExpress.SharePoint.ADXSPRibbonTab component to the designer.

Then, in the in-place visual designer, use tool buttons to add or delete the Ribbon components that form the Ribbon interface of your SharePoint 2010, 2013 or SharePoint Online project.

To create the Ribbon UI shown in the screenshot above, change the caption of your tab to "My Ribbon Tab". Then, add a Ribbon group, and change its caption to "My Ribbon Group". Finally, select the group, add a button and set its caption to "My Ribbon Button". Use the ImageList and Image properties to set the image for the button; add an ImageList component onto the designer surface to provide images for your Ribbons.

See also Ribbon controls in detail, Dealing with built-in Ribbon controls.

Server-side events

Add an event handler to the OnAction event of the button and write the following code:

			Private Sub AdxspRibbonButton1_OnAction(sender As System.Object, _
				e As AddinExpress.SharePoint.ADXSPButtonActionEventArgs) _
				Handles AdxspRibbonButton1.OnAction
				' This event is not supported in sandboxed solutions.
				e.Result = ProcessMessage("Button is clicked")
			End Sub

			Private Function ProcessMessage(Message As String) As String
				Dim result As String = "Message is NOT processed"
				Dim rnd As New System.Random
				Dim val As Integer = rnd.Next()
				If CBool(val Mod 2) Then result = "Message is processed"
				Return "Message is:" + Message + " Result is:" + result
			End Function
			

			private void adxspRibbonButton1_OnAction(object sender, 
				ADXSPButtonActionEventArgs e)
			{
				// This event is not supported in sandboxed solutions.
				e.Result = ProcessMessage("Button is clicked");
			}

			private string ProcessMessage(string Message)
			{
				string result = "Message is NOT processed";
				System.Random rnd = new System.Random();
				int val = rnd.Next();
				if (val % 2 == 0)
					result = "Message is processed";
				return "Message is:" + Message + " Result is:" + result;
			}
			

To handle the result, you add an event handler to the OnInitialize event (this is a JavaScript event) of the Ribbon Designer and write this code:

			SPRibbonProject.SPRibbon.prototype.SPRibbonOnInitialize_EventHandler =
				function (sender, isPostBack) {
				if (isPostBack) {
					var result = this.getPostBackResult();
					if (result != null && result != "") {
						alert(result);
					}
				}
			}
			

Client-side events

Now, let's handle an event of a Ribbon control on the client side.

You start with adding an event handler to the OnClick event of the Ribbon button created on the previous step. Now, write this JavaScript code:

			SPRibbonProject.SPRibbon.prototype.AdxspRibbonButton1OnClick_EventHandler =
				function (sender) {
				
				var defaultMessage = "[no message]";
				var message = prompt("Enter a message", defaultMessage);
				if (message != null && message != "" & message != defaultMessage) {
					// See the OnAction event of the Ribbon Designer
					this.Submit("ProcessMessage", message);
				}
				else
					sender.AllowPostback = false;
			}
			

That is, when required conditions are met, the event handler calls the Submit method. The parameters passed to the method are the "ProcessMessage" string (which is interpreted as an action's ID) and the message itself. If conditions are not met, the event handler prevents generation of a postback request.

If the event handler for the OnAction event of the Ribbon Designer is supplied with the corresponding action ID, it invokes the ProcessMessage method as follows:

			Private Sub SPRibbon_OnAction(sender As System.Object, _
				e As AddinExpress.SharePoint.ADXSPRibbonActionEventArgs) _
				Handles MyBase.OnAction
				' This event is not supported in sandboxed solutions.   
				If (e.ActionId = "ProcessMessage") Then
					e.Result = ProcessMessage(e.CustomData)
				End If
			End Sub

			Private Function ProcessMessage(Message As String) As String
				Dim result As String = "Message is NOT processed"
				Dim rnd As New System.Random
				Dim val As Integer = rnd.Next()
				If CBool(val Mod 2) Then result = "Message is processed"
				Return "Message is:" + Message + " Result is:" + result
			End Function
			

			private void SPRibbon_OnAction(object sender, ADXSPRibbonActionEventArgs e)
			{
				// This event is not supported in sandboxed solutions.
				if (e.ActionId == "ProcessMessage")
					e.Result = ProcessMessage(e.CustomData);
			}

			private string ProcessMessage(string Message)
			{
				string result = "Message is NOT processed";
				System.Random rnd = new System.Random();
				int val = rnd.Next();
				if (val % 2 == 0)
					result = "Message is processed";
				return "Message is:" + Message + " Result is:" + result;
			}
			

Debugging the project

For instructions on debugging SharePoint projects, see Debugging SharePoint solutions.

Deploying the Ribbon UI

For instructions on deploying SharePoint projects, see Packaging and deploying SharePoint solutions. The functionality of the Ribbon Designer is provided in AddinExpress.SharePoint.dll; you must deploy this file onto the target server.

Deploying for Office 365

The Ribbon Designer completely supports sandboxed solutions, so it can be deployed on an Office 365 web site.