## Core

### Modal box

When you want create your custom extension for Trumbowyg, you can open and close a modal box with custom inner HTML code, listen events and more.

#### Open and close

For that use the right method: `openModal` or `closeModal` like that:

    // Open a modal box
    var $modal = trumbowyg.openModal({
        title: 'A title for modal box',
        content: '<p>Content in HTML which you want include in created modal box</p>'
    });

    // Close current modal box
    trumbowyg.closeModal();

An `openModal` call returns a jQuery object which contains the modal box. You need this object if you want to use listen events (see below).

Only one modal box can open at any given moment. So, `openModal` return false if a modal is currently opened.

#### Events on modal box

Modal boxes in Trumbowy come with two buttons: "Confirm" and "Cancel". An event is associated to each one:

- `tbwsubmit`: triggered when form is submit
- `tbwreset`: triggered when user cancels operation

    // Open a modal box
    var $modal = trumbowyg.openModal({
        title: 'A title for modal box',
        content: '<p>Content in HTML which you want include in created modal box</p>'
    });

    // Listen clicks on modal box buttons
    $modal.on('tbwconfirm', function(e){
        // Do what you want
        trumbowyg.closeModal();
    });
    $modal.on('tbwcancel', function(e){
        trumbowyg.closeModal();
    });

#### Only build inputs in modal

If you want to only add inputs in the modal box, this function is more simple. Indeed, you do not manage confirm and close buttons, and get all input value on confirm.

    var img = $('img#an-img');
    $modal = trumbowyg.openModalInsert({
        title: 'A title for modal box',
        fields: {
            url: {
                value: img.attr('src')
            },
            alt: {
                label: 'Alt',
                name: 'alt',
                value: img.attr('alt'),
                type: 'text',
                attributes: {}
            },

            // Build your own input by setting type as a function and returning the html
            referrerpolicy: {
                label: 'Referrer Policy',
                name: 'referrerpolicy',
                type: function(field, fieldId, prefix, lg) {
                    var html += '<div class="' + prefix + 'input-row">' +
                        '<div class="' + prefix + 'input-infos">' +
                          '<label for="' + fieldId + '">' +
                            '<span>' + (lg[field.label] ? lg[field.label] : field.label) + '</span>' +
                          '</label>' +
                        '</div>' +
                        '<div class="' + prefix + 'input-html">' +
                            '<select id="' + fieldId + '" name="' + field.name + '">' +
                                '<option' + (field.value === 'no-referrer' ? ' selected="selected"' : '') + '>no-referrer</option>' +
                                '<option' + (field.value === 'no-referrer-when-downgrade' ? ' selected="selected"' : '') + '>no-referrer-when-downgrade</option>' +
                                '<option' + (field.value === 'origin' ? ' selected="selected"' : '') + '>origin</option>' +
                                '<option' + (field.value === 'origin-when-cross-origin' ? ' selected="selected"' : '') + '>origin-when-cross-origin</option>' +
                                '<option' + (field.value === 'unsafe-url' ? ' selected="selected"' : '') + '>unsafe-url</option>' +
                           '</select>' +
                        '</div>' +
                    '</div>';

                    return html;
                }
            },
            example: {
                // Missing label is replaced by the key of this object (here 'example')
                // Missing name is the key
                // When value is missing, value = ''
                // When type is missing, 'text' is assumed. You can use all the input field types,
                //   plus checkbox and radio (select and textarea are not supported)
                // When attributes is missing, {} is used. Attributes are added as attributes to
                //   the input element.
                // For radio and checkbox fields, you will need to use attributes if you want it
                //   to be checked by default.
            }
        },
        // Callback is called when user confirms
        callback: function(values){
            img.attr('src', values['url']);
            img.attr('alt', values['alt']);

            return true; // Return true if you have finished with this modal box
            // If you do not return anything, you must manage the closing of the modal box yourself
        }
    });

    // You can also listen for modal confirm/cancel events to do some custom things
    // Note: the openModalInsert callback is called on tbwconfirm
    $modal.on('tbwconfirm', function(e){
        // Do what you want
    });
    $modal.on('tbwcancel', function(e){
        trumbowyg.closeModal();
    });

### Range

Managing correctly text range, is not so trivial. Trumbowyg has a system to save and restore selection range which does not involve typical getter/setter.

#### Save and get current range

    // Save current range
    trumbowyg.saveRange();

    // Restore last saved range
    trumbowyg.restoreRange();

#### Get selection range

    // range contains a JavaScript range
    var range = trumbowyg.getRange();

#### Get last saved range text (aka selected text)

    var text = trumbowyg.getRangeText();

### Manage content

You can set and get current HTML content of the editor with a getter/setter:

    // Get HTML content
    trumbowyg.html();

    // Set HTML content
    trumbowyg.html('<p>Your content here</p>');

### Empty

You can empty the content of the editor.

    trumbowyg.empty();

### Enable/disable edition

Added in 2.1.0

As you can disable editor by using disabled option, you can also switch between enabled and disabled states by using API.

    trumbowyg.setDisabled(true);
    trumbowyg.setDisabled(false);

### Toggle between HTML & WYSIWYG modes

You can switch between HTML view and WYSIWYG view via toggle method.

    trumbowyg.toggle();