Ribbon Element Customization

Levels of Customization
A key point to understanding the customizations of the Ribbon is the level at which you
perform the customization.
You can apply your customization at each of the following levels. Each of these levels
corresponds to an entry in the 'Solution Elements' panel.
 Tab Level
 Group Level
 Button Level
 Command Level
 Tab Scale Level
The top most level of your customisation will appear in the Solution Elements Panel, but any
sub-elements will considered children of your customisation and will not have a node in the
Solution Elements Panel.
For example, if you drag a Tab on to the design surface you will see a Solution Element under
'Tabs'. If you drag a Button onto that Tab, you will not see a solution element under 'Buttons'
because it is a child of the Tab solution element. Equally if you customise an existing Tab, then
again, you will see it appear under Solution Elements, but if you then drag a button onto the
customised Tab, it will not appear as it's own Solution Element.

If you drag a Button onto an existing standard Tab, you will see a Button element under
'Buttons in the Solution Elements because the parent is not already part of the solution
elements.
If you customise a Group or add a new Group - it is similar to the Tab scenario, but the top level
is at the Group Level:

If you try and customise an element at a higher level where a child element is already a top
level Solution Element, you will receive the following message.

Ribbon Controls
The following diagram shows you where you can drag each Ribbon Element within the Design
Surface from the Toolbox.
Tabs
Tabs group buttons and are the top most container of Ribbon Customisations. Standard tabs
can be moved by first Customising the Tab and then dragging it to another position.
Groups
Groups contain Layout Sections that can contain Buttons, Fly Out Anchors and Split Buttons.
Groups can be dragged around to reposition, but cannot be moved between tabs.
Buttons
Buttons are associated with a Command that is run when clicked. Buttons can be moved
around within Groups, into a different Group or moved to another Tab by dragging onto the
Tab Title.
Note: If you move a Button from one top level solution element to another, it will no longer be
part of the customisations.
Fly Out Anchor Buttons
A Fly Out Anchor is essentially a drop down menu that can contain Menu Sections and Menu
Items. Each Menu Item acts the same as a Button.
A default Menu Section is created for you when you drop a Fly Out Anchor on a Ribbon, but you
can add more using the 'Right Click' 'Add Menu Section'
Menu Items can then be added by using the 'Right Click' on the Menu Section and using 'Add
Menu Item':

Split Buttons
A Split Button is a cross between a Button and a Fly Out Anchor in that it can be clicked, or a
sub-item selected from it's drop down menu.
Menu Section
If you are customising the Ribbon Jewel, The Menu Section acts like a Menu Item Group that
contains Buttons. These are shown as drop down menus when the Jewel is clicked.

Getting started with the Ribbon Workbench

In this chapter we are going to look at the basics of using the Ribbon Workbench for CRM 2011,
and cover the following points:
What is the Ribbon Workbench?
The Ribbon Workbench for CRM 2011 is a tool written to make customizing the Ribbon easier
and quicker. The Ribbon is the user interface element that appears at the top of all recent
Microsoft Applications, and was the successor to the old ‘toolbar’. Rather than have a single
toolbar that was full of all command buttons and a set of drop down menus that could be
multiple layers deep, the Ribbon attempts to show only the commands that you need
depending on the task that you are doing. The ribbon also attempts to scale to the available
window width, making some less important commands smaller or even move them to drop
down menus when the space is limited. The ribbon designer decides on the importance of each
command and therefore the order in which commands are ‘demoted’ as the window width is
reduced.
Before the Ribbon Workbench, there was the CRM2011 Ribbon Visual Editor that allowed the
simple addition of buttons and groups to existing tabs, but any more complex scenarios such as
drop down menus, changing the ‘out of the box’ ribbons or adding new tabs was confined to
the realms of editing page upon page of hard to understand xml.
The Ribbon Workbench for CRM2011 was written to provide a ‘drag and drop’ developer
experience that allows all customization scenarios to give complete control over your CRM
2011 ribbon!
Installing the Ribbon Workbench
The Ribbon Workbench is a CRM 2011 solution (If you are not sure of what a CRM solution is, I
suggest you read an Introduction to Solutions before carrying on). To install you will need to
follow these steps:
1. From within Dynamics CRM 2011, navigate to Settings → Solutions → Import
2. Download the Ribbon Workbench, and then select the downloaded solution file and
following the instructions.
3. Once imported, you can click the ‘Ribbon Workbench’ button on the ribbon. This button is
only visible if you have customizations rights and you are in the ‘Solutions’ area.

Creating and loading a solution into the Ribbon Workbench

