Using the Office Ribbon

In this article
Ribbon Overview
Defining the Ribbon Resource
Creating Ribbon Event Handlers

Although you can insert buttons and user controls on your form, implementing the Office Ribbon provides a user interface that has a similar appearance to the built-in tools and other Office applications.

Ribbon Overview

To use the Office Ribbon, you must implement the IRibbonExtensibility interface and return a string that contains your CustomUI XML definition in the GetCustomUI method. This is the only required step in creating and displaying a ribbon for your tool. The CustomUI that you define will be combined with the standard Workspace and View tabs. By default, your ribbon tabs will appear after the View tab. However, you can customize the ordering of the tabs by using the insertBeforeMso and insertAfterMso attributes.

Defining the Ribbon Resource

In the templates and samples, the CustomUI definition is stored as a string resource within the Ribbon.resx resource. You can find the XML file that contains the CustomUI in the Resources directory of the sample.

        public string GetCustomUI(string RibbonID)
        {
            return Ribbon.CustomUI;
        }

When you create a new project from the SharePoint Workspace 2010 Add-In template, the file CustomUI.xml contains the following:

<?xml version="1.0" encoding="UTF-8"?>
<customUI onLoad="Ribbon_Load" xmlns="https://schemas.microsoft.com/office/2006/01/customui" >
    <ribbon>
        <tabs>
            <tab id="tab1" label="AddIn" insertBeforeMso="TabWorkspace">
                <group id="group1" label="View">
                    <button id="save" onAction="OnSave" imageMso="FileSave" label="Save" showImage="true" size="large" />
                    <button id="clear" onAction="OnClear" imageMso="TableEraser" label="Clear" showImage="true" size="large" />
                    <button id="update" onAction="OnFetch" imageMso="Refresh" label="Refresh" showImage="true" size="large" />
                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>

Creating Ribbon Event Handlers

To make the ribbon useful and relevant to your add-in, you can create event handlers for various controls on your ribbon to give it functionality.

To implement a ribbon event handler, you define a method with the name that you specified in your CustomUI Xml for the event. You can perform start-up operations on the ribbon by providing an onLoad event handler. This lets you save a reference to the IRibbonUI interface, which enables you to make calls to the Ribbon UI, such as to invalidate control states.

For example, if CustomUI.xml contains the following:

<customUI onLoad="Ribbon_Load" ...>
...

then your application should have the following code:

private IRibbonUI ribbonUI;

public void Ribbon_Load(IRibbonUI ribbonUI)
{
    this.ribbonUI = ribbonUI;
    this.ribbonUI.ActivateTab("tab1");
}

To implement a button onAction event handler, CustomUI.xml can contain:

<button id="save" onAction="OnSave" imageMso="FileSave" label="Save" showImage="true" size="large" />

And your application should have the following code:

public void OnSave(IRibbonControl control)
{
    this.dataAdapter.Update(this.dataSet);
}

See the samples provided with the SDK for more examples of creating ribbon extensions.