#### Limitless - Editors

##### Ace code editor

Editors /editors/ace/

###### Overview

Ace is an embeddable code editor written in JavaScript. It matches the features and performance of native editors such as Sublime, Vim and TextMate. It can be easily embedded in any web page and JavaScript application. Ace is maintained as the primary editor for Cloud9 IDE and is the successor of the Mozilla Skywriter (Bespin) project. Main features:

- Syntax highlighting for over 110 languages (TextMate/Sublime Text.tmlanguage files can be imported)
- Over 20 themes (TextMate/Sublime Text .tmtheme files can be imported)
- Automatic indent and outdent
- An optional command line
- Handles huge documents (four million lines seems to be the limit!)
- Fully customizable key bindings including vim and Emacs modes
- Search and replace with regular expressions
- Highlight matching parentheses
- Toggle between soft tabs and real tabs
- Displays hidden characters
- Drag and drop text using the mouse
- Line wrapping
- Code folding
- Multiple cursors and selections
- Live syntax checker (currently JavaScript/CoffeeScript/CSS/XQuery)
- Cut, copy, and paste functionality

###### Usage

Ace can be easily embedded into any existing web page. You can either use one of pre-packaged versions of ace (just copy one of `src*` subdirectories somewhere into your project), or use requireJS to load contents of lib/ace as ace. By default the editor only supports plain text mode; many other languages are available as separate modules.

Basic markup is:

    <!-- Basic markup-->
    <div id="html_editor">

    	<!-- Default card -->
    	<div class="card">
    		<div class="card-header header-elements-md-inline">
    			<h5 class="card-title">
    				Card title
    				<span class="font-weight-semibold">Default</span>
    				<small>Full featured toolbar</small>
    			</h5>
    		</div>

    		<div class="card-body">
    			Card body
    		</div>
    	</div>
    	<!-- /default card -->

    </div>

Initialize via JavaScript:

    // HTML editor
    var html_editor = ace.edit("html_editor");
        html_editor.setTheme("ace/theme/monokai");
        html_editor.getSession().setMode("ace/mode/html");
        html_editor.setShowPrintMargin(false);

###### Plugin info

Property | Description
--- | ---
File name | ace.js, [modes, extensions, themes]
Location | global_assets/js/plugins/editors/ace/
Links | Official plugin website Google Group Github project page

##### Summernote editor

Editors summernote.min.js

###### Overview

Summernote is a JavaScript library that helps you create WYSIWYG editors online. The editor uses open source libraries - jQuery and Bootstrap. Font Awesome was required as well, but i've replaced it with Icomoon icon set. Summernote editor supports keyboard shortcuts, full list you can find in demos by clicking "Help" toolbar button. Summernote has a few special features:

- Paste images from clipboard
- Saves images directly in the content of the field using base64 encoding, so you don't need to implement image handling at all
- Simple UI
- Interactive WYSIWYG editing
- Handy integration with server

###### Usage

Usage is pretty simple. First include main JS file and Uniform plugin. Uniform is needed to style checkboxes and file inputs inside modal dialogs:

    <!-- JS file path -->
    <script src="../../../../global_assets/js/plugins/editors/summernote/summernote.min.js"></script>

    <!-- Uniform plugin file path -->
    <script src="../../../../global_assets/js/plugins/forms/styling/uniform.min.js"></script>

Then place a `div` tag somewhere in the `body` tag. This element will be replaced with the summernote editor:

    <!-- Target element -->
    <div id="summernote">Hello Summernote</div>

Finally, run this script after the DOM is ready:

    // Initialize plugin
    $(document).ready(function() {
    	$('#summernote').summernote();
    });

###### Custom toolbar

Summernote allows you to make own custom toolbar. To create one, use `toolbar` option:

    // Font style only toolbar
    $('.summernote').summernote({
      toolbar: [
        //[groupname, [button list]]

        ['style', ['bold', 'italic', 'underline', 'clear']],
        ['font', ['strikethrough', 'superscript', 'subscript']],
        ['fontsize', ['fontsize']],
        ['color', ['color']],
        ['para', ['ul', 'ol', 'paragraph']],
        ['height', ['height']],
      ]
    });