The Ribbon is edited in two distinct ways:
 Edit the Application Ribbon to make changes system wide (e.g. add a button once that
appears on forms on all records)
 Edit individual Entity Ribbons to make changes for a specific entity (e.g. add a button
only to the contact form)
If you wanted to add a button to the Contacts Form Ribbon (the form shown at the top of the
form when editing a Contact), you would add the Contact entity to a solution and load it into
the Ribbon Workbench. If you wanted to add a button to all Form tabs for all entities you would
add the Application Ribbon to a solution.
To add the Contact entity to the solution
1) Navigate within Dynamics CRM to Settings → Solutions → New
2) Enter the name of the solutions (e.g. 'Contact') and click 'Save'.

3) Now select Components → Entities → Add Existing → Contact

To add the Application Ribbon to the solution
1) Within your solution, select Components → Client Extensions → Add Existing → Application
Ribbons
Solution Webresources
Webresources are simple files that can be uploaded into a solution that can be used by your
customizations. Later on we'll see how you can use webresources to provide scripts that can be
executed via buttons on the ribbon, but for now we'll concentrate on simply adding an image
webresource. Since we are going to create a new button on the ribbon we’ll need some pretty
images to put on them.
Ribbon buttons require two images of type png, gif or jpg. The two sizes are used when the
ribbon resizes to fit the available window width. If there is limited space, a button can change
into a smaller button or become a drop down menu. Here are two example button images of
the correct size that you can use.
 16x16 PNG format

 32x32 PNG format

You can create these images in any image editing package – a great free tool is Paint.NET.
To add these images to your solution, you need to:
1) Within you solution, select Components → Web Resources → New
 Name: new_Image32.png
 Display Name: Image32.png
 Type: PNG
 Upload File: Select your 32x32 image file
2) Within you solution, select Components → Web Resources → New
 Name: new_Image16.png
 Display Name: Image16.png
 Type: PNG
 Upload File: Select your 16x16 image file
You should now have a solution that likes:

Now go ahead and open the Ribbon Workbench from Settings→Solutions→Ribbon Workbench
and when presented with a list of solutions, select your newly created solution named
‘Contact’.
You should be presented with a view of the ‘Home Page’ ribbon of the contact entity.
Before we look at the different parts of the Ribbon Workbench, go ahead and have a play -
nothing is saved until you click 'Publish Solution'!
Top Bar
The top bar provides the main control over loading and publishing solutions

Ribbon Editor Panel

The Ribbon Editor Panel provides the main design surface for editing the currently selected
entity ribbon. Each ribbon is divided into different tabs. When you select the Application
Ribbon you'll see many more tabs that if you select the 'Contact' entity.
 A really import thing to notice at this point is that here are a number of different types
of ribbon tabs that can be edited by selecting from the drop down in the top right of the Ribbon
Editor Panel.

 Homepage – Tabs that are displayed in the main CRM 2011 application screens.
 Form – Tabs displayed when a specific record form is opened.
 SubGrid – Tabs shown when a list view is selected on a specific record form.
 Jewel – The menu options that available when the ‘Jewel’ is selected. This is the blue
‘File’ tab that is show on the left hand side of the Homepage ribbon. These are only
editable when the ‘Application Ribbon’ is selected.
Try selecting different types of ribbon and see which tabs are shown.
Toolbox, Entities and Solution Elements
You'll notice the panels shown under the Ribbon Editor Panel. You can select the divider bars
between these panels to resize them to the position that suits you best.
Toolbox Panel - The toolbox allows you to drag and drop ribbon controls on to the ribbon
design surface. When you drag an item it must be positioned next to where you would like it to
appear. The cursor will change to a blue plus icon when dropping the control is allowed. If you
want to place a new tab, you must drag the tab control directly next to an existing tab, rather
than drop it where the controls appear.
Entities Panel - The entities that you included in your solution will appear as a list in the Entities
Panel. By selecting an entity, the Ribbon Workbench will show you the tabs that are available
for that entity and the currently selected ribbon type
Solution Elements Panel - This panel is one of the most important areas for understanding your
ribbon customizations. As you drop items on the Ribbon Design Surface, Custom Actions will
appear in the Solution Elements. Later we will look at what each of these elements mean.
Adding a button to the Ribbon
Let's start by adding a button to the 'Records' area of the Contact Form Ribbon:
1) Select the 'Form' ribbon types in the top right drop down list
2) Select the 'Contact' entity in the Entities Panel
3) Drag a button from the toolbox onto the 'Records' ribbon group.
Try dragging the button to different places - you'll see that some places will show a 16x16
button and some places will show a 32x32 button. This is because the Ribbon template defines
the size of buttons in each layout area within each group. At this stage we should take a look at
how the ribbon is made up.
Each tab is sub-divided into the following elements:

