Documentation Center

How to add a button to the ribbon toolbar

Overlays can be used to add buttons to the ribbon toolbar in the editor.

When adding buttons to the editor user interface, you should consider the following:

Adding buttons in the configuration

This example is a section from an XML configuration file. As you can see using Role is relatively easy to do but a bit more limited. Whereas Command is a bit more work to implement, it allows you more flexibility. For example with Command you can use it for the display of custom panels.

In the first section, we create a button that assigns a role to block of selected text (or creates an empty element with the cursor positioned inside of it). Note that the "after" attribute places it after the standard "hyperlinkRoleButton" in the UI.

Next, we create a second button that uses the "command" attribute to associate it with a JavaScript command and the "after" attribute to specify that this comes after the first button. In order for the command to work, you will need to define the command object in JavaScript and reference this script from your configuration so the editor can make use of it. See below for the JavaScript.

The final section is the node configuration for the "editornote" role. In addition to specifying the role, it also includes placeholder text for empty elements.

<overlay xmlns="http://xopus.com/2009/lui">
  <!-- add buttons -->
 
	 <!-- first button is added using  the "editornote" role -->
  <ribbon-normalbutton
    iconsrc="notes.gif"
    label="Insert Note"
    after="hyperlinkRoleButton"
    id="noteButton"
    role="editorNote" />

  <!-- the second button is added using the "insertFigure" command-->
		<ribbon-normalbutton 
    command="insertFigure" 
    label="Insert Figure"
    iconsrc="figureButton.gif" 
    id="figureButton"
    after="noteButton" />

</overlay>

<!-- for first button, we define the "editornote" role -->
<x:nodeConfig>

<!-- some other node configuration goes here -->

  <x:node match="editornote">
    <name xml:lang="en">Note</name>
    <name xml:lang="nl">Note</name>
    <placeholder>New {name}</placeholder>
    <role>editornote</role>
  </x:node>

<!-- more node configuration here -->

</x:nodeConfig> 

Matching Javascript code sample for the insertFigure command

For the insertFigure command specified in the XML section above, the JavaScript includes two key functions:
  • "execute" is the portion that performs the actual function of the button
  • "getEnabled" is used by the UI to determine whether the button is active or not.
In this case, since we are inserting a specific element, "getEnabled" contains the logic to determine if the element is legal at the current cursor location and, if not, disables the button by taking advantage of changes in the state of the variable ("xmlSelection") used. Since the button will be disabled in locations that do not allow the element to be inserted, we don't need to worry about those checks when inserting the element.
var insertFigure =  { 
   
execute: function (scope) 
  {
   var range = Editor.Selection.getRange();
   var start = range.getStartContainer();
   var parent = start.getParentNode();
   var document = Editor.getActiveDocument();
   var figNode = document.createElement("fig");
   var resultNode = parent.appendChild(figNode);
   parent.makeValid();
   return;
  }, 
  
getEnabled: function (scope)
  {
   var canvas = Editor.Canvas.getActiveCanvas();
   if (!canvas)
    return false;
   var xmlSelect = scope.get("
xmlSelection");
   var range = Editor.Selection.getRange();
   if (!range)
    return false;
   var start = range.getStartContainer();
   var parent = start.getParentNode();
   var document = Editor.getActiveDocument();
   var figNode = document.createElement("fig");
   var result = parent.canAppendChild(figNode);
   if (result == 5)
    return true;
   else 
    return false;
  },
  getLabel: function (scope)
  {
   return "Insert Figure";
  }
 }
Editor.addCommand("insertFigure", insertFigure);