How to: Customize the Ribbon UI by using a Visual Basic COM Add-in

  • Article

The Ribbon user interface (UI) in the 2007 release of Microsoft® Office suites offers users a flexible way to work with Office applications. Ribbon Extensibility (RibbonX) uses text-based, declarative XML markup that simplifies creating and customizing the Ribbon UI. This sample demonstrates how to add create a custom Ribbon UI that appears in the Office application regardless of the document that is open. In the following steps, you create application-level customizations using a managed COM add-in which we create in Microsoft Visual Studio® 2005 using Microsoft Visual Basic® 6.0. The project adds a custom tab, a custom group, and button to the Ribbon UI that when clicked, inserts a company name into a Word 2007 document. You will:

  1. Create a COM add-in project in Microsoft Visual Basic® 6.0 that works with Word 2007.
  2. Add a reference to the IRibbonExtensibility interface.
  3. Implement the only member of the interface: GetCustomUI.
  4. Add the XML customization markup code.
  5. Add the subroutine that is called when the button is clicked.
  6. Test the project.
  7. Troubleshoot the project, if necessary.

Create the COM Add-in in Visual Basic 6.0

In this step you create a COM add-in by using an add-in designer.

  1. Start Microsoft Visual Basic® 6.0 and select Addin as the project type. This adds a designer class to the project (Connect) and a form (frmAddin).
  2. In the Project Explorer window, open the Designer window by right-clicking Connect and then select View Object. Select Microsoft Word from the Applicationlist.
  3. In the Initial Load Behavior list, select Startup.
  4. In the Project Explorer, right-click MyAddin and in the Property window change the name of the add-in to RibbonSampleVB.
  5. Remove frmAddin from the project.
  6. From the Project window, right-click the Connect item and select view code.
  7. Remove all of the code in the designer's code window. This code works for Visual Basic add-ins but not Microsoft Office add-ins.
  8. Add the following statement to the OnConnection method to obtain a reference to Word when the add-in loads:
    

    Set oWD = Application

    9. This step is optional however if you want to be notified that your add-in is actually loading when you start Word, you can add the following statement to the **OnConnection** procedure. Once you're satisfied that the add-is being loaded, you can remove the line and rebuild the project: 
      MsgBox "My Addin started in " & Application.Name

    Add a reference to the IRibbonExtensibility interface

    At the top of the code window, add the following statements to set aside memory for the Word Application object you added earlier, and to create a reference to the Ribbon UI interface:

      Option Explicit
 
Dim oWD As Object   
Implements IRibbonExtensibility

    Implement the IRibbonExtensibility interface

    In this step, you implement the IRibbonExtensibilty interface's only member: GetCustomUI. Add the following procedure at the bottom of the code window:

      Public Function IRibbonExtensibility_GetCustomUI(ByVal RibbonID As String) As String
      IRibbonExtensibility_GetCustomUI = GetRibbonXML()
   End Function

    This procedure calls the GetRibbonXML method that, as its name implies, returns the customization XML to the GetCustomUI method which then adds it to the Ribbon UI to implement when the add-in loads.

    Retrieve the XML customization code

    In this step, add the GetRibbonXML function. In this instance, the customization code is stored in a String variable that is returned to the GetCustomUI method:

      Public Function GetRibbonXML() As String
   Dim sRibbonXML As String

    sRibbonXML = "<customUI http://schemas.microsoft.com/office/2006/01/customui"" >" & _
            "<ribbon>" & _
            "<tabs>" & _
            "<tab id=""CustomTab"" label=""My Tab"">" & _
            "<group id=""SampleGroup"" label=""Sample Group"">" & _
            "<button id=""Button"" label=""Insert Company Name"" size=""large"" onAction=""InsertCompanyName"" />" & _
            "</group >" & _
            "</tab>" & _
            "</tabs>" & _
            "</ribbon>" & _
            "</customUI>"

    

    GetRibbonXML = sRibbonXML
    

    End Function

    Add the procedure that is called when you click the button

    Add the procedure that gets called when you click the custom button:

      Public Sub InsertCompanyName(ByVal control As IRibbonControl)
   ' Inserts the specified text at the beginning of a range.
   Dim MyText As String
   Dim MyRange As Object
   Set MyRange = oWD.ActiveDocument.Range
   MyText = "Microsoft Corporation"  
   ' Inserts text at the beginning
   ' of the active document.
   MyRange.InsertBefore (MyText)
End Sub

    This procedure creates a reference to a range in the active document and then inserts the company name text into the range.

    Test the project

    In this step, you test the add-in:

    1. To make sure the code compiles without error, on the Run menu, click Start with Full Compile.
    2. Once the code compiles without error, save the project and create the RibbonSampleVB.dll by clicking the File menu and then clicking Make RibbonSampleVB.dll.... The designer registers the add-in for you.
    3. Start Word. You should see the My Tab tab to the right of the other tabs.
    4. Click the tab and then click Insert Company Name. The company name is inserted into the document.

    Troubleshoot the project

    If you do not see the My Tab tab when you start Word, you may need to add an entry to the Microsoft Windows® registry. To do this, perform the following steps:

    Aa434079.vs_Caution(en-us,office.12).gif  Caution
    The next few steps contain information about modifying the registry. Before you modify the registry, be sure to back it up and make sure that you understand how to restore the registry if a problem occurs. For information about how to back up, restore, and edit the registry, search for the following article in the Microsoft Knowledge Base: 256986 Description of the Microsoft Windows Registry.
    1. On the desktop, click Start, click Run, and type regedit.
    2. From the Registry tab, navigate to the following registry key for the add-in: HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleVB.Connect
      Aa434079.vs_note(en-us,office.12).gif  Note
      If the RibbonXSampleVB.Connect key does not exist, you can create it. To do so, right-click the Addins folder, point to New, and then click Key. Name the key RibbonXSampleVB.Connect. Add a LoadBehaviorDWord and set its value to 3.