General

Prefix

You can change prefix of all class added on elements of Trumbowyg using this option:


$('textarea').trumbowyg({
    prefix: 'custom-prefix'
});
            

For example, the bold button class is now custom-prefix-bold-button

Default value is trumbowyg

Localization

Your users don't speak english? No problem, Trumbowyg has a language parameter. You have to load the appropriate lang file. Search in /dist/langs folder to see if a language file already exists, if not create it and share it :). See add a localization for more details on language file.

Don't forget include the lang file in your pages:


<script type="text/javascript" src="js/dist/langs/fr.min.js"></script>
            

Warning, include lang file after Trumbowyg and before instantiating the editor!

Usage of language parameter:


$('textarea').trumbowyg({
    lang: 'fr'
});
            

If the lang was not found, english values are used by default.

Custom skin

Trumbowyg is flexible and simple. You want a different look?

Replace existing CSS file

Copy /src/ui/ folder somewhere and customize style. Finally, link your new CSS file and remove link to Trumbowyg default style.

It is not recommended to directly edit the CSS file in the trumbowyg folder. When you update the plugin, your modifications will be erased.


Multiple skins for multiple Trumbowyg

This is useful when you do not want same design for all instances of Trumbowyg.

Use the prefix option:


$('.editor-modern-ui').trumbowyg({
    prefix: 'modern-ui'
});
            

In your CSS, you can now stylize .modern-ui-link-button for example, whitout conflicts with the default skin. It's necessary to redefine style for all elements. If you want to start from the default skin, copy /src/ui/ folder, replace all trumbowyg- by your prefix and work from here.

SVG icons

Added in 2.1.0

A pack of SVG icons is available and enabled by default. This file is loaded via XHR request in JavaScript so it is possible the path is not matching with your assets file paths. You can change the path of the SVG or disable this feature.

Change SVG path globally

To change SVG path, you need to set the path in global Trumbowyg configuration object:


$.trumbowyg.svgPath = '/assets/my-custom-path/icons.svg';
            

This global way needs to be done before initialize any Trumbowyg instance.

Disable SVG icons globally

If you do not want SVG icons, you can set this option to false. Then, you can add your custom icons by CSS or what you want.


$.trumbowyg.svgPath = false:
            

This global way needs to be done before initialize any Trumbowyg instance.

Change SVG path or disable SVG icons locally

You can also apply svgPath option for an isolated editor only.


$('.editor').trumbowyg({
    svgPath: false // or a path like '/assets/my-custom-path/icons.svg'
});
            

Use SVG icons without XHR or via an another protocol that HTTP(S)

If you do not want use HTTP(S) protocol or use XHR to load icons, you can load icons in your HTML by your own. You just need to include the icons.svg file inline in your <body>:


<div id="trumbowyg-icons">
    <svg xmlns="http://www.w3.org/2000/svg">
        <symbol id="trumbowyg-blockquote" viewBox="0 0 72 72"><path d="..."></path></symbol>
        <symbol id="trumbowyg-bold" viewBox="0 0 72 72"><path d="..."></path></symbol>
        <symbol id="trumbowyg-close" viewBox="0 0 72 72"><path d="..."></path></symbol>
        <!-- ... all other icons here -->
    </svg>
</div>
            

You need to use this id: <prefix>-icons.

Trumbowyg check if a #<prefix>-icons exists. If not, it loads SVG icons file via XHR and put it in a div with this id. Next editor on the page did not load icons again. By adding this div in the page, you "hack" this mecanism to load it by your own.

Placeholder

Added in 1.1.3

Like the HTML5 attribute on input and textarea, you can add a placeholder with Trumbowyg.


<div class="my-editor" placeholder="Your text as placeholder"></div>
            

Placeholder is visible only if the element is empty (no HTML/text).

Placeholder is both managed in JS and CSS with the default style. If you create your own style, you need to apply the following style (replace trumbowyg by your prefix):


.trumbowyg-editor[contenteditable=true]:empty::before{
    content: attr(placeholder);
    color: #999;
}
                

Disabled

Added in 2.1.0

Trumbowyg supports disabled attribute on a textarea and an option.


<textarea class="my-editor" disabled></textarea>
            

