## Existing plugins

If you want to add a plugin, be sure to read the use plugins section of documentation before continue.

### Allow tags from paste

Stable

Need documentation

Need demo

Allow tags from paste plugin allows you to filter tags allowed when an user paste some code into the editor.

View allowTagsFromPaste plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Base 64

Stable

Base 64 plugin allows you to insert images inline as base64.

Try base64 live demo! View base64 plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/base64/trumbowyg.base64.min.js"></script>

Then you can use the new button definition `base64`

    $('#my-editor').trumbowyg({
        btns: [
            ['base64']
        ]
    });

### Clean paste

Stable

Need demo

Clean paste plugin handle paste events, clean the HTML code before insert content into the editor.

View cleanpaste plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/cleanpaste/trumbowyg.cleanpaste.min.js"></script>

Clean paste works now on every new Trumbowyg instance.

### Colors

Stable

Colors plugin allows you to change foreground and background color of your text.

Try colors live demo! View colors plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg colors style in <head>... -->
    <script src="node_modules/trumbowyg/dist/plugins/colors/ui/trumbowyg.colors.css"></script>

    <-- Import Trumbowyg colors JS at the end of <body>... -->
    <script src="node_modules/trumbowyg/dist/plugins/colors/trumbowyg.colors.min.js"></script>

Then you can use the new button definitions `foreColor` and `backColor`

    $('#my-editor').trumbowyg({
        btns: [
            ['foreColor', 'backColor']
        ]
    });

Some doc to write about color options...
You can contribute to this documentation by submitting a Pull Request :)

### Emoji

Stable

Emoji plugin allows you to insert some emojis in your editor.

Try emoji live demo! View emoji plugin code on GitHub

#### How to use it?

This plugin require emojify.js which can be installed with: `npm install emojify.js`

    <-- Import emojify.js and Trumbowyg emoji at the end of <body>... -->
    <script src="node_modules/emojify.js/dist/js/emojify.min.js"></script>
    <script src="node_modules/trumbowyg/dist/plugins/emoji/trumbowyg.emoji.min.js"></script>

You should setup emojify.js, then you can use the new button definition `emoji`

    // Setup emojify.js
    emojify.setConfig({
        img_dir : '//cdnjs.cloudflare.com/ajax/libs/emojify.js/1.1.0/images/basic/',
    });

    $('#my-editor').trumbowyg({
        btns: [
            ['emoji']
        ]
    });
    emojify.run();

    // Will transform an :emoji: to img tag at each input
    $('.trumbowyg-editor').on('input propertychange', function() {
        emojify.run();
    });

### Font family

Stable

Need documentation

Need demo

This plugin allows user to custom font family.

View font family plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Font size

Stable

Need documentation

Need demo

This plugin allows user to custom font size.

View font size plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Code Highlight

Stable

This plugin allows user to add code highlight parts.

Try highlight plugin live demo! View highlight plugin code on GitHub

#### How to use it?

This plugin require prismjs which can be installed with: `npm install prismjs`

    <-- Import prismjs style in <head>... -->
    <link rel="stylesheet" href="node_modules/prismjs/themes/prism.css">
    <-- Import highlight plugin style in <head>... -->
    <link rel="stylesheet" href="node_modules/trumbowyg/dist/plugins/highlight/ui/trumbowyg.highlight.css">
    <-- Import prismjs and Trumbowyg highlight at the end of <body>... -->
    <script src="node_modules/prismjs/prism.js"></script>
    <script src="node_modules/trumbowyg/dist/plugins/highlight/trumbowyg.highlight.min.js"></script>

You also can add another prism language syntaxes for example:

    <-- Import prismjs and Trumbowyg highlight at the end of <body>... -->
    <script src="node_modules/prismjs/prism.js"></script>
    <script src="node_modules/prismjs/components/prism-csharp.js"></script>
    <script src="node_modules/prismjs/components/prism-go.js"></script>
    <script src="node_modules/prismjs/components/prism-markdown.js"></script>
    <script src="node_modules/trumbowyg/dist/plugins/highlight/trumbowyg.highlight.min.js"></script>

Also on your website you must connect prismjs styles to lighting code worked. For example connect prism.css in head:

    <-- Import prismjs style in <head>... on your site -->
    <link rel="stylesheet" href="node_modules/prismjs/themes/prism.css">

### History

Stable

History plugin is an enhanced implementation of the undo and redo functionality. It tracks changes of the editor and will add each change to a history stack. If a word is typed in or text was pasted, it counts as a single stack entry.