Groups - Groups each have a title and group buttons on a tab

Layouts - Each Group is sub-divided into multiple Layouts which then contain controls that
are all shown at a particular size. Each Layout is assigned a different size by the template layout
that is selected. More on this later.

Controls - The Controls are positioned within each Layout. When the ribbon is shown to
the user, they can't see the different layouts, only that in each group, there are buttons shown
at different sizes.

Whenever a ribbon is part of the loaded solution it will show a red tick ( ). It is
important to understand here that you can customise out of the box ribbon elements, or add
new ribbon elements. In both cases the elements will have a red tick on them since they are
included in the solution. If you customise an out of the box group or add a new group, a red tick
will appear on all of the buttons in that group. If you customise or add a new tab, a red tick will
appear on all of the groups and buttons in that tab.
Setting the Button Images
If you remember earlier we added two images to our solution for use on our button. We can
now specify these by selecting our Button and using the Property Panel.

Click the search icon on the Image16by16 and Image32by32 Property and select the
corresponding image from those in the solution.

The Ribbon Workbench only shows webresources selectable if they have been added to
the solution currently loaded.
Go ahead and drag your new button around on the ribbon to see where it can go. You'll notice
that in some Layouts it will show as the 16x16 button, and in some it'll show as 32x32.
At this point you may also like to change the LabelText from 'Button' to something like 'Open
Bing' using the 'LabelTextText' property. You will notice that you can change the Language using
the drop down box at the top of the Properties Panel. The available languages depend on those
that you have provisioned inside your CRM Organisation.
Defining a Button Command
Now we have a button, the next item on our TODO list is to define what happens when the user
clicks it. There will be much more on this later, but for now, we'll simply make it open a new IE
window that contains a Bing search page.
1) Navigate to the Solution Elements Panel → Commands → (Right Click) → Add New
2) Expand the Commands Node and select the new command. You'll see that it has been
given an ID that uses the solution prefix in the format:
new.contact.Command0.Command
The prefix can be changed to your choice by using the Information Tab of your Solution and
selecting the 'Publisher'. The Prefix can be edited and saved.

For this to take effect in the Ribbon Workbench, you must re-open your solution.
3) You have the option of changing the ID using the Properties Panel. This Panel will show the
properties of which ever element you have selected in the Workbench.

The Ribbon Workbench creates a consistent naming convention for your ribbon elements, so
it's advisable to only change the Command0 bit.
E.g.
new.contact.OpenBingWindow.Command
4) You may be wondering why we are creating a new command when we have already added
a button to the ribbon. This is because the Ribbon allows a command to be defined such that it
can be used by multiple buttons. So although we are only going to associate our command with
the new button, we could add more buttons that all call the same command. Commands use
'Actions' to define what should happen when a user clicks any associated buttons. To define the
Actions, click on the magnifying glass icon next to the 'Actions' Property:

5) Any existing actions that are defined for this command would display here, but because it is
a new command, the list will be empty. Go ahead and click 'Add' to create a new one and select
the 'Open Url Action'. The other 'Javascript Function Action' option is for more complicate
actions that involve calling code, but more on this later.
6) Now we set the properties of the action:
 Address: http://bing.com
 WinMode: Window
 WinParams: resizable=yes
The WinParams is a string that has a structure depending on the WinMode.
For a Normal Window refer to http://www.w3schools.com/jsref/met_win_open.asp

For dialog windows, refer to

http://msdn.microsoft.com/en-us/library/ie/ms536759(v=vs.85).aspx
7) Now that we have oure command, click Ok, and the select our new button in the ribbon.
The Properties Panel should now show the Properties for the ID. You could rename the button
ID if you liked at this point.
To ensure that the OpenBingWindow Command is called when the user clicks the button, select
our command from the Command Property Drop down:

Publishing the solution

Now that we have everything setup, we can publish our solution to make the user interface
available to the user. To publish, simply click on the 'Publish Solution' button on the Top Bar.
The publish may take a little time depending on how much resources your CRM Server has been
allocated, but once finished, you should be able to navigate to a Contact record and use the
new button.

You may have noticed that after the publish was completed, the Messages Tab is shown and
displays some warnings:
To avoid these warnings you can select your button and provide some text for the
'ToolTipTitleText' and 'ToolTipDescriptionText' properties.

