ModificationDescription

Class for providing context about template modifications.

class ModificationDescription

Description

ModificationDescription provides metadata about modifications for version history, undo/redo functionality, and internationalization support. Every modification applied through the Template Modifier API requires a description to document the change and provide context for collaboration and history tracking.

Import

import { ModificationDescription } from '@stripoinc/ui-editor-extensions';

Constructor

constructor(key: string)

Parameters

Parameter	Type	Description
key	string	Description text or internationalization key

Example

// Simple text description
const description = new ModificationDescription('Changed button color');

// Internationalization key
const i18nDescription = new ModificationDescription('actions.button_color_changed');

Methods

withParams()

Adds parameters for template string interpolation.

withParams(params: Record<string, any>): ModificationDescription

Parameters

Parameter	Type	Description
params	Record<string, any>	Key-value pairs for template interpolation

Returns

ModificationDescription - Returns this instance for method chaining

Description

This method allows you to provide dynamic values that will be interpolated into the description text. Parameters are replaced in the description string using {paramName} syntax.

Example

const description = new ModificationDescription('Changed color from {oldColor} to {newColor}')
    .withParams({
        oldColor: '#000000',
        newColor: '#FF0000'
    });
// Results in: "Changed color from #000000 to #FF0000"

---

asHidden()

Version Availability

This method is available starting from v3.11.0

Marks the modification as a background change.

asHidden(hidden: boolean = true): ModificationDescription

Parameters

Parameter	Type	Description
hidden	boolean	(Optional) Pass false to keep the modification visible. Defaults to true

Returns

ModificationDescription - Returns this instance for method chaining

Description

The modification is applied to the template as usual, but the patch it produces is kept out of the version history UI and out of undo/redo, so the user never sees (nor can accidentally undo) a change they did not make. The change still belongs to the document, so restoring an older version keeps it consistent with the rest of the template.

Usage Notes

• Use for technical changes an extension makes on its own, without a user action (e.g., migrating block markup or syncing service attributes)
• A hidden modification is not a separate undo/redo step: when it follows a visible modification, it is undone and redone together with that modification
• The patch is saved like any other, but the host application is not notified about it: the onDataChanged callback stays silent for background modifications
• Do not rely on onDataChanged to track changes an extension makes this way
• Changes made in response to user actions should stay visible, so users can find them in the version history and undo them

Example

this.api.getDocumentModifier()
    .modifyHtml(node)
        .setAttribute('data-block-version', '2')
    .apply(new ModificationDescription('Migrated block markup').asHidden());

---

isHidden()

Version Availability

This method is available starting from v3.11.0

Tells whether the modification was marked as a background change via asHidden().

isHidden(): boolean

Returns

boolean - true when the produced patch must stay out of version history and undo/redo. Defaults to false

---

getValue()

Returns the description data structure.

getValue(): {key: string; params: Record<string, any>}

Returns

An object containing:

• key: The description text or i18n key
• params: The parameters object (may be undefined if not set)

Example

const description = new ModificationDescription('Button updated')
    .withParams({ type: 'primary' });

console.log(description.getValue());
// Output: { key: 'Button updated', params: { type: 'primary' } }