Edit

Implementing the IRibbonExtensibility Interface

  • Article

A Microsoft Outlook add-in that customizes the ribbon, shortcut menus, new-item menus, or Microsoft Office Backstage view must implement the following interfaces:

  • DTExtensibility2

  • IRibbonExtensibility](../../../api/Office.IRibbonExtensibility.md)

In Visual C# and Visual Basic add-ins, you must implement these interfaces in the same class. When you implement Office.IRibbonExtensibility, use the IRibbonExtensibility.GetCustomUI method to return XML markup for your custom user interface to Outlook. The way that Outlook calls GetCustomUI and when it calls it is unique among Microsoft Office applications:

  • Office calls GetCustomUI during Outlook startup to load ribbon customizations for the explorers.
  • Office calls GetCustomUI to load inspector-specific ribbon customizations when the first instance of a given inspector type, such as an appointment or contact inspector, is displayed.
  • Viewing an item in the Reading Pane does not cause GetCustomUI to be called because the ribbon is not displayed in the Reading Pane.

The ribbon ID is a string that is passed from Office to GetCustomUI and that specifies the UI customization to load. Add-in developers can use this string to determine the custom XML markup to return to Outlook. You can also use the ribbon ID to determine the type of Outlook item to display.

In some cases, such as a MailItem or PostItem, Outlook calls GetCustomUI once when the first compose note is displayed (where RibbonID = Microsoft.Outlook.Mail.Compose) and another time when the first read note is displayed (where RibbonID = Microsoft.Outlook.Mail.Read).

Outlook uses the following unique ribbon IDs.

Ribbon ID Message Class
Microsoft.OMS.MMS.Compose IPM.Note.Mobile.MMS.*
Microsoft.OMS.MMS.Read IPM.Note.Mobile.MMS.*
Microsoft.OMS.SMS.Compose IPM.Note.Mobile.MMS.*
Microsoft.OMS.SMS.Read IPM.Note.Mobile.MMS.*
Microsoft.Outlook.Appointment IPM.Appointment.*
Microsoft.Outlook.Contact IPM.Contact.*
Microsoft.Outlook.DistributionList IPM.DistList.*
Microsoft.Outlook.Journal IPM.Activity.*
Microsoft.Outlook.Mail.Compose IPM.Note.*
Microsoft.Outlook.Mail.Read IPM.Note.*
Microsoft.Outlook.MeetingRequest.Read IPM.Schedule.Meeting.Request or IPM.Schedule.Meeting.Canceled
Microsoft.Outlook.MeetingRequest.Send IPM.Schedule.Meeting.Request
Microsoft.Outlook.Post.Compose IPM.Post.*
Microsoft.Outlook.Post.Read IPM.Post.*
Microsoft.Outlook.Report IPM.Report.*
Microsoft.Outlook.Resend IPM.Resend.*
Microsoft.Outlook.Response.Compose IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.Response.CounterPropose IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.Response.Read IPM.Schedule.Meeting.Resp.*
Microsoft.Outlook.RSS IPM.Post.Rss
Microsoft.Outlook.Sharing.Compose IPM.Sharing.*
Microsoft.Outlook.Sharing.Read IPM.Sharing.*
Microsoft.Outlook.Task IPM.Task. and IPM.TaskRequest.
Microsoft.Outlook.Explorer Not applicable. This ribbon ID lets you return XML for explorer ribbons, shortcut menus, and Backstage view.

| [!NOTE] | Sticky notes don't implement the ribbon, so IPM.StickyNote is not listed in the table of ribbon IDs and message classes.

For all of the ribbon ID values except for Microsoft.Outlook.Explorer, notice that the corresponding message class is listed as IPM.Type. in the table. That means that either the first instance of the base message class (for example, IPM.Contact) or of a derived custom message class (IPM.Contact.ShoeStore) that appears in an inspector will cause Outlook to call GetCustomUI.

Because a base message class shares the same ribbon XML with the custom message classes that are derived from it, and because Outlook calls GetCustomUI only one time per ribbon ID, you cannot specify a ribbon XML markup that is applied exclusively to a derived custom message class, and not to the base message class. However, if you want controls to appear in the ribbon on inspectors for one custom message class and not all other message classes with the same base message class, do the following:

  1. In GetCustomUI, return the XML markup for the ribbon ID for the custom message class (for example, IPM.Contact.ShoeStore) to the ribbon. All ribbons that are used by items with the same base message class (for example, IPM.Contact) will contain the added controls.
  2. In the ribbon XML, specify IRibbonControl.Context callbacks for each tab, group, and control that is specific to the custom message class. These callbacks will be used to display the controls for the custom message class and to hide the controls for the base message class and all other message classes with the same base message class.
  3. In each getVisible callback, cast the IRibbonControl.Context parameter that is passed to the callback to an Outlook Inspector object. Use the MessageClass property of Inspector.CurrentItem to determine whether to return True or False in the getVisible callback.

To customize the ribbon on all or multiple Outlook message classes, use the following recommendations:

  • To customize the first built-in tab on all Outlook inspectors, you must supply separate ribbon XML for different ribbon IDs because built-in first tabs don't have the same name across all ribbon IDs.
  • To customize the ribbon on multiple Outlook inspectors, you might have to supply separate ribbon XML for different ribbon IDs depending upon the tab name.

For more information, including examples, about customizing explorer and inspector ribbons, shortcut menus, and Backstage view, see Extending the User Interface in Outlook 2010 on the MSDN Web site.

See also

Office Fluent User Interface Extensibility for Outlook Overview of the IRibbonUI Object Detecting Errors Overview of the IRibbonControl Object

Support and feedback

Have questions or feedback about Office VBA or this documentation? Please see Office VBA support and feedback for guidance about the ways you can receive support and provide feedback.