$('.a-disabled-editor').trumbowyg({
    disabled: true
});
            

You can switch between disabled and enabled states by using API

Direction

Removed since 2.0.0

Since 2.0.0, prefer use the _dir variable in the language file

If your language needs to be read from left to right, use the dir option:


$('textarea').trumbowyg({
    dir: 'rtl'
});
            

If the localization file used define a direction, you cannot override it.

Animation duration

Removed since 2.0.0

Since 2.0.0, this parameter is not customisable without rebuild Trumbowyg from source.

Lot of elements have animations, their duration is configurable via the duration option:


$('textarea').trumbowyg({
    duration: 1000
});
                

duration is defined in milliseconds, because this value is directly used in .animate() jQuery method.

Basic Options

Button pane

It's probably the most interesting option, it allows you to choose the buttons that appears in the button pane. This option is an array containing string values representing the buttons or vertical separators (using the pipe character). To create your own custom button pane, define an array and pass it to the btns option.


$('.simple-editor').trumbowyg({
    btns: [['bold', 'italic'], ['link']]
});
            

By default, btns option value is:


$('.simple-editor').trumbowyg({
    btns: [
        ['viewHTML'],
        ['formatting'],
        'btnGrp-semantic',
        ['superscript', 'subscript'],
        ['link'],
        ['insertImage'],
        'btnGrp-justify',
        'btnGrp-lists',
        ['horizontalRule'],
        ['removeformat'],
        ['fullscreen']
    ]
});

/** WTF are btnGrp-* buttons? There are just arrays of strings :)
*  jQuery.trumbowyg.btnsGrps = {
*      design:   ['bold', 'italic', 'underline', 'strikethrough'],
*      semantic: ['strong', 'em'],
*      justify:  ['justifyLeft', 'justifyCenter', 'justifyRight', 'justifyFull'],
*      lists:    ['unorderedList', 'orderedList']
*  };
*/
                
btnsAdd option does not exist since 2.0.0

If you want keep the default button pane but just add some buttons at the end, you can use the btnsAdd option. It could be usefull to add plugin buttons like colors or preformatted at the end of your button pane.


$('.editor-with-colors-plugin').trumbowyg({
    btnsAdd: ['|', 'foreColor', 'backColor']
});
                

Semantic

Generates a better, more semantic oriented HTML (i.e. <em> instead of <i>, <strong> intsead of <b>, etc.). It's just a boolean:


$('.trumbowyg').trumbowyg({
    semantic: false
});
            

This option deactivates the underline button by default because they do not convey any real semantic. If you want to reactivate them, you have to do it explicitly, see Button pane

This option is set to true by default since 2.0.0

This option was set to false by default in 1.0.0

Reset CSS

If you don't want the page style to impact on the look of the text in the editor, you will need to apply a reset-css on the editor. You can activate this with the resetCss option:


$('.trumbowyg').trumbowyg({
    resetCss: true
});
            

This option is set to false by default. The reset only applies to the editor, not to the generated HTML code.

Remove format pasted

Added in 2.0.0

If you don't want styles pasted from clipboard (from Word or other webpage for example), pass the removeformatPasted option to true


$('.trumbowyg').trumbowyg({
    removeformatPasted: true
});
            

Remove format pasted is not active by default (set to false).

Auto grow

The text editing zone can extend itself when writing a long text. To activate this feature, use the autogrow option:


$('.trumbowyg').trumbowyg({
    autogrow: true
});
            

Autogrow is not active by default (set to false).

Close button

Removed since 2.0.0

Since 2.0.0, 'close' is a button like others. You can add/remove it from button pane configuration

To have a close button in the top left corner, set closable to true.


$('.trumbowyg.closable').trumbowyg({
    closable: true
});
            

By default, a Trumbowyg editor is not closable.

Fullscreen

Removed since 2.0.0

Since 2.0.0, 'fullscreen' is a button like others. You can add/remove it from button pane configuration

To disable the fullscreen button:


$('.trumbowyg.closable').trumbowyg({
    fullscreenable: false
});
            

This code desactives the possibility for user to edit content in fullscreen. Note that fullscreen mode is not really fullscreen (like with a press on F11), it just expands the editor to the whole current page.

Fullscreen default value is to true

Mobile & Tablet