The Ribbon Workbench will always download the latest entity customisations
(attributes, forms, webresources etc.) before publishing your ribbon customisations so any
changes that have been made since you opened the solution (other than ribbon changes) will
be preserved provided they are not published in between downloading and re-uploading. If you
have multiple people working on your solution, you need to be careful that two people are not
publishing their customisations to the ribbon at the same time since the last person to publish
will overwrite the ribbon changes of the previous person.
Hiding Standard Elements
If you wanted to remove the button that you've just added, you can simply 'Right Click' on the
button either in the ribbon, or in the Solution Elements Panel and click 'Un-Customise Button'.
You may have noticed that whenever you drop an element onto the ribbon, it shows up in the
Solution Elements Panel so that you can keep track of what you have customised. If you select
the button in the Solutions Elements Panel, the button in the ribbon is also selected so that you
can easily find it, even if it's on a different tab type to the one currently selected (Form, Home
Page, Sub Grid).
If you needed to hide a standard button, or tab for what ever reason, the Ribbon Workbench
makes it easy to do so:
1) Select the Button or Tab that you would like to hide, and select 'Hide' from the 'Right click'
menu. You will notice that the element now has a red-line through it, indicating that it will be
hidden.

At any point you can then use 'UnHide' in the same way. Just as with new buttons appearing in
the Solution Elements, when you hide a ribbon element it appears in the Solution Elements as a
'Hide Action'.

Once you have published a solution with an element hidden, it will no longer show in
the solution ribbon when loaded again. If you want to 'Un-Hide' it after publishing you must
locate the Hide Action in the Solution Elements Panel, and select 'UnHide'
Summary
In this chapter we have learnt the basics of using the Ribbon Workbench, adding a new button,
associating it with a command, and publishing the solution. We also looked at hiding ribbon
elements and how to unhide them.
In the next chapter we will look at the different types of Ribbon in a bit more depth so that you
can understand where you need to make your customisations.
Customising User Interface Elements
Customisations to standard ribbon elements can be applied at different levels:
 Menu Items within a Split/Fly out button - Allows customisation of:
 Menu Item name
 Menu Item command
 Menu Item icons
 Menu Section within a Split/Flyout button - Allows customisation of:
 Section Name
 Position of Menu Items within that section
 Individual Buttons/Controls - Allows customisation of:
 All of the above
 Button Name
 Button Command(s) being called
 Icons of buttons
 Ribbon Groups - Allows customisation of:
  All of the above at the button level
 Changing the name of the group
 Changing the layout template applied to group
 The sequence of buttons within that group (drag-and-drop)
 The scaling of the group when the ribbon is resized.
 Ribbon Tabs - The whole tab is customised so that any element maybe changed. This
includes all of the above, but also:
 All of the above at the button and group level.
 The position of groups within the tab
 The name of the tab
 The rules for determining when the tab is displayed
 The scaling of all the groups within the tab
To customise at each of these levels using the Ribbon Workbench, simply use the right click
menu on the ribbon element (tab, group or button) and select 'Customise'. Once customised a
red tick will appear and it will be included in the Ribbon Elements Panel tree-view. Once a
specific level is customised it will also customise all lower levels - so if you customise a tab, all
groups and buttons included within that tab will also be customised. To avoid conflicting
customisations you cannot customise a higher level once you've customised a lower level - so if
you've customised a button, you'll not be able to customise a group or tab that it is included
within.

Once you've customised a standard button, group or tab, it essentially acts as though
you had dragged it onto your ribbon as a new element - the only difference is that it will be
overriding the standard behavior when the ribbons are merged together.
Customising Commands
As well as the user interface elements (menus, buttons, groups & tabs), the Ribbon Workbench
allows you to customise commands that are called by buttons whilst not customising the
button it's self. This is useful if multiple buttons call the same command, or where you want to
change the behavior of the button, but don't want to change the look.
You may have notice that when a button was customised earlier, it contained a property named
'CommandCore' - this is a free text field that points to a 'Core' command that is outside of the
solution. If at any point you need to override the behavior of a button's command you have two
options:
 Create a new Command in the Solution and selecting this command in the Buttons
'Command' Property. This option is the same as we performed in Chapter 1.
 Customise the Button's command and change the standard behavior. This is the
approach that is described below.
You will recall that a Command is made up of:
 Actions - used to define what will happen when the command is called (e.g. JavaScript
function called or web page opened)
 Display Rules - used to define when a button that calls this command will be displayed
 Enable Rules - used to define when a button that calls this command will be enabled