Try history plugin live demo! View history plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg history style in <head>... -->
    <script src="node_modules/trumbowyg/dist/plugins/history/ui/trumbowyg.history.css"></script>

    <-- Import Trumbowyg history JS at the end of <body>... -->
    <script src="node_modules/trumbowyg/dist/plugins/history/trumbowyg.history.min.js"></script>

Then you can use the new button definitions `historyUndo` and `historyRedo`

    $('#my-editor').trumbowyg({
        btns: [
            ['historyUndo', 'historyRedo']
        ]
    });

### Insert audio

Stable

Do the same as insert image, but for audio.

Try insert audio live demo! View insertaudio plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/insertaudio/trumbowyg.insertaudio.min.js"></script>

Then you can use the new button definition `insertaudio`

    $('#my-editor').trumbowyg({
        btns: [
            ['insertaudio']
        ]
    });

### Line height

Stable

Need documentation

Need demo

This plugin allows user to custom line height.

View line height plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### MathML

Stable

Need documentation

Need demo

This plugin allows user to use MathML.

View MathML plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Mention

Stable

Need documentation

Need demo

This plugin allows user to mention an user with AJAX autocomplete.

View mention plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Noembed

Stable

Allows you to embed any content from a link using noembed.com API.

Try noembed live demo! View noembed plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/noembed/trumbowyg.noembed.min.js"></script>

Then you can use the new button definition `noembed`

    $('#my-editor').trumbowyg({
        btns: [
            ['noembed']
        ]
    });

### Paste embed

Stable

Paste embed plugin handles paste events. It looks for paste event, checks if it's a url and uses noembed and MAXmade APIs to retrieve an iframe from that url. If it can't retrieve an iframe, it will put an anchor tag around the url. It doesn't do anything on text or HTML paste.

Try pasteembed live demo! View pasteembed plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/pasteembed/trumbowyg.pasteembed.min.js"></script>

Paste embed now works on every new Trumbowyg instance.

### Paste image

Stable

Need demo

Paste image plugin handle paste events, check if you have image files in your clipboard, then paste them into the editor as base64. It do nothing on text or HTML paste.

View pasteimage plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/pasteimage/trumbowyg.pasteimage.min.js"></script>

Paste image works now on every new Trumbowyg instance.

### Preformatted

Stable

Need demo

Wrap your code with `<pre>` tags.

View preformatted plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/preformatted/trumbowyg.preformatted.min.js"></script>

Then you can use the new button definition `preformatted`

    $('#my-editor').trumbowyg({
        btns: [
            ['preformatted']
        ]
    });

### Resizimg

Stable

Allows you to resize images (preserving aspect ratio) by dragging their bottom-right corner. Available options:

- `minSize` (default: 32): minimal size of image and also of draggable right-bottom corner
- `step` (default: 4): increment when increasing / decreasing image height

#### Dependencies

This plugin depends on the jquery-resizable plugin, which must be loaded beforehand.

#### Notes and caveats

The resulting image size is currently absolute: CSS height in pixels (`style` attribute). A possible enhancement would be to support relative sizes as well, typically as percentage height of the container.

Try resizimg live demo! View resizimg plugin code on GitHub

### Ruby

Stable

Need demo

Allows you to support ruby markup.

Try ruby live demo! View ruby plugin code on GitHub

Some doc to write...
You can contribute to this documentation by submitting a Pull Request :)

### Table

stable

Table plugin allows users to create and manage tables.

View table plugin code on GitHub

Check bugs on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/table/trumbowyg.table.min.js"></script>

Then you can use the new button definition `table`

    $('#my-editor').trumbowyg({
        btns: [
            ['table']
        ],
        plugins: {
            table: {
                // Some table plugin options, see details below
            }
        }
    });

#### Parameters

`rows` `integer`
  The count of rows which should be used for table building in the table grid dropdown.
  Default: `8`
`columns` `integer`
  The count of columns which should be used for table building in the table grid dropdown.
  Default: `8`
`styler` `string`
  The class which should be assigned to each table by default
  Default: `'table'`

The table plugin provides a button with two different dropdowns depending on current selection.
If the current cursor is not placed within a table, the dopdown renders a table grid where you can
build the table. Otherwise the dropdown will render a few options for the current table like

- Add row to table
- Add column to table
- Delete row from table
- Delete column from table
- Delete table

### Template

Stable

Need documentation

Manage a set of HTML templates to insert fast.

Try template live demo! View template plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/template/trumbowyg.template.min.js"></script>

