Walkthrough: Creating a Custom Tab by Using Ribbon XML

  • Article

This walkthrough demonstrates how to create a custom Ribbon tab by using the Ribbon (XML) item.

Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2013 and Excel 2010; InfoPath 2013 and InfoPath 2010; Outlook 2013 and Outlook 2010; PowerPoint 2013 and PowerPoint 2010; Project 2013 and Project 2010; Visio 2013 and Visio 2010; Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

  • Adding buttons to the Add-Ins tab. The Add-Ins tab is the default tab that is defined in the Ribbon XML file.

  • Automating Microsoft Office Word by using the buttons on the Add-Ins tab.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

link to video For a related video demonstration, see How Do I: Use the Ribbon Designer to Customize the Ribbon in Excel?.

Creating the Project

The first step is to create a Word add-in project. You will later customize the Add-Ins tab of this document.

To create a new project

  • Create a Word Add-in project with the name MyRibbonAddIn.

    For more information, see How to: Create Office Projects in Visual Studio.

    Visual Studio opens the ThisAddIn.cs or ThisAddIn.vb code file and adds the MyRibbonAddIn project to Solution Explorer.

Creating the Add-Ins Tab

To create the Add-Ins tab, add a Ribbon (XML) item to your project. Later in this walkthrough, you will add some buttons to this tab.

To create the Add-Ins tab

  1. On the Project menu, click Add New Item.

  2. In the Add New Item dialog box, select Ribbon (XML).

  3. Change the name of the new Ribbon to MyRibbon, and click Add.

    The MyRibbon.cs or MyRibbon.vb file opens in the designer. An XML file that is named MyRibbon.xml is also added to your project.

  4. In Solution Explorer, right-click ThisAddin.cs or ThisAddin.vb, and then click View Code.

  5. Add the following code to the ThisAddin class. This code overrides the CreateRibbonExtensibilityObject method and returns the Ribbon XML class to the Office application.

    Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

    protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

  6. In Solution Explorer, right-click the MyRibbonAddIn project and then click Build. Verify that the project builds without errors.

Adding Buttons to the Add-Ins Tab

The goal for this add-in is to give users a way to add boilerplate text and a specific table to the active document. To provide the user interface, add two buttons to the Add-Ins tab by modifying the Ribbon XML file. Later in this walkthrough, you will define callback methods for the buttons. For more information about the Ribbon XML file, see Ribbon XML.

To add buttons to the Add-Ins tab

  1. In Solution Explorer, right-click MyRibbon.xml and then click Open.

  2. Replace the contents of the tab element with the following XML. This XML changes the label of the default control group to Content, and it adds two new buttons with the labels Insert Text and Insert Table.

    <tab idMso="TabAddIns">
    <group id="ContentGroup" label="Content">
        <button id="textButton" label="Insert Text"
             screentip="Text" onAction="OnTextButton"
             supertip="Inserts text at the cursor location."/>
        <button id="tableButton" label="Insert Table"
             screentip="Table" onAction="OnTableButton"
             supertip="Inserts a table at the cursor location."/>
    </group>
</tab>

Automating the Document by Using the Buttons

You must add onAction callback methods for the Insert Text and Insert Table buttons to perform actions when the user clicks them. For more information about callback methods for Ribbon controls, see Ribbon XML.

To add callback methods for the buttons

  1. In Solution Explorer, right-click MyRibbon.cs or MyRibbon.vb, and then click Open.

  2. Add the following code to the top of the MyRibbon.cs or MyRibbon.vb file. This code creates an alias for the Microsoft.Office.Interop.Word namespace.

    Imports Word = Microsoft.Office.Interop.Word

    using Word = Microsoft.Office.Interop.Word;

  3. Add the following method to the MyRibbon class. This is a callback method for the Insert Text button that adds a string to the active document at the current location of the cursor.

    Public Sub OnTextButton(ByVal control As Office.IRibbonControl)
    Dim currentRange As Word.Range = Globals.ThisAddIn.Application.Selection.Range
    currentRange.Text = "This text was added by the Ribbon." 
