Skip to content

Latest commit

 

History

History
105 lines (59 loc) · 4 KB

README.markdown

File metadata and controls

105 lines (59 loc) · 4 KB
Raw

Toupee

A jQuery port of the WysiHat JavaScript framework

Toupee is heavily based on work by Joshua Peek and the other contributors to the WysiHat project (http://github.com/josh/wysihat).

Introduction

Building the project

From inside the project directory, run the build script:

./build

You will have a new file at dist/toupee.js. There isn't any minifying or obfuscation done, as I've found most projects have their own static asset compression strategy. Feel free to add one.

Supported platforms

This is alpha quality software; use at your own risk. Toupee appears to work in:

  • Firefox 3
  • Safari 4 beta

It has not been examined in:

  • Microsoft Internet Explorer
  • Mozilla Firefox 2
  • Apple Safari 3
  • Opera
  • Google Chrome

Known shortcomings

  • The test suite hasn't been ported over yet
  • The selection and range components of WysiHat haven't been ported yet
  • Copy/Cut/Paste not yet implemented

Dependencies

  • jQuery 1.3.2

API

Toupee takes a somewhat different approach that WysiHat when it comes to code structure and extensibility. My goal is to leverage custom events to make Toupee as flexible as possible.

$$

There is a global utility method, $$ for accessing a DOM element's jQuery data hash. This technique and code are lifted from an article by Yehuda Katz on evented programming.

Creating an editor

To create an instance of the Toupee editor, call toupee() on a jQuery object that contains textareas:

$('textarea').toupee();

This method will return the first element's editor instance, which can also be accessed using the aforementioned $$ method:

$$(domNodeOrJQuery).editor;

When a change is made by the user, the hidden textarea's content is updated. So form submissions should work as the did before enhancement.

The editor has many useful methods.

How it works

Toupee, like most other WYSIWYG editors, uses an iframe with designMode turned on. The original textarea is hidden, and it's contents are updated as changes are made to the content in the iframe. This may become a performance issue, at which point updating the textarea's content will be fired by the form's submission.

editor.bind(eventName, callback)

editor.bind is a convenience method for binding event listeners to the editor (actually, all events/listeners are fired on/attached to editor.widget). Inside the callback, this is a reference to editor.widget.

Here is how to create a button that will create a link when clicked:

$$(domNome).editor.bind('link.click.toupee', function(event, editor) {
    var link = prompt('Please enter the URL to link to:');
    if (link) {
        editor.exec('createLink', link);
    }
});

editor.button(buttonName, options)

Creates a new button in the toolbar, which will fire buttonName.click.toupee on editor.widget when clicked. This method and editor.bind allow for the creation of custom toolbars.

editor.exec(commandName, optionalArgument)

Basically a wrapper for execCommand. For more info, see Rich-Text Editing in Mozilla.

editor.run(func1, func2, ...)

Since all configuration is done by calling methods on an editor instance, this method will call all argument functions, passing in the editor. This allows for packaging a set of toolbar buttons or configurations into a function for easy reuse. See toupee.buttons.js for some examples.

editor.htmlContent()

Returns the cleaned HTML content from the editor.

Examples

There is a single example under example/ to get you started.

License

Toupee, like WysiHat, is released under the MIT license.