Home

Awesome

Overview

Bootstrap-wysihtml5 is a javascript plugin that makes it easy to create simple, beautiful wysiwyg editors with the help of wysihtml5 and Twitter Bootstrap.

About this fork

This fork provides the same functionality as the original by jhollingworth but skips bootstrap 2 support and adds bootstrap 3 support.

Besides it uses bower for client side dependency management.

Why a fork again?

The old repository seems to be dead. Pull Requests are not accepted anymore since some time. The other bootstrap-wysihtml5 packages in the bower registry do NOT provide bootstrap 3 support, even if the name so suggests. They are not maintained either.

Furthermore the packages on bower do not use proper dependency management.

I will (eventually) maintain this repo and I will (eventually) accept pull requests.

Dependencies

Additionally to the existing dependencies I added handlebars in version 0.2.0. You only need the handlebars.runtime.min.js. The templates are precompiled during build. This adds less than 7kB to your client (~3kB gzipped). Thus it is easier to maintain the code.

Because maintaining code requires maintainable code.

About us

Development

Install all development dependencies via

npm install

Additionaly you need grunt, grunt-cli and bower as global packages installed.

Also install the client dependencies via

bower install

There is a grunt task for building. Just run

grunt

on the command line and everything should build fine.

Installation

If you are using bower use the “bootstrap3-wysihtml5-bower” package.

bower install bootstrap3-wysihtml5-bower

If using Rails, use the gem "bootstrap-wysihtml5-rails" by adding the following to your Gemfile

gem "bootstrap-wysihtml5-rails"

Examples

For use with requirejs see the examples in the repo.

Files to reference

In the folder dist you will the plain unminified javascript files and two kinds of minified files.

bootstrap3-wysihtml5.min.js: This file contains the jquery plugin, the templates and the english translations. If you are referencing this file, you have to reference jquery, bootstrap jquery plugin, handlebars runtime and wysihtml.js.

bootstrap3-wysihtml5.all.min.js: This file contains all of the normal minified file plus the handlebars runtime and editor library. If you are referencing this file, you have to reference jquery and bootstrap jquery plugin.

bootstrap3-wysihtml5.min.css: This is the stylesheet for this plugin.

If you are using any other translation than english, you have to either build this plugin yourself, or reference it separately.

Usage

Editable Div

This is the new style from version 0.3 on and will be supported on all browsers.

The javascript will keep the same. For example it is easier to change the content dynamically on runtime.

$('.textarea').html('Some text dynamically set.');

Textarea

This is the old style usage and does use a sandboxed iframe, which will from version 0.3 on not work in IE.

<textarea id="some-textarea" placeholder="Enter text ..." style="styles to copy to the iframe"></textarea>
<script type="text/javascript">
	$('#some-textarea').wysihtml5();
</script>

You can get the html generated by getting the value of the text area, e.g.

$('#some-textarea').val();

RequireJS Support

From version 0.3 on, requirejs is supported.

The usage with requirejs will be the same with a slightly difference to the localisation feature. English will not be pre loaded, so translations not in the used language will not fallback to english but are just empty. Also if using english you have to load the locale dependency.

A minimum example:

require.config({
  paths: {
    'domReady': '../components/requirejs-domready/domReady',
    'jquery': '../components/jquery/jquery.min',
    'bootstrap': '../components/bootstrap/dist/js/bootstrap.min',
    'bootstrap.wysihtml5': '../dist/amd/bootstrap3-wysihtml5.all',
    'bootstrap.wysihtml5.de-DE': '../dist/locales/bootstrap-wysihtml5.de-DE'
  },
  shim: {
    'bootstrap': {
      deps: ['jquery']
    }
  },
  deps: [
    './start'
  ]
});

define([
  'require',
  'domReady',
  'jquery',
  'bootstrap.wysihtml5.de-DE'
], function(require, domReady, $) {
  'use strict';

  domReady(function() {
    $('.textarea').wysihtml5({
      locale: 'de-DE'
    }); 
  });
});

Advanced

Options

An options object can be passed in to .wysihtml5() to configure the editor:

$('#some-textarea').wysihtml5({someOption: 23, ...})

Buttons

To override which buttons to show, set the appropriate flags:

$('#some-textarea').wysihtml5({
	"font-styles": true, //Font styling, e.g. h1, h2, etc. Default true
	"emphasis": true, //Italics, bold, etc. Default true
	"lists": true, //(Un)ordered lists, e.g. Bullets, Numbers. Default true
	"html": false, //Button which allows you to edit the generated HTML. Default false
	"link": true, //Button to insert a link. Default true
	"image": true, //Button to insert an image. Default true,
	"color": false, //Button to change color of font  
	"blockquote": true, //Blockquote  
  "size": <buttonsize> //default: none, other options are xs, sm, lg
});

