This documentation is archived and is not being maintained.

Walkthrough: Updating the Controls on a Ribbon at Run Time

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

  • Document-level projects

  • Application-level projects

Microsoft Office version

  • Excel 2007

  • Word 2007

  • Outlook 2007

  • PowerPoint 2007

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to use the Ribbon object model to update the controls on a Ribbon after the Ribbon is loaded into the Office application.

The example pulls data from the Northwind sample database to populate a combo box and menu in Microsoft Office Outlook. Items that you select in these controls automatically populate fields such as To and Subject in an e-mail message.

This walkthrough illustrates the following tasks:

  • Creating a new Outlook add-in project.

  • Designing a custom Ribbon group.

  • Adding the custom group to a built-in tab.

  • Updating controls on the Ribbon at run time.

NoteNote:

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.

You need the following components to complete this walkthrough:

  • Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

  • Microsoft Office Outlook 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

First, create an Outlook add-in project.

To create a new Outlook add-in project

  1. In Visual Studio, create an Outlook 2007 add-in project with the name Ribbon_Update_At_Runtime.

  2. In the New Project dialog box, select Create directory for solution.

  3. Save the project to the default project directory.

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

The Ribbon does not appear in the main interface area of Outlook, so the Ribbon for this example will appear when a user composes a new mail message. To create a custom group for the Ribbon, first add a Ribbon item to your project, and then design the group in the Ribbon Designer. This custom group will help you generate follow-up e-mail messages to customers by pulling names and order histories from a database.

To design a custom group

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

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

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

    The CustomerRibbon.cs or CustomerRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.

  4. Click the Ribbon Designer to select it.

  5. In the Properties window, click the drop-down arrow next to the RibbonType property, and then click Microsoft.Outlook.Mail.Compose.

    This enables the Ribbon to appear when the user composes a new mail message in Outlook.

  6. In the Ribbon Designer, click Group1 to select it.

  7. In the Properties window, set Label to Customer Purchases.

  8. From the Office Ribbon Controls tab of the Toolbox, drag a ComboBox onto the Customer Purchases group.

  9. Click ComboBox1 to select it.

  10. In the Properties window, set Label to Customers.

  11. From the Office Ribbon Controls tab of the Toolbox, drag a Menu onto the Customer Purchases group.

  12. In the Properties window, set Label to Product Purchased.

  13. Set Dynamic to true.

    This enables you to add and remove controls on the menu at run time after the Ribbon is loaded into the Office application.

A built-in tab is a tab that is already on the Ribbon of an Outlook Inspector. In this procedure, you will add the custom group to a built-in tab, and then specify the position of the custom group on the tab.

To add the custom group to a built-in tab

  1. Click the TabAddins (Built-In) tab to select it.

  2. In the Properties window, expand the ControlId property, and then set OfficeId to TabNewMailMessage.

    This adds the Customer Purchases group to the Messages tab of the Ribbon that appears in a new mail message.

  3. Click the Customer Purchases group to select it.

  4. In the Properties window, expand the Position property, click the drop-down arrow next to the PositionType property, and then click BeforeOfficeId.

  5. Set the OfficeId property to GroupClipBoard.

    This positions the Customer Purchases group before the Clipboard group of the Messages tab.

Use the Data Sources window to add a typed dataset to your project.

To create the data source

  1. On the Data menu, click Add New Data Source.

    This starts the Data Source Configuration Wizard.

  2. Select Database, and then click Next.

  3. Select a data connection to the Northwind sample Microsoft SQL Server Compact 3.5 database, or add a new connection by using the New Connection button.

  4. After a connection has been selected or created, click Next.

  5. Click Next to save the connection string.

  6. On the Choose Your Database Objects page, expand Tables.

  7. Select the check box next to each of the following tables:

    1. Customers

    2. Order_Details

    3. Orders

    4. Products

  8. Click Finish.

Use the Ribbon object model to perform the following tasks:

  • Add customer names to the Customers combo box.

  • Add menu and check box controls to the Products Purchased menu that represent sales orders and products sold.

  • Populate the To, Subject, and Body fields of new mail messages by using data from the Customers combo box and Products Purchased menu.

