Stripo Editor v2 Migration Guide

This guide is primarily for users with prior experience using Stripo Editor v1, and it aims to clarify the changes and improvements introduced in v2. The guide will help you seamlessly transition from v1 to v2 by explaining the key differences in syntax, initialization, and functionality.

Editor Space

v1 Syntax

In Stripo Editor v1, two containers were required for the settings panel and the preview area:

<div id="stripoSettingsContainer"></div>
<div id="stripoPreviewContainer"></div>

v2 Syntax

In Stripo Editor v2, this has been simplified to a single container for the entire editor:

<div id="stripoEditorContainer"></div>

This change reduces the complexity of the HTML structure and streamlines the initialization process.

Editor Script

v1 Syntax

For the latest version:

https://plugins.stripo.email/static/latest/stripo.js

For a specific version:

https://plugins.stripo.email/static/rev/[version]/stripo.js

v2 Syntax

For the latest version:

https://plugins.stripo.email/resources/uieditor/latest/UIEditor.js

For a specific version:

https://plugins.stripo.email/resources/uieditor/rev/[version]/UIEditor.js

Editor Initialization

v1 Syntax

Initialization required specifying the IDs of the settings and preview containers, along with calling the window.Stripo.init function:

const stripoConfig = {
    settingsId: '[put here ID of your settings container]',
    previewId: '[put here ID of your preview container]',
    [put here your plugin JSON configuration]
}

window.Stripo.init(stripoConfig);

v2 Syntax

Initialization now involves directly passing the DOM element of the editor container to the window.UIEditor.initEditor function:

const domContainer = document.querySelector('#stripoEditorContainer');
const stripoConfig = {...};

window.UIEditor.initEditor(domContainer, stripoConfig);

This change simplifies the initialization process and provides more flexibility by allowing the direct use of DOM elements.

Initialization Parameters

v1 Syntax

The v1 initialization required multiple specific parameters:

• settingsId
• previewId
• html
• css
• apiRequestData -> emailId
• getAuthToken

const stripoConfig = {
    settingsId: '[put here ID of your settings container]',
    previewId: '[put here ID of your preview container]',
    html: '[put here HTML code of your email]',
    css: '[put here CSS code of your email]',
    apiRequestData: {
        emailId: '[put here ID of email in your external application]'
    },
    getAuthToken: function(callback) {
        const token = // get token from backend
        callback(token);
    }
}

v2 Syntax

In v2, the initialization is more streamlined with fewer required parameters and additional optional ones for enhanced functionality:

• html (only for new emails opened for the first time)
• css (only for new emails opened for the first time)
• metadata -> emailId
• onTokenRefreshRequest

Optional, but recommended for co-editing mode:

• username
• avatarUrl
• onUserListChange

const stripoConfig = {
    metadata: {
        emailId: '[put here ID of email in your external application]',
        username: '[put here full user name]',
        avatarUrl: '[put here URL of user avatar image]',
    },
    html: '...',
    css: '...',
    ​​onTokenRefreshRequest: function(callback) {
        const token = // get token from backend
        callback(token);
    },
    onUserListChange: function(usersList) {
        // Update user avatars in custom header logic
    }
}

These changes provide greater flexibility and support new features like real-time co-editing.

Editor Termination

v1 Syntax

To stop all processes when the editor is closed:

window.StripoApi.stop();

v2 Syntax

This has been updated in v2 to:

window.UIEditor.removeEditor();

The new method ensures that all editor resources are properly released, improving overall application performance.

Authentication

v1 Syntax

The POST request body for authentication in v1:

{
    "pluginId": "YOUR_PLUGIN_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "role" : "PLUGIN_EDITOR_USER_ROLE"
}

v2 Syntax

In v2, an additional userId parameter is required to enhance security and user-specific interactions:

{
    "pluginId": "YOUR_PLUGIN_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "role" : "PLUGIN_EDITOR_USER_ROLE",
    "userId": "ID_OF_CURRENT_USER"
}

This update provides better tracking and management of individual users within the editor.

External Header Panel

v1 Syntax

Initialization parameters used to configure external header panels:

• codeEditorButtonId
• undoButtonId
• redoButtonId

v2 Syntax

IDs were replaced with CSS selectors for more flexibility, and additional button selectors were introduced:

• codeEditorButtonSelector
• undoButtonSelector
• redoButtonSelector
• mobileViewButtonSelector
• desktopViewButtonSelector
• versionHistoryButtonSelector

The onUserListChange callback was also added to update user avatars during co-editing sessions.

Initialization Parameters

• Some initialization parameters changed their names or were replaced with new ones with extended meaning.
• All parameters that are responsible for external application notification about something and require functions to be provided are now started from the “on” prefix. Example: onSaveStarted()
• All parameters that are responsible for external decisions and require functions to be provided are now started from the “should” prefix. Example: shouldBeSavedToLibrary()

v1 Syntax	v2 Syntax
apiRequestData	metadata
getAuthToken	onTokenRefreshRequest
userFullName	metadata: { username }
codeEditorButtonId	codeEditorButtonSelector
undoButtonId	undoButtonSelector
redoButtonId	redoButtonSelector
viewOnly	replaced with “User Permissions API”
versionHistory	replaced with params: versionHistoryButtonSelector onVersionHistoryVisibilityChanged
draft: { showAutoSaveLoader: function() { console.log('Auto save in process') }, hideAutoSaveLoader: function(error) { console.log('Auto save completed') } }	onSaveStarted: function() { console.log('Auto save in process'); }, onSaveCompleted: function(error) { console.log('Auto save completed'); }
onToggleCodeEditor	onCodeEditorVisibilityChanged
localePatch Asset URL: https://plugins.stripo.email/static/latest/assets/i18n/en.json	localePatch Asset URL: https://github.com/stripoinc/stripo-plugin-releases/blob/main/static/assets/i18n/en.json
blocks: { moveBlockAvailability: true }	moveBlockAvailability
eventHandler	onEvent
modules: { syncModulesEnabled: true }	syncModulesEnabled
shouldBeSavedToLibrary	shouldBeSavedToLibrary
imageLibrary: { needHideImageUrlFunc: function(url) { return url.includes('test.com'); } }	shouldHideImagePath: function(url) { return url.includes('test.com'); }
different custom settings and popups	to be replaced with extensions

JavaScript API

v1 Syntax

const stripoEditorApi = window.StripoApi;

v2 Syntax

const stripoEditorApi = window.StripoEditorApi;