TechNet Magazine > Home > Issues > 2009 > May > A Step by Step Guide to Customizing

the

Office ...

Microsoft Office

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

Contents
What's involved in creating a customized Ribbon?
What tools do you need to get started?
Create a custom Ribbon tab
Adding the customUI File to the ZIP Package
Adding VBA Macros to the Ribbon
Getting Creative
Sharing your customizations

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:
1. Create a simple Office Word 2007 document, save the file and close it.

2. Change the file extension for your new document to .zip.

3. Open that ZIP package and take a look around. When you first open the package, it should
look pretty much like Figure 1.

4. 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.
5. 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:
1. Create a file named customUI.xml and add the markup to that file for your customization.

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

3. Open the file named .rels and add one line of markup to it to tell the document about
your customized Ribbon.

4. 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.
1. In Word, Excel, or PowerPoint, click the Microsoft Office button and then, at the bottom
of the menu, click <Program> Options.

2. 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:

Copy Code

<?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.
1. 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.

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

3. 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:

Copy Code

<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:

Copy Code

<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 …>:

Copy Code

<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:

Copy Code

ByVal Control as IRibbonControl

Now, the macro looks like this:

Copy Code

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.

Copy Code
 <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.

Getting Creative
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:

Copy Code

<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:

Copy Code

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

Copy Code

<ribbon startFromScratch="true">

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:

Copy Code

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

Copiado de: http://technet.microsoft.com/en-us/magazine/2009.05.ribbon.aspx