Then you can use the new button definition `template` and can add your template code.

    $('#my-editor').trumbowyg({
        btns: [
            ['template']
        ],
        plugins: {
            templates: [
                {
                    name: 'Template 1',
                    html: 'I am a template!'
                },
                {
                    name: 'Template 2',
                    html: 'I am a different template!'
                }
            ]
        }
    });

### Upload

Stable

Need documentation

Add an upload front-end allowing users to select an image, upload it with progress bar and then insert the uploaded image in the editor.

Try upload live demo! View upload plugin code on GitHub

#### How to use it?

    <-- Import Trumbowyg plugins... -->
    <script src="node_modules/trumbowyg/dist/plugins/upload/trumbowyg.upload.min.js"></script>

Then you can use the new button definition `upload`

    $('#my-editor').trumbowyg({
        btns: [
            ['upload']
        ],
        plugins: {
            upload: {
                // Some upload plugin options, see details below
            }
        }
    });

#### Parameters

`serverPath` `string`
  The URL to the server which catch the upload request
  Default: `''`
`fileFieldName` `string`
  The POST property key associated to the upload file
  Default: `'fileToUpload'`
`data` `array<Object>`
  Additional data for ajax. jQuery.ajax data option Example: `[{name: 'myKey1', value: 'myValue1'}, {name: 'username', value: 'myUsername'}]`
  Default: `[]`
`headers` `Object`
  Additional headers. Check jQuery.ajax headers option Example: `{headerKey: 'headerValue', Authorization: 'Client-ID xxxxxxxxx'}`
  Default: `{}`
`xhrFields` `Object`
  Additional xhrFields. Check jQuery.ajax xhrFields option
  Default: `{}`
`urlPropertyName` `string`
  How to get image URL in the JSON response. Example: `'url'` for `{url: 'https://example.com/myimage.jpg', success: true}`
  Default: `'file'`
`statusPropertyName` `string`
  How to get status from the json response. Example: `'success'` for `{success: true, url: 'https://example.com/myimage.jpg'}`
  Default: `'success'`
`success` `function`
  Success callback: `function (data, trumbowyg, $modal, values) {}`
  Default: `null`
`error` `function`
  Error callback: `function () {}`
  Default: `null`
`imageWidthModalEdit` `boolean`
  Add a field allowing user to set image width
  Default: `false`

#### Server side

Server side receives a POST request with the image in the `fileFieldName` field and `alt` which contains image description:

    alt: 'Image description'
    fileToUpload: // The image file

It must save this image, then return a JSON response like that:

    {
        success: true, // Must be false if upload fails
        url: 'https://example.com/myimage.jpg'
    }

## Create your own

### Introduction

A plugin can be a button, a paste handler or what you want. If you want add a plugin myplugin to official Trumbowyg list, your should follow this tree:

    plugins
     └── myplugin
         ├── ui
         │   ├── icons
         │   │   └── myplugin.svg
         │   └── sass
         │       └── trumbowyg.myplugin.scss
         └── trumbowyg.myplugin.js

As plugin can be something else than a button, icons and scss are optionnal depending on your feature.

In a plugin, you get access to all Trumbowyg core and you can extends all things as you wish.

### Skeleton

To create a new plugin, you should start you `trumbowyg.myplugin.js` with this code:

    (function ($) {
        'use strict';

        // My plugin default options
        var defaultOptions = {
        };

        // If my plugin is a button
        function buildButtonDef(trumbowyg) {
            return {
                fn: function() {
                    // My plugin button logic
                }
            }
        }

        $.extend(true, $.trumbowyg, {
            // Add some translations
            langs: {
                en: {
                    myplugin: 'My plugin'
                }
            },
            // Add our plugin to Trumbowyg registred plugins
            plugins: {
                myplugin: {
                    init: function(trumbowyg) {
                        // Fill current Trumbowyg instance with my plugin default options
                        trumbowyg.o.plugins.myplugin = $.extend(true, {},
                            defaultOptions,
                            trumbowyg.o.plugins.myplugin || {}
                        );

                        // If my plugin is a paste handler, register it
                        trumbowyg.pasteHandlers.push(function(pasteEvent) {
                            // My plugin paste logic
                        });

                        // If my plugin is a button
                        trumbowyg.addBtnDef('myplugin', buildButtonDef(trumbowyg));
                    },
                    tagHandler: function(element, trumbowyg) {
                        return [];
                    },
                    destroy: function() {
                    }
                }
            }
        })
    })(jQuery);

### Interact with content

To interact with editor and its content, you should use Trumbowyg core API. You can also check existing plugins source code to see how it works!

Go to the core API documentation