Walkthrough: Updating the Controls on a Ribbon at Run Time

Article
11/16/2012

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.

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.

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:

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.

Creating a New Outlook Add-in Project

First, create an Outlook add-in project.

To create a new Outlook add-in project

In Visual Studio, create an Outlook 2007 add-in project with the name Ribbon_Update_At_Runtime.
In the New Project dialog box, select Create directory for solution.
Save the project to the default project directory.

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

Designing a Custom Ribbon Group

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

On the Project menu, click Add New Item.
In the Add New Item dialog box, select Ribbon (Visual Designer).
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.
Click the Ribbon Designer to select it.
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.
In the Ribbon Designer, click Group1 to select it.
In the Properties window, set Label to Customer Purchases.
From the Office Ribbon Controls tab of the Toolbox, drag a ComboBox onto the Customer Purchases group.
Click ComboBox1 to select it.
In the Properties window, set Label to Customers.
From the Office Ribbon Controls tab of the Toolbox, drag a Menu onto the Customer Purchases group.
In the Properties window, set Label to Product Purchased.
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.

Adding the Custom Group to a Built-in Tab

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

Click the TabAddins (Built-In) tab to select it.
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.
Click the Customer Purchases group to select it.
In the Properties window, expand the Position property, click the drop-down arrow next to the PositionType property, and then click BeforeOfficeId.
Set the OfficeId property to GroupClipBoard.

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

Creating the Data Source

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

To create the data source

On the Data menu, click Add New Data Source.

This starts the Data Source Configuration Wizard.
Select Database, and then click Next.
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.
After a connection has been selected or created, click Next.
Click Next to save the connection string.
On the Choose Your Database Objects page, expand Tables.
Select the check box next to each of the following tables:
1. Customers
2. Order_Details
3. Orders
4. Products
Click Finish.

Updating Controls in the Custom Group at Run Time

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

On the Project menu, click Add Reference.
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.
In Solution Explorer, click CustomerRibbon.cs or CustomerRibbon.vb to select it.
On the View menu, click Code.

The Ribbon code file opens in the Code Editor.

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

using System.Data.Linq;
using System.Linq;
using System.Data.Linq.Mapping;
using System.Linq.Expressions;
using Outlook = Microsoft.Office.Interop.Outlook;
using System.Data;
using System.IO;
using Ribbon_Update_At_Runtime.NorthwindDataSetTableAdapters;

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()

//Declare the Northwind dataset.
NorthwindDataSet nwDataSet = new NorthwindDataSet();

//Declare the data tables.

NorthwindDataSet.CustomersDataTable customerTable;
NorthwindDataSet.OrdersDataTable orderTable;
NorthwindDataSet.Order_DetailsDataTable orderDetailsTable;
NorthwindDataSet.ProductsDataTable productsTable;

//Declare the data table adapters for each table.

CustomersTableAdapter customerTableAdapter = new CustomersTableAdapter();
OrdersTableAdapter ordersTableAdapter = new OrdersTableAdapter();
Order_DetailsTableAdapter detailsTableAdapter = new Order_DetailsTableAdapter();
ProductsTableAdapter productsTableAdapter = new ProductsTableAdapter();

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

private void CustomerRibbon_Load(object sender, RibbonUIEventArgs e)
{
    customerTable = nwDataSet.Customers;
    customerTableAdapter.Fill(customerTable);

    var customerQuery = from customers in customerTable.AsEnumerable().Take(20)
        select new 
        { 
            CustomerID = customers.Field<string>("Customer ID"), 
            CustomerName = customers.Field<string>("Contact Name") 
        };


    // Execute the query. 
    foreach (var item in customerQuery)
    {
        this.comboBox1.Items.Add(new RibbonDropDownItem());
        this.comboBox1.Items.Last().Label = 
            item.CustomerID.ToString() + "|" + item.CustomerName;
    }
    this.comboBox1.Text = this.comboBox1.Items.First().Label;
    PopulateSalesOrderInfo();
}

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

private void PopulateSalesOrderInfo()
{
    String[] tempArray = comboBox1.Text.Split(new Char[] { '|' });
    menu1.Items.Clear();

    orderTable = nwDataSet.Orders;
    orderDetailsTable = nwDataSet.Order_Details;
    productsTable = nwDataSet.Products;

    ordersTableAdapter.Fill(orderTable);
    detailsTableAdapter.Fill(orderDetailsTable);
    productsTableAdapter.Fill(productsTable);

    var orderQuery = from orders in orderTable.AsEnumerable()
         where orders.Field<string>("Customer ID") == tempArray[0]
         select new { OrderID = orders.Field<int>("Order ID") };

    foreach (var orderItem in orderQuery)
    {
        RibbonMenu menu2 = new RibbonMenu();
        menu2.Dynamic = true;

        menu2.Label = orderItem.OrderID.ToString();
        menu2.Tag = orderItem.OrderID;

        var productQuery = from orderDetail in orderDetailsTable.AsEnumerable()
               join product in productsTable.AsEnumerable() on 
                   orderDetail.Field<int>("Product ID") 
               equals product.Field<int>("Product ID")
               where orderDetail.Field<int>("Order ID") == 
                   orderItem.OrderID
               select new { ProductName = product.Field<string>("Product Name") };

        foreach (var productItem in productQuery)
        {
            RibbonCheckBox checkBox = new RibbonCheckBox();
            checkBox.Label = productItem.ProductName;
            checkBox.Click += new EventHandler<RibbonControlEventArgs>(checkBox_Click);
            menu2.Items.Add(checkBox);
        }
        menu1.Items.Add(menu2);
    }
}

In Solution Explorer, double-click the Ribbon code file.

The Ribbon Designer opens.
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.
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
```
```
private void comboBox1_TextChanged(object sender, 
    RibbonControlEventArgs e)
{
    PopulateSalesOrderInfo();
    PopulateMailItem(comboBox1.Text);
}
```

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

private void checkBox_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;
    RibbonCheckBox myCheckBox = (RibbonCheckBox)sender;
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = myMailItem.Body + "\n" + "* " + myCheckBox.Label;
}

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

private void PopulateMailItem(string addressToLine)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;

    myMailItem.To = "";
    String[] tempArray = addressToLine.Split(new Char[] { '|' });
    myMailItem.To = tempArray[1] + "@example.com";
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = "Hello " + tempArray[1] + "," +
        "\n" + "We would like to get your feedback on the " + 
        "following products that you recently ordered: ";
}

Testing the Controls in the Custom Group

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

Press F5 to run your project.

Outlook starts.
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.
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.
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.

Next Steps

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

Add context-based UI to any document-level customization. For more information, see Actions Pane Overview.
Extend a standard or custom Microsoft Office Outlook form. For more information, see Walkthrough: Designing an Outlook Form Region.
Add a custom task pane to Outlook. For more information, see Custom Task Panes Overview.