HTML 5

5.5. Command APIs

The execCommand(commandId, doShowUI, value) method on the HTMLDocument interface allows scripts to perform actions on the current selection or at the current caret position. Generally, these commands would be used to implement editor UI, for example having a "delete" button on a toolbar.

There are three variants to this method, with one, two, and three arguments respectively. The doShowUI and value parameters, even if specified, are ignored unless otherwise stated.

In this specification, in fact, the doShowUI parameter is always ignored, regardless of its value. It is included for historical reasons only.

When any of these methods are invoked, user agents must act as described in the list below.

For actions marked "editing hosts only", if the selection is not entirely within an editing host, of if there is no selection and the caret is not inside an editing host, then the user agent must do nothing.

If the commandId is undo

The user agent must move back one step in its undo transaction history, restoring the associated state. If there is no further undo information the user agent must do nothing. See the undo history.

If the commandId is redo

The user agent must move forward one step in its undo transaction history, restoring the associated state. If there is no further undo (well, "redo") information the user agent must do nothing. See the undo history.

If the commandId is selectAll

The user agent must change the selection so that all the content in the currently focused editing host is selected. If no editing host is focused, then the content of the entire document must be selected.

If the commandId is unselect

The user agent must change the selection so that nothing is selected.

We need some sort of way in which the user can make a selection without risk of script clobbering it.

If the commandId is superscript

Editing hosts only. The user agent must act as if the user had requested that the selection be wrapped in the semantics of the sup element (or unwrapped, or, if there is no selection, have that semantic inserted or removed — the exact behaviour is UA-defined).

If the commandId is subscript

Editing hosts only. The user agent must act as if the user had requested that the selection be wrapped in the semantics of the sub element (or, again, unwrapped, or have that semantic inserted or removed, as defined by the UA).

If the commandId is formatBlock

Editing hosts only. This command changes the semantics of the blocks containing the selection.

If there is no selection, then, where in the description below refers to the selection, the user agent must act as if the selection was an empty range at the caret position.

If the value parameter is not specified or has a value other than one of the following literal strings:

• <address>
• <aside>
• <h1>
• <h2>
• <h3>
• <h4>
• <h5>
• <h6>
• <nav>
• <p>
• <pre>

...then the user agent must do nothing.

Otherwise, the user agent must, for every position in the selection, take the furthest block-level element ancestor of that position that contains only inline-level content and is not being used as a structured inline-level element, and, if that element is a descendant of the editing host, rename it (as if the Element.renameNode() method had been used) according to the value, by stripping the leading < character and the trailing > character and using the rest as the new tag name, using the HTML namespace.

If the commandId is delete

Editing hosts only. The user agent must act as if the user had performed a backspace operation.

If the commandId is forwardDelete

Editing hosts only. The user agent must act as if the user had performed a forward delete operation.

If the commandId is insertLineBreak

Editing hosts only. The user agent must act as if the user had requested a line separator.

If the commandId is insertParagraph

Editing hosts only. The user agent must act as if the user had performed a break block editing action.

If the commandId is insertText

Editing hosts only. The user agent must act as if the user had inserted text corresponding to the value parameter.

If the commandId is vendorID-customCommandID

User agents may implement vendor-specific extensions to this API. Vendor-specific extensions to the list of commands should use the syntax vendorID-customCommandID so as to prevent clashes between extensions from different vendors and future additions to this specification.

If the commandId is something else

User agents must do nothing.