LibrarySites.Banner

All About the Content Editor Ribbon in the Sitecore ASP.NET CMS

The How to create contextual button or ribbon or strip? thread on the Sitecore Developer Network (SDN) forums prompted me to write this blog post that contains or links to everything I know or could find about the ribbon in the Content Editor application in the Sitecore ASP.NET CMS.

To maximize familiarity and hence usability, Sitecore 6 and later follow the ribbon UI conventions defined by Microsoft, most prominently in the Content Editor browser-based user interface. For tips on using the ribbon, see my blog posts Sitecore Mouse and Keyboard Shortcuts and Maximize Sitecore Content Editor Performance.

The ribbon appears at the top of the Content Editor and includes the Sitecore logo (which actually functions like a button, just like in Microsoft Word), a series of tabs, and a "strip" containing the "commands" (buttons) associated with the selected tab. Clicking each tab activates a different strip.

Each strip contains a number of groups (sometimes called chunks), and each group contains some number of commands. Groups are just containers for commands, and you can reuse groups on multiple strips (tabs). The ribbon supports a number of different types of commands - some display no user interface, simply updating data and refreshing the Content Editor view. Others have drop-down menus, while some trigger flyouts or even standalone dialogs. For information about why a tab, group, or command might not appear, see my blog post Missing Tabs on Ribbons in the Sitecore ASP.NET CMS.

The /Sitecore/Content/Applications/Content Editor/Ribbons branch in the Core database contains the strip, group and command definition items that make up the ribbon, including the commands in each group. The Click field in each command definition item references a command code defined in the /App_Config/Include/Commands.config file, which maps the command code to the class that implements that command. These classes implement the Sitecore.Shell.Framework.Commands.Command abstract base class.

When you click the command, Sitecore invokes the Execute() method in the associated class. To override one of the default commands, create a class that inherits from this abstract base class or from the default implementation for that command, implement the Execute() method and then replace the class referenced in the /App_Config/Include/Commands.config file for the command code referenced in the command definition item with your class. You can also override and add custom commans with web.config include files. For more information about web.config include files, see my blog post All About web config Include Files with the Sitecore ASP.NET CMS.

One additional aspect of the ribbon is dialog launchers, which appear after the names of specific groups and open additional dialogs. For example, the Sorting group on the Home tab provides a dialog launcher that lets you choose a child sorting rule for the selected item. To enable a dialog launcher, enter a command code in the Click field in the Data section of the group definition item in the Core database.

You can move, copy, remove, and otherwise manipulate commands on the ribbon. You can even add custom commands - for one example, see my blog post Add a Button to the Sitecore Content Editor Ribbon to Debug Any Item in Any Database. If you use commands extremely frequently, you might want to add them to the context menu instead of or in addition to the ribbon. For one example, see my blog post Add a Command to the Sitecore Item Context Menu (context menu commands appear even when the ribbon does not, such as in selection trees). For a more complete example, see Brian Pederson's blog post Unlock sitecore items.

To control whether a command is enabled or disabled, or to hide or show a command, implement the QueryState() method in the command class to return CommandState.Enabled, Disabled or Hidden. In general, disable commands rather than hiding them. Otherwise, the user interface can appear jumpy as the user navigates between items that shows the command and items that do not. Sitecore uses the client roles to control access to commands; you can add or remove users from roles or change access rights for the group and command definition items (if the user can't see any groups on a strip, they can't see that tab). For more information about the Sitecore client roles, see the Client Configuration Cookbook on SDN.

You can also add custom tabs to the ribbon to expose commands for specific data templates. To add a custom tab, define the custom toolbar based on one of the existing items under the /Sitecore/Content/Applications/Content Editor/Ribbons/Contextual Ribbons item in the Core database. In the data template, on the Configure tab, in the Appearance group, click the Contextual Tab command. In the dialog that appears, select the custom tab created previously. Technically, this sets the __Ribbon field in the Appearance group defined in the standard template to the ribbon that you created.

It might be worth noting that you use the same infrastructure to build ribbons into other applicaitons.

If you have additional information or resources about the ribbon, or to describe how you have customized the ribbon, please comment on this blog post.

More posts All About the Sitecore ASP.NET CMS.

  • Having successfully created a contextual tab and asscociated it with a template, when I display an item based on that template, the contextual tab gets selected automatically. How can I change that? I.e, in the content editor, if I have chosen one tab, I don't want sitecore to change tabs for me, just because I chose another item.

  • @Peter:  I might be missing something, but it doesn't look easy to override the component that renders the ribbon to do what you want, but maybe you can manipulate the UI afterwards.  I would try to invoke some JavaScript, maybe on completion of the item:load event or something. I see references to something called "scActiveEditorTab", which may be a JavaScript variable or form element, and may indicate the tab selected before the user clicked this item (if that is empty, then maybe you want to default to the Content tab). Then:  scContent.onEditorTabClick(null, '<tab name or ID>');  I am not sure this would work and it might present a strange UI refresh even if it did work. I would probably avoid this effort if possible.

  • The functionality I am looking for seems to be already implemented as standard behaviour for templates: When you click on a template in the template manager, an extra tab appears (Builder / Options), but it does not get selected automatically. I just don't know how to replicate that behaviour. I am using sitecore 6.4.1 rev 110720

  • @Peter: Template Builder is a custom editor (the Builder tab that appears on the second tabstrip, before the Inheritance and Content tabs), and that editor must pull in this ribbon, but not activate it. See the /sitecore/content/Applications/Templates/Template Builder item in the Core database, which defines that Options tab. Sitecore uses the __Editors field to specify those editors, so this takes a different approach. If you can implement your application as a custom editor, then I think you can get this functionality. Otherwise, I think you have to accept that Sitecore activates that tab, or maybe do something with JavaScript (though the code I suggested might not be the right stuff - I think that is for editor tabs but you are talking about the top tabs). If this is really important to you and you can't find the right JavaScript, let me know and I can look into it further, but I am pretty sure you will have to fake a click on the tab that was selected before the user clicked the item that specifies the custom tab. There may be other alternatives, such as using an event that fires when loading the item to call some API code to add the tab under specific conditions rather than using the __Ribbon field.