custom-ribbon-endresult

How to create a custom ribbon in Sitecore Content Editor

In this how to article we will learn how to create a new ribbon section in the toolbar of Sitecore Content Editor and how to use the various controls available to be used in the ribbon.

How the ribbon is structured

Let’s take for example the Home ribbon.

home-ribbon

it consist of

  • One strip, as a container of multiple chunks such as Edit, Insert, Operations, Rename, and Sorting
  • Inside of those chunks there’s the actual buttons

In summary Toolbar -> Ribbon -> Strip -> Chunk -> Button

This is what we want to achieve in this article:

custom-ribbon-endresult

Here’s how we can do that

First step, create the new ribbon

  • switch to the core database
  • under /sitecore/content/Applications/Content Editor/Ribbons/Default create a new item with using the Reference template ({EF295CD8-19D4-4E02-9438-94C926EF5284}) and name it Custom Ribbon
  • notice that the reference template on has one field which is the Reference field, we need to pass in the item id of our next item
  • under /sitecore/content/Applications/Content Editor/Ribbons/Strips create a new item with using the Strip template ({EC6D62A5-5D00-4329-8958-8AC1AD100EBB}) and name it Custom Strip
    • in the Header field insert “Custom”
    • in the ID field insert “CustomStrip”
    • in the Access Key field insert “C”, this is useful for your content editor so that they can access the ribbon by using the ALT+C key combination
    • Copy the item id and assign it to the /sitecore/content/Applications/Content Editor/Ribbons/Default/Custom Ribbon Reference field
  • under /sitecore/content/Applications/Content Editor/Ribbons/Strips/Custom Strip create a new item with using the Reference template ({EF295CD8-19D4-4E02-9438-94C926EF5284}) and name it Small Buttons
  • under /sitecore/content/Applications/Content Editor/Ribbons/Chunks create a new item with using the Chunk template ({8F3D8F9B-2D76-4ACE-803F-35415D2B230A}) and name it Custom Chunk
    • in the Header field insert “Custom Chunk – Small”
    • in the ID field insert “CustomChunkSmall”
    • Copy the item id and assign it to the /sitecore/content/Applications/Content Editor/Ribbons/Strips/Custom Strip/Small Buttons Reference field
  • under /sitecore/content/Applications/Content Editor/Ribbons/Chunks/Custom Chunk create a new item with Small Button template ({9F62EBD5-2280-4A35-BE51-A210D831D687}) and name it Small Button
    • in the Header field insert “Small Button”
    • in the ID field insert “SmallButton”

now you can see the ribbon with your newly created button.

new-custom-chunk-small

Seems like a long step just to get our custom ribbon showing, that’s because there need to be at least one item in the ribbon before Sitecore can display your custom ribbon

Now you get the general idea of how to create a custom ribbon on the Content Editor. After we have our custom ribbon ready we could start adding various controls to it, the available controls that we can use are

  • Small Button/Large Button
  • Small Check Button
  • Small Gallery Button/Large Gallery Button
  • Small Combo Button/Large Combo Button
  • Small Dropdown Box
  • Small Menu Combo Button/Large Menu Combo Button
  • Small Input Box
  • Panel

Let’s go through them one by one.

Small Button/Large Button

large-buttonsmall-button

The small button or large button support an action to be triggered when the user clicks on the button. For example displaying an alert window.

alert-command

How do we do that?

First let’s check the fields value for that button

small-button-field-values

In the Click field we put customribbons:alert command, Sitecore will trigger this command every time the button is clicked.

The command is registered through a separate config file

The actual command class

Nothing fancy happening in the command class, this is just to give you an idea on how to wire the whole thing.

Small Check Button/Large Check Button

small-check-button

The small check button support a checkbox control for the user to represent toggled/untoggled state.

small-check-button-ticked

The small check button fields are basically the same as the small button except that it doesn’t have the option to set an icon.

The command class for this example

Don’t forget to register the command class in the config file.

Small Gallery Button/Large Gallery Button

large-gallery-button small-gallery-button

The gallery button is a special type of button that execute a XAML application when the button is clicked, for example this demo app below

large-gallery-button-clicked

Let’s see how that can be achieved.

Here’s Large Gallery Button field values.

large-gallery-button-field-values

We have a command class which registered as customribbons:gallery

The command class is not doing anything, however we still need this command class in order for it to work.

And then we have Gallery.Demo in the Gallery field, when set Sitecore will seek any XAML application under Sitecore/Sitecore Modules folder that has the matching tag.

The XAML file has a backing class that handles the functionality of the XAML page

 

Small Combo Button/Large Combo Button

large-combo-button small-combo-button

The combo button support two type of event

  1. When you click on the button itself
  2. When you click on the arrow

Let’s take a look at the field values

small-combo-button-field-values

Here’s what it will do:

  1. It will trigger the customribbons:alert when the button is clicked
  2. It will run the Gallery.Demo xaml application when the arrow is clicked

Small Dropdown Box

small-dropdown-box

The small drop-down box control will basically take a string separated by a pipeline in the Items field and render it as the drop-down items

small-dropdown-box-clicked

Small drop-down box field values

small-dropdown-box-field-values

In the example I’ve put a pipeline character in front as the default item in the dropdown control. This control will trigger the customribbons:dropdown command.

 

Small Menu Combo Button/Large Menu Combo Button

large-menu-combo-buttonsmall-menu-combo-button

Like the combo button control, the menu combo button control also support two types of event. Clicking on the button and clicking on the arrow.

The Large Menu Combo Button field values

large-menu-combo-button-field-values

In the Menu field it refers to the menu items created under /sitecore/content/Applications/Content Editor/Menues/Custom Menus

custom-menus

The control will list the items referred when the arrow is clicked

large-menu-combo-button-arrow-clickedThe menu item also support the command class to be entered in the Message field.

Small Input Box

small-input-box

The small input box as it’s name represent has an input text field available. When the cursor is out of focus from the control or when the enter key is pressed it will trigger the command.

small-input-box-triggered

The command class

 

Panel

Panel is a way provided for the developer if the out of the box control does not meet their need, they can create their own control then register it as a panel to be used in the ribbon.

An example of this would be the Insert chunk in the Home ribbon

insert-chunk-home-ribbonWhich we can re purpose for something else, for example

panel

In the field values, there’s only one field which is Type where we register our custom Panel

panel-field-values

The panel class

The source code can be found in github

And that concludes this little article.

Leave a Reply

Your email address will not be published. Required fields are marked *