RealObjects Nimbudocs Editor 3.0.3929_Beta1

Guide: Event Handling


Introduction

Nimbudocs Editor features a rich event handling API which can be used to execute custom code after one of the various supported events has been fired.

Event handlers are registered by using the API method addEventListener. The first parameter specifies the target to which the handler is registered and the second parameter defines the event type. A custom event handler can then be passed as the third parameter.

Supported Events

Document Events

Document events are fired when the user interacts with HTML elements in the document in certain ways. The supported events mimic the functionality of JavaScript and jQuery mouse events.

Please note that some events like "mouseover" may be fired very frequently. Therefore adding an excess amount of listeners to these events or executing complex code during these events may negatively impact performance.

Supported document events:

A simple event handler

editor.addEventListener("p", "mousedown", function(e) {
    console.log("This is a paragraph");
});

Show tooltips for images

// add a tooltip container to the web page
jQuery("body").append("<div id='tooltip'></div>");

// show the tooltip
editor.addEventListener("img[alt]", "mouseenter", function(e) {
    jQuery("#tooltip")
        .text(e.target.attributes.alt) // set the text content of the tooltip from the 'alt' attribute of the element
        .css({ left: e.target.offsetLeft + e.target.width, // set the position of the tooltip, relative to the element
                top: e.target.offsetTop })
        .show(); // make the tooltip visible
});

// hide the tooltip
editor.addEventListener("img[alt]", "mouseleave", function(e) {
    jQuery("#tooltip").hide();
});

Action Events

There is only one supported event which is fired when an action is invoked.

Supported action events:

An action event handler

editor.addEventListener("bold", "actioninvoke", function(e) {
    console.log("boldifying...");
});

Spell Check Events

The only supported event "dictionaryChange" is fired when one of the dictionaries was changed, e.g. when a new word was added.

Supported spell check events:

An action event handler

editor.addEventListener("document", "dictionaryChange", function(e) {
    var newDictionary = e.dictionary;
    var promise;
    
    if (newDictionary === undefined) {
        promise = editor.spellChecker.fetchDictionary(e.persistanceLevel).then(function(dictionary) {
            newDictionary = e.dictionary;
        });
    }
    
    NimbudocsEditor.when(promise).then(function() {
        console.log(newDictionary);
    });
});

The Event Object

An event object is passed to each listener which contains useful information about the event. This object is an instance of Event. Some of its properties are present for all event types, e.g. type which contains the event type. Other properties are exclusive to specific event types or have different data types depending on the event type.

Please see the API documentation for more information about the properties and methods.