Customizing the Ephox editor's toolbar

Customize the Ephox editor's toolbar for use in IBM Connections™.

About this task

The toolbar is defined in the editor's config.js file. The following code snippet shows default toolbar definition:

toolbar: [
  'undo',
  {
    label: 'group.insert',
    items: [
      {
        id: 'insert',
        label: 'menu.insert',
        items: [
          [
            'link',
            'conn-insert',
            'bookmark',
            'media',
            'table'
          ],
          [
            'specialchar',
            'hr'
          ]
        ]
      }
    ]
  },
  'style',
  'emphasis',
  'align',
  'listindent',
  'format',
  [
    'conn-other',
    'conn-emoticons',
    'conn-macros'
  ],
  'language',
  'tools'
]
At run time, the following placeholders are merged with information from the CK configuration to provide items on the toolbar:
  • conn-emoticons - Emoticons dialog button
  • conn-insert - Insert commands that depend on the application
  • conn-macros - Macros menu (only in Wikis)
  • conn-insert - Insert commands that depend on the application
  • conn-other - Other IBM Connections™ commands
You can add your own items to the toolbar by inserting the corresponding code within the items[ ] array; for example:
{
  id: 'hello',
  text: 'Insert greeting',
  icon: '/path/to/icon1.png',
  action: function() {
    textboxio.getActiveEditor().content.insertHtmlAtCursor('Hello');
  }
},

If you don't have an icon available, you can un-comment the reference to the wizard wand icon and use that.

You can also make more sophisticated changes with the Selection API.

The items listed in the toobar array will be displayed from left to right on the Ephox Editors toolbar. All the items at the top level are groups which allows the editor to resolve the ambiguity of group IDs and command IDs with the same value.

The toolbar has three concepts:
  • Groups - One or more toolbar items that are displayed together and visually separated from other things. When using keyboard navigation tabbing jumps between groups and the arrow keys move between the group items.
  • Commands - A button or menu item that does some action when clicked.
  • Placeholders - A placeholder that expands to IBM Connections specific commands at run-time in a context sensitive way. This extension was added by the integration and is not in the base Ephox Editor.

Procedure

  1. Groups can be specified in three ways:
    • Built-in [group identifiers](https://docs.ephox.com/display/tbio/Command+Item+IDs#CommandItemIDs-GroupIDs) undo
    • Labeled group 
      { label: 'group.undo', items: ['undo', 'redo'] }
      Note: uses the built-in [translation key](https://docs.ephox.com/display/tbio Command+Item+IDs#CommandItemIDs-Grouplabels) 'group.undo'.
    • Custom Menu 
      { id: 'relPosMenu', label: 'Relative text position', icon: '/path/to/icon/relPosMenu.png', items: ['superscript', 
'subscript'] }
      Note: label is optional but it is helpful for users of screen-readers.
    The menu items array may contain commands or unlabeled groups containing commands.
  2. Commands can be specified in two ways:
    • Built-in [command identifiers](https://docs.ephox.com/display/tbio/Command+Item+IDs#CommandItemIDs-CommandIDsCommandIDs) 'undo'
    • Custom commands 
      { id: 'hello', text: 'Insert greeting', icon: '/path/to/icon/hello.png', action: function() 
{ textboxio.getActiveEditor().content.insertHtmlAtCursor('Hello'); } }
      Note: 'text' is optional but is used for tooltips and screen-readers.
  3. These placeholders expand to a list of commands.
    • 'conn-emoticons' emoticons dialog command.
    • 'conn-insert' insert commands that depend on the application.
    • 'conn-macros' macros menu.
    • 'conn-other' other IBM Connections commands.
  4. Customize the toolbar by modifying the config.js file as explained in Customizing the Ephox Editors.