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
- 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.
- Create a CSS stylesheet that refers to these icons, and add it to your Visual Studio solution.
- From the Add-ons screen in Content Manager Explorer, download the Add-on package (ZIP file) that contains your GUI Editor extension.
- From the ZIP file you downloaded, extract the GUI Editor's configuration file and open it for editing.
- If you have not yet done so previously, in the
cfg:groupssection, create a newcfg:groupelement to represent your GUI controls' resources and dependencies. Set itsnameattribute to a meaningful name, say,MyCustomization.AllMyControls, and insert acfg:filesetand acfg:dependencieselement inside it. Inside thecfg:dependencieselement, insert acfg:dependencyelement and set it to the name of the resource group containing all your commands. - Inside the
cfg:filesetelement of the resource group, add acfg:fileelement with itstypeattribute set tostyleand its value set to the name of your CSS stylesheet. - In the
extensionssection, locate theext:ribbontoolbarssection. Inside this section, create or find an<ext:add>element. - For each button you want to add to a group in a Ribbon toolbar, create an
ext:extensionelement 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:viewspecifies 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
EditorViewand replace TOOLBAR_NAME withMainToolbar. - Content Manager Explorer Ribbon toolbar
-
To add the button to the Ribbon of the Content Manager Explorer user interface, replace VIEW_NAME with
DashboardViewand replace TOOLBAR_NAME withDashboardToolbar.
- 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
insertbeforeattribute to theext:extensionelement and set its value to the ID of the button before which you want to position this new button. - 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> - 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
isEnabledand/orisAvailablemethod that checks whether certain conditions hold. Whenever the view under the Ribbon toolbar changes,isEnabledandisAvailableget 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 returntrueorfalsedepending on what you see.Note also that if all the buttons in a Group are not displayed (that is, ifisAvailablereturnsfalsefor 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. - 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).
- From the Add-ons screen in Content Manager Explorer, upload the updated Add-on package (ZIP file). It replaces your old Add-on package.