CLEditor - WYSIWYG HTML Editor

Getting Started

CLEditor is shipped with the following files. It is recommended that you install these files into a folder called cleditor with a subfolder called images.

jquery.cleditor.js - jQuery Plugin (source)
jquery.cleditor.css - Style Sheet
images/*.png - Toolbar and Buttons Images

When installing plugins, this same folder structure should be used. All javascript and style sheets go in the cleditor folder and all images go in the cleditor/images folder.

Getting Started
Usage
Optional Parameters
.cleditor(options) Method
cleditor Object
$.cleditor Object

Usage

CLEditor takes a standard html textarea element and turns it into a full featured rich text editor. To use CLEditor, just apply the cleditor method to a standard jQuery object containing the textarea elements you would like transformed. The textareas will be hidden and rich text editors will appear in their place.

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="jquery.cleditor.css" />
    <script type="text/javascript" src="jquery.min.js"></script>
    <script type="text/javascript" src="jquery.cleditor.min.js"></script>
    <script type="text/javascript">
      $(document).ready(function() {
        $("#input").cleditor();
      });
    </script>
  </head>
  <body>
    <textarea id="input" name="input"></textarea>
  </body>
</html>

Behind the scenes, an iframe is created, placed in design mode and kept in sync with the textarea. At any time, you can access the HTML content of the editor using the textarea value. The textarea is also available server-side for postbacks.

Optional Parameters

For more control, you can supply a number of optional parameters as in the following example.

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="../jquery.cleditor.css" />
    <script type="text/javascript" src="jquery.min.js"></script>
    <script type="text/javascript" src="jquery.cleditor.min.js"></script>
    <script type="text/javascript">
      $(document).ready(function() {
        $("#input").cleditor({
          width:        500, // width not including margins, borders or padding
          height:       250, // height not including margins, borders or padding
          controls:     // controls to add to the toolbar
                        "bold italic underline strikethrough subscript superscript | font size " +
                        "style | color highlight removeformat | bullets numbering | outdent " +
                        "indent | alignleft center alignright justify | undo redo | " +
                        "rule image link unlink | cut copy paste pastetext | print source",
          colors:       // colors in the color popup
                        "FFF FCC FC9 FF9 FFC 9F9 9FF CFF CCF FCF " +
                        "CCC F66 F96 FF6 FF3 6F9 3FF 6FF 99F F9F " +
                        "BBB F00 F90 FC6 FF0 3F3 6CC 3CF 66C C6C " +
                        "999 C00 F60 FC3 FC0 3C0 0CC 36F 63F C3C " +
                        "666 900 C60 C93 990 090 399 33F 60C 939 " +
                        "333 600 930 963 660 060 366 009 339 636 " +
                        "000 300 630 633 330 030 033 006 309 303",    
          fonts:        // font names in the font popup
                        "Arial,Arial Black,Comic Sans MS,Courier New,Narrow,Garamond," +
                        "Georgia,Impact,Sans Serif,Serif,Tahoma,Trebuchet MS,Verdana",
          sizes:        // sizes in the font size popup
                        "1,2,3,4,5,6,7",
          styles:       // styles in the style popup
                        [["Paragraph", "<p>"], ["Header 1", "<h1>"], ["Header 2", "<h2>"],
                        ["Header 3", "<h3>"],  ["Header 4","<h4>"],  ["Header 5","<h5>"],
                        ["Header 6","<h6>"]],
          useCSS:       false, // use CSS to style HTML when possible (not supported in ie)
          docType:      // Document type contained within the editor
                        '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">',
          docCSSFile:   // CSS file used to style the document contained within the editor
                        "", 
          bodyStyle:    // style to assign to document body contained within the editor
                        "margin:4px; font:10pt Arial,Verdana; cursor:text"
        });
      });
    </script>
  </head>
  <body>
    <textarea id="input" name="input"></textarea>
  </body>
</html>

The above optional parameter object supports the following properties and callbacks:

Properties

width - The editor width not including margins, borders or padding.
height - The editor height not including margins, borders or padding.
controls - A space seperated list of the controls in the toolbar.
colors - A space seperated list of the colors in the color popup.
fonts - A comma seperated list of the font names in the font popup.
sizes - A comma seperated list of the sizes in the font size popup.
styles - An array of styles in the style popup.
useCSS - A boolean value used to force CSS styling of HTML elements when possible.
docType - The document type to assign to the editor contents.
docCSSFile - The CSS file used to style the editor contents.
bodyStyle - The style to assign to the body of the editor contents.

Callbacks

.updateTextArea(html) - This handler is called by the .updateTextArea() method of the cleditor object to convert HTML into source code. This handler receives the internal iframe contents as the html parameter and should return the source code to store in the textarea.
.updateFrame(source) - This handler is called by the .updateFrame() method of the cleditor object to convert source code into HTML. This handler receives the textarea contents as the source parameter and should return the HTML to store in the internal iframe.

Defaults

Using the defaultOptions object, you can override any of the above properties or callbacks as follows:

$.cleditor.defaultOptions.width = 200;
$.cleditor.defaultOptions.height = 100;
$("#input").cleditor();

Overrides done using the defaultOptions object apply to all new editors.

.cleditor(options) Method

Returns a jQuery object containing cleditor objects for the set of matched textarea elements. If the cleditor object does not exist for a matched textarea element, it will be created using the default options combined with the supplied options. This is the core method for creating and selecting cleditor objects.

Examples

$("#input").cleditor({width:500, height:250})
$("textarea").cleditor()
var editor = $("#input").cleditor()[0]
var $editors = $("textarea").cleditor()

cleditor Object

An editor is composed of a main div element used to hold a toolbar, a text area and an iframe. The toolbar can hold multiple groups which in turn hold multiple buttons.

The cleditor object is created and exposed using the .cleditor(options) method described above. It defines a single editor instance and supports the following properties and methods.

Properties

These properties should be considered readonly.

.$area - The textarea wrapped in a jQuery object.
.$frame - The iframe wrapped in a jQuery object.
.$main - The main div wrapped in a jQuery object - When moving an editor, this is the DOM element to re-parent.
.$toolbar - The toolbar div wrapped in a jQuery object.
.disabled - True if the editor is currently disabled; otherwise false.
.doc - The document object currently being edited in the iframe.
.options - The options used to create the editor.

Methods

Note: All methods except sourceMode, selectedHTML and selectedText support chaining by returning the object they were executed on.

.change(handler) - shortcut method used to bind the change event.
.clear() - Clears the contents of the internal textarea and iframe.
.disable(disabled) - Disables or enables the editor. Pass in true to disable or false to enable.
.execCommand(command, value, useCSS, button) - Executes a design mode command using the supplied value. If useCSS is true, CSS will be used to style the markup when possible. If an error occurs during execution, a popup message will be displayed under the button or centered under the toolbar if button is omitted.
.focus() - Sets input focus to the editor.
.hidePopups() - Hide any popups currently showing in any editor.
.refresh() - Forces the editor to resize it's toolbar, textarea and iframe. This method should be called after initializing a hidden editor and making it visible, or after changing the the width, height or parent of the $main div element.
.select() - Selects the entire contents of the editor.
.selectedHTML() - Returns the editor's current selection as an HTML formatted string.
.selectedText() - Returns the editor's current text selection as a string.
.showMessage(message, button) - Displays a popup message under the button or centered under the toolbar if button is omitted.
.sourceMode() - Returns true if the editor is currently displaying source code or false when rich text is showing.
.updateFrame() - Updates the editor's internal iframe with its textarea contents.
.updateTextArea() - Updates the editor's textarea with its internal iframe contents.

Events

change - This event is triggered whenever the contents of the editor have changed. Since change detection is done using the keyup and mouseup events, this event occurs frequently as the user types.

$.cleditor Object

This object contains global properties and methods used to create custom plugins and override built in functionality.

Properties

.defaultOptions - Contains the default optional parameter values used in the creation of new editors.

See the optional parameters section above for a description of each property on the $.cleditor.defaultOptions object.

.buttons - An array object containing the button definitions used to construct the editor.

Each button definition contains the following properties. Any optional properties are undefined if not supplied.

.name - The internal name of the button.

.title - The tooltip to display when the user hovers their mouse over the button.

.css - A standard jQuery style css map used to define the button image (optional).

.image - The name of the image file (in the images folder) to display for the button (optional).

.stripIndex - When using an image strip, this property identifies the zero based index into the strip (optional).

.command - The design mode command associated with the button (optional).

.popupName - The name of the popup to display when the button is clicked (optional).

.popupContent - The content of the popup to display when the button is clicked (optional).

Each button definition also supports the following optional callbacks.

.getEnabled(data) - This handler is called when the enabled state of the button is needed and should return false to disable the button or true to enable it. If no value is returned, the button will be enabled.

.getPressed(data) - This handler is called when the pressed state of the button is needed and should return true to have the button appear pressed or false to have the button appear normal. If no value is returned, the button will appear normal.

.buttonClick(event, data) - This handler is called when the button is clicked. When the button does not display a popup, this handler should return false to prevent CLEditor from executing the command on the data object parameter. By default, CLEditor will execute the command using the value and useCSS properties found on the data parameter.

.popupClick(event, data) - This handler is called when an element in the popup is clicked and should return false to prevent CLEditor from executing the command on the data object parameter. By default, CLEditor will execute the command using the value and useCSS properties found on the data parameter.

The data object passed into the above callback functions contains the following properties.

.editor - The cleditor object containing the clicked button.

.button - The clicked button's div element.

.buttonName - The name of the clicked button.

.popup - The popup div element.

.popupName - The name of the button's popup.

.command - The design mode command associated with the button.

.value - The value associated with the design mode command.

.useCSS - A boolean value that forces the design mode command to generate CSS markup when possible.

Methods

.imagesPath() - Returns the path to the images folder including the trailing slash.

CLEditor - WYSIWYG HTML Editor

Getting Started

Table of Contents

Usage

Optional Parameters

Properties

Callbacks

Defaults

.cleditor(options) Method

Examples

cleditor Object

Properties

Methods

Events

$.cleditor Object

Properties

Methods