ckeditor5-elements / ElementListCommand

Class: ElementListCommand

Makes a list of the blocks, as CKEditor's list commands do, for a list of the element of its items, e.g. a bulleted list: the selected blocks go in the list, each one in an item.

const command = new ElementListCommand(editor, 'bullets', 'item', ['numbers']);

editor.commands.add('bulletedList', command);
editor.execute('bulletedList'); // The blocks of the selection.

In a list, it unwraps the list and its items, so the blocks are where the list was. In another list with the same items, e.g. a numbered list, it turns that list into its own. It is "on" in a list of its own.

Extends

• ElementContainerCommand

Constructors

Constructor

new ElementListCommand(
   editor, 
   elementName, 
   itemName, 
   otherLists?
): ElementListCommand;

Parameters

Parameter	Type	Default value	Description
editor	Editor	undefined	-
elementName	string	undefined	The name of the element of the list.
itemName	string	undefined	The name of the element of its items.
otherLists?	Iterable<string>	[]	The names of the other lists with the same items, e.g. a numbered list for a bulleted one.

Returns

ElementListCommand

Overrides

ElementContainerCommand.constructor

Properties

elementAttributes

elementAttributes: Record<string, unknown> = {};

The attributes the element must have to be the element of the command. The new elements get them.

Inherited from

ElementContainerCommand.elementAttributes

---

elementName

readonly elementName: string;

The name of the model element of the command.

Inherited from

ElementContainerCommand.elementName

---

icon

icon: string | undefined;

Observable

The icon (SVG string) of the command.

Inherited from

ElementContainerCommand.icon

---

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.

Inherited from

ElementContainerCommand.isForceDisabled

---

isOn

isOn: boolean;

Observable

Whether the target is in the element, or is one, for the commands that toggle it.

Inherited from

ElementContainerCommand.isOn

---

isToggleable

isToggleable: boolean = true;

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.

Inherited from

ElementContainerCommand.isToggleable

---

itemName

readonly itemName: string;

The name of the element of the items of the list.

---

otherLists

readonly otherLists: ReadonlySet<string>;

The names of the other lists with the same items, which the command turns into its own.

---

title

title: string;

Observable

The title of the command.

Inherited from

ElementContainerCommand.title

---

tooltip

tooltip: string | boolean;

Observable

The tooltip of the command. true uses the title.

Inherited from

ElementContainerCommand.tooltip

Methods

_canHold()

protected _canHold(
   position, 
   items, 
   name?
): boolean;

Whether an element (by default, the one of the command) can be at a position, and hold the items there: the check for wrapping them, or for renaming their parent.

Parameters

Parameter	Type
position	ModelPosition
items	Iterable<ModelItem>
name?	string

Returns

boolean

Inherited from

ElementContainerCommand._canHold

---

_canUnwrap()

protected _canUnwrap(element): boolean;

Whether the children of an element can be in its place: the check for unwrapping it.

Parameters

Parameter	Type
element	ModelElement

Returns

boolean

Inherited from

ElementContainerCommand._canUnwrap

---

_canWrap()

protected _canWrap(range): boolean;

Whether the list can be in place of the nodes of a range, and each node in an item.

Parameters

Parameter	Type
range	ModelRange

Returns

boolean

Overrides

ElementContainerCommand._canWrap

---

_createElement()

protected _createElement(writer): ModelElement;

Creates a new element of the command, with the elementAttributes.

Parameters

Parameter	Type
writer	ModelWriter

Returns

ModelElement

Inherited from

ElementContainerCommand._createElement

---

_findElement()

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

Returns the closest element of the command that the target is, or is in: by default, the selection. Never a root.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

| ModelElement | null

Inherited from

ElementContainerCommand._findElement

---

_getAncestors()

protected _getAncestors(elementOrPosition?): ModelElement[];

Returns the elements the target is, or is in (by default, the selection), the inner first: an element and its ancestors, or the parent of a position and its ancestors. Not the root.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ModelElement[]

Inherited from

ElementContainerCommand._getAncestors

---

_getBlocks()

protected _getBlocks(elementOrPosition?): ModelElement[];

Returns the blocks of the target, by default of the selection: the selected blocks, or the block-level element the target is, or is in (e.g. the paragraph with the cursor, a selected horizontal line, or a block quote).

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ModelElement[]

Inherited from

ElementContainerCommand._getBlocks

---

_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

Inherited from

ElementContainerCommand._getElement

---

_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

Inherited from

ElementContainerCommand._getElementOrPosition

---

_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

Inherited from

ElementContainerCommand._getPosition

---

_getSelectedRanges()

protected _getSelectedRanges(elementOrPosition?): 
  | ModelRange[]
  | null;

Returns the ranges of the selected content, when the command is for the selection, and the selection is content, not a cursor nor an element.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

| ModelRange[] | null

Inherited from

ElementContainerCommand._getSelectedRanges

---

_getStateFor()

protected _getStateFor(elementOrPosition?): ElementOrPositionState;

Enabled when the target can be edited, and is in a list with the same items, or its blocks can go in a list. "On" in a list of its own. Both from the list, found once.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ElementOrPositionState

Overrides

ElementContainerCommand._getStateFor

---

_getWrapRange()

protected _getWrapRange(elementOrPosition?): ModelRange | null;

Returns the range to wrap: from the first block of the target to the last, as siblings: the blocks themselves, or their ancestors in the parent they share. null when the element cannot wrap them (see _canWrap).

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

ModelRange | null

Inherited from

ElementContainerCommand._getWrapRange

---

_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

Inherited from

ElementContainerCommand._isEnabledFor

---

_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

Inherited from

ElementContainerCommand._isOnFor

---

_keepSelection()

protected _keepSelection(
   writer, 
   change, 
   ranges?
): void;

Changes the content of ranges, by default the ones of the selection, and selects the same content then: the ends of the ranges stick to the content, so they follow it into new elements and out of them, which the selection does not.

Parameters

Parameter	Type
writer	ModelWriter
change	() => void
ranges?	Iterable<ModelRange>

Returns

void

Inherited from

ElementContainerCommand._keepSelection

---

_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

Inherited from

ElementContainerCommand._requireElement

---

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

Inherited from

ElementContainerCommand.clearForceDisabled

---

execute()

execute(elementOrPosition?): void;

Unwraps the list the target is in, or turns it into this one, or wraps the blocks of the target in a new list.

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

void

Overrides

ElementContainerCommand.execute

---

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

Inherited from

ElementContainerCommand.executeFor

---

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

Inherited from

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

Inherited from

ElementContainerCommand.getState

---

isElement()

isElement(node): node is ModelElement;

Whether a node is an element of the command: it is named elementName, and has the elementAttributes.

Parameters

Parameter	Type
node	| ModelDocumentFragment | ModelItem | null

Returns

node is ModelElement

Inherited from

ElementContainerCommand.isElement

---

refresh()

refresh(elementOrPosition?): void;

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

Parameters

Parameter	Type
elementOrPosition?	ElementOrPosition

Returns

void

Inherited from

ElementContainerCommand.refresh