Jump to content

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

+ 1
  dannyg1's Photo
Posted Oct 29 2009 09:00 AM

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.

The Command System

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.

Commanding an Editable Document

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:

&#60;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.

TextRange Features

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).

Command IE Moz Opera Description Value parameter
2D-Position. Makes absolute—positioned element inherently draggable (IE 5.5 or later)Boolean to enable (true) or disable (false) dragging
AbsolutePosition.Sets style.position property to absolute (IE 5.5 or later)Boolean to enable (true) or disable (false) setting
BackColor...Sets background color of current selectionColor value (name or hex triplet)
Bold. ..Makes the current selection bold weightNone
ContentReadOnly. .Locks the documentBoolean to enable (true) or disable (false) setting
Copy. .Copies the range to the Clipboard (Moz signed scripts)None
CreateBookmark.Wraps an
<a name=>
tag around the range or modifies an existing
<a>
tag
A string of the anchor name; tag is removed if value is omitted
CreateLink...Wraps an
<a href=...>
tag around the current selection
A string of a complete or relative URL
Cut...Copies the range/selection to the Clipboard, then deletes range/selection (Moz signed scripts)None
DecreaseFontSize. .Reduces selection one HTML font sizeNone
Delete.. .Deletes the range/selectionNone
FontName.. .Sets the font family of current selectionA string of the font family name
FontSize.. .Sets the HTML font size of current selectionA string of the font size (1–7)
ForeColor.. .Sets the foreground (text) color of current selectionColor value (name or hex triplet)
FormatBlock.. .Wraps a block tag around the current objectHTML tag (e.g.,
<p>
) as string
Heading.Wraps a heading tag around the current objectHTML tag (e.g.,
<h1>
) as string
HiliteColor.Sets the background color of the selectionColor value (name or hex triplet)
IncreaseFontSize.. Raises selection one HTML font sizeNone
Indent..Indents current selectionNone
InsertButton.Inserts a
<button>
tag at current insertion point
A string for the element ID
InsertFieldset.Inserts a
<fieldset>
tag at current insertion point
A string for the element ID
InsertHorizontalRule..Inserts
<hr>
at current insertion point
A string of the rule size (not working)
InsertHTML..Inserts HTML markup into selection HTML markup as string
InsertIFrame.Inserts an
<iframe>
tag at current insertion point
A string of a URL for the src property
InsertImage... Inserts an
<img>
tag at current text selection (IE 5 or later)
A string of a URL for the src property
InsertInputButton .Inserts an
<input type="button">
tag at current insertion point
A string for the element ID
InsertInputCheckbox.Inserts an
<input type="checkbox">
tag at the current insertion point
A string for the element ID
InsertInputFileUpload.Inserts an
<input type="file">
tag at the current insertion point
A string for the element ID
InsertInputHidden.Inserts an
<input type="hidden">
tag at current insertion point
A string for the element ID
InsertInputImage.Inserts an
<input type="image">
tag at current insertion point
A string for the element ID
InsertInputPassword.Inserts an
<input type="password">
tag at current insertion point
A string for the element ID
InsertInputRadio.Inserts an
<input type="radio">
tag at current insertion point
A string for the element ID
InsertInputReset.Inserts an
<input type="reset">
tag at current insertion point
A string for the element ID
InsertInputSubmit.Inserts an
<input type="submit">
tag at current insertion point
A string for the element ID
InsertInputText.Inserts an
<input type="text">
tag at current insertion point
A string for the element ID
InsertMarquee.Inserts a
<marquee>
tag at current insertion point
A string for the element ID
InsertOrderedList...Inserts an
<ol>
tag at current insertion point
A string for the element ID
InsertParagraph..Inserts a
<p>
tag at current insertion point
A string for the element ID
InsertSelectDropdown.Inserts a
<select>
tag whose type is select—one at current insertion point
A string for the element ID
InsertSelectListbox.Inserts a
<select>
tag whose type is select—multiple at current insertion point
A string for the element ID
InsertTextArea.Inserts a
<textarea>
tag at current insertion point
A string for the element ID
InsertUnorderedList...Inserts a
<ul>
tag at current insertion point
A string for the element ID
Italic...Wraps an
<i>
tag around the range
None
JustifyCenter...Center justifies the current selection None
JustifyFull ..Full justifies the current selectionNone
JustifyLeft...Left justifies the current selectionNone
JustifyRight...Right justifies the current selectionNone
LiveResize.Dynamically refresh element resizing in edit mode (IE 5.5 or later)Boolean to enable (true) or disable (false) setting
MultipleSelection. Allow multiple element selections in edit mode (IE 5.5 or later)Boolean to enable (true) or disable (false) setting
Outdent.. .Outdents the current selectionNone
OverWrite.Sets the input—typing mode to overwrite or insertBoolean (true if mode is overwrite)
Paste..Pastes contents of the Clipboard at current insertion point or over the current selection (Moz signed scripts)None
Print.Displays Print dialog box (IE 5.5 or later)None
Redo.. Undoes the previous undo commandNone
Refresh .Reloads the current documentNone
RemoveFormat...Removes formatting from current selection None
SaveAs.Saves the page as a local file (optional file dialog)A string of a URL for the path
SelectAll..Selects entire text of the documentNone
Strikethrough.. .Formats selection as strikethrough textNone
StyleWithCSS.Use CSS markup (default true)Boolean to enable (true) or disable (false) setting
Subscript. ..Formats selection as subscript textNone
Superscript. ..Formats selection as superscript textNone
UnBookmark.Removes anchor tags from the selection or text rangeNone
Underline. ..Wraps a
<u>
tag around the range
None
Undo..Undo previous commandNone
Unlink...Removes a link from the selection or text rangeNone
[inlinecode]Unselect.. Clears a selection from the documentNone
[inlinecode]UseCSS..Use CSS markup (deprecated in Mozilla)Boolean to enable (true) or disable (false) setting
Dynamic HTML: The Definitive Reference

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.

See what you'll learn


Tags:
0 Subscribe


0 Replies