Base API shared by every block instance (Block, InlineBlock, and all concrete block types). Instances are obtained via app.block.get(), app.blocks.findByEl(el), or app.blocks.create(type).
Class: CommonBlock
Access:
app.block.get()
app.blocks.findByEl(el)
app.blocks.create(type)App code:
const block = app.block.get();Plugin:
const block = this.app.block.get();getEl#
Returns the root DOM element bound to this block instance.
Returns: HTMLElement
block.getEl();getTag#
Returns the lowercase HTML tag name of the root element, or an empty string when the element is missing.
Returns: string
block.getTag();getId#
Returns the id attribute value from the root element.
Returns: string
block.getId();setId#
Sets or removes the id attribute. Pass null or false to remove it.
Parameters:
- value (
any) — value to store
Returns: void
block.setId('section-intro');getPlaceholder#
Returns the data-placeholder text from the placeholder element.
Returns: string
block.getPlaceholder();setPlaceholder#
Sets or removes data-placeholder on the placeholder element. Does nothing when no placeholder element exists.
Parameters:
- value (
any) — value to store
Returns: void
block.setPlaceholder('Type here…');getPlaceholderEl#
Returns the element that carries the placeholder attribute. The default implementation returns the root element.
Returns: HTMLElement
block.getPlaceholderEl();getUid#
Returns the stable data-uid identifier stored on the root element.
Returns: string
block.getUid();setUid#
Sets or removes the data-uid attribute on the root element.
Parameters:
- value (
any) — value to store
Returns: void
block.setUid('uid-42');getTime#
Returns the data-time timestamp stored on the root element.
Returns: string
block.getTime();setTime#
Sets or removes the data-time attribute on the root element.
Parameters:
- value (
any) — value to store
Returns: void
block.setTime(Date.now());getClassnames#
Returns user-facing class names as a space-separated string, excluding internal editor classes such as rx-block-has-placeholder.
Returns: string
block.getClassnames();setClassnames#
Replaces the element class attribute with a string or array of class names.
Parameters:
- value (
any) — value to store
Returns: void
block.setClassnames('lead muted');removeClassnames#
Removes all user-facing classes from the root element while preserving internal editor classes.
Returns: void
block.removeClassnames();getAttrs#
Returns a plain object of custom HTML attributes, excluding internal editor and schema attributes.
Returns: object
block.getAttrs();setAttrs#
Applies multiple custom attributes from an object. Pass null or false as a value to remove an attribute.
Parameters:
- attrs (
object) — HTML attributes ({ name: value };true/nullsets a boolean attribute)
Returns: void
block.setAttrs({ role: 'note', tabindex: '0' });getStyles#
Parses the inline style attribute into a camelCase property object.
Returns: object
block.getStyles();setStyles#
Applies inline styles from an object and removes the style attribute when it becomes empty.
Parameters:
- styles (
object) — CSS declarations ({ color: '#f00' }or{ backgroundColor: 'yellow' })
Returns: void
block.setStyles({ color: '#333', marginTop: '1em' });getClassname#
Detects which variant class is active. With an object map, returns the matching key; with an array, returns the matched class name.
Parameters:
- items (
Array) — list of items to process - fallback (
any) — fallback when key is missing
Returns: string
block.getClassname({ left: 'align-left', right: 'align-right' });setClassname#
Switches a variant class by removing known alternatives from items and adding classname. Ignores empty values and the sentinel none.
Parameters:
- classname (
string) — CSS class name to add or remove - items (
Array) — list of items to process
Returns: void
block.setClassname('align-center', { left: 'align-left', center: 'align-center' });getFigcaptionEl#
Returns the nested <figcaption> element when the root element is a <figure>.
Returns: HTMLElement | null
block.getFigcaptionEl();getMeta#
Returns the static metadata object defined on this block class.
Returns: object
block.getMeta();isEditable#
Returns true when the block metadata marks the content as editable.
Returns: boolean
block.isEditable();getType#
Returns the block type string from metadata, such as text or image.
Returns: string
block.getType();getContent#
Returns the trimmed innerHTML of the root element.
Returns: string
block.getContent();isTopLevel#
Returns true when the block is a direct child of the editor root or of a schema section wrapper.
Returns: boolean
block.isTopLevel();isMustNotBeEmpty#
Returns true when metadata sets canBeEmpty to false.
Returns: boolean
block.isMustNotBeEmpty();isInline#
Returns whether this instance is an inline block. Standard Block subclasses always return false. InlineBlock (and its subclasses) return the inline flag from block metadata (typically true).
Returns: boolean
block.isInline();isType#
Checks whether the block type matches any of the given type names. Accepts multiple arguments or a single array.
Parameters:
- ...types (
Array) — block types filter
Returns: boolean
block.isType('text', 'heading');getItemBlocks#
Finds descendant item blocks inside the root element. Defaults to list-item and todo-item when no types are provided.
Parameters:
- types (
Array) — block types filter
Returns: Array<Block>
block.getItemBlocks();closestTag#
Walks up the DOM from the root element and returns the nearest ancestor matching the CSS selector.
Parameters:
- selector (
string) — CSS selector
Returns: HTMLElement | null
block.closestTag('figure');closestBlockType#
Finds the nearest registered parent block whose type is in types.
Parameters:
- types (
Array) — block types filter - includeSelf (
boolean) — include the starting element/block itself in the result
Returns: Block | null
block.closestBlockType(['list', 'todo']);isNonEditable#
Returns true when the root element has data-noneditable="true".
Returns: boolean
block.isNonEditable();setNonEditable#
Marks the block as non-editable (data-noneditable="true") and sets contenteditable="false" when appropriate. Pass false to clear.
Parameters:
- enabled (
boolean) — whether the feature is enabled
Returns: boolean
block.setNonEditable();clearNonEditable#
Removes the non-editable flag and restores contenteditable when the block type is editable.
Returns: boolean
block.clearNonEditable();getText#
Returns normalized plain text for clipboard export, with invisible markers removed and whitespace collapsed.
Returns: string
block.getText();isNonDeletable#
Returns true when the root element has data-nondeletable="true".
Returns: boolean
block.isNonDeletable();setNonDeletable#
Marks the block as non-deletable (data-nondeletable="true"). Pass false to clear.
Parameters:
- enabled (
boolean) — whether the feature is enabled
Returns: boolean
block.setNonDeletable();clearNonDeletable#
Removes the non-deletable flag from the block root element.
Returns: boolean
block.clearNonDeletable();isProtected#
Base implementation always returns false. Subclasses such as Block override this to reflect edit and delete protection.
Returns: boolean
block.isProtected();isDeletionProtectedOnly#
Base implementation always returns false. Subclasses override this when only deletion should be blocked.
Returns: boolean
block.isDeletionProtectedOnly();isContentFullySelected#
Returns true when the current editor selection fully covers the root element.
Returns: boolean
block.isContentFullySelected();remove#
Unregisters the block from the block registry and removes its root element from the DOM.
Returns: boolean
block.remove();isEmpty#
Returns true when the root element has no visible text or element content other than a lone <br>.
Returns: boolean
block.isEmpty();removeBlockAttrs#
Strips editor output attributes from the given element and removes its data-block marker.
Parameters:
- el (
HTMLElement | string) — DOM element
Returns: void
block.removeBlockAttrs(block.getEl());removeIfVisuallyEmpty#
Removes the root element from the DOM when it is visually empty. Returns false when the element is not empty or has no parent.
Returns: boolean
block.removeIfVisuallyEmpty();getData#
Returns common serializable fields (id, classname, styles, attrs, placeholder, uid, time, noneditable, nondeletable). Subclasses extend this with type-specific data.
Returns: object
block.getData();clearContent#
Unregisters descendant blocks and clears the root element innerHTML.
Returns: boolean
block.clearContent();setContent#
Replaces the root element HTML and remounts nested blocks found in the new markup.
Parameters:
- content (
object | string) — content to render (string, Node, or array)
Returns: boolean
block.setContent('Updated content');getUIButtonsOverride#
Reads toolbar or dropdown button overrides from block metadata for the given UI surface.
Parameters:
- uiType (
string) — UI component type identifier - dropdown (
any) — dropdown instance
Returns: { replace: string[] | null, add: string[] | null, hide: string[], click: boolean } | null
block.getUIButtonsOverride('format');isUIButtonAllowed#
Checks whether a toolbar button should be visible for this block, based on metadata overrides.
Parameters:
- name (
string) — identifier name - uiType (
string) — UI component type identifier
Returns: { visible: boolean, enabled: boolean }
block.isUIButtonAllowed('bold', 'format');toHTML#
Serializes the block root element to an output-ready HTML string.
Returns: string
block.toHTML();getSerializableContent#
Returns trimmed inner HTML suitable for persistence, with inline blocks finalized and editable output cleaned.
Parameters:
- root (
HTMLElement | string) — root element for serialization
Returns: string
block.getSerializableContent();cleanEditableOutput#
Removes selection markers and invisible characters from editable output, and normalizes lone <br> or non-breaking-space placeholders.
Parameters:
- el (
HTMLElement | string) — DOM element
Returns: void
block.cleanEditableOutput(cloneEl);update#
Applies common block fields from a data object (id, classname, styles, attrs, placeholder, uid, time, noneditable, nondeletable).
Parameters:
- data (
object) — payload data
Returns: void
block.update({ classname: 'highlight', placeholder: 'Add text…' });getContentText#
Returns plain text from the resolved content root.
Parameters:
- options (
object) — object with the keys below- scope (
string) — content root scope (e.g.'main','todo-text','blockquote','caption'); default uses the block element itself - excludeNestedLists (
boolean) — for list-item / todo-item blocks, omit nested lists from the text
- scope (
Returns: string
block.getContentText();
block.getContentText({ scope: 'main' });getContentHTML#
Returns HTML from the resolved content root.
Parameters:
- options (
object) — object with the keys below- scope (
string) — content root scope (e.g.'main','todo-text','blockquote','caption'); default uses the block element itself - stripBlocks (
boolean) — unwrap nested block-level tags into inline HTML - joiner (
string) — string inserted between unwrapped block pieces whenstripBlocksis true - excludeNestedLists (
boolean) — for list-item / todo-item blocks, omit nested lists from the HTML
- scope (
Returns: string
block.getContentHTML();
block.getContentHTML({ stripBlocks: true });