EventfulEditor {Beta} - Powered by Everyday Events

Eventful Editor adds the flexibility and power of Events with content editing. Ok, so what's different from the other fifty out there? Well, everything. Most editors use the power of contenteditable or designmode to allow you to use browser based triggers to wrap content. Some of them are even nice enough to try to make the browser formats the same. We don't. We say we don't care what the browser can do, we want absolute control. If I want the B button to make it italics, I will. In this concept we can provide more functionality and better support for everything. Now if you like the controls the browser has, use them, you have that right, but if you don't, use anything you like. Ok, but seriously, let me guess you guys have the worse UI ever? Nope, we got rid of it. we give you access to events, if you want to make a button to trigger an action, go ahead. We give you, through the power of jQuery, the ability to listen, attach, and trigger events, you don't even need the buttons to start. If you know the user is done selecting you can ask the user what they want to do next! Take charge of the experience and make it the best it's ever been. So where is the catch? We don't support IE version 8 or below, and we only support running in non-quirks mode. Damn shame isn't it, but with growing technologies there is a time and place for older browsers and we had to draw a line to support the future.

Events and Usage

Initialization:

Getting an editor up and running is extremely simple. Built on jQuery plugin standards we support calling all functions and initialization by calling the plugin. See the examples below.

Calling the default constructor.

$("textarea").EventfulEditor();

Stop Making me Type EventfulEditor!

Ok, so we got tired of it too, so in typical programmer fashion we made a short hand, you can simply us ee in place of EventfulEditor.

$("textarea").ee();

Passing options to the constructor. For a complete list of options see the area labelled Options.

$(".editors").EventfulEditor({editableElement: "<p></p>"});

Calling the constructor with a callback when load has completed.

$("#my-editor").EventfulEditor(function(){ /* do this on load complete */ });

or with options

$("#my-editor").EventfulEditor({editableElement: "<p></p>"}, function(){ /* do this on load complete */ });

Destruction:

We don't know why you would ever want to destroy the wonderful thing we've made but it happens so if you need to destroy the editor you can call the destroy method passing true/false or nothing at all, the default is false. This value indicates whether the options that were used when creating the editor should be left, to be used on the next initialization, or if they should be removed as well.

Calling the destructor

$("#my-editor").EventfulEditor("destroy");

or like this to remove the options

$("#my-editor").EventfulEditor("destroy", true);

On:

Attaching events is the reason we are here! Calling the on method works using the same options you are used to with the jQuery .on() method so you can see their documentation for the most up to date options. The difference here is that in order to keep standard plugin style and operation we call the plugin with the event parameters. By doing it this way we are also able to allow custom events of our own, and yours!

Calling the on method to attach event listeners

$("#my-editor").EventfulEditor("on", "click", function(){ /* do something on click */ });

Off:

Making events simple but sometimes you just need to turn them off. The off method works in the same relation as the on method above does with jQuery so see the jQuery site for help with off.

Turning off, unregistering, event listeners

$("#my-editor").EventfulEditor("off", "click");

or if you have a specific function to turn off

$("#my-editor").EventfulEditor("off", "click", function(){ /* something */ });

Trigger:

Want to trigger events? You're in the right place. As you've seen from on and off we're right on track with jQuery, why why not keep going?

Triggering events

$("#my-editor").EventfulEditor("trigger", "click");

or passing additional parameters

$("#my-editor").EventfulEditor("trigger", "click", ["my", "custom", "parameters"]);

Sync:

There are normally two pieces to the editor although being tricky you can make them one. In times when these are separate you need the ability to sync the html area, normally a textarea, and the preview area, normally a contenteditable div. This method allows that functionality with a simple call. Without parameters the function will sync the current content of the preview area to the html area but it times that you need the opposite, such as html editing view, you can pass true and sync the html area to the preview pane.

Syncing the panes

$("#my-editor").EventfulEditor("sync");

or in the opposite direction

$("#my-editor").EventfulEditor("sync", true);

Selection and Range API

If you've never used the browsers Range and Selection API's I suggest reading this article from quirks mode. In IE 9 and Opera 10 these browsers started catching up with the times and decided to start playing more by the standards and with that came implementation of the Range and Selection API's. This is one reason, and only one of many, we decide to support IE 9+ and Opera 10+. This will make your and our life much easier. Now that being said there is still a ton to learn and when using the browser API's and jQuery together, things get a little hairy. This is where we took a step and tried to provide some easily usable functions that allow you to use jQuery object with some of the more common Range and Selection API's. This in no way means you are restricted to them!

getSelection:

Gets the Selection from the browsers window object.

$("#my-editor").EventfulEditor("getSelection");

