RTElements

An interface for retrieving and managing rich text elements.

Hooks provide access to rich text elements and related data from inside React components. Unlike data accessed using static methods, hooks will cause the component to rerender when the data changes.

Returns a rich text element by ID or null if the element does not exist.

useRichTextElement<T extends RTElement>(id: string): T | null;

Returns a { [id]: RTElement } map of rich text elements by ID. If a requested element does not exist, it is ommited from the map.

Optionally, the returned elements can be filtered by passing in RTElementFilters. See the RTElementFilters section for filtering options.

useRichTextElements<T extends RTElement>(elementIds: string[], filters?: RTElementFilters): RTElementMap<T>;

Retrieves rich text elements by ID. If provided a single ID string, returns the matching rich text element. If provided an array of IDs, returns a { [id]: RTElement } map of the corresponding rich text elements.

Optionally, when getting multiple rich text elements, the returned elements can be filtered by passing in RTElementFilters. See the RTElementFilters section for filtering options.

Throws a RichTextElementNotFoundError if a requested element does not exist.

// Get a single element
RichTextElements.get<T extends RTElement>(elementId: string): T

// Get multiple elements
RichTextElements.get<T extends RTElement>(
  elementId: string[],
  filters?: RTElementFilters
): RTElementMap<T>

Retrieves all rich text elements as a { [id]: RTElement } map.

Optionally, the returned elements can by filtered by passing in RTElementFilters. See the RTElementFilters section for filtering options.

RichTextElements.getAll<T extends RTElement>(filters?: RTElementFilters): RTElementMap<T>

Filters rich text elements according to the provided filters.

The provided elements must be of registered types, or a RichTextElementTypeNotRegisteredError will be thrown.

RichTextElements.filter<T extends RTElement>(
  element: RTElementMap<T>,
  filters: RTElementFilters
): RTElementMap<T>

RTElementFilters

Options for filtering rich text elements.

Creates a new rich text element and dispaches a rich-text-element:create event. Returns the newly created element.

To create an element, the element type must first be registered using the RichTextElements.register method.

If the element has attached files, the IDs of the file references must be listed as the files property. The element will automatically be added as a parent on the attached files.

If the element has nested elements (only supported on 'block' level elements), the element will automatically be added as a parent on those elements.

• Throws a RichTextElementTypeNotRegisteredError if the element type is not registered.

• Throws a RichTextElementValidationError if the element contains invalid data or is missing required fields.

RichTextElements.create<
  TElement extends RTElement,
  TData extends CreateRTElementData,
>(core: Core, data: TData): TElement;

CreateRTElementData

In addition to the data below, you can include any custom data required by your rich text element.

Creates a new rich text element of the given type. Dispatches a rich-text-element:create event and returns the newly created element.

• Throws a RichTextElementTypeNotRegisteredError if the element type is not registered.

RichTextElements.createOfType<
  TElement extends RTElement,
>(core: Core, type: string, data?: DataInsert | RTFragment): TElement

Updates a rich text element and dispaches a rich-text-element:update event. Returns the updated rich text element.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a RichTextElementTypeNotRegistered if the element type is not registered

• Throws a RichTextElementValidationError if the updated element is invalid.

RichTextElements.update<
  TElement extends RTElement,
  TData extends CreateRTElementData,
>(core: Core, elementId: string, data: TData): TElement

UpdateRTElementData

In addition to the data below, you can include any custom data required by your rich text element.

Deletes a rich text element and dispaches a rich-text-element:delete event. Returns the deleted element.

• Throws a RichTextElementNotFoundError if the element does not exist.

Deleted rich text elements can be restored using the RichTextElements.restore method.

RichTextElements.delete<TElement extends Element>(core: Core, elementId: string): TElement

Restores a deleted rich text element and dispatches a rich-text-element:restore event. Returns the restored element.

• Throws a RichTextElementNotFoundError if the element does not exist.

RichTextElements.restore<
  TElement extends RTElement,
>(core: Core, elementId: string): TElement

Permanently deletes a rich text element and dispatches a rich-text-element:delete-permanently event. Returns the deleted element.

• Throws a RichTextElementNotFoundError if the element does not exist.

Permanently deleted rich text elements cannot be restored.

RichTextElement.deletePermanently<
  TElement extends RTElement,
>(core: Core, elementId: string): TElement

Adds parent references to a rich text element and dispaches a rich-text-element:add-parents event. Returns the updated rich text element.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a ParentReferenceValidationError if any of the parent references are invalid.

RichTextElements.addParents<
  TElement extends RTElement
>(core: Core, elementId: string, parents: ParentReference[]): TElement

Removes parent references from a rich text element and dispaches a rich-text-element:remove-parents event. Returns the updated rich text element.

• Throws a RichTextElementNotFoundError if the element does not exist.

RichTextElements.removeParents<
  TElement extends RTElement
