ExternalMergeTagsLibrary

Version Availability

This class is available starting from v3.11.0

Core class for integrating external merge tags libraries with the Stripo Email Editor.

class ExternalMergeTagsLibrary

Description

ExternalMergeTagsLibrary enables integration of your own catalog of merge tags into the input fields of the Stripo Email Editor. When a library is registered, the editor opens it instead of the built-in merge tags picker in the following places:

• The merge tag icon of text inputs in the settings panel (for example, button text, image alt text, menu and social items, UTM parameters) and of RICH_TEXT UI elements with the has-merge-tag-icon attribute
• The merge tag icon of link fields
• The merge tag icon of the image path field
• The Insert merge tag option of the email Subject and Hidden Preheader fields

The merge tags selector of the text block is not affected by this class. To replace it, override UIElementType.MERGETAGS with a custom UI element as shown in the External Merge Tags Selector tutorial. Both integrations can be used side by side.

Import

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

Properties

api

api: BaseApi

Type

BaseApi

The API instance providing access to editor configuration, translations, and other core functionality. Automatically injected by the framework.

Methods

openMergeTagsLibrary()

Opens the external merge tags library interface for merge tag selection.

openMergeTagsLibrary(
  currentValue: string,
  onSelectCallback: ExternalMergeTagSelectCallback,
  onCancelCallback: ExternalMergeTagCancelCallback,
  context: ExternalMergeTagsContext
): void

Parameters

Name	Type	Description
currentValue	string	Current value of the whole field the library is opened for (e.g., input text or link URL)
onSelectCallback	ExternalMergeTagSelectCallback	Called with the merge tag value when user selects a merge tag
onCancelCallback	ExternalMergeTagCancelCallback	Called when user cancels
context	ExternalMergeTagsContext	Information about the field the library is opened for

Usage Notes

• The selected value is inserted as-is: in text fields, at the cursor position (limited by the field's maximum length); in link fields, it replaces the whole URL
• Only the first call of onSelectCallback or onCancelCallback is taken into account
• If the method throws an error, the editor falls back to the built-in merge tags picker

Type Definitions

ExternalMergeTagsContext

Describes the field the library is opened for.

interface ExternalMergeTagsContext {
  fieldType: ExternalMergeTagsFieldType;
  fieldName?: string;
}

Property	Type	Description
fieldType	ExternalMergeTagsFieldType	'link' for link fields, 'text' for all other fields (text inputs, image path, Subject, Hidden Preheader)
fieldName	string	(Optional) Identifier of the field. For RICH_TEXT UI elements, it equals the element's name attribute

ExternalMergeTagsFieldType

Type of the field the library is opened for.

type ExternalMergeTagsFieldType = 'text' | 'link';

Callback Types

type ExternalMergeTagSelectCallback = (value: string) => void;
type ExternalMergeTagCancelCallback = () => void;

Example

import {
  ExtensionBuilder,
  ExternalMergeTagCancelCallback,
  ExternalMergeTagSelectCallback,
  ExternalMergeTagsContext,
  ExternalMergeTagsLibrary,
} from '@stripoinc/ui-editor-extensions';
import { MergeTagsModal } from './MergeTagsModal'; // your own modal implementation

class MyMergeTagsLibrary extends ExternalMergeTagsLibrary {
  openMergeTagsLibrary(
    currentValue: string,
    onSelectCallback: ExternalMergeTagSelectCallback,
    onCancelCallback: ExternalMergeTagCancelCallback,
    context: ExternalMergeTagsContext
  ): void {
    // Offer only URL merge tags for link fields
    const mergeTags = context.fieldType === 'link'
      ? [{ label: this.api.translate('Profile page'), value: '*|PROFILE_URL|*' }]
      : [
          { label: this.api.translate('First Name'), value: '*|FNAME|*' },
          { label: this.api.translate('Last Name'), value: '*|LNAME|*' }
        ];

    new MergeTagsModal(mergeTags).open({
      onSelect: (mergeTag) => onSelectCallback(mergeTag.value),
      onClose: () => onCancelCallback()
    });
  }
}

export default new ExtensionBuilder()
  .withExternalMergeTagsLibrary(MyMergeTagsLibrary)
  .build();

Full Example Implementation: How to Integrate External Merge Tags — one merge tags modal shared by the text block and input fields.