Ribbon Designer
for Microsoft® SharePoint® and and Office 365Add-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 or Office 365 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:
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:
Click the project's node in Solution Explorer. Then, on the Project menu, click Add New Item to open the
Add New Item dialog. In the dialog, in the Installed Templates list, expand the SharePoint node, and then click 2010.
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 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.
Back to Ribbon Designer for SharePoint and Office 365 homepage | 