>(core: Core, elementId: string, parents: ParentReference[]): TElement

Nests rich text block elements into another rich text block element and dispatches a rich-text-element:nest event. Returns the updated element.

The elements is added as a parent on the nested elements.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a RichTextElementValidationError if the element is not a block level element.

• Throws a RichTextElementValidationError if any of the nested elements do not exist or are not block level elements.

RichTextElements.nest<
  TElement extends RTBlockElement
>(core: Core, elementId: string, nestElementIds: string[]): TElement

Unnests rich text block elements from another rich text block element and dispatches a rich-text-element:unnest event. Returns the updated element.

The elements is removed as a parent from the nested elements.

• Throws a RichTextElementNotFoundError if the element or any of the nested elements do not exist.

RichTextElements.unnest<
  TElement extends RTBlockElement
>(core: Core, elementId: string, unnestElementIds: string[]): TElement

Adds files to a rich text element and dispaches a rich-text-element:add-files event. Returns the updated rich text element.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a FileReferenceNotFoundError if any of the file references do not exist.

The element is added as a parent on the file references.

RichTextElements.addFiles(core: Core, elementId: string, fileIds: string[]): RTElement

Removes files from a rich text element and dispatches a rich-text-element:remove-files. Returns the updated rich text element.

The element is removed as a parent from the file references.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a FileReferenceNotFoundError if any of the file references do not exist.

RichTextElements.removeFiles(core: Core, elementId: string, fileIds: string[]): RTElement

Replaces files in a rich text element (removing current files and adding given files) and dispatches a rich-text-element:replace-files event. Returns the updated rich text element.

The element will be added as a parent onto the added files, and removed as a parent from the removed files.

• Throws a RichTextElementNotFoundError if the element does not exist.

• Throws a FileReferenceNotFoundError if any of the file references do not exist.

RichTextElements.replaceFiles(core: Core, elementId: string, fileIds: string[]): RTElement

Registers a new rich text element type and dispaches a rich-text-element:register event.

RichTextElements.register(
  core: Core,
  config: RTBlockElementConfig | RTInlineElementConfig,
): void

Unregisters a rich text element type and dispaches a rich-text-element:unregister event.

RichTextElements.unregister(core: Core, type: string): void

Converts one or more rich text elements to a plain text string. Void elements are converted using their toPlainText method. If they do not have such a method, they are omited.

• Throws a RichTextElementNotFoundError if any of the elements' nested elements do not exist.

RichTextElements.toPlainText(element: RTElement | RTElement[]): string

Returns the initialzed custom data for a new rich text element. The data is initialized using the element type config's initializeData method if present, otherwise, returns an empty object.

• Throws a RichTextElementTypeNotRegistered error if the element type is not registered.

RichTextElements.initializeData<TData = {}>(
  type: string,
  fromData?: DataInsert | RTFragment
): TData

Converts a rich text block element from one type to another. Note that his method does not actually update the element, it simply returns the converted element.

The conversion of an element from one type to another follows these steps:

1. The default data for the new element type is generated using the element's initializeData method (if defined).

2. The conversion data is generated using the new element's convertData method (if defined).

3. The element's custom data fields (if present) are removed.

4. If converting to a void element type, children is removed. Conversly, if converting from a void element type to a non-void element type, children (consisting of a RTFragment containing the original element's plain text value) is added.

5. The default data (generated in step 1) is merged into the element.

6. The conversion data (generated in step 2) is merged into the element.

7. The element's type is changed to the new type.

• Throws a RichTextElementTypeNotRegistered if the current or new element type is not registered

• Throws a InvalidParameterError if the either the element or the new element type are not 'block' level elements.

• Throws a RichTextElementValidationError if the updated element is invalid.

RichTextElements.convert<
  TElement extends RTBlockElement,
>(element: RTBlockElement, type: string): TElement

Loads rich text elements into the store and dispatches a rich-text-element:load event.

RichTextElements.load(core: Core, element: RTElement[]): void

Clears all rich text elements from the store. This method is only intended for use in tests, do not use within your extension code.

RichTextElements.clearElements(): void

Clears all registered rich text element configs from the store. This method is only intended for use in tests, do not use within your extension code.

RichTextElements.clearRegistered(): void

See below the table for more details on the data passed by rich text element related events.

RTElement events are dispatched with one of the following types of data.

RTElement

See the RTElement interface page.

RTElementConfig

See the RTElementConfig interface page.

ParentReference

See the ParentReference interface page.

UpdateRTElementEventData

RTElementChanges

In addition to the data below, the changes data may include custom data according to the rich text element type.

AddParentsToRTElementEventData

RemoveParentsFromRTElementEventData

NestRTElementEventData

RemoveParentsFromRTElementEventData

AddFilesToRTElementEventData

RemoveFilesFromRTElementEventData

ReplaceFilesInRTElementEventData