Because You Want To, Not Because You Have To


You’ve written an add-in to Microsoft Word.

It creates an entry point at the bottom of the Tools menu.

“Crikey!  There is no Tools menu.  Call Sgt. Pepper immediately!”

We know there are thousands of add-ins, macros, and other projects that extend Office or use it to host UI.  Exactly none of these were written with the expectation that eventually they would be run in a version of Office without menus and toolbars.

At the same time, we knew that it would not be feasible (or polite) to ask people to make changes to their code just because we changed things around in Office.  Very occasionally a customer will even sadly report that they lost the source code to their crucial add-in.

So, we started designing the Office 12 extensibility story around a promise: the promise that we will do everything possible to make all existing code run untouched in Office 12.  If you want to take full advantage of the new opportunities afforded by the new UI, you do need to make a few changes.  But, as a rule, any add-in or macro that ran in Office 2003 should run just fine in Office 12.

“But how does this work?” you might be asking.  And rightfully so.  User interface extensibility in Office 97-2003 was based on the CommandBars object model, which provided access to the menus and toolbars in each application.  Your code could choose to add a button to the 7th position on the Standard toolbar, or to the very top of the Format menu.  Or anywhere else in-between.

What does asking Word to position you as the 7th button on the Standard toolbar mean when there is no Standard toolbar?  Does it mean you want to be next to Print Preview?  Or next to Spell Check?  Or, perhaps you want to be next to the special alignment toolbar button that only shows up in Japanese versions of Word?  Or maybe you just want to be in the middle of the screen?

We racked our brains trying to come up with some way of mapping CommandBars requests to organization in the new UI.  And it turned out that there wasn’t really any way to do it reasonably.  We can’t infer enough about what the intention behind the UI was to do something intelligent–and doing something “automatic” some of the time and getting it wrong most of the time is just about the most confusing thing possible.  So instead, we went for predictability.

Whenever code tries to add a control via the CommandBars object model (or other legacy means of adding menus such as WordBasic), we show an extra tab in the Ribbon called “Add-ins.”  Two chunks can be present in this tab: Menu Commands and Toolbar Commands.  Existing code that tries to add to the old menu structure is re-routed to the Menu Commands chunk.  Likewise, adds to the Toolbars show up in the Toolbar Commands chunk.  If you create your own toolbar, it is converted into your very own chunk and all of the controls you add are inside.


(Click to view full picture)

We present a “virtual” menu and toolbar structure to existing code, so to an add-in internally it looks just like it’s running in Office 2003.  In practice, only the UI added by the add-in shows up on the tab.  (If you change the action of built-in Office controls, they do show up in the Add-ins tab as well.)

The benefits: UI shows up in a predictable place.  Controls are presented in a way that makes sense depending on the control type and the required destination.  UI controls intended to be shown together remain together.  And, best of all, no code changes are required in order for UI to show up on the Add-ins tab.

Of course, if you are willing to write a small amount of code, you can upgrade your project to take full advantage of the Office 12 UI through the new extensibility model, code-named “RibbonX.”

But, until you are, you can rest more soundly knowing that the UI for the WordBasic add-in you originally wrote for Word 6.0 still shows up in the Ribbon.

Crikey!

Comments (13)

  1. Jim Rech says:

    I think I understand why you chose to handle legacy app menu changes this why, Jensen, and I’m not sure there really was any other way to do it.

    Just to be sure I understand this, an example. Say I have an add-in that makes three menu additions – one to Excel’s Edit menu, one to the Fill submenu on the Edit menu, and one to the Tools menu. Will all three appear next to each other on the Menu Commands chunk? (Thus losing their ‘menu context’? No criticism intended, just asking<g>).

  2. Jim Rech says:

    I’m having trouble visualizing what I’ll see with a ‘dictator app’, Jensen.

    Say I have an app that hides all the built-in Excel menus and toolbars. It builds its own menu bar, replacing the Worksheet Menu bar. And this custom menu bar has, say, four menus on it each of which has menu items, submenus and submenu items.

    Will each of the four menus get its own chunk? And will it still be possible to drill down into the submenus and submenu items?

  3. Keeron says:

    Jensen,

    Any example (screenshot) of a likely office 2003 add-in in Office12? Say like one that adds couple of menu items, and one that adds toolbar items.

    Would love to see how the new Add-ins tab look with these menuitems and buttons.

  4. SavrajD says:

    Hi Jim and Keeron,

    I’ve got some answers to your questions–I’m a program manager on the same team as Jensen. 🙂

    Q1: Yes — if you added three items to across various menus and submenus, they all appear right next to each other in the menu commands chunk.

    Q2: If you added a new toolbar with four menus to replace the menu bar, you will see one chunk on the add-ins tab containing the four menus. It will still be possible to drill down into the submenus and submenu items.

    Q3: Let’s say I added a new top level menu called "My New Top Level Menu," a button to the Tools Menu called "My Button on the Tools Menu", did the same for the Format Menu, put some buttons on the built-in toolbars, and created my own toolbar called "My Toolbar."

    If you click on the freshly inserted image in the post above, you’ll see what this looks like on the add-ins tab.

    I hope that helps. Stay tuned for more info!

    – SavrajD

  5. Tom Winter says:

    In "old" versions of Word, any customizations made to the CommandBars (either interactively or programmaticaly) where saved into the current template (Application.CustomizationContext). Will RibbonX customizations work the same way? Thanks!

    -Tom

  6. Fox Cutter says:

    I’m reminded of what Winston Churchill once said about democracy, the worst possible solution–except for all the others. What you have here strikes me as the simplest way to handle the problem… I’m sure there are more "correct ways" (big air quotes on that) to do it, but this one will cause the less problems.

    It’s a good compromise, and seems like it will work well.

  7. Perhaps this has already been covered, but can an add-in take part in contextualization?

    For example, could an image processing add-in listed in the add-ins tab be highlighted, preselected, or otherwise visually suggested whenever an image is selected just as, say, the tables tab is manipulated when the cursor is inside of a table?

  8. Savraj says:

    To respond:

    – There is no longer a ‘customization context’ for Word in RibbonX–we found that it hurt more than it helped. Customizations follow a simple rule–if your add-in, template, or solution with UI customizations is open or loaded, its UI gets loaded. If it’s not loaded, the UI associated with it is not loaded. You cannot affect, through another document or template, what’s stored in Normal. You can, however, make changes to Normal directly, and then the customUI in Normal will apply to all documents.

    – An add-in can take part in contextualization by adding itself to the appropriate contextual tabs or tab sets. In your example, the image processing add-in can add itself to the Picture Tools contextual experience so that it appears only when the built-in picture tools appear.

    Thanks!

    Savraj

  9. Savraj, as I understand it, the RibbonX customization is stored for a workbook. I often need menu customization to be associated with a specific sheet of a workbook, and to follow that sheet if it’s copied or moved to other workbooks. At the moment, I can do this using an addin to hooks Sheet_Activate events and sets up the appropriate menu changes based on the values of specific defined names. How do I do that with RibbonX?

    (for more information, please see the private MVP office developer newsgroup).

    Thanks

    Stephen Bullen

  10. Over the course of this blog, I think I have covered to some degree every tab in Excel 2007 except for…