The interesting part of customising commands is that although you can't alter the visual
elements of buttons that call it, you can alter when those buttons are enabled or hidden.
Customising a Command is achieved by selecting the standard button that calls it, using the
right click menu and selecting 'Customise Command'. Once customised, the command will
appear in the Solution Elements in the same way as it would if you had added a new command
as we did in Chapter 1.
Now that the command is customised you can change or add to the command actions in much
the same way as you would if it was a new command. If you customise the command on
another button that calls the same command, nothing will happen since it is already
customised.
Uncustomising Commands
If at any point you no longer want to customise a command, you can simply use the right click
command and select 'Delete'. This will remove it from the Solution Elements in the same way it
would when you had created a new Command. The difference being that the command will
now revert back to the core definition upon the next publish rather than removing it all
together.
Using 'Core' Display and Enable Rules
In the same way as a button can point to a 'Core' command without it being included in the
solution, a Command can also point to a 'Core' Enable or Display Rule such as the built-in
'Mscrm.Enabled' rule. When you customise a command, all of the Enable and Display Rules it
uses will initially also be customised. These can then be 'Uncustomised' by changing the 'IsCore'
property to 'False' if you don't need to change the behavior of these rules.

Moving on up...
A common requirement in Microsoft Dynamics CRM projects is to hide or move buttons around
on the ribbon. The Ribbon Workbench for CRM 2011 allows you easily do this with very little
fuss.
Moving a Button within a group
In order to move a button within a group you need to change sequence of the button with the
group. You might first think that this could be done simply by customising the button and then
changing the sequence, however this does not seem to reliably work.
The most effective way is either customise the entire group and move the buttons around, or to
hide the core button and create a custom copy of the button in the new desired position.
Moving a button using 'Customise Group'
1) Select the group you wish to move a button within and use the right click menu to select
'customise group'
2) Drag the button you wish to move into to it's new location
3) Publish the solution
Moving a button by hiding the core and creating a copy.
1) Customise the button you wish to move by selecting 'Customise Button' from the right click
menu.
2) Drag the button to the new location. The Ribbon Workbench will conveniently hide the old
button and create a copy of it for the new location.
3) You can also move buttons a completely different group or tab using this method so it is the
method that is recommended. To move to a different tab, simply drop the button on the tab
label and the button will be placed at the start of that tab. You are then free to drag it to the
new location.
Customisation of Sections
As with moving buttons, menu items can also be re-arranged by customising the parent
button.
1) Select the Anchor or Fly-out button you would like to change the order of menu items within.
2) Click on the button to show its menu, and then select the section that contains the button
you would like to move.
3) Select the item you want to move and use the right click menu 'Move Up' or 'Move Down'
Since the section has been customised, you may also add new menu items using the 'Add New
Menu Item' on the right click menu of the menu section. If you don't want to move the menu
item, you can simple customise the item to change it's look or the command that it calls.

Hiding/UnHiding Ribbon Elements

I've always found that too many options presented to a user will be just as damaging to their
experience as too-little. The CRM 2011 ribbon allows you to hide ribbon elements using two
approaches:
 Global Hide Actions - Elements are hidden globally at all times.
 Dynamic Display Rules - Elements are made visible dependent on particular conditions
that are specific to the current record or the user logged in. Dynamic Enable Rules go
hand-in-hand with Display Rules.
Global Hide Actions
Clearly it is important to decide which option to use, but often the quickest and most effective
way of clearing up the user interface is through 'Hide Actions'
1) Find the Tab or Button you would like to hide - some buttons may exist on more than one
Ribbon - Form, Home Page and SubGrid - so make sure you have the correct one using the drop
down in the top right of the design surface.
2) Use the 'Right Click' -> 'Hide'
3) Once you have hidden an item, you will see a red strike-through:

Hiding Groups
If you want to hide an entire Group, then you simply need to hide each button within it, and the
Group will not be rendered. The Ribbon Xml schema actually allows you to apply Hide Actions
to groups, however I've found that this can cause JavaScript errors in the UI and so it is worth
avoiding.
Dude, where's my Button?...UnHiding a Tab or Button
Once you've hidden a Button or Tab and published and re-loaded, it will no longer appear in the
Ribbon Workbench Design Surface. When you re-load the solution, you'll see a message
indicating that there is a Hide Action, and the element is not visible until you delete the Hide
Action and re-load the solution.

To un-hide a ribbon element, you can select the corresponding Hide Action in the Solution
Elements -> Hide Actions, and use the left-click menu 'UnHide':
Custom Elements that are also hidden
If you try and hide an element that is already customised in some way (e.g. a Tab that has a
custom button/group) the Ribbon Workbench will give you an message similar to the following:

This is because the Tab, once hidden, will no-longer appear in the Ribbon Workbench, and you
will not be able to access your customisations. If you've already hidden a customised tab by
manually editing the xml, you will receive a message when loading the solution indicating as
such. In this scenario you should be warned that publishing the customisations will remove you
customisations and leave only the hide action.