Documentation Center

Adding a new button to a group in a Ribbon toolbar

Add a new button to a group in a Ribbon toolbar to provide a user with access to built-in or custom functionality.

Procedure

  1. Create a set of icons for your button. These should be four image files in the PNG format, in the sizes 16x16 pixels and 32x32 pixels, with a disabled and enabled version in both sizes. Add these image files to your Visual Studio solution.
  2. Create a CSS stylesheet that refers to these icons, and add it to your Visual Studio solution.
  3. From the Add-ons screen in Content Manager Explorer, download the Add-on package (ZIP file) that contains your GUI Editor extension.
  4. From the ZIP file you downloaded, extract the GUI Editor's configuration file and open it for editing.
  5. If you have not yet done so previously, in the cfg:groups section, create a new cfg:group element to represent your GUI controls' resources and dependencies. Set its name attribute to a meaningful name, say, MyCustomization.AllMyControls, and insert a cfg:fileset and a cfg:dependencies element inside it. Inside the cfg:dependencies element, insert a cfg:dependency element and set it to the name of the resource group containing all your commands.
  6. Inside the cfg:fileset element of the resource group, add a cfg:file element with its type attribute set to style and its value set to the name of your CSS stylesheet.
  7. In the extensions section, locate the ext:ribbontoolbars section. Inside this section, create or find an <ext:add> element.
  8. For each button you want to add to a group in a Ribbon toolbar, create an ext:extension element with the following contents:
    <ext:extension pageid="RibbonTabID" groupid="GroupID" name="ButtonLabel" assignid="MyCommandButton">
    	<ext:command>MyCommand</ext:command>
    	<ext:title>TooltipLabel</ext:title>
    	<ext:dependencies>
    		<ext:dependency>MyCustomization.AllMyControls</ext:dependency>
    	<ext:dependencies>
    	<ext:apply>
    		<ext:view name="VIEW_NAME">
    			<ext:control id="TOOLBAR_NAME" />
    		</ext:view>
    	</ext:apply>
    </ext:extension>

    where RibbonTabID identifies the tab in the Ribbon, GroupID identifies the group in that tab, ButtonLabel is the display label of the button, MyCommand is the name of the command as specified in one of your command sets, and TooltipLabel is the displayed tooltip when you hover over this button. You can find the IDs of existing Ribbon tabs and Groups by examining the HTML of a Web page that displays the tab. ext:view specifies the Ribbon toolbar and view that you are adding this button to:

    Web site Ribbon toolbar
    To add the button to the Ribbon that end users see when they edit a Web page, replace VIEW_NAME with EditorView and replace TOOLBAR_NAME with MainToolbar.
    Content Manager Explorer Ribbon toolbar
    To add the button to the Ribbon of the Content Manager Explorer user interface, replace VIEW_NAME with DashboardView and replace TOOLBAR_NAME with DashboardToolbar.
  9. If this Group already contains other buttons, then by default, this new button appears as the rightmost button in the Group. To place it somewhere else, add an insertbefore attribute to the ext:extension element and set its value to the ID of the button before which you want to position this new button.
  10. By default, the new button appears as a large button in the (non-minimized) Ribbon toolbar. If you want to display the button as a small button instead in the non-minimized Ribbon toolbar, insert the following child element directly under the <ext:title> element:
    <ext:issmallbutton>true</ext:issmallbutton>
  11. By default, the new button is always displayed and always enabled. You can change this behavior in the JavaScript file associated with the command that executes when you click the button. In this JavaScript file, you can create an isEnabled and/or isAvailable method that checks whether certain conditions hold. Whenever the view under the Ribbon toolbar changes, isEnabled and isAvailable get called to see if the button should be greyed out or hidden, respectively. In your methods, then, you can check the properties of the current view (say, which items are selected in a list) and return true or false depending on what you see.
    Note also that if all the buttons in a Group are not displayed (that is, if isAvailable returns false for all of them), the Group itself is not displayed either. However, a Ribbon toolbar tab remains available and can be clicked, even if it has no Groups to display.
  12. Save and close the configuration file and update it in the ZIP file. You may want to increase the build number in the filename of the ZIP file, or even the version number of the Add-on (which you must also then change in the manifest file).
  13. From the Add-ons screen in Content Manager Explorer, upload the updated Add-on package (ZIP file). It replaces your old Add-on package.