Sorry that the post is late. It took me a lot longer to write this than I thought it would. The post today is going to show you how to do the following in Excel, PowerPoint and Word from a document or template:

Specifically, I will show the following:

• How to add RibbonX to a document or template
  
• How to add a group with a label to the Home tab using RibbonX
• How to add a button to this group with a label and icon using RibbonX

In the second part, I am going to show you the free tool Microsoft offers to make your life a lot easier when writing RibbonX for documents and templates. If you know of any other tools that are already out there, please post a comment and I will make sure to include it in my discussion. Part 3 of this will show you how to implement an action in VBA that is triggered when the user presses the “Hello World” button.

Writing RibbonX code

If you remember my overview from the last post, the first step in customizing the Office UI is the RibbonX code itself. For this sample, I am going to use the following code, which works for Excel, PowerPoint and Word:

The first line specifies that this is a UI modification for Office 2007 and points to the XML Schema that defines what the syntax of RibbonX has to be (RibbonX XML Schema, sorry that it is not a link to MSDN. I couldn’t find it there, but it should be there) .

The ribbon tag specified that this is a modification of the ribbon. If you have read about RibbonX already, you will know that you can also modify the QAT and repurpose Office commands (having your action triggered when someone uses an MS control) with it. You might have seen in other examples the attribute startFromScratch=”false” used with the ribbon tag. Specifying it as false is not required, because that is the default. Specifying true means that you want to start with a blank ribbon and only have the items on the ribbon specified in your RibbonX code. That setting is only recommended if you truly have a completely different ribbon for your application (the most common use of this is probably with Access applications and Excel Dictator Applications). If you modify the Ribbon only slightly, do not use startFromScratch=”true”.

The following tag (tabs) specified that we are dealing with the main tabs and not contextual tabs. The tag (tab) indicates the actual tab we are working with. The attribute idMso means that we are using an MS-provided tab, in this case the Home tab. If I had specified an attribute id instead, I would have been creating my own tab.

With the next line, I am adding a group to the Home tab. This group has the id “helloWorldGroup” and I gave it the label “Hello World”. Note that labels are optionals, ids (or idMsos or idQs) are not.

The following line adds a button to the group. The button will be large (size attribute), have the id “helloWorldButton”, the label “Hello World” and use the icon the MS-control with the id “Conference” has. If I had written “Paste” instead, I would have been using the image from the MS-Control Paste. To figure out the idMso of all MS controls, either download the control ID list or go into Options, Customization. In that dialog, the tooltip in the list of controls you can add to the QAT will show you the idMso in parenthesis:

The remaining lines are the closing tags XML requires (in XML, all tags that were opened need to be closed again in reverse order of opening). Notice that the tag <button … /> is an XML shorthand for <button …></button>. You can use this shorthand if a tag does not contain any other tags.

You can copy & paste this code into Notepad e.g. and then save the file as “customUI.xml” on your Desktop. You can also download the file.

Loading RibbonX code into Word via a document

Now that you have your RibbonX code written, you need to load this into Office. For the first example, I am going to use Word and load the code via a document.

Before you get started with any RibbonX loading, you should activate the display of RibbonX errors: In Word, you can find the settings in Word Options, Advanced, General, “Show add-in user interface errors” (at the very bottom of that long list of settings). It’s called the same and in the same spot for all other Ribbon apps. If you enable it in one program, it will be enabled for all. You absolutely should enable it, because if you don’t, Office will not tell you when you made a mistake in your RibbonX code and you will be wondering why certain things are not displayed or don’t work.

You can only load RibbonX code from a document or template in the new XML-based Office 2007 file formats. If you don’t know anything at all about them, you can find a lot of background information on Brian Jones’s blog. I will explain though the basics you need to make your RibbonX code work.

The new file formats are nothing else than a collection of several files, mostly in XML format, zipped together. I say mostly, because media files (pictures etc) are stored in their original form in the zip container as well. All these files are woven together using the Open Container Format. The short explanation for what that is, is that even though all files are present in the zip container, all files need to be referenced in a tree-like structure. There is one central XML file that contains relationships to the top level XML components. Those in turn have relationship files that link in to the next level components, etc.

To add your RibbonX code to a Word document, all you need to know is that you need to modify the top-level relationship XML file and a relation there to your customUI.xml file. If you just add the customUI.xml file to the zip container without adding that relation, Office will give you an error. Due to a bug, that error might claim that Office has trouble accessing the file itself instead of telling you that the problem is within the file.