End Sub

    public void OnTextButton(Office.IRibbonControl control)
{
    Word.Range currentRange = Globals.ThisAddIn.Application.Selection.Range;
    currentRange.Text = "This text was added by the Ribbon.";
}

  4. Add the following method to the MyRibbon class. This is a callback method for the Insert Table button that adds a table to the active document at the current location of the cursor.

    Public Sub OnTableButton(ByVal control As Office.IRibbonControl)
    Dim missing As Object = System.Type.Missing

    Dim currentRange As Word.Range = Globals.ThisAddIn.Application.Selection.Range
    Dim newTable As Word.Table = Globals.ThisAddIn.Application.ActiveDocument.Tables.Add( _
               currentRange, 3, 4)

    ' Get all of the borders except for the diagonal borders. 
    Dim borders() As Word.Border = New Word.Border(6) {}
    borders(0) = newTable.Borders(Word.WdBorderType.wdBorderLeft)
    borders(1) = newTable.Borders(Word.WdBorderType.wdBorderRight)
    borders(2) = newTable.Borders(Word.WdBorderType.wdBorderTop)
    borders(3) = newTable.Borders(Word.WdBorderType.wdBorderBottom)
    borders(4) = newTable.Borders(Word.WdBorderType.wdBorderHorizontal)
    borders(5) = newTable.Borders(Word.WdBorderType.wdBorderVertical)

    ' Format each of the borders. 
    For Each border As Word.Border In borders
        border.LineStyle = Word.WdLineStyle.wdLineStyleSingle
        border.Color = Word.WdColor.wdColorBlue
    Next 
End Sub

    public void OnTableButton(Office.IRibbonControl control)
{
    object missing = System.Type.Missing;
    Word.Range currentRange = Globals.ThisAddIn.Application.Selection.Range;
    Word.Table newTable = Globals.ThisAddIn.Application.ActiveDocument.Tables.Add(
    currentRange, 3, 4, ref missing, ref missing);

    // Get all of the borders except for the diagonal borders.
    Word.Border[] borders = new Word.Border[6];
    borders[0] = newTable.Borders[Word.WdBorderType.wdBorderLeft];
    borders[1] = newTable.Borders[Word.WdBorderType.wdBorderRight];
    borders[2] = newTable.Borders[Word.WdBorderType.wdBorderTop];
    borders[3] = newTable.Borders[Word.WdBorderType.wdBorderBottom];
    borders[4] = newTable.Borders[Word.WdBorderType.wdBorderHorizontal];
    borders[5] = newTable.Borders[Word.WdBorderType.wdBorderVertical];

    // Format each of the borders. 
    foreach (Word.Border border in borders)
    {
        border.LineStyle = Word.WdLineStyle.wdLineStyleSingle;
        border.Color = Word.WdColor.wdColorBlue;
    }
}

Testing the Add-In

When you run the project, Word opens and the tab named Add-Ins appears on the Ribbon. Click the Insert Text and Insert Table buttons on the Add-Ins tab to test the code.

To test your add-in

  1. Press F5 to run your project.

  2. Confirm that the Add-Ins tab is visible on the Ribbon.

  3. Click the Add-Ins tab.

  4. Confirm that the Content group is visible on the Ribbon.

  5. Click the Insert Text button in the Content group.

    A string is added to the document at the current location of the cursor.

  6. Click the Insert Table button in the Content group.

    A table is added to the document at the current location of the cursor.

Next Steps

You can learn more about how to customize the Office UI from these topics:

  • Customize the Ribbon of a different Office application. For more information about the applications that support customizing the Ribbon, see Ribbon Overview.

  • Customize the Ribbon of an Office application by using the Ribbon Designer. For more information, see Ribbon Designer.

  • Create a custom actions pane. For more information, see Actions Pane Overview.

  • Customize the UI of Microsoft Office Outlook by using Outlook Form Regions. For more information, see Walkthrough: Designing an Outlook Form Region.

See Also

Tasks

Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Concepts

Ribbon XML

Other Resources

Ribbon Overview