ckeditor5-elements / ElementOrPositionCommand

Class: ElementOrPositionCommand

The base command for commands that operate on a model position or a model element: clipboard, insert or toggle commands, for example.

It has the observable icon, title and tooltip properties, so buttons can reflect it, and helpers that resolve the target. When no target is given, it is taken from the current selection: the selected element if there is one, otherwise the first selection position.

It does not define what execute() does; subclasses do. Subclasses define when they are enabled (and "on") for a target in _isEnabledFor (and _isOnFor), so the state can be computed for any target with getState, e.g. for a context menu item of an element, without changing the command's own state. A command that computes both from the same work, e.g. from the selected blocks, overrides _getStateFor instead.

execute() runs only when the command is enabled for its target: for the selection, as for every command, and for the target given to it too, e.g. editor.execute('deleteElement', element); executeFor does it for a target the command is not enabled for at the selection. So execute() does not check it again.

A command disabled with forceDisabled() is disabled for every target, not only for the selection.

Extends

• Command

Extended by

• ElementCommand
• ElementMoveCommand
• ElementDuplicateCommand
• ElementDeleteCommand
• ElementCopyCommand
• ElementPasteCommand
• ElementAttributesCommand
• QuickInsertCommand
• QuickInsertPositionCommand

Constructors

Constructor

new ElementOrPositionCommand(editor): ElementOrPositionCommand;

Parameters

Parameter	Type
editor	Editor

Returns

ElementOrPositionCommand

Overrides

Command.constructor

Properties

icon

icon: string | undefined;

Observable

The icon (SVG string) of the command.

---

isForceDisabled

readonly isForceDisabled: boolean;

Observable

Whether the command is disabled with forceDisabled() (and not enabled back with clearForceDisabled() for every id), so it is disabled for every target.

---

isToggleable

isToggleable: boolean = false;

Whether the command can be "on" (see _isOnFor), e.g. because it toggles something. Its buttons then tell assistive technology whether it is on: toolbar buttons with aria-pressed, menu items with aria-checked. Defaults to false; the commands of one element that toggle it set it, e.g. ElementInlineCommand.

---

title

title: string;

Observable

The title of the command.

---

tooltip

tooltip: string | boolean;

Observable

The tooltip of the command. true uses the title.

Methods

_getElement()

protected _getElement(elementOrPosition?): 
  | ModelElement
  | null;

Resolves the target (see _getElementOrPosition) to an element: a position becomes its parent element. Never returns a root.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

| ModelElement | null

---

_getElementOrPosition()

protected _getElementOrPosition(elementOrPosition?): ElementOrPosition | null;

Returns the given position or element, or resolves it from the current selection when absent. Returns null for a target that is not in the document (any more), e.g. a removed element, so commands ignore such targets.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ElementOrPosition | null

---

_getPosition()

protected _getPosition(elementOrPosition?): 
  | ModelPosition
  | null;

Resolves the target (see _getElementOrPosition) to a position: an element becomes the position before it.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

| ModelPosition | null

---

_getStateFor()

protected _getStateFor(elementOrPosition?): ElementOrPositionState;

Returns whether the command is enabled and "on" for the target, before read-only mode and forceDisabled(): the one source of the state, for refresh and getState. By default, from _isEnabledFor and _isOnFor.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ElementOrPositionState

---

_isEnabledFor()

protected _isEnabledFor(elementOrPosition?): boolean;

Whether the command is enabled for the target. By default: when there is a target and it can be edited.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

boolean

---

_isOnFor()

protected _isOnFor(elementOrPosition?): boolean;

Whether the command is "on" for the target. By default: never. Commands that override it should set isToggleable.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

boolean

---

_requireElement()

protected _requireElement(elementOrPosition?): ModelElement;

Returns the element of the target (see _getElement), in execute() of a command that is enabled only for a target with an element: execute() runs only then, so there is one. Throws when there is none.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ModelElement

---

clearForceDisabled()

clearForceDisabled(id): void;

Clears the disabling done by forceDisabled with this id. When no id is left, the command is refreshed, so isEnabled follows the selection again.

Parameters

Parameter	Type
id	string

Returns

void

Overrides

Command.clearForceDisabled

---

executeFor()

executeFor(elementOrPosition, ...args): unknown;

Executes the command for the target, even when the command is disabled for the selection (execute() checks isEnabled, which follows the selection). Does nothing when the command is disabled for the target.

The target is the first argument of execute(); the other arguments are passed after it.

Parameters

Parameter	Type
elementOrPosition	ElementOrPosition
...args	unknown[]

Returns

unknown

---

forceDisabled()

forceDisabled(id): void;

Disables the command for every target until it is enabled back with clearForceDisabled for every id it was disabled with. See isForceDisabled.

Parameters

Parameter	Type
id	string

Returns

void

Overrides

Command.forceDisabled

---

getState()

getState(elementOrPosition?): ElementOrPositionState;

Returns whether the command would be enabled and "on" for the target, without changing isEnabled. Commands that change the data are disabled in read-only mode, and all commands are disabled when isForceDisabled.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ElementOrPositionState

---

refresh()

refresh(elementOrPosition?): void;

Sets isEnabled for the target (by default, the selection). See _getStateFor.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

void

Overrides

Command.refresh