How to Create a User-Editable Region in a Web Page

Internet Explorer was the first browser to include a set of commands outside of the JScript context that worked directly with the document and (Win32 only) TextRange objects. In many cases, these commands mimic the functionality available through setting properties or invoking methods of the objects. Some of the newer commands operate within the context of the MSHTML Edit Mode. All of these commands exist outside of the primary document object model and are therefore treated separately in this appendix.

This mechanism comes in very handy when implementing a user-editable region (usually inside an iframe element) in a web page. The main page in such an environment typically contains scripts and toolbars to assist users in creating or modifying HTML content without users having to know anything about HTML. The commands connected to the tools perform actions, such as inserting images and styling text content. This same concept, including the very same command system, has been adopted by Mozilla and Opera to allow those browsers to support the design of a user interface (e.g., toolbars) for user-editable content.

Access to these commands is through a set of document and (in IE only) inlinecode]TextRange[/inlinecode] object methods. These commands and syntax are:

execCommand("commandName"[, UIFlag[, value]])

queryCommandEnabled("commandName")

queryCommandIndeterm("commandName")

queryCommandState("commandName")

queryCommandSupported("commandName")

queryCommandText("commandName")

This appendix focuses on the commands and values that may be applied to the execCommand( ) method (the commands may also be applied to the other methods).

Because Microsoft's scope includes both the document and TextRange object, the list of commands in that environment is much larger than those implemented to date in the Mozilla and Opera browsers. Although there are many commands (listed later in this appendix) that are implemented across all browsers, such cross-browser commands may have additional powers in IE when applied to a TextRange object.

As you've come to expect, even where there is commonality among scripting operations across browsers, you'll still have to contend with some inconsistencies. Such is the case in a typical user-editable environment consisting of an iframe element and scripts in (or linked into) the main document bearing the various user editing tools (e.g., for controlling font sizes, colors, special element insertions, etc.).

The primary concern is obtaining a reference to the document object of the iframe from scripts running in the main document. Assuming the use of an iframe element as the editable region of the page, a script in the main document needs to set the designMode property of the document object within the iframe differently for IE and W3C DOM browsers:

// Internet Explorer 5.5 or later

var editDoc = document.getElementById("editableIframe").contentwindow.document;

// W3C DOM

var editDoc = document.getElementById("editableIframe").contentDocument;

The following script and HTML fragments demonstrate a simplified editing environment offering a few invocations of commands that modify selections within the editable document. The HTML portion is as follows:

<div>

<form>

Font Color:<select onchange="setFontColor(this)">

    <option value="black">Black</option>

    <option value="red">Red</option>

    <option value="green">Green</option>

    <option value="blue">Blue</option>

</select>

Font Style:<select onchange="setFontStyle(this)">

    <option value="bold">Bold</option>

    <option value="italic">Italic</option>

    <option value="underline">Underline</option>

    <option value="strikethrough">Strikethrough</option>

</select>

Font Family:<select onchange="setFontFamily(this)">

    <option value="serif">Serif</option>

    <option value="sans-serif">Sans-serif</option>

    <option value="monospace">Mono</option>

    <option value="comic sans ms">Comic Sans</option>

</select>

</form>

</div>

<iframe id="editableIframe" width="400" height="300"></iframe>

The script portion first initializes the iframe element's document to be editable. Other functions respond to choices made from the "tools" above the iframe element:

<script type="text/javascript">

function setFontColor(choice) {

    if (editDoc) {

        editDoc.execCommand("forecolor", false, choice.value);

    }

}

function setFontStyle(choice) {

    if (editDoc) {

        editDoc.execCommand(choice.value, false, null);

    }

}

function setFontFamily(choice) {

    if (editDoc) {

        editDoc.execCommand("fontname", false, choice.value);

    }

}

var editDoc;

function init( ) {

    if (document.getElementById) {

        var iframe = document.getElementById("editableIframe");

        if (iframe.contentWindow) {

            editDoc = iframe.contentwindow.document;

        }else if (iframe.contentDocument) {

            editDoc = iframe.contentDocument;

        }

    }

    if (editDoc && editDoc.designMode) {

        editDoc.designMode = "on";

    }

}

window.onload

</script>

There are other internal differences among implementations of the execCommand( ) method. IE and Opera modify the document tree for style changes using "old-fashioned" HTML markup, such as and tags. Mozilla will do that, too, but operates in a default mode that instead wraps a selection inside a tag, and assigns CSS properties to the style attribute of the span element.

For an extended example of creating a user editing environment for Mozilla, visit http://developer.moz...ting_in_Mozilla.

As shown earlier, some commands work on the current selection in a document. In IE, however, you can also let scripting assist with the selection with the aid of the TextRange object. For example, the following function locates every instance of a string passed as a parameter and turns its text color to red:

function redden(txt) {

    var rng = document.body.createTextRange( );

    for (var i = 0; rng.findText(txt) != false; i++) {

        rng.select( );

        document.execCommand("ForeColor","false","red") ;

        rng.collapse(false);

        rng.select( );

    }

}

The process is iterative. After creating a text range for the entire document body, the function repeatedly looks for a match of the string. Whenever there is a match, the matched word is selected, and the execCommand( ) method invokes the ForeColor command, passing the value red as the color. To continue searching through the range, the range is collapsed after the previously found item, and the selection is removed (by selecting a range of zero length).

<a name=>

<a>

<a href=...>

<p>

<h1>

<button>

<fieldset>

<hr>

<iframe>

<img>

<input type="button">

<input type="checkbox">

<input type="file">

<input type="hidden">

<input type="image">

<input type="password">

<input type="radio">

<input type="reset">

<input type="submit">

<input type="text">

<marquee>

<ol>

<p>

<select>

<select>

<textarea>

<ul>

<i>

<u>

Learn more about this topic from Dynamic HTML: The Definitive Reference, 3rd Edition. 

Packed with information on the latest web specifications and browser features, this new edition is your ultimate one-stop resource for HTML, XHTML, CSS, Document Object Model (DOM), and Javascript development. Here is the comprehensive reference for designers of Rich Internet Applications who need to operate in all modern browsers, including Internet Explorer 7, Firefox 2, Safari, and Opera. You can instantly see browser support for the latest standards-based technologies.