This documentation is archived and is not being maintained.
A Guide to Customizing the Office 2007 Ribbon
At a Glance:
- Architecture of an Office Open XML file
- Steps to creating a custom Ribbon tab
- Adding VBA macros to the Ribbon
Whether you manage a 2007 Microsoft Office system environment, you're a Microsoft Office power user who likes to customize the environment, or you write Visual Basic for Applications (VBA) macros, you'll want to see just how easy it can be to customize the Ribbon for 2007 Office system documents, templates, and add-ins. And all you need is Windows Notepad. In this article, I'm going to show you how.
In order to jump right into creating a custom UI, I am making certain assumptions about your familiarity with the Office Open XML Formats and with VBA. You probably already know that an Office Open XML document is a ZIP package comprised of XML files (known as document parts), other files (such as any media files included in the document), and a handful of folders to organize all these elements. And you've probably seen Office Open XML markup or something similar (even if you've never actually written it). So, you already know that Office Open XML is written in fairly plain language—that is, you don't have to be a developer to get it. Note that I will also discuss VBA in this article because you will probably want to add your own macros (and not just built-in commands) to your custom Ribbon.
If you are not yet familiar with Office Open XML documents, take a look at the structure before you begin customizing the Ribbon:
- Create a simple Office Word 2007 document, save the file and close it.
- Change the file extension for your new document to .zip.
- Open that ZIP package and take a look around. When you first open the package, it should look pretty much like Figure 1.
- Open the _rels folder and you'll see a file named .rels. This defines the relationships between the top-level document components that you see here. I'll be editing the .rels file later in this article.
- Now open the word folder; you'll see that it contains such items as document.xml (that's the main document body), styles.xml, and other parts that are probably familiar.
Figure 1 The Structure of an Office Open XML Document
You might also see some additional files and folder names depending on the content in your file. For example, you'll see a media folder if your document contains pictures, sound files, or other media.
What's involved in creating a customized Ribbon?
You can make this much more complicated than what I'm about to discuss. But I'm a big fan of using the simplest solution for any task. To add customization to the Ribbon in a 2007 Office system Word, Excel, or PowerPoint file, all you need to do is the following:
- Create a file named customUI.xml and add the markup to that file for your customization.
- Create a file folder named customUI, place your customUI.xml file there, and then drop the folder into the top-level of your document's ZIP package.
- Open the file named .rels and add one line of markup to it to tell the document about your customized Ribbon.
- Open the document and bask in the beauty of your creation.
That's all there is to it and I'll show you how to do all of it by the end of this article.
What tools do you need to get started?
You can write your customUI.xml file using Windows Notepad.
There are also two downloads you should grab from the Microsoft Web site for reference: The first is the "2007 Office System Document: Lists of Control IDs", which contains the Ribbon control ID workbooks for all built-in commands in the Ribbon-enabled 2007 Office system programs. The second download is the "2007 Office System Add-In: Icons Gallery", which is a macro-driven workbook that contains the IDs for all of the Office 2007 built-in Ribbon icons.
After you've edited the contents of the package, you need to change the file extension back from .zip to its original extension. But you don't have to keep changing the extension to .zip each time you want to edit the underlying package. Instead, you can use a utility that will recognize your Office Open XML Format document as a ZIP package without ever changing the extension in the first place. There are at least a few of these. One open source option that I like is 7-zip. After you install it, just right-click your Office Open XML Format document, point to 7-zip, and then click Open Archive. You can even edit XML document parts directly in the package, and the archive utility will prompt you to update the package after you save your changes.
Before you begin, there is one more thing you might want to do. There's a setting in the Office applications that you can enable to prompt you if you open a file containing UI errors. Sometimes an error prevents the custom Ribbon from displaying, but not always, so it's helpful to get a warning right away. The error message you see tells you where the error is located, which can also be a timesaver. You can enable this setting in Word, Excel, or PowerPoint (or even Access) and it will apply to all.
- In Word, Excel, or PowerPoint, click the Microsoft Office button and then, at the bottom of the menu, click <Program> Options.
- On the Advanced tab, scroll to the bottom to find the General settings. Check the box labeled Show add-in user interface errors, and then click OK.
Now go ahead and open Notepad to follow along with this article. Notepad is all you'll need to follow along with the rest of this article. But, if you happen to have Microsoft Visual Studio 2008 handy, don't be afraid to use that. You don't have to write any managed code (or even know what managed code is) to get some pretty cool benefits from using that software to edit Office Open XML document parts. I use Visual Studio 2008 because Visual Studio knows the customUI schema, so it provides IntelliSense menus and automatic syntax checking. This can save a lot of time, and the IntelliSense menus are handy when you're learning the terminology.
Create a custom Ribbon tab
The Ribbon in each applicable 2007 Office system application contains several tabs, each tab contains several groups, and each group may display several commands. Many types of controls are used to display commands, including buttons, galleries, split-buttons, menus, and others.
You can customize any built-in tab (as well as the Microsoft Office Button menu), create your own custom tabs, or even start your own completely custom Ribbon from scratch. Of course, I can't explore every possible type of Ribbon customization in one article, but I will show you quite a lot of the things you can do.
I'll start by creating a simple custom tab for Word that displays a few controls that run built-in commands. In this scenario, I need to create a document template for users and want to start the custom Ribbon with a group of commands that I know the users will frequently need. Of course, I could put them on the Quick Access Toolbar for the template without writing any XML, but I want these commands to be as large as any on the Ribbon and side-by-side with some other custom commands that I'll add to the tab in a bit. Figure 2 shows what the new custom group will look like. Here's the customUI.xml markup I used to create it:
<?xml version="1.0" encoding="utf-8"?> <customUI xmlns="http://schemas.microsoft.com/ office/2006/01/customui"> <Ribbon> <tabs> <tab id="customTab" label="My Custom Tab"> <group id="customGroup1" label="Helpful Tools"> <gallery idMso="QuickStylesGallery" visible="true" size="large" /> <button idMso="PasteSpecialDialog" visible="true" size="large" imageMso="Paste"/> <button idMso="CrossReferenceInsert" visible="true" size="large" label="Insert a Cross-Reference" /> </group> </tab> </tabs> </Ribbon> </customUI>
Figure 2 A Simple Custom Tab
Let's take a look at the XML structure in this markup.
- If you open any Office Open XML document part, you'll see the same first line shown here (see the red markup). It's an indicator of the format being used. Just type it as you see it here. That second line is the tag that defines what type of data is being provided here. That's the customUI tag, and the underlined attribute (xmlns) is a namespace definition that indicates the schema being used. Again, just type it exactly as you see it.
- Notice that many of the tags shown here are paired (see the blue markup). You have the start tags near the top: customUI, followed by ribbon, followed by tabs (referring to the set of all tabs on the Ribbon), tab (referring to the individual tab you're working on), and group (the group you are creating). Then, beneath the data for the commands in the new group, you see the end tags in reverse order for each. The paired tags are nested inside one another. Note that each tag is enclosed in angled brackets, the end tag for each pair of tags begins with a slash after the open bracket, and each attribute is followed immediately by an equal sign and then its value inside quotation marks. A small syntax error, such as a missing slash, can keep your UI customization from being displayed.
- The commands in this custom group are each inside a standalone tag (see the green markup). They don't require end tags because all the data you need for the command is in this tag—there are no additional tags nested inside of them. So, the slash that indicates the end of the data for the tag comes at the end of each of these tags. Keep in mind, however, that not all Ribbon controls are standalone tags. For instance, if I create a custom gallery to which I add other controls, that would require a paired tag in order to nest other tags. Similarly, a custom menu control is a paired tag inside of which you can add buttons and other controls.
Okay, let's look a bit closer. Every element you add to the structure of your custom UI needs a way to be uniquely identified:
<tab id="customTab" label="My Custom Tab"> <group id="customGroup1" label="Helpful Tools">
Notice that the tag for my custom tab and the tag for the group I created each have an id attribute. You can name it just about whatever you like (but no spaces, please) as long as it's unique within the file. The only other attribute I customized for each of these tags was its label.
Because the three commands on this custom tab are built-in Office 2007 commands, I needed to use the idMso attribute as identifiers, rather than id:
<gallery idMso="QuickStylesGallery" visible="true" size="large" /> <button idMso="PasteSpecialDialog" visible="true" size="large" imageMso="Paste" /> <button idMso="CrossReferenceInsert" visible="true" size="large" label="Insert a Cross-Reference" />
I found these control IDs in the Word Ribbon Controls workbook. There are a few things worth noting about these tags and their attributes.
The first command is a gallery, the other two are buttons. I know this because I've used the features, but you can also find this information in the Ribbon control workbooks for each program (the command type is listed right next to its ID).
The visible attribute is true by default, so technically you don't have to add it, but it's a good idea. You may want to control visibility of commands at some point.
The size command, on the other hand, defaults to "normal" (which looks, for example, like the Cut, Copy, or Format Painter commands on the Home tab in Word, Excel, and PowerPoint). If you want the commands to appear large, you have to add this attribute.
If you take a look at the Paste Special command in one of the 2007 Office system programs, you'll see that it's a normal size command by default. Some commands displayed this way have icons that still look correct when displayed larger, but this isn't one of those. If you leave the custom icon for this control, it will look fuzzy. So, I added the image for the Paste command that you see on the Paste split button on the Home tab. That's the imageMso attribute that you see in the button tag for the Paste Special command.
I also chose to adjust the label for Cross-Reference a bit, as you see in the button tag for that control. By default, it's just Cross-reference, but I wanted to add a bit more information since it doesn't appear on a tab that provides context.
Adding the customUI File to the ZIP Package
Now is the time, if you haven't already, to create a folder named customUI and place the customUI.xml file inside it. I'm going to add this customUI folder to a Word template. Because I also want to include macros in this template that I'll add to the Ribbon, I saved my template as a .dotm file (a macro-enabled Word 2007 template). Keep in mind that you can add a custom UI using the same steps shown here to any Office 2007 Open XML Format Word, Excel, or PowerPoint document, template, or add-in file.
Open the Office Open XML package to which you're going to add your customUI folder and drop it right in. It goes on the top level, alongside the _rels, docProps, and program-specific document folder (i.e., word, xl, or ppt, depending on the document type you're customizing), and the [Content_Types].xml file.
Now open the _rels folder and then open the file named .rels. (If you are not using a utility that enables you to edit the file while it's in the package, you may have to copy it out of the package first.) In this file, you see a nested structure similar to the one in the customUI.xml file. There is a set of relationships in the paired <Relationships … > tag and a standalone tag for each relationship. Each relationship tag contains three attributes: the Id, the Type, and the Target.
Add the following tag for your customUI content to the .rels file, making sure that it falls between the start and end tag for the group of <Relationships …>:
<Relationship Id="rId5" Type="http://schemas.microsoft.com/office/2006/relationships/ ui/extensibility" Target="customUI/customUI.xml"/>
If the .rels file already contains a relationship tag with the ID rId5, use a different number. The ID needs to be unique.
After you add that information to your file, the file should look something like that shown in Figure 3. If you're using Notepad as an editor and want to view your markup with structure (as shown in Figure 3), you can open the file in Internet Explorer.
Figure 3 My Edited .rels File
If you had to copy the .rels file out of the ZIP package to edit it, copy it back in. Then open the file in Word and check out your work. The new tab (named "My Custom Tab" if you used my example) appears at the end of the Ribbon.
Adding VBA Macros to the Ribbon
It was easy to add built-in commands to the ribbon, but what if you need to add your own tools? Here's what you do.
Open that template file and press ALT+F11 to open the Visual Basic Editor (VBE). If you have not already done so, select your template in the Project Explorer that appears on the left side of the VBE. Then, on the Insert menu, click Module to add a code module to your template. You can then add a simple message box, as shown in Figure 4. (Of course, you can use whatever macro you want.)
Figure 4 Adding a Code Module to the Template
For those of you with more VBA experience, and those who plan to acquire it, note that there are other elements we really should add here for best practices. But none of those elements are critical for the task at hand (which is adding this macro to the ribbon), so I'll skip those tasks for simplicity.
Before leaving the VBE, there is one more thing to add to this macro so that the Ribbon will recognize it. You have to declare it as a Ribbon control. To do that, just add the following text inside the parentheses that follow the procedure name:
ByVal Control as IRibbonControl
Now, the macro looks like this:
Sub TakeABreak(ByVal control As IRibbonControl) MsgBox "Go get some coffee! You deserve it." End Sub
Note the macro name, because you need to add that to the customUI.xml file. Then, save and close the template.
You can now add this command to your customUI.xml file by adding the following markup wherever you'd like on your custom tab. I've created a new group for this command, which I'm going to place after the first group.
<group id="customGroup2" label="Break Time" > <button id="myBreak" visible="true" size="large" label="Take a Break" imageMso="HappyFace" onAction="TakeABreak" /> </group>
When you add this content, be sure to add it after the end tag for the previous group and before the end tag for the custom tab. Or, if you don't want to create a new group, you can just add the button information in its own tag within your existing group.
There are a few things worth noting here.
- Remember that if you're creating a new group, it needs its own unique ID. I also gave this group a unique label.
- My new button uses a custom command, so the id attribute is used instead of idMso. In addition to the attributes you know from creating the first group, I've added an onAction attribute. That's the attribute I use to call my macro. The value for that attribute is the macro name.
- The capitalization you see of any Office Open XML tag names, attribute names, and built-in 2007 Office control names is usually as much a requirement as any other part of the syntax.
- I selected the HappyFace icon from the Icons Gallery workbook.
After you add your new button, update the customUI.xml file in your ZIP package. There's no need to edit any other files in the package—just open your template. (You will likely need to enable macros when you do this.) Then go ahead and click your new button to give the macro a try.
Once you have the basics down and have created a custom tab with built-in and custom commands, you can do quite a bit more just by adding various attributes. Here are some examples.
If you want your tab to fall somewhere other than the end of the ribbon, specify that in the tab's start tag, with the attribute insertBeforeMso. For example, to make the tab you've just created the first tab in the Ribbon, place it before the Home tab, like so:
<tab id="customTab" label="My Custom Tab" insertBeforeMso="TabHome">
You can find the correct name of any built-in tab in the Ribbon Control workbooks for the applicable program.
To add a group to a built-in tab, just add the markup for that tab to your customUI.xml file. It doesn't matter which tab appears first in the customUI file; just be sure to nest the new markup properly. For example, if you place it after your custom tab, it should fall after the end tag for your custom tab and before the end tag for the group of tags ( between </tab> and </tabs>). Here I've added the Break Time group to the Insert tab:
<tab idMso="TabInsert"> <group id="customGroup2" label="Break Time" insertAfterMso="GroupInsertTa bles" > <button id="myBreak" visible="true" size="large" label="Take a Break" imageMso="HappyFace" onAction="TakeABreak" /> </group> </tab>
If you're creating a unique template with special requirements and you want to provide only custom commands to the user, you may want to create an entirely custom Ribbon for that template. To do this, in the start tag for the Ribbon (the <ribbon> tag) in customUI.xml, just add the attribute startFromScratch="True" as you see here.
To add a custom command other than a button, the syntax is always the same. If you want to add a split button menu, for example, just keep the rules for paired tags and nesting tags in mind and this customization will be very easy. Say you want to put all of the commands you've added so far onto a single split button menu instead of separate buttons. Try this:
<splitButton id="customSplit1" visible="true" size="large"> <menu id="customMenu1" visible="true" > <button id="myBreak" visible="true" label="Take a Break" imageMso="HappyFace" onAction="TakeABreak" /> <button idMso="PasteSpecialDialog" visible="true" imageMso="Paste" /> <button idMso="CrossReferenceInsert" visible="true" label="Insert a Cross-Reference" /> <gallery idMso="QuickStylesGallery" visible="true" /> </menu> </splitButton>
The result of this is shown in Figure 5. Note that the first button command in the menu becomes the split button default. That's why I reordered the commands for my happy face to be on top. The split button has to be a button control. If Quick Styles (which uses a gallery control) was first, it would have been skipped over for the split button control and that control would have used the first button control in the menu.
Figure 5 A Single Split Button Menu
This is just a sample of what you can do to customize the UI. You can find plenty of help online to take this further, like adding your own custom image to a command or using a VBA macro to conditionally control the behavior of some commands. Check out the Office Developer Center on MSDN for ideas.
To search for help on conditionally controlling the Ribbon behavior, look up attributes such as getVisible and getLabel. The 'get' prefix is used before the attribute you already know when you want the Ribbon to look at a macro for direction on how to behave (referred to as a callback).
Sharing your customizations
You can save UI customizations in any 2007 Office system Word, Excel, or PowerPoint document, template, or add-in. What if you want to install your custom UI so it's available regardless of the document or template being used? This is also quite easy.
In Word, just save the .dotm file that contains your macros and related customUI to the Word Startup folder and it will load automatically when Word starts.
In Excel or PowerPoint, you need to save the file that contains your macros and custom UI settings as an add-in, and then load that add-in. Open the file in the applicable program (enable macros if prompted) and then use the Save As command to save a copy as an add-in. (The add-in file type for an Excel 2007 add-in is .xlam and for PowerPoint 2007 it is .ppam.) When you save the file with that format, it's automatically saved in the Microsoft AddIns folder. Now load it through the <Program> AddIns dialog box, which you find via the bottom of the <Program> Options, AddIns tab. You may be prompted to enable macros the first time you load your add-in–just click Enable Macros. After that, it should load automatically when the program opens.
Stephanie Krieger is a Microsoft Office System MVP and the author of two books, Advanced Microsoft Office Documents 2007 Edition Inside Out and Microsoft Office Document Designer. She also frequently writes, presents, and creates content for Microsoft. You can reach Stephanie through her blog, arouet.net.