Add a button to the toolbar in Xopus 4

Overlays can be used to add buttons to the toolbar in Xopus 4. Adding buttons to the toolbar in Xopus 3 is different from adding them in Xopus 4.

A toolbar button must specify either a role, which must correspond to one of the roles specified by the nodeConfig elements or it must specify a command which corresponds to a JavaScript command (see Editor.addCommand). It should also specify a label for the button tooltip that will be shown when the button is moused over and an ID that can be used by other UI elements (most often other buttons) to refer to it.

As an example, see the following section of a configuration XML file:

<overlay xmlns="http://xopus.com/2009/lui">
  <!-- add buttons -->
  <toolbar-button 
    command="insertFigure" 
    label="Insert Figure"
    iconsrc="figureButton.gif" 
    id="figureButton"
    after="hyperlinkRoleButton" />

  <toolbar-button
    iconsrc="notes.gif"
    label="Insert Note"
    after="figureButton"
    id="noteButton"
    role="editorNote" />
</overlay>

<nodeConfig>
<!-- some other node configuration goes here -->
  <node match="editornote">
    <name xml:lang="en">Note</name>
    <name xml:lang="nl">Note</name>
    <placeholder>New {name}</placeholder>
    <role>editornote</role>
  </node>
<!-- more node configuration here -->
</nodeConfig>

In this section, we create a button that uses the "command" attribute to associate it with a JavaScript command and the "after" attribute to specify that this comes after the standard "hyperlinkRoleButton" in the UI. In order for the command to work, you will need to define the command object in JavaScript and have that included in your HTML page so that Xopus can make use of it. See below for the JavaScript.

Next, 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 frist button we created.

The final section has the node configuration for the "editornote" role. Note that in addition to specifying the role, it also includes placeholder text for empty elements.

You can also add a button that creates a drop-down menu. Usually you would do this for a group of similar commands but in this case, we're going to create a drop-down of the same two items above.

<overlay xmlns="http://xopus.com/2009/lui">
  <!-- adding drop down menu button -->
  <dropdown-button 
    after="hyperlinkRoleButton" 
    iconsrc="menubutton.gif"
    id="customMenuButton"
    label="Custom Menu">
    <menu>
      <menu-group>
        <menu-item 
          command="insertFigure" 
          label="Insert Figure" 
          iconsrc="figurbutton.gif"
          id="figureMenuItem" />
        <menu-item
          role="editorNote"
          label="Insert Note"
          iconsrc="notes.gif"
          id="noteMenuItem" />
      </menu-group>
    </menu>
  </dropdown-button>
</overlay>

<!-- the nodeConfig is the same as the version above -->

This segment of configuration XML sets up a drop-down menu with two items in it, both in a single group. If I had wanted each to be in their own group with separators between the, I would have had to close the first menu-group after the first menu-item and then open a second menu-group for the second menu-item.

For the insertFigure command specified in both of the XML sections above, the JavaScript looks like this:

var insertFigure =  { 
  configure: function (scope)
  { },
  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);

The important parts of this object are the "execute" and "getEnabled" functions. "Execute" is the portion that performs the actual function of the button and "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. 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 we go to insert the element.

See the toolbar-button config for more information and examples concerning Toolbar Buttons.

Documentation
› How To
› Add a button to the toolbar in Xopus 4