createRange:

Creating a Range is fairly straight forward but we also wanted to use jQuery objects so we made the createRange method help by setting up some defaults. There is no guess as to how these methods are named and we do it to make it just like using the native API's.

Create a Range Using the Default Constructor

The default constructor will create the same object with the same settings as the browsers default document.createRange() method.

var range = $("#my-editor").EventfulEditor("createRange");

Passing the initial arguments

Passing arguments can be extremely useful for setting a default start or end node or both. By passing either Element nodes or jQuery objects, you can set the beginning node in the Range by default, sending the beginning node and ending this node will select from the beginning of the beginning node to the beginning of the ending node.

var beginningNode = $("#my-paragraph"), endNode = $("my-span"), range = $("#my-editor").EventfulEditor("createRange", beginningNode, endNode);

Setting the Beginning Nodes Offset

In some situations it may be needed to set the offset of the beginning node, this can be done with or without passing the ending node. In such cases the beginning node is only set and the Range will have no end set.

var beginningNode = $("#my-paragraph"), offset = 5, range = $("#my-editor").EventfulEditor("createRange", beginningNode, offset);

Using createRange to its Full Potential

In the majority of cases you will want to set the beginning node, beginning offset, end node, and end offset. This can easily be done by specifying all parameters in that order.

var beginningNode = $("#my-paragraph"), beginOffset = 5, endNode = $("my-span"), endOffset = 2,
range = $("#my-editor").EventfulEditor("createRange", beginningNode, beginOffset, endNode, endOffset);

addRange:

Given a Range you can add it to the window selection natively or use the addRange function.

var beginningNode = $("#my-paragraph"), beginOffset = 5, endNode = $("my-span"), endOffset = 2,
range = $("#my-editor").EventfulEditor("createRange", beginningNode, beginOffset, endNode, endOffset);
$("#my-editor").EventfulEditor("addRange", range);

collapseToStart:

Collapses the Current Selection to it's starting point.

$("#my-editor").EventfulEditor("collapseToStart");

collapseToEnd:

Collapses the Current Selection to it's ending point.

$("#my-editor").EventfulEditor("collapseToEnd");

getRangeAt:

Returns the Range at the passed index, if the index does not exist or is out of bounds undefined is returned. Note: At time of documentation only Firefox supports multiple ranges for a selection.

var range = $("#my-editor").EventfulEditor("getRangeAt", 0);

selectAllChildren:

Creates a new selection, discarding the current selection, by selections all child nodes of the node passed.

$("#my-editor").EventfulEditor("selectAllChildren", $("#right-block"));

removeAllRanges:

Removes all Ranges from the Selection.

$("#my-editor").EventfulEditor("removeAllRanges");

removeRange:

Removes the Range at the passed index from the Selection.

var range = $("#my-editor").EventfulEditor("getRangeAt", 0);
$("#my-editor").EventfulEditor("removeRange", range);

deleteFromDocument:

Deletes the text inside the current selection from the DOM.

$("#my-editor").EventfulEditor("deleteFromDocument");

Options

disableDocTypeCheck(Boolean) -- default: false

We have made our code HTML5 ready and in order to do so we check for DOCTYPE compliance. If for some reason you need to force this behavior to be turned off specify true as we'll assume you know what you're doing.

previewEditOnly(Boolean) -- default: false

In order to allow the eventful editor to be super flexible we actually allow you to not use forms to post data. If you want to cater to only those with JavaScript you can set this setting to true and use Ajax and event listeners to save, load, and control the data in the editor.

editableElement(String | Element | Selector) -- default: "<div></div>"

This is the element that will be made editable and displayed as the preview pane to the user. If the string passed is a selector, that item will be used where it is in the DOM, if a string such as "<div/>" the item will be created and appended where the html pane was attached. If an element was passed in it will be used in place like the selector.

customEvents(String) -- default: ""

Eventful Editor is based on events and new events are supported by browsers in partial or full all the time. What we've done is taken the most basic of events and built them in, then made the ability to add custom events. One such event is copy, or paste. Some browsers support these events but not all and so we leave them out by default. Using this option you can easily add them in when they are needed by your application, plugin, or button by passing a string of comma separate values. A list of default events is provided below but be wary, adding custom events that are the same as default events could cause events to fire more than once.

Default Support Events:

• blur
• click
• change
• dblclick
• focus
• focusin
• focusout
• hover
• keydown
• keypress
• keyup
• load
• mousedown
• mouseenter
• mouseleave
• mousemove
• mouseout
• mouseover
• mouseup
• selectstart*
• selectionchange*
• resize
• scroll
• unload

*: Implementations are custom due to poor/uniform browser native support