Blocks

Document-level block collection: insert, iterate, HTML export.

Access:

app.blocks
app.getModule('blocks')
app.invoke('blocks.method', …)

add#

Registers a block instance in the internal list and map.

Parameters:

• block (Block | HTMLElement) — block instance

app.blocks.add(block);

create#

Creates a new block via blockManager.

Parameters:

• type (string) — block or entity type name
• data (object) — payload data

Returns: Block

app.blocks.create('text');

rebind#

Updates blockMap when a block element is replaced.

Parameters:

• block (Block | HTMLElement) — block instance
• oldEl (HTMLElement | string) — previous DOM element being replaced

app.blocks.rebind(block, oldEl);

remove#

Removes block from registry and calls block.destroy.

Parameters:

• block (Block | HTMLElement) — block instance

app.blocks.remove(block);

replace#

Swaps block instance and DOM element in registry.

Parameters:

• oldBlock (Block | HTMLElement) — previous block instance being replaced
• newBlock (Block | HTMLElement) — new block instance

app.blocks.replace(oldBlock, newBlock);

clear#

Destroys and clears all registered blocks.

app.blocks.clear();

removeBlocksInElement#

Removes all blocks found inside a container element.

Parameters:

• container (HTMLElement | string) — container element to search or clear within

app.blocks.removeBlocksInElement(el);

removeDescendantBlocks#

Removes descendant blocks inside container, excluding container itself.

Parameters:

• container (HTMLElement | string) — container element to search or clear within

app.blocks.removeDescendantBlocks(section);

mountBlocksInSubtree#

Walks DOM subtree and mounts unregistered block elements.

Parameters:

• root (HTMLElement | string) — root element for serialization

app.blocks.mountBlocksInSubtree(root);

getAll#

Returns all active block instances.

Returns: Block[]

app.blocks.getAll();

hasProtectedBlocks#

Returns whether any given blocks are protected from deletion.

Parameters:

• items (Array) — list of items to process

Returns: boolean

app.blocks.hasProtectedBlocks(selected);

findByEl#

Looks up block instance by root element.

Parameters:

• el (HTMLElement | string) — DOM element

Returns: Block|null

app.blocks.findByEl(el);

getHTML#

Serializes blocks inside container to HTML.

Parameters:

• container (HTMLElement | string) — container element to search or clear within

Returns: string

app.blocks.getHTML();

isSingleBlockSelected#

Returns whether collapsed caret is inside a single block.

Returns: boolean

app.blocks.isSingleBlockSelected();

getCurrentBlock#

Returns block at caret or data-selected, optionally filtered by type.

Parameters:

• type (string) — block or entity type name

Returns: Block|null

app.blocks.getCurrentBlock('text');

get#

Returns visually selected blocks, filtered by the given options.

Parameters:

• editable (boolean) — when true/false, only match blocks that are/aren't editable (default: no filter)
• types (Array) — only include these block type(s)
• excludeTypes (Array) — exclude these block type(s)
• topLevelOnly (boolean) — only include top-level blocks (default false)
• includeInline (boolean) — include inline blocks (default false)
• partial (boolean) — include blocks that are only partially selected (default false)
• headingLevel (number) — when filtering headings, only match this level
• listTag (string) — when filtering lists, only match this tag ('ul' / 'ol')

Returns: Block[]

app.blocks.get({ topLevelOnly: true, types: ['heading'] });

is#

Returns whether any blocks are visually selected.

Returns: boolean

app.blocks.is();

getBlocksFromElements#

Resolves block instances from elements, filtered by the given options (same shape as blocks.get).

Parameters:

• elements (Array) — DOM elements to process
• options (object) — object with the keys below
  • editable (boolean) — when true/false, only match blocks that are/aren't editable (default: no filter)
  • types (Array) — only include these block type(s)
  • excludeTypes (Array) — exclude these block type(s)
  • topLevelOnly (boolean) — only include top-level blocks (default false)
  • includeInline (boolean) — include inline blocks (default false)
  • partial (boolean) — include blocks that are only partially selected (default false)
  • headingLevel (number) — when filtering headings, only match this level
  • listTag (string) — when filtering lists, only match this tag ('ul' / 'ol')

Returns: Block[]

app.blocks.getBlocksFromElements(els, { types: ['text'] });

getBlocksInSelection#

Returns blocks intersecting the native selection range, filtered by the given options.

Parameters:

• types (Array) — only include these block type(s)
• excludeTypes (Array) — exclude these block type(s)
• topLevelOnly (boolean) — only include top-level blocks (default false)
• includeInline (boolean) — include inline blocks (default false)
• partial (boolean) — include blocks that are only partially selected (default false)
• headingLevel (number) — when filtering headings, only match this level
• listTag (string) — when filtering lists, only match this tag ('ul' / 'ol')

Returns: Block[]

