The documentation was created for version 1.1 and is currently outdated
Visual Ribbon Editor
Overview / How it works:
The Visual Ribbon Editor works by connecting to the CRM server and creating a new "Ribbon Editor" un-managed solution that includes the entity you want to customize. It then exports this solution and extracts the ribbon customizations.
Since the solution only contains the current unmanaged custom changes to the button, it will also retrieve the full ribbon XML from the server and use all of this information to render the ribbon on the screen. You can then edit the ribbon (add buttons
and groups, etc.) and then save the changes back to the CRM server. When saving, it will re-package the same "Ribbon Editor" solution and import it back into CRM.
The Visual Ribbon Editor UI consists of 3 main sections
- A toolbar at the top of the window. This toolbar provides the following controls
- Connection - Edit CRM connection info (server url, username, password, etc)
- Open Ribbon - Shows a dialog that lets you select which entity ribbon to edit (or pick the "Application Ribbon")
- Save - Saves the current ribbon back to CRM.
- Ribbon Type - picklist to select which type of ribbon to edit (Form ribbon, Mainpage ribbon, or Sub-Grid ribbon)
- New Button - Click this to add a new button to the selected group
- New Group - Click this to add a new group to the selected tab
- Delete - Click to delete the currently selected button or group. Note: only custom buttons and groups can be deleted
- Hide - Click to hide a system button
- Un-Hide - If you hide system buttons using the "Hide" action, then you can un-hide hidden buttons using this dialog.
- View XML - view the current RibbonDiffXML (note: this xml is read-only, changes made to this XML do not affect the ribbon being edited)
- The Ribbon Preview. This Shows the current ribbon being edited.
- Click on the tabs to change the current Tab.
- Click on a button to select it.
- Click on the name of a group (the text below the buttons) to select the group.
- The Details section
- When editing a button or group, this section allows you to make various changes to the group or button.
Editing a Button
Use the "Details" tab to make the following changes to a button:
- Change the Label or Tooltip for the button
- Change the Template Alias
- The Template Alias determines the location and size of the button.
- Click the "Show Sections" button to show guide lines on the ribbon preview that indicate where each template alias is located on the current group. The orange lines show the different sections of the group. The Orange text shows the templateAlias
of each section and also the size of the buttons in that section.
- Set the Sequence of the Button
- Note: the sequence determines the order of buttons inside of a section. Use the "Show Sections" button to display the sections on the ribbon, and change the button's Template Alias to move it to a different section.
- Set the images used for this button.
- As you type into the image field, it will auto-resolve on the names of PNG web-resources that have already been uploaded to CRM.
- It is recommended that you provided an image for both 16x16 and 32x32 sizes because large buttons will shrink if there isnt enough room to display the full ribbon.
Use the Action tab to define what happens when the user clicks the custom button:
- For URL Actions, you must specify the URL to navigate to when the user clicks the button
- For both action types, you can add optional parameters that will be passed as function parameters (for jscript) or querystring parameters (for urls)
Use the EnableRules and DisplayRules tabs to define when the button is enabled or visible.
- Both the EnableRules and DisplayRules tabs contain a tree of rules.
- Click the "Add..." button to add new rules.
- Each rule has a list of properties that can be edited.
- Properties that are in BOLD are required.
- Some rules (such as the "Or Rule" or the "CustomRule" allow you to add sub-rules to them.
- To add sub-rules, just click the "Add..." button on the OrRule or CustomRule.
- To remove a rule, just click the "Remove" button next to it.
- Note: Rules are not evaluated in any way in the preview ribbon displayed in the Visual Ribbon Editor, to test if your rules are working correctly you will have to save the ribbon and test in CRM.
- It is helpful to look at the rules that are defined on existing system buttons to figure out how they work (system button enable rules can be viewed but are not editable)
To edit a group, click on the name of the group on the ribbon (click on the text)
Unlike buttons, groups only have the one "Details" tab:
The following properties can be change on a custom group:
- Change the label and tooltip description of the group.
- Edit the sequence of the group. This determines the ordering of the group within the system groups.
- You can click the < and > buttons to decrease or increase the sequence relative to the groups neighbors.
- Set the Image for the group. This image is only shown when the ribbon is shrunk so much that the group turns into a popup control
- Set the Template used for the group.
- The template determines what sections are available in the group. Sections, along with the button's TemplateAlias will determine where buttons are placed within the group and what size they will be.
- Click the "Show Sections" button to display the sections on the ribbon. This will let you see how the changes to the Template affect the position and size of the buttons.
After you are done making changes to the ribbon, click the "Save" button to save the changes back to CRM. These changes will be included in the current un-managed solution on the server. If you want to include these changes in your
own solution that you export from CRM, simply just include the same entity (or application ribbon) in your own solution. As long as both solutions are un-managed, then they will contain the same ribbon customizations.
After saving is completed, you can view the changes in CRM: