Module Editing Mode

Plan: Enterprise only. Available from v2.67.0.

By default, the Plugin Editor opens emails for editing (entityType: 'email'). With Module Editing Mode you can launch the same editor to create or edit a single reusable module (a stripe, structure, or container) stored in your plugin's module library — without opening a full email.

This lets you use Stripo as a standalone module editor inside your own application: build a "New module" button, an "Edit module" action in your library UI, and let users design modules in the same drag-n-drop editor they already know.

The mode is controlled entirely through initialization parameters. No new permanent UI elements are added to the editor.

Module Editing Mode is available on the Enterprise plan only. If the editor is initialized with entityType: 'module' on any other plan, it does not initialize and shows a toaster notification signaling that the Enterprise plan is required for this mode.

Enabling the Mode ​

Pass entityType: 'module' when initializing the editor:

window.UIEditor.initEditor(domContainer, {
  metadata: { /* ... */ },
  entityType: 'module',
  onTokenRefreshRequest: function (callback) { /* ... */ }
  // + module parameters, see below
});

What happens next depends on whether you pass a moduleId:

• moduleId provided → the editor opens that existing module for editing.
• moduleId omitted → the editor starts creating a new module (moduleType is required).

If entityType is omitted or set to email, the editor works in the regular email-editing mode and every parameter on this page is ignored.

Editing an Existing Module

Pass moduleId to open a module that already exists in your library:

window.UIEditor.initEditor(domContainer, {
  metadata: { 
     /* other parameters */
     moduleId: '12345'
  },
  entityType: 'module',
  onTokenRefreshRequest: function (callback) { /* ... */ }
});

Where to get a moduleId: use the Modules API (GET /api/v1/customblocks/v4/modules/list) to list the modules that belong to your plugin. It supports filtering by key, category, tags, name, synchronization status, and ID, with pagination — and every returned module includes its id, which you pass here. The auth token must have the API role.

When moduleId is provided:

• Any html and css passed in the configuration are ignored — the module content is loaded from the plugin database.
• The editor validates that the module:
  • is not deleted,
  • belongs to the current pluginId,
  • is available for editing.
• If validation fails — the module is not found, deleted, or does not belong to this plugin — the editor does not initialize and a toaster notification is shown to the user (see Error handling).

When both moduleId and moduleType are provided, the editor treats it as editing an existing module and ignores moduleType.
The metadata parameters (moduleName, moduleDescription, moduleCategoryId, moduleTags) are also ignored when editing an existing module — its existing metadata is preserved.

Creating a New Module

Omit moduleId and pass moduleType to start a new module:

window.UIEditor.initEditor(domContainer, {
  metadata: { /* ... */ },
  entityType: 'module',
  moduleType: 'STRUCTURE',      // 'STRIPE' | 'STRUCTURE' | 'CONTAINER'
  key: 'shared-modules',        // optional: target folder storage key
  css: '...',                   // optional: see CSS below
  onTokenRefreshRequest: function (callback) { /* ... */ }
});

Rules:

• moduleType is required and must be one of STRIPE, STRUCTURE, or CONTAINER. If it is missing or invalid, the editor does not initialize and a toaster notification is shown (see Error handling).
• key (optional) is the storage key of the folder the new module will be saved to — the same Storage Key ID you configure for module folders (see Modules Library). If omitted, the first folder the user is allowed to write to is used.
• An empty module of the chosen type is prepared, but it is persisted only after the first change to the module content or its metadata (see Saving).

The html parameter is not used in Module Editing Mode. A new module always starts empty for the chosen moduleType; an existing module is always loaded from the database by moduleId. Any html passed at init is ignored in both cases.

CSS

• If css is provided, it is applied to the new module on creation.
• If css is not provided, the editor's default CSS is applied.
• css applies only when creating a new module; it is ignored when editing an existing module (moduleId).

Initial Metadata for a New Module

When creating a new module you can preset its metadata so the module is saved with the right name, description, category, and tags — without requiring the end user to fill them in manually.

window.UIEditor.initEditor(domContainer, {
  metadata: { /* ... */ },
  entityType: 'module',
  moduleType: 'STRIPE',
  moduleName: 'Promo header',
  moduleDescription: 'Reusable promotional header with CTA',
  moduleCategoryId: 12,
  moduleTags: ['promo', 'header'],
  onTokenRefreshRequest: function (callback) { /* ... */ }
});

Parameter	Type	Default	Description
moduleName	string	New module	Name of the new module. Maximum length is 200 characters; longer values are trimmed to 200.
moduleDescription	string	empty	Description of the new module. Maximum length is 500 characters; longer values are trimmed to 500.
moduleCategoryId	number	Uncategorized	ID of the category assigned to the new module. Silently ignored if the category does not exist or is unavailable for this plugin — initialization is not blocked and no toaster is shown.
moduleTags	string[]	no tags	Tags applied to the new module.

These parameters apply only when creating a new module (when moduleId is not provided). If moduleId is provided, all four are ignored without error. If a parameter is omitted, the default value above is used.

Saving

Saving in Module Editing Mode follows your plugin's existing save configuration:

• Autosave — if autosave is enabled in your Plugin configuration, it works in module mode too. If it is disabled, only manual saving is available via window.StripoEditorApi.actionsApi.save(). See Autosaving.
• New modules are written to the library only after the first change to the module content or its metadata. Opening the editor and closing it without edits creates nothing.
• The module is stored in Stripo's module database and assigned to your plugin and the target folder key.

The module save callbacks already available in the plugin are supported in this mode:

• onBeforeModuleSave — called on save and update, lets you preprocess the module before it is stored.
• validateModuleSave — called on save and update, lets you allow or block the operation.

Module Details Dialog

In Module Editing Mode the module metadata (name, description, category, tags) is edited in a details dialog, similar to account mode. You can open this dialog programmatically — for example, from a "Show module data" button in your own UI:

window.StripoEditorApi.modulesApi.openModuleDetailsDialog();

See JavaScript API for the full API surface.

Limitations

In entityType: 'module' mode the following are not supported:

• versioning;
• version history;
• simultaneous (collaborative) editing.

The following work as usual:

• autosave (when enabled);
• manual saving;
• standard editing logic.

Compatibility With Other Settings

• html passed at init is always ignored in this mode (a new module starts empty; an existing module is loaded by moduleId).
• css is honored only when creating a new module and ignored when editing an existing one.
• Version History does not work in Module Editing Mode — version-history controls (e.g. versionHistoryButtonSelector) have no effect, because version history is disabled in this mode.
• Email-specific metadata and features (e.g. UTM, email title/preheader) do not apply to modules.
• All other editor configuration — panel position, locale, permissions, image gallery, fonts, etc. — behaves the same as in email mode.

Error Handling

Errors during initialization are surfaced to the user through the standard toaster. HTTP error codes (400 / 403) are not returned to the initialization function — initialization simply does not complete and the user sees a notification.

Situation	Message
entityType: 'module' on a non-Enterprise plan	Editor does not initialize; a toaster notification signals that this mode requires upgrading to the Enterprise plan.
Invalid or unavailable moduleId (not found, deleted, or not owned by this plugin)	Module not found or unavailable for this plugin
Missing or invalid moduleType (create mode)	Invalid module type. Allowed values: Stripe, Structure, Container.

To display these messages, your plugin implementation must support notifications. See Notification Settings.

Example

// Edit an existing module
window.UIEditor.initEditor(document.getElementById('editor'), {
  metadata: { 
    /* other mandatory parameters */
    moduleId: '8842', 
  },
  entityType: 'module',
  onTokenRefreshRequest: refreshToken
});

// Create a new "structure" module preset with metadata, saved to a specific folder
window.UIEditor.initEditor(document.getElementById('editor'), {
  metadata: { /* ... */ },
  entityType: 'module',
  moduleType: 'STRUCTURE',
  key: 'marketing-modules',
  moduleName: 'Footer · Legal',
  moduleDescription: 'Standard legal footer',
  moduleCategoryId: 8,
  moduleTags: ['footer', 'legal'],
  onBeforeModuleSave: function (data) { return { canSave: true }; },
  validateModuleSave: function (data) { return { canSave: true }; },
  onTokenRefreshRequest: refreshToken
});