app.blocks.getBlocksInSelection({ partial: true });

getBlocksFromNode#

Collects ancestor blocks from a DOM node up to editor root.

Parameters:

• node (HTMLElement | string) — DOM node

Returns: Block[]

app.blocks.getBlocksFromNode(node);

getClosestBlock#

Finds nearest block ancestor of a node.

Parameters:

• nodeOrEl (HTMLElement | string) — DOM node or element

Returns: Block|null

app.blocks.getClosestBlock(node);

getParentBlocks#

Returns parent block chain from a starting block.

Parameters:

• from (Block | HTMLElement) — block instance to start the ancestor walk from
• types (Array) — only include ancestors matching these block type(s)
• includeSelf (boolean) — include from itself in the result

Returns: Block[]

app.blocks.getParentBlocks({ from: block, types: ['layout'] });

getChildrenBlocks#

Returns descendant blocks inside a parent block.

Parameters:

• from (Block | HTMLElement) — parent block instance to collect descendants from
• types (Array) — only include descendants matching these block type(s)

Returns: Block[]

app.blocks.getChildrenBlocks({ from: layout });

getParentBlock#

Returns direct parent block of a child block.

Parameters:

• childBlock (Block | HTMLElement) — child block instance

Returns: Block|null

app.blocks.getParentBlock(child);

getClosestTopLevel#

Returns nearest top-level ancestor block.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: Block|null

app.blocks.getClosestTopLevel();

getClosestBlockByTypes#

Returns nearest block matching any of the given types.

Parameters:

• from (Block | HTMLElement) — starting block for traversal
• types (Array) — block types filter

Returns: Block|null

app.blocks.getClosestBlockByTypes(null, ['table']);

getClosestUnwrapLineInsertBlock#

Returns nearest ancestor with unwrapLineInsert meta flag.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: Block|null

app.blocks.getClosestUnwrapLineInsertBlock();

ensureTopLevelUid#

Assigns data-uid to top-level block when enabled by options.

Parameters:

• blockOrEl (Block | HTMLElement) — block instance or its root element
• force (boolean) — force operation even when normally skipped

Returns: boolean

app.blocks.ensureTopLevelUid(block, { force: true });

focusNextBlock#

Focuses next sibling block in document order.

Parameters:

• fromBlockOrEl (Block | HTMLElement) — starting block instance or element for traversal
• options (object) — object with the keys below
  • alwaysSelect (boolean) — force reselecting the block even when it is already focused
  • caret (any) — place the caret at 'start' or 'end' of the block after focusing
  • nestedCaret (boolean) — allow the caret to land inside nested child blocks (list/table/layout containers)

Returns: Block|null

app.blocks.focusNextBlock(block);

focusPrevBlock#

Focuses previous sibling block in document order.

Parameters:

• fromBlockOrEl (Block | HTMLElement) — starting block instance or element for traversal
• options (object) — object with the keys below
  • alwaysSelect (boolean) — force reselecting the block even when it is already focused
  • caret (any) — place the caret at 'start' or 'end' of the block after focusing
  • nestedCaret (boolean) — allow the caret to land inside nested child blocks (list/table/layout containers)

Returns: Block|null

app.blocks.focusPrevBlock(block);

getNextBlock#

Returns next sibling block without focusing.

Parameters:

• fromBlockOrEl (Block | HTMLElement) — starting block instance or element for traversal

Returns: Block|null

app.blocks.getNextBlock(block);

getPrevBlock#

Returns previous sibling block without focusing.

Parameters:

• fromBlockOrEl (Block | HTMLElement) — starting block instance or element for traversal

Returns: Block|null

app.blocks.getPrevBlock(block);

clearFocus#

Clears block focus via blockFocus service.

app.blocks.clearFocus();

appendBlock#

Appends block element to editor and registers it.

Parameters:

• block (Block | HTMLElement) — block instance

Returns: Block

app.blocks.appendBlock(block);

prependBlock#

Prepends block element to editor and registers it.

Parameters:

• block (Block | HTMLElement) — block instance

Returns: Block

app.blocks.prependBlock(block);

insertBlockAfter#

Inserts block in DOM and order after reference block.

Parameters:

• block (Block | HTMLElement) — block instance
• afterBlockOrEl (Block | HTMLElement) — block instance or element to insert after

Returns: Block|null

app.blocks.insertBlockAfter(block, ref);

insertBlockBefore#

Inserts block in DOM and order before reference block.

Parameters:

• block (Block | HTMLElement) — block instance
• beforeBlockOrEl (Block | HTMLElement) — block instance or element to insert before

Returns: Block|null

app.blocks.insertBlockBefore(block, ref);

insertDefaultTextBlock#

Creates and appends a default text block.

Parameters:

• data (object) — payload data

Returns: Block|null

app.blocks.insertDefaultTextBlock();