Edit

Walkthrough: Update the controls on a ribbon at run time

  • Article

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.

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

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 email message.

This walkthrough illustrates the following tasks:

  • Create a new Outlook VSTO Add-in project.

  • Design a custom Ribbon group.

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

  • Update 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 Personalize the Visual Studio IDE.

Prerequisites

You need the following components to complete this walkthrough:

Create a new Outlook VSTO Add-in project

First, create an Outlook VSTO Add-in project.

To create a new Outlook VSTO Add-in project

  1. In Visual Studio, create an Outlook VSTO 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 Office projects in Visual Studio.

Design a custom Ribbon group

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 email 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.

Add the custom group to a built-in tab

A built-in tab is a tab that is already on the ribbon of an Outlook Explorer or 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.

Create the data source

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 Dataset, and then click Next.

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

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

  6. Click Next to save the connection string.

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

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

    1. Customers

    2. Order Details

    3. Orders

    4. Products

  9. Click Finish.

Update 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 button 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).

    using System.Data.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.Northwind40DataSetTableAdapters;

  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 dataset.
Northwind40DataSet nwDataSet = new Northwind40DataSet();

//Declare the data tables.

Northwind40DataSet.CustomersDataTable customerTable;
Northwind40DataSet.OrdersDataTable orderTable;
Northwind40DataSet.Order_DetailsDataTable orderDetailsTable;
Northwind40DataSet.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();

  7. Add the following block of code to the CustomerRibbon class. This code adds three helper methods that create controls for the ribbon at run time.

    private RibbonDropDownItem CreateRibbonDropDownItem()
{
    return this.Factory.CreateRibbonDropDownItem();
}
private RibbonMenu CreateRibbonMenu()
{
    return this.Factory.CreateRibbonMenu();
}
private RibbonButton CreateRibbonButton()
{
    RibbonButton button = this.Factory.CreateRibbonButton();
    button.Click += new RibbonControlEventHandler(button_Click);
    return button;
}

  8. 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 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(CreateRibbonDropDownItem());
        this.comboBox1.Items.Last().Label =
        item.CustomerName + "|" + item.CustomerID.ToString();
    }
    this.comboBox1.Text = this.comboBox1.Items.First().Label;
    PopulateSalesOrderInfo();
}

  9. 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 buttons to each submenu for the products related to the sales order.

    • Adds event handlers to each button.

      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[1]
                     select new { OrderID = orders.Field<int>("Order ID") };

    foreach (var orderItem in orderQuery)
    {
        menu1.Items.Add(CreateRibbonMenu());

        RibbonMenu orderMenu = (RibbonMenu)menu1.Items.Last();
        orderMenu.Dynamic = true;
        orderMenu.Label = orderItem.OrderID.ToString();
        orderMenu.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)
        {
            RibbonButton button = CreateRibbonButton();
            button.Label = productItem.ProductName;
            orderMenu.Items.Add(button);
        }
    }
}

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

    The Ribbon Designer opens.

  11. 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.

  12. 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 void comboBox1_TextChanged(object sender,
    RibbonControlEventArgs e)
{
    PopulateSalesOrderInfo();
    PopulateMailItem(comboBox1.Text);
}

  13. Add the following Click event handler to the CustomerRibbon class. This code adds the name of selected products to the Body field of new mail messages.

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

  14. Add the following code to the CustomerRibbon class. This code performs the following tasks:

    • Populates the To line of new mail messages by using the email address of the currently selected customer.

    • Adds text to the Subject and Body fields of new mail messages.

      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[0] + "@example.com";
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = "Hello " + tempArray[0] + "," +
        "\n" + "We would like to get your feedback on the " +
        "following products that you recently ordered: ";
}

Test 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 email 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 email 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.

Next steps

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

Related content