The Toolbar

The toolbar makes DokuWiki easy to use even for novice users. Sometimes you may want to extend the toolbar with another button. This page will tell you a bit how the toolbar works and how to extend it.

The toolbar is completely built through JavaScript. Which buttons the toolbar contains, is read from an array called toolbar. This array is initialized in /lib/exe/js.php when it is called with the mode edit. This is simply done by converting the PHP array structure defined in inc/toolbar.php to JavaScript using JSON.

This means, the toolbar gets cached like any other JavaScript in DokuWiki and will only be loaded when editing pages. When ever you do changes affecting the toolbar you should refresh your browser cache while editing a page¹⁾.

The mentioned toolbar array contains one entry per button. The order of the entries defines the position of the button, with the first entry defining the most left button.

Each entry is an associative array itself, defining the behavior of the button. The following table explains the available fields for the entries.

A look at inc/toolbar.php should give you enough examples of what can be defined. Because the array is simply translated from PHP to JavaScript, the above description applies to the PHP array as well as to the resulting JavaScript array from which the toolbar is finally built.

The toolbar can be customized in two ways - via JavaScript or PHP. Which method you choose basically depends on your skills and familiarity with the language at hand. For the PHP approach you will always need to write a plugin, the JavaScript method can be used from a userscript as well.

To extend the toolbar from your plugin you need to write a Action Plugin which registers as handler for the TOOLBAR_DEFINE event with an AFTER advise. Your handler function will receive the toolbar array as described earlier.

Create your button structure according to the above information and add it to the received event data.-function in inc/toolbar.php.

Example:

function register(&$controller) {
    $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
}
 
// ...
 
/**
 * Inserts a toolbar button
 */
function insert_button(& $event, $param) {
    $event->data[] = array (
        'type' => 'format',
        'title' => $this->getLang('abutton'),
        'icon' => '../../plugins/example/abutton.png',
        'open' => '<abutton>',
        'close' => '</abutton>',
    );
}

Adding a button using JavaScript is similar to doing it in PHP. You just extend the toolbar array.

Because user and plugin scripts will be loaded on all requests, but the toolbar is initialized on editing only, you need to make sure the toolbar array does exist first. Do this by checking if window.toolbar is defined. If it is, you can add your button at the end of the array.

if(window.toolbar!=undefined){
  toolbar[toolbar.length] = {"type":"format",
                             "title":"A Butoon",
                             "icon":"abutton.png",
                             "key":"",
                             "open":"<abutton",
                             "close":"</abutton>"};
}

Here is another example defining a picker dropdown:

if(window.toolbar!=undefined){
  var notes_arr = new Array(); /* array[key]= insertion string , value = icon filename. */
  notes_arr['<note></note>\\n']          ='note.png';
  notes_arr['<note tip></note>\\n']      ='tip.png';
  notes_arr['<note important></note>\\n']='important.png';
  notes_arr['<note warning></note>\\n']  ='warning.png';
 
  toolbar[toolbar.length] = {"type":"picker",
                             "title":"Notes",
                             "icon":"note.png",
                             "key":"",
                             "list": notes_arr,
                             "icobase":"notes"}; /* subdir of lib/images/ where images found.*/
}

The above methods work well for adding static buttons that add static data. When you need to do something more dynamic like adding the current date, you can not simply extend the toolbar array. Instead you need to dynamically add your button into the DOM using JavaScript.

lib/scripts/edit.js contains some useful functions to help you with this.

Here's an example by Joseph Nahmias to create a button for inserting the current date:

// Add a toolbar button to insert the current date in '17 Nov 2006' format
function my_get_current_date()
{
  var d = new Date();
  var mons = [
    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
  ];
 
  return d.getDate() + ' ' + mons[d.getMonth()] + ' ' + d.getFullYear();
}
function installDateButton()
{
  var toolbar = document.getElementById('tool__bar');
  if (!toolbar) return;
 
  var btn = createToolButton('calendar.png', 'Insert Date');
  btn.onclick = function() {
    insertAtCarret('wiki__text', my_get_current_date());
    return false;
  };
 
  toolbar.appendChild(btn);
}
addInitEvent(installDateButton);

• If you don't want to append your button at the end of the toolbar, you just need to insert your data into the toolbar array at the position where you want your button, shifting the other buttons to the right.
• The current page ID is in a hidden field of the edit form which you can access from your JavaScript, this might be handy when doing some more dynamic stuff.