Removed since 2.0.0

Since 2.0.0, prefer use an external library for that like enquire.js

Trumbowyg is compatible with mobiles devices, but you can deactive support for mobile and tablet with the following:


$('.trumbowyg.allow-mobile').trumbowyg({
    mobile: true,
    tablet: true
});
            

If you set false, Trumbowyg transforms the targeted element as a textarea.

Defaults values are mobile to false and tablet to true

Advanced Options

Add a localization

The structure of a language file is simple, it is a JavaScript Object which associate a translation to any key. For example:


jQuery.trumbowyg.langs.fr = {
    _dir: "ltr", // This line is optionnal, but usefull to override the `dir` option

    bold: "Gras",
    close: "Fermer"
};
            

Some localizations are added each day, you can find them here

You can submit a new localization file by creating a new pull request on the Github repository.

English is the default localization, you don't need to include any file to get Trumbowyg in English.

API

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 .trumbowyg() method and give parameters "openModal" or "closeModal" like that:


// Open a modal box
var $modal = $("#editor").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
$("#editor").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 curently opened.

Events on modal box

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

  • tbwsubmit: Trigged when form is submit
  • tbwreset: Trigged when user cancel operation

// Open a modal box
var $modal = $("#editor").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('trumbowyg-confirm', function(e){
    // Save datas
    $("#editor").trumbowyg("closeModal");
});
$modal.on('trumbowyg-cancel', function(e){
    $("#editor").trumbowyg("closeModal");
});
            

Only build inputs in modal

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


var img = $('img#an-img');
$("#editor").trumbowyg("openModalInsert", {
    title: "A title for modal box",
    fields: {
        url: {
            value: img.attr('src')
        },
        alt: {
            label: 'Alt',
            name: 'alt',
            value: img.attr('alt')
        },
        example: {
            // Missing label is replaced by the key of this object (here 'example')
            // Missing name is the same
            // When value is missing, value = ''
        }
    },
    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 need manage yourself the closure of the modal box
    }
});
            

Range

Added in 2.0.0

Range is the new selection for v2.

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

Save and get current range


// Save current range
$('#editor').trumbowyg('saveRange');

// Restore last saved range
$('#editor').trumbowyg('restoreRange');
            

Get selection range


// range contains a JavaScript range
var range = $('#editor').trumbowyg('getRange');
            

Get last saved range text


var text = $('#editor').trumbowyg('getRangeText');
            

Manage content

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


// Get HTML content
$('#editor').trumbowyg('html');

// Set HTML content
$('#editor').trumbowyg('html', "<p>Your content here</p>");
            

Empty

You can empty the content of the editor.


$('#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.


$('#editor').trumbowyg('disable');
$('#editor').trumbowyg('enable');
            

Destroy editor

When you wish, you can restore the previous state of the element was used to create the editor.


$('#editor').trumbowyg('destroy');
            

Events

Added in 1.1.0 & 2.0.0

Some events are fired on the jQuery element which is used to build the editor.

  • Focus on editor: tbwfocus
  • Blur on editor: tbwblur
  • Editor is initialized: tbwinit 2.0.0
  • Change in editor: tbwchange 2.0.0
  • Resize the editor on autogrow: tbwresize 2.0.0
  • Paste something in the editor: tbwpaste 2.0.0
  • Switch to fullscreen mode: tbwopenfullscreen 2.0.0
  • Leave editor's fullscreen mode: tbwclosefullscreen 2.0.0
  • Close the editor: tbwclose 2.0.0

$('#editor')
.trumbowyg() // Build Trumbowyg on the #editor element
.on('tbwfocus', function(){ console.log('Focus!'); }); // Listen for `tbwfocus` event
.on('tbwblur', function(){ console.log('Blur!'); }); // Listen for `tbwblur` event
            

Selection

Removed since 2.0.0

Since 2.0.0, use Range

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

Save and get current selection


// Save current selection
$('#editor').trumbowyg('saveSelection');

// Restore last saved selection
$('#editor').trumbowyg('restoreSelection');
            

Get selection range


// sel contains a JavaScript range
var sel = $('#editor').trumbowyg('getSelection');
            

Get selection value


var text = $('#editor').trumbowyg('getSelectedText');