You can compose a toolbar with pre-shipped buttons:

Category | Button id | Function
--- | --- | ---
Insert | `picture` | Insert a picture
`link` | Insert a hyperlink
`video` | Insert a video
`table` | Insert a table
`hr` | Insert a horizontal rule
Style | `style` | Format selected block
`fontname` | Set font family
`fontsize` | Set font size
`color` | Set foreground and background color
`bold` | Toggle weight
`italic` | Toggle italic
`underline` | Toggle underline
`strikethrough` | Toggle strikethrough
`clear` | Clearing all styles
Layout | `ul` | Make an un-ordered list
`ol` | Make an ordered list
`paragraph` | Set text alignment
`height` | Set height of text
Misc | `fullscreen` | Toggle fullscreen editing mode
`codeview` | Toggle wysiwyg and html editing mode
`undo` | Undo
`redo` | Redo
`help` | Show help dialog

###### API reference

Usage is pretty simple. First include main JS file and Uniform plugin. Uniform is needed to style checkboxes and file inputs inside modal dialogs:

`code` - get the HTML source code underlying the text in the editor:

    // Summernote API
    var sHTML = $('#summernote').code();

`Destroy` Summernote:

    // Destroy editor
    $('#summernote').destroy();

Note: Full Summernote API can be found on official API documentation pages.

###### Plugin info

Property | Description
--- | ---
File name | summernote.min.js
Location | global_assets/js/plugins/editors/summernote/
Links | Official plugin website Full documentation Demonstration Github project page

##### Trumbowyg

Editors /editors/trumbowyg/

###### Overview

Trumbowyg is a lightweight WYSIWYG editor optimized for HTML5 support. Options and design are entirely configurable to suit your needs. However, the default design is compatible with Retina display and optimized for a great and simple user experience. Editor can be extended with additional plugins, supports 30+ languages and custom packages. Trumbowyg is an MIT-licensed open source project and completely free to use.

###### Usage

Installation is fairly simple - just load `trumbowyg.min.js` after `jquery.min.js` (minimum required version 1.8), make sure `$enable-trumbowyg` variable in `_config.scss` is set to `true` and initialize plugin in JS:

If you don't already do it, load jQuery at bottom of `<body>` or in `<head>` and load Trumbowyg after it. In addition, load necessary plugins:

    <!-- Include jQuery -->
    <script src="../../../../global_assets/js/main/jquery.min.js"></script>

    <!-- Include editor -->
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/trumbowyg.min.js"></script>

    <!-- Plugins -->
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/base64/trumbowyg.base64.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/cleanpaste/trumbowyg.cleanpaste.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/colors/trumbowyg.colors.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/insertaudio/trumbowyg.insertaudio.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/noembed/trumbowyg.noembed.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/preformatted/trumbowyg.preformatted.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/template/trumbowyg.template.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/upload/trumbowyg.upload.js"></script>
    <script src="../../../../global_assets/js/plugins/editors/trumbowyg/plugins/pasteimage/trumbowyg.pasteimage.js"></script>

This the minimal code to transform a simple div into the amazing WYSIWYG editor which is Trumbowyg. Or if you want to set options to Trumbowyg, add an object which contains your options as parameters:

    // Initialize default editor
    $('#trumbowyg-demo').trumbowyg();

    // Initialize with options
    $('#trumbowyg-demo').trumbowyg({
        btns: ['strong', 'em', '|', 'insertImage'],
        autogrow: true
    });

###### Options

Following is a list of all configuration parameters with their corresponding default values:

Prefix
default: 'trumbowyg'

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

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

Localization
default: null

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 :). Don't forget include the lang file in your pages:

    <!-- Include lang file -->
    <script type="text/javascript" src="js/dist/langs/fr.min.js"></script>

Make sure to include lang file after Trumbowyg and before instantiating the editor!

Usage of language parameter (English is a fallback lang):

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

Button pane
default: all buttons

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:

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

    // Default button set
    $('.simple-editor').trumbowyg({
        btns: [
            ['viewHTML'],
            ['undo', 'redo'], // Only supported in Blink browsers
            ['formatting'],
            ['strong', 'em', 'del'],
            ['superscript', 'subscript'],
            ['link'],
            ['insertImage'],
            ['justifyLeft', 'justifyCenter', 'justifyRight', 'justifyFull'],
            ['unorderedList', 'orderedList'],
            ['horizontalRule'],
            ['removeformat'],
            ['fullscreen']
        ]
    });

Hide button texts
default: false

You can hide button texts showed when you put `svgPath` to `false`

    // Globally
    $.trumbowyg.hideButtonTexts = true

    // Or locally
    $('.trumbowyg').trumbowyg({
        hideButtonTexts: true
    });

Semantic
default: true

Generates a better, more semantic oriented HTML (i.e. `<em>` instead of `<i>`, `<strong>` instead of `<b>`, etc.). It's just a boolean. 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 :

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

Reset CSS
default: false

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:

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

Remove format pasted
default: false

If you don't want styles pasted from clipboard (from Word or other webpage for example), pass the `removeformatPasted` option to `true`. In order to use this option, you need to define a font size in your CSS or use a reset like normalize.

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

Auto grow
default: false

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

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

Auto grow on enter
default: false

The text editing zone can extend itself when editor get focus and reduce on blur. To activate this feature, use the following option:

    // Initialize
    $('.trumbowyg').trumbowyg({
        autogrowOnEnter: true
    });

Image width modal edit
default: false

Add a field in image insert/edit modal which allow users to set the image width. To activate this feature, use the following option:

    // Initialize
    $('.trumbowyg').trumbowyg({
    	imageWidthModalEdit: true
    });

URL protocol
default: false

An option to auto-prefix URLs with a protocol. When this option is set to `true`, URLs missing a protocol will be prefixed with `https://`. Alternatively, a string can be provided for a custom prefix. For example, a value of true would convert example.com to https://example.com, while a value of ftp converts to ftp://example.com.

    // Initialize
    $('.trumbowyg').trumbowyg({
        urlProtocol: true
    });

Minimal links
default: false

Reduce the link overlay to use only `url` and `text` fields, omitting `title` and `target`.

    // Initialize
    $('.trumbowyg').trumbowyg({
        minimalLinks: true
    });

###### Modal box 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 modal box
    var $modal = $('#editor').trumbowyg('openModal', {
        title: 'A title for modal box',
        content: 'Content in HTML which you want include in created modal box'
    });

    // 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)
Events on modal box

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

- tbwsubmit: trigged when form is submit
- tbwreset: trigged when user cancel operation

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

    // Listen clicks on modal box buttons
    $modal.on('tbwconfirm', function(e){
        // Save datas
        $("#editor").trumbowyg('closeModal');
    });
    $modal.on('tbwcancel', function(e){
        $('#editor').trumbowyg('closeModal');
    });

Only build inputs in modal

If you want 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.

    // Config
    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'),
                type: 'text'.
                attributes: {}
            },
            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: 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 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

    // Get 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.

    // Clear editor
    $('#editor').trumbowyg('empty');

###### Enable/disable edition

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

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

###### Toggle between HTML & WYSIWYG modes

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

    // Toggle views
    $('#editor').trumbowyg('toggle');

###### Destroy editor

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

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

###### Events

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`
- Change in editor: `tbwchange`
- Resize the editor on autogrow: `tbwresize`
- Paste something in the editor: `tbwpaste`
- Switch to fullscreen mode: `tbwopenfullscreen`
- Leave editor's fullscreen mode: `tbwclosefullscreen`
- Close the editor: `tbwclose`

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

###### Plugin info

Property | Description
--- | ---
File name | trumbowyg.min.js
Location | global_assets/js/plugins/editors/trumbowyg/
Links | Official plugin website Full documentation Github project page