To get started, you need a Word document to work with. Open Word, and when you have the default blank file in front of you, click the Office button, Save As (yes, this is a button you can click). As type, choose Word Macro-Enabled Document (*.docm) and save the file on your desktop as helloWord.docm.

Close Word and rename the file into helloWord.zip (if you don’t have extensions displayed by default, open any folder in Windows Explorer, go into Tools, Folder Options and deselect in the View tab “Hide extensions for known file types”). To rename the file, right-click it and select Rename, then replace .docm with .zip. Windows is going to ask you whether you really want to do this, say Yes. If you now click on the file, it will open with your default zip program. If you don’t have a program like WinZip installed, it will open with the Windows built-in zip folder functionality. I am going to use that one in my example (if you have another default zip program, right-click the file, select Open With and select “Compressed (zipped) folder”). You should see the following window then:

As the first step, you are going to add your XML file to this zip container. We could add the file wherever we wanted, but for this example, let’s add the file to the “word” folder. Click on “word”. Then copy the file customUI.xml from your desktop (right-click, copy) and paste it into this folder (right-click, paste). After that, go back to the top-level folder of the zip file shown in the screenshot above and click on “_rels”. The file “.rels” is the top-level relationship file that we need to edit. Right-click it, say copy and paste it onto your Desktop. Then open it with notepad (open Notepad from All Programs, Accessories, select File, Open, change file type to all files and select the “.rels” file). You will probably see something like this:

If you only see two lines of text, activate Format, Word Wrap.

You should notice that this is not a neatly indented XML file like the RibbonX code I showed above. The reason for that is that XML doesn’t care about whitespace (tabs, enter, spaces). In fact, whitespace reduces the performance when reading an XML file which is why all XML of the new Open XML format avoids whitespace. If you like to see your XML neatly aligned, you should get an XML editor that is able to “pretty print XML”. One such editor is Altova XMLSpy. You can get the Home version for free. The pretty-print feature is in the Edit menu.

I used it to get this pretty-printed version of the .rels file:

What we want to do is add a relationship to this file. A relationship needs an Id, which has to be unique. It doesn’t matter though what you pick as Id, as Office will reassign them every time it saves a file anyhow. The important thing is to get Type correct. Type has to be: “Type=”http://schemas.microsoft.com/office/2006/relationships/ui/extensibility”. As Target, you need to set the path to the customUI.xml file. In this case, we specify “word/customUI.xml”. I should note at this point that the filename doesn’t matter either. Word will identify the file using this relationship tag only. The finished Relationship tag looks like this:

<Relationship Id=”customUI” Type=”http://schemas.microsoft.com/office/2006/relationships/ui/extensibility” Target=”word/customUI.xml” />

And the entire .rels file now like this:

You can now save the file, copy it from the desktop and paste it back into the “_rels” folder of the zip folder (making sure to overwrite the .rels file there). After that is done, close the zip folder and rename the file back into “helloWorld.docm”. You can download the file as well. You can now open your file in Word and should see the following:

It could be the case that Word presents you with an error message when you open the file. If the error message dialog has as its title “Error Loading Custom UI XML” (see the screenshot below for an example), then the error is in your RibbonX code.

If you see a different error message, e.g. the following, the error is in the “.rels” file.

What could you have done possibly wrong? A good guess is that XML is CASE-SENSITIVE, which means if you don’t follow the exact capitalization, you will get that error message. Please remember the following: “Id” has a capital I in the “.rels” file, but “id” is all lower case in RibbonX! (I made that mistake myself first while writing this). Another thing you might want to look at is quotes (”). When a blog post is published from Word, it can very well happen that you end up with curly type quotes instead of the straight ones. You have to make sure that your quotes are the standard straight ones.
Off-topic: Did I mention that blogging in OneNote has one great advantage? When lightning causes a power spike that switches off your desktop while typing, you don’t lose much. In my case, I think I lost 3 characters in total!

Loading RibbonX into Excel, PowerPoint and Word documents and templates

The procedure for loading RibbonX into other file types is exactly the same.

For Word documents use “Word Macro-Enabled Document (*.docm)”

For Word templates use “Word Macro-Enabled Template (*.dotm)”

For Excel documents use “Excel Macro-Enabled Workbook (*.xlsm)”

For Excel templates, use “Excel Macro-Enabled Template (*.xltm)”

For PowerPoint documents, use “PowerPoint Macro-Enabled Presentation (*.pptm)”

For PowerPoint templates, use “PowerPoint Macro-Enabled Template (*.potm)”

The next post will showcase a free tool from Microsoft that inserts RibbonX code for you into Office documents.

Edited to fix the pictures and include the quote remark. Thanks Greg for pointing both things out!