Since v0.3.0 toolbar options are nested in toolbar. So use therefore following syntax:

$('#some-textarea').wysihtml5({
  toolbar: {
    "font-styles": true, //Font styling, e.g. h1, h2, etc. Default true
    "emphasis": true, //Italics, bold, etc. Default true
    "lists": true, //(Un)ordered lists, e.g. Bullets, Numbers. Default true
    "html": false, //Button which allows you to edit the generated HTML. Default false
    "link": true, //Button to insert a link. Default true
    "image": true, //Button to insert an image. Default true,
    "color": false, //Button to change color of font  
    "blockquote": true, //Blockquote  
    "size": <buttonsize> //default: none, other options are xs, sm, lg
  }
});

Font Awesome

To use Font Awesome for the icons of the toolbar you can use since v0.3.1 following option:

  toolbar: {
    "fa": true
  }

Don't forget to add the font awesome stylesheet in this case, which is a bower dependency since v0.3.1.

Custom Templates for Toolbar Buttons

see wikie: Custom Templates

Data Attributes

As of version 0.2.4 there are two new data attributes.

<dl> <dt>data-wysihtml5-format-name</dt> <dd>Normally the inner html of the format command is used to display as current font style. This attribute overrides this value.</dd> <dt>data-wysihtml5-display-format-name</dt> <dd>Whether to show the current font style in the toolbar anyways.</dd> </dl>

Stylesheets

It is possible to supply a number of stylesheets for inclusion in the editor <iframe>:

$('#some-textarea').wysihtml5({
	"stylesheets": ["/path/to/editor.css"]
});

Events

Wysihtml5 exposes a number of events. You can hook into these events when initialising the editor:

$('#some-textarea').wysihtml5({
	"events": {
		"load": function() { 
			console.log("Loaded!");
		},
		"blur": function() { 
			console.log("Blured");
		}
	}
});

Shallow copy by default, deep on request

Options you pass in will be added to the defaults via a shallow copy. (see jQuery.extend for details). You can use a deep copy instead (which is probably what you want if you're adding tags or classes to parserRules) via 'deepExtend', as in the parserRules example below.

Parser Rules

If you find the editor is stripping out tags or attributes you need, then you'll want to extend (or replace) parserRules. This example extends the defaults to allow the <code><strong></code> and <code><em></code> tags, and the class "middle":

$('#some-textarea').wysihtml5('deepExtend', {
  parserRules: {
    classes: {
      "middle": 1
    },
    tags: {
      strong: {},
      em: {}
    }
  }
});

There's quite a bit that can be done with parserRules; see wysihtml5's advanced parser ruleset for details. bootstrap-wysihtml5's default parserRules can be found in the source (just search for 'parserRules' in the file).

Shortcuts

You can map your own shortcuts to commands. For example if you want to map the underline command to Alt+T call the editor with following options:

$('#some-textarea').wysihtml5({
  shortcuts: {
    '84': 'underline'
  }
});

The code executes the command with Alt, Meta or Ctrl pressed. In the example above Ctrl-T in Chrome is already occupied by "New Tab", thus not overridable.

Defaults

You can change bootstrap-wysihtml5's defaults by altering:

$.fn.wysihtml5.defaultOptions

This object has the same structure as the options object you pass in to .wysihtml5(). You can revert to the original defaults by calling:

$(this).wysihtml5('resetDefaults')

Operations on the defaults are not thread-safe; if you're going to change the defaults, you probably want to do it only once, after you load the bootstrap-wysihtml plugin and before you start instantiating your editors.

The underlying wysihtml5 object

You can access the wysihtml5 editor object like this:

var wysihtml5Editor = $('#some-textarea').data("wysihtml5").editor;
wysihtml5Editor.composer.commands.exec("bold");

I18n

You can use Bootstrap-wysihtml5 in other languages. There are some translations available in the src/locales directory. You can include your desired one after the plugin and pass its key to the editor. Example:

<script src="src/locales/bootstrap-wysihtml5.pt-BR.js"></script>
<script type="text/javascript">
  $('#some-textarea').wysihtml5({locale: "pt-BR"});
</script>

It is possible to use custom translations as well. Just add a new key to $.fn.wysihtml5.locale before calling the editor constructor.

Release Notes

Thanks for assistance and contributions