To update controls in the custom group by using the Ribbon object model

  1. On the Project menu, click Add Reference.

  2. In the Add Reference dialog box, click the .NET tab, select the System.Data.Linq assembly, and then click OK.

    This assembly contains classes for using Language-Integrated Queries (LINQ). You will use LINQ to populate controls in the custom group with data from the Northwind database.

  3. In Solution Explorer, click CustomerRibbon.cs or CustomerRibbon.vb to select it.

  4. On the View menu, click Code.

    The Ribbon code file opens in the Code Editor.

  5. Add the following statements to the top of the Ribbon code file. These statements provide easy access to LINQ namespaces and to the namespace of the Outlook primary interop assembly (PIA).

    Imports Microsoft.Office.Tools.Ribbon
    Imports System.Data.Linq
    Imports System.Linq
    Imports System.Data.Linq.Mapping
    Imports System.Linq.Expressions
    Imports Outlook = Microsoft.Office.Interop.Outlook
    Imports Ribbon_Update_At_Runtime.NorthwindDataSetTableAdapters
    
  6. Add the following code inside the CustomerRibbon class. This code declares the data table and table adapters that you will use to store information from the Customer, Orders, Order Details, and Product tables of the Northwind database.

    'Declare the Northwind data set. 
    
    Dim nwDataSet As NorthwindDataSet = New NorthwindDataSet()
    
    'Declare the data tables. 
    
    Dim customerTable As NorthwindDataSet.CustomersDataTable
    Dim orderTable As NorthwindDataSet.OrdersDataTable
    Dim orderDetailsTable As NorthwindDataSet.Order_DetailsDataTable
    Dim productsTable As NorthwindDataSet.ProductsDataTable
    
    'Declare the data table adapters for each table. 
    
    Dim customersTableAdapter As CustomersTableAdapter = New CustomersTableAdapter()
    Dim ordersTableAdapter As OrdersTableAdapter = New OrdersTableAdapter()
    Dim detailsTableAdapter As Order_DetailsTableAdapter = New Order_DetailsTableAdapter()
    Dim productsTableAdapter As ProductsTableAdapter = New ProductsTableAdapter()
    
  7. Replace the CustomerRibbon_Load event handler method with the following code. This code uses a LINQ query to perform the following tasks:

    • Populate the Customers combo box by using the ID and name of 20 customers in the Northwind database.

    • Calls the PopulateSalesOrderInfo helper method. This method updates the ProductsPurchased menu with sales order numbers that pertain to the currently selected customer.

    Private Sub CustomerRibbon_Load(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonUIEventArgs) _
        Handles MyBase.Load
    
         customerTable = nwDataSet.Customers
         customersTableAdapter.Fill(customerTable)
    
         Dim customerQuery = From customers In customerTable.AsEnumerable.Take(20) _
                 Select CustomerID = customers.Customer_ID, _
                 CustomerName = customers.Contact_Name
    
             ' Execute the query. 
         For Each item In customerQuery
             Me.ComboBox1.Items.Add(New RibbonDropDownItem())
             Me.ComboBox1.Items.Last().Label = item.CustomerID.ToString() _
                 + "|" + item.CustomerName
         Next item
    
         Me.ComboBox1.Text = Me.ComboBox1.Items.First().Label
         PopulateSalesOrderInfo()
     End Sub
    
  8. Add the following code to the CustomerRibbon class. This code uses LINQ queries to perform the following tasks:

    • Adds a submenu to the ProductsPurchased menu for each sales order related to the selected customer.

    • Adds check boxes to each submenu for the products related to the sales order.

    • Adds event handlers to each check box.

    Private Sub PopulateSalesOrderInfo()
    
        Dim tempArray As [String]() = comboBox1.Text.Split(New [Char]() {"|"c})
        Menu1.Items.Clear()
    
        orderTable = nwDataSet.Orders
        orderDetailsTable = nwDataSet.Order_Details
        productsTable = nwDataSet.Products
    
        ordersTableAdapter.Fill(orderTable)
        detailsTableAdapter.Fill(orderDetailsTable)
        productsTableAdapter.Fill(productsTable)
    
        Dim orderQuery = From order In orderTable.AsEnumerable() _
                         Where order.Customer_ID.ToString() = tempArray(0) _
                         Select New With {.SalesOrderID = order.Order_ID}
    
        For Each orderItem In orderQuery
            Dim Menu2 As New RibbonMenu()
            Menu2.Dynamic = True
    
            Menu2.Label = orderItem.SalesOrderID.ToString()
            Menu2.Tag = orderItem.SalesOrderID
    
            Dim productQuery = From orderDetail In orderDetailsTable.AsEnumerable(), _
                                   product In productsTable.AsEnumerable() _
                               Where orderDetail.Product_ID = _
                                   product.Product_ID _
                               And orderDetail.Order_ID = _
                               Menu2.Tag _
            Select productName = product.Product_Name
    
            For Each productItem In productQuery
                Dim checkBox As RibbonCheckBox = New RibbonCheckBox()
                checkBox.Label = productItem
                AddHandler (checkBox.Click), AddressOf CheckBox_Click
                Menu2.Items.Add(checkBox)
            Next productItem
            Menu1.Items.Add(Menu2)
        Next orderItem
    End Sub
    
  9. In Solution Explorer, double-click the Ribbon code file.

    The Ribbon Designer opens.

  10. In the Ribbon Designer, double-click the Customers combo box.

    The Ribbon code file opens in the Code Editor, and the ComboBox1_TextChanged event handler appears.

  11. Replace the ComboBox1_TextChanged event handler with the following code. This code performs the following tasks:

    • Calls the PopulateSalesOrderInfo helper method. This method updates the Products Purchased menu with sales orders that relate to the selected customer.

    • Calls the PopulateMailItem helper method and passes in the current text, which is the selected customer name. This method populates the To, Subject, and Body fields of new mail messages.

    Private Sub ComboBox1_TextChanged(ByVal sender As System.Object, _
        ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
            Handles ComboBox1.TextChanged
        PopulateSalesOrderInfo()
        PopulateMailItem(ComboBox1.Text)
    End Sub
    
  12. Add the following Click event handler to the CustomerRibbon class. This code adds the name of selected products to the Microsoft.Office.Interop.Outlook.MailItem.Body field of new mail messages.

    Private Sub CheckBox_Click(ByVal sender As System.Object, _
        ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs)
        Dim application As Outlook.Application = Globals.ThisAddIn.Application
        Dim inspector As Outlook.Inspector = application.ActiveInspector()
        Dim myMailItem As Outlook.MailItem = CType(inspector.CurrentItem,  _
            Outlook.MailItem)
        Dim myCheckBox As RibbonCheckBox = CType(sender, RibbonCheckBox)
        myMailItem.Subject = "Following up on your order"
        myMailItem.Body = myMailItem.Body + ControlChars.Lf + "* " _
            + myCheckBox.Label
    End Sub
    
  13. Add the following code to the CustomerRibbon class. This code performs the following tasks:

    • Populates the Microsoft.Office.Interop.Outlook.MailItem.To line of new mail messages by using the e-mail address of the currently selected customer.

    • Adds text to the Microsoft.Office.Interop.Outlook.MailItem.Subject and Microsoft.Office.Interop.Outlook.MailItem.Body fields of new mail messages.

    Private Sub PopulateMailItem(ByVal addressToLine As String)
        Dim application As Outlook.Application = Globals.ThisAddIn.Application
        Dim inspector As Outlook.Inspector = application.ActiveInspector()
        Dim myMailItem As Outlook.MailItem = _
            CType(inspector.CurrentItem, Outlook.MailItem)
    
        myMailItem.To = "" 
        Dim tempArray As [String]() = addressToLine.Split(New [Char]() {"|"c})
        myMailItem.To = tempArray(1) + "@example.com"
        myMailItem.Subject = "Following up on your order"
        myMailItem.Body = "Hello " + tempArray(1) + "," _
            + ControlChars.Lf + "We would like to get your feedback" + _
            "on the following products that you recently ordered: " 
    End Sub
    

When you open a new mail form in Outlook, a custom group named Customer Purchases appears on the Messages tab of the Ribbon.

To create a customer follow-up e-mail message, select a customer, and then select products purchased by the customer. The controls in the Customer Purchases group are updated at run time with data from the Northwind database.

To test the controls in the custom group

  1. Press F5 to run your project.

    Outlook starts.

  2. In Outlook, on the File menu, point to New, and then click Mail Message.

    The following actions occur:

    • A new mail message Inspector window appears.

    • On the Message tab of the Ribbon, the Customer Purchases group appears before the Clipboard group.

    • The Customers combo box in the group is updated with the names of customers in the Northwind database.

  3. On the Message tab of the Ribbon, in the Customer Purchases group, select a customer from the Customers combo box.

    The following actions occur:

    • The Products Purchased menu is updated to show each sales order for the selected customer.

    • Each sales order submenu is updated to show the products purchased in that order.

    • The selected customer's e-mail address is added to the To line of the mail message, and the subject and body of the mail message are populated with text.

  4. Click the Products Purchases menu, point to any sales order, and then click a product from the sales order.

    The product name is added to the body of the mail message.

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

Show: