Stripo Plugin Reference

Getting Started

Displaying the editor

Stripo plugin is written in native Javascript and designed like a component in a way to be easily configured and extended within your web-application.

From UI point of view it's just a 2 div areas (Settings Panel and Preview Area) and one JS that can be configured according to your needs to be embedded into these areas.

In order to display the plugin on your end please do the following:

Define 2 containers for Stripo settings panel (where controls will be located) and Stripo preview area (the area where the rendered email template will be displayed).

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

Please be advised:

• you may set the width of each container according to your preferences;
• the height of "stripoPreviewContainer", by default, stretches from the place where it was inserted to the bottom of the screen. To set another value, you have to set the max-height inlined style for this container;
• the height of "stripoSettingsContainer" is, by default, stretched to the height of the content and limited to the bottom of the screen. To set another, you need to set the max-height style for this container;

For example, max-height: calc (100vh - 100px); where 100px is the total height of the top and bottom panels. The max-height style must be specified for each panel separately, if not specified, the height will be adjusted by default, from the insertion point to the bottom of the screen.

Include the script taken from the application details page of the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

<script src="https://plugins.stripo.email/static/latest/stripo.js"></script>

                                    or

<script src="https://plugins.stripo.email/static/rev/[version]/stripo.js"></script>

To check the available versions of Stripo Plugin, please go to Release Notes.

If you want to host Stripo Plugin assets on your end you can download them from Stripo Github repo: https://github.com/ardas/stripo-plugin.

Plugin initialization

Once you have added Stripo Plugin assets on your web page you need to initialize the plugin:

window.Stripo.init({[put here your plugin JSON configuration]});

The default initialization script for Stripo Plugin should be:

window.Stripo.init({
   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) {
      //put here get Auth Token logic
   }
});

If the editor is closed by the user in the client’s web application, we recommend calling the following function to stop all processes and improve performance:

window.StripoApi.stop();

Plugin configuration

Here is the list of available configuration parameters:

Plugin request parameters

Plugin configuration contains parameter called “apiRequestData”. This is a JSON object that contains parameters that will be sent to server with each request. They are used to identify path to image library documents and modules. All of them are sent to a third-party permission checker system. See the Permissions checker API section.

The only “emailId” param here is mandatory for Stripo Plugin infrustructure. It is a string type of data with the max limit of 255 characters.

Use different emailId values for different emails to provide correct work of autosaving feature.

Plugin authentication

To authenticate your instance with Stripo Plugin Editor, call the endpoint shown in the sample code below with your PluginId and Secret Key, which are available on the plugin details page.

POST: /api/v1/auth
Host: https://plugins.stripo.email
Content-Type: application/json
Accept: application/json
Body: {pluginId:YOUR_PLUGIN_ID,secretKey:YOUR_SECRET_KEY,role:PLUGIN_EDITOR_USER_ROLE}
Response: {token:YOUR_AUTH_TOKEN}

AUTH REQUEST PARAMS:

Plugin configuration contains parameter called getAuthToken. Plugin calls function (this parameter value) each time a token is expired in order to get a new one. You have to implement this method on your side.

The full authentication schema should look like this:

1. Stripo Plugin can't do any operation without authentication token. To get it plugin calls "getAuthToken" function defined in Customer Application UI.
2. Customer Application UI sends GET request without any parameters to Customer Application Backend (for example "/token" request).
3. Customer Application Backend loads "Plugin Id" and "Secret Key" values from storage.
4. Customer Application Backend sends "/auth" POST request to Stripo Plugin Backend with "pluginId", "secretKey" and "role" parameters.
5. Stripo Backend generates plugin authentication token.
6. Stripo Backend sends token back to Customer Application Backend.
7. Customer Application Backend sends token back to Customer Application UI.
8. Customer Application UI calls "callback(token)" method from "getAuthToken" method params to load token to Stripo Plugin.

IMPORTANT

Do NOT call Stripo Backend directly from UI. It is insecure and your "Secret Key" can be stolen. Keep your "Secret Key" on your backend and do not tell it to anyone.

Example of “getAuthToken implementation”:

getAuthToken: function(callback) {
   $.ajax({
  type: 'GET',
  url: '/backend/plugin/token',
  contentType: 'application/json; charset=utf-8',
  dataType: 'json',
  success: data => callback(data.token),
  error: error => callback(null)
   });
}

Template requirements

The email templates that may be created/edited with Stripo editor, consist of two parts: the HTML code and the CSS code. These parts of one template should be stored in customer’s database separately and passed simultaneously (see the initialization parameters) when the user decides to edit the template.

In order to activate editor’s drag-n-drop feature for an imported email template, it is required that this template has particular Stripo classes, which are used by the editor to parse the HTML layout correctly.

In case you have a list of email templates created with another builder and you want to edit them with Stripo editor, please make sure you have converted the HTML code of those templates correctly (with specific classes included into their HTML code) to activate Stripo editing features. Please, read this article from our blog with the list of all specific classes and examples of how to convert the HTML code — https://stripo.email/blog/advanced-option-email-templates-adaptation-stripo-builder/

If you want to show Stripo free email templates and display them in you application for your end users for inspirational purposes you can download them from here.

If you want to open the editor to enable your users to create new email templates (as if they click “Create template from the scratch”) please go to the editor, find HTML and CSS code of an empty (scratch) email template that can be used as default email template. It is required that the email template HTML code has at least one stripe with one structure in it. The examples of basic and empty email templates can be taken from here.

UI Configuration

The UI settings can be configured in the the ‘UI settings’ tab. Get there from the application details page of the Stripo Plugin Integration menu in your Stripo account (if you don’t have one, sign up).

Please see explanations of each UI Settings controls provided below.

Image storage configuration

In Stripo editor, image management can be performed through Image Gallery, which can be configured according to your needs on the application details page.

It is up to you to configure the features as follows:

1. Image Storage;
2. Folder Configuration;
3. Limits;
4. Stock Images Configuration.

Image Storage

Stripo currently supports 4 different ways to store images, used in your instance of plugin:

This option is activated by default when you create plugin application. Please be advised that there might be a limitation to use Stripo storage depending on the selected plugin pricing plan. In order to have full control over the images used by your users in newsletters we do recommend keeping them on your own file storage servers.

Custom AWS S3 bucket is a plugin application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to store images.

When choosing this option, you have to fill out the form to establish connection with your storage. This is a description of the form fields with specifications regarding what information you will need to provide in each of them:

Please be sure that provided account has read and write access to the given bucket. You can take a look at the Helpers section to get more details on how to configure your AWS S3 storage More about AWS credentials.

Azure Blob storage is a plugin application configuration feature that allows you to easily connect your own Azure storage account to store images.

To do it, you need to generate connection string in your Azure portal account:

When choosing “Azure Blob Storage” option, you have to fill out the form to establish connection with your storage. This is a description of the form field with specifications regarding what information you will need to provide in each of them:

We created a way to connect to a custom file system provider (via HTTP protocol), allowing you to use Stripo editor with your own file storage, no matter which technology you use. A custom file system provider is an API that will allow the Stripo editor to perform actions with files out of the plugin environment, connecting your file system to Stripo’s file manager. It can be built with your preferred technology: just be sure to follow our instructions to provide successful communication between the two systems.

The Basic Authentication is used to send these requests, so please be sure that you have specified correct Login, Password and API URL on the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

File system operations:

GET LIST OF FILES

GET: /?keys=KEY_FOLDER_1,KEY_FOLDER_2,...
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response: [{key: KEY_FOLDER_1, documents: [{url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}]}, {key: KEY_FOLDER_2, documents:[]}]

UPLOAD FILE TO STORAGE

POST: /
Host: YOUR_BASE_URL
Content-Type: multipart/form-data
Accept: application/json
Body: 
    key:KEY_FOLDER,
    file: MULTIPART_FILE
Response: {url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,
height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}

DELETE/REMOVE FILE FROM STORAGE

POST: /delete
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Body: {url:DOC_URL}

GET FILE INFO

GET: /info?src=DOC_URL
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response:{"originalName":DOC_ORIGINAL_NAME,"size":DOC_SIZE_IN_BYTES}

Folder Configuration

In the Image Gallery, customer may see as many folders (tabs) as you have configured for your plugin application. For example, below you may see 3 folders in the Image Gallery called “Email”, “Project”, “Common”.

This is because they were configured this way on the application details page.

In this section, you can manage:

• the number of folders – simply click the “Add” icon to add a new folder or the “Remove” button to delete one. Please, be advised that in case a folder is removed it won't be displayed on UI anymore but the folder itself and all images in it will still be existing.
• their names. You have the option to specify what names a created folder should have in every supported language.
• the path to images that should be stored in particular folders. You can specify the relative path to the repository and insert into variables, that may be taken from your end when the Stripo editor is initialized. For example, if you want to separate the images of one email template from another, you can create the ‘Emails’ folder and specify its path as ${emailId}. When initializing the plugin, you have to pass the emailId value (e.g. 00000) among the parameters and, as a result, the the plugin will get the images from that folder 00000 (this folder will be automatically created in case it does not exist).
• and define the write permissions. At this stage, there are only two predefined roles in the Stripo editor. Please, read more about it here. By leveraging the proper role you can manage who of your customers is able to add and remove images to/from particular folders.

Please be advised that by default the Stripo plugin also creates the technical folder to store generated banners and image previews for “Video” basic block, etc. This folder cannot be managed from the Stripo Plugin Integration menu.

Limits

You can set the maximum size of one image uploaded to Image Gallery by your customers. The limit can be specified for all folders simultaneously in a range from 1 to 20 Mb per 1 file.

Stock Images Configuration

In case you want to provide your customers with an option to search and use free stock images within Image Gallery when they create email templates with Stripo builder, you need to simply activate the ‘Stock images’ option.

Once it’s activated, please specify the stock folder name, choose the available stock images provider and specify their configuration according to provided instructions.

Currently we do support only Pexels.com and Pixabay.com providers. The list of providers will be extended in the future.

Configuration of custom modules library

Similar to the Image Gallery, customer may see as many folders (tabs) in the Modules as you configured for your plugin application. For example, below you may see 3 folders in the Library of custom modules called “My blocks”, “Template blocks”, “General blocks”.

This is because they were configured this way in the application details page

In this section you can manage:

• the number of folders – simply click the “Add’ icon to add a new folder or the “Remove” button to delete one. Please, be informed that in case a folder has been removed it won't be displayed on UI as well as all saved modules removed from the server.
• their names. You have the option to specify what names a created folder should have in every supported language.
• the storage key ID will be assigned to modules and will be used as an identifier. You can specify the key as a static value or variable (use braces for this). For example, if you want to restrict access to the modules of one customer from another, you can create the ‘My blocks’ folder and specify its path as ${UserId}. When initializing the plugin, you have to pass the userId value (e.g. 00000) among the parameters and, as a result, the the plugin will get the modules from the DB by the key “00000”.
• and define the write permissions. At this stage, there are only two predefined roles in the Stripo editor. Please read more about it here. By leveraging the proper role you can manage who of your customers is able to add and remove modules to/from particular folders.

Please be informed that you can turn off this feature so that Library section won’t be displayed in the editor at all. In this case there won’t be an option to save selected elements from the context menu

Merge Tags

Merge tags help dynamically insert text templates into a text, such as the very common scenarios, like “Dear {first_name}”.

Merge tags can be inserted from a formatting panel of text basic block by clicking on the “Merge tags” button in the expanded text block toolbar.

Once you have activated this option while configuring the plugin, the Stripo plugin will handle all transferred merge tags correctly, otherwise this option won’t be displayed on the formatting panel at all.

Here is the example of creating mergeTags you can pass while plugin initialization:

{
    "mergeTags": [
        {
            "category": "MailChimp",
            "entries": [
                {
                    "label": "First Name",
                    "value": "*|FNAME|*"
                }
            ]
        }
    ]
}

Here is the description of parameters:

Fonts management

This new feature helps you to:

• Expand the list of available fonts displayed in the editor, adding own web fonts from popular services, such as Google fonts and others;
• Reduce the list of fonts to a limited number of options, removing the default fonts.

The list of fonts that should be displayed inside the editor must be defined each time the editor is initialized. This approach helps you to implement a variety of scenarios on your end like:

• You want your users to customize the list of fonts loaded in the editor when they edit emails. You can now create an interface in your app to do so, and instruct the editor accordingly;
• You are a digital marketing agency, and you want to customize the list of fonts in the editor depending on the client’s brand for which the email template is being created.

Here is the example of fonts object you can pass while plugin initialization:

{
    "editorFonts": {
        "showDefaultStandardFonts": true,
        "showDefaultNotStandardFonts": true,
        "customFonts": [
            {
                "name": "Oswald",
                "fontFamily": "'Oswald', 'helvetica neue', helvetica, arial, sans-serif",
                "url": "https://fonts.googleapis.com/css?family=Oswald"
            },
            {
                "name": "Barriecito",
                "fontFamily": "'Barriecito', cursive",
                "url": "https://fonts.googleapis.com/css?family=Barriecito&display=swap"
            }
        ]
    }
}

In this case both default fonts (Standard and Non Standard) are loaded, and two new custom fonts are added to the list (to the Custom fonts section).

Here is the description of parameters:

Please be advised, Stripo accepts only the CSS font embedding method, and the CSS file must be hosted in HTTPS protocol. You can use services like Google fonts, that provides host, font stacks and a well formatted CSS file.

Notice that if you want to change the default set of fonts, you need to disable them and use custom fonts to indicate the new set, including the URL parameter for web fonts. In this case you don’t have to pass the url parameter for the fonts from the “Standard fonts” list.

Сustom Font Sizes list

Please be advised that this feature is available on all pricing plans (including FREE one).

This feature helps you to:

• Expand the list of available font sizes displayed in the editor, adding own values of font sizes;
• Reduce the list of font sizes to a limited number of options, removing the default sizes (standard and non-standard ones).

The list of font sizes that should be displayed inside the editor may be defined each time the editor is initialized. This approach helps you to implement a variety of scenarios on your end like:

• You want your users to customize the list of font sizes loaded in the editor when they edit emails. You can now create an interface in your app to do so, and instruct the editor accordingly;
• You are a digital marketing agency, and you want to customize the list of available font sizes in the editor depending on the client’s brand for which the email template is being created.

Here is the example of font size object you can pass while plugin initialization:

"editorFontSizes": {
    "showDefaultStandardFontsSizes": false,
    "showDefaultNotStandardFontsSizes": true,
    "customFontsSizes": [17, 27, 32, 45]
}

In this case one default section (Non standard sizes) is loaded, and two 4 custom font sizes are added to the list (to the Custom sizes section).

Here is the description of parameters:

Notice that if you want to change the default set of font sizes, you need to disable them and use custom ones to indicate the new set.

Custom Color Palette

Please be advised that this feature is available on all pricing plans (including FREE one).

This feature helps you to reduce the number of color options in the list of color palette displayed in the editor.

The list of custom colors that should be displayed inside the editor must be defined each time the editor is initialized. This approach helps you to implement a variety of scenarios on your end like:

• You want your users to customize the list of colors loaded in the editor when they edit emails.
  You can now create an interface in your app to do so, and instruct the editor accordingly;
• You want your users to customize the list of colors loaded in the editor when they edit emails. You can now create an interface in your app to do so, and instruct the editor accordingly;

Here is the example of custom color palette object you can pass while plugin initialization:

"customColorPalette": [
    "#882724",
    "#35882C",
    "#FFD351",
    "#1924FF",
    "#B621EC",
    "#95C4EC"
]

In this case instead of standard color palette list, the only specified values will be displayed for selection. Please also be advised that the input fields related to colors will be disabled in order to prevent typing incorrect color values.

Here is the description of parameters:

Display Сonditions

Display conditions allow you to change the content of emails displayed to recipients, depending on whether the specified condition is met or not.

Users can set conditions manually in the editor (Custom) or select them from a list of predefined conditions added earlier (Predefined).

Below you can see the Conditions tab with custom condition category for selected Container looks like.

Let’s consider the following use-case ー you’re preparing a sale newsletter for your eCommerce project. You’d like to show different banner for men and women withing a single newsletter. In your customer database, you are able to identify customers’ gender.

So here how you can use this information to prepare customized newsletters. After the initial set up you’ll get the following result.

This is how women will see the email:

This is how men will see the email:

Now let’s go through the initial process of activating and customizing Display Conditions for plugin users.
The very first thing to do is activate the Display Conditions while plugin initialization:

{
 ...
 conditionsEnabled: boolean = false; //activation of the Display Conditions tab in the Editor
 customConditionsEnabled: boolean = true; //ability to create Local Display Conditions inside the Editor
 conditionCategories: (PredefinedCategory | ExternalCategory)[] = []; //List of Condition categories
 ...
}

Here is the type of the Predefined Category:

PredefinedCategory {
 type: string = 'PREDEFINED';
 category: string; //Category name
 conditions: PredefinedCondition[]; //conditions array with PredefinedCondition type
}

This activates the Conditions tab in the editor

You may have some ready categories you want to apply to conditions and use them in the editor. In our example, this is Gender - Male & Female.

Here is the type of predefined condition:

PredefinedCondition {
 id: number; // unique ID of the Condition
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

And here is the instance of the predefined category with one condition:

{
 type: 'PREDEFINED',
 category:'Gender'
 conditions:[
  {
   id:1;
   name: 'Gender - female',
   description:'Only female customers will see this part of the email.',
   beforeScript:'{% if contact.gender === \"Female\" %}',
   afterScript:'{% endif %}';
  }
 ]
}

In the editor, we get the following:

Same could be set up for any conditions, for example, Gender- male:

Instead of providing ready to use list of conditions you can specify External category which will allow you to implement your own condition selecting functionality. After the user selects the condition by the means you will provide to him, it will be sent back to the plugin via a callback function. Here is the type of external category:

ExternalCategory{
 type: string = 'EXTERNAL',
 category: string, //Category name
 openExternalDisplayConditionsDialog: (callback: ExternalDisplayConditionSelectedCB) => void; // callback that accepts a condition with type ExternalCondition
}

type ExternalDisplayConditionSelectedCB = (condition: ExternalCondition) => void;

ExternalCondition{
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

Here is the instance of external category:

{
 type: 'EXTERNAL',
 category:'Gaming platform'
 openExternalDisplayConditionsDialog: function(cb){
  // your code goes here
  cb({
   {
      name: 'Console',
      description:'Only console gamers will see this part of the email.',
      beforeScript:'{% if contact.gamingPlatform=== \"peasant\" %}',
      afterScript:'{% endif %}';
   }
  });
 }
}

Here is a full example of Display Condition configuration:

{
 "conditionsEnabled": true,
 "customConditionsEnabled": true,
 "conditionCategories": [
   {
    "type": "PREDEFINED",
    "category":"Gender",
    "conditions":[
     {
      "id":1,
      "name": "Gender - female",
      "description":"Only female customers will see this part of the email.",
      "beforeScript":"{% if contact.gender === \"Female\" %}",
      "afterScript":"{% endif %}"
     }
    ]
   }
 ]
}

Undo-redo actions

You can activate this feature to enable users to undo/redo their actions in the editor. Please be informed that you need to implement undo/redo buttons by yourself outside the Stripo Plugin Editor, and pass their IDs during the plugin initialization (see “Plugin configuration” section). This allows you to add these buttons in any place on your web page and style them the way you wish.

Social Networks

You can include your favorite social networks in “Social Network” block. To do this, add this config parameter:

{
    "socialNetworks": [
        {
            "name": "twitter",
            "href": ""
        },
        {
            "name": "facebook",
            "href": ""
        }
    ]
}

Full list of supported network names:

Ask.fm
Behance
Dribbble
Facebook
Flickr
Foursquare
Google-plus
Instagram
Last.fm
Linkedin
Livejournal
Myspace
Odnoklassniki
Pinterest
Soundcloud
Tumblr
Twitter
Vimeo
Vkontakte
Weibo
Youtube
Hangouts
ICQ
Mail.Ru Agent
Messenger
Skype
Snapchat
Telegram
Viber
Wechat
Whatsapp
Slack
Blogger
Email
Website
Map Marker
World
Address
Share
RSS
AppStore
Playmarket
Windows Store
Medium

Basic blocks management

While configuring Stripo plugin application you can decide which basic blocks to display in the initialized editor for your users.

In case you want to hide any of the blocks on editor’s UI please be sure to have turned them off in the plugin configuration section named “Basic blocks management”

Advanced controls settings

In this section, we gathered some advanced controls that can help your customers create their email templates in the most powerful mode. The list of controls with their explanations is as follows:

This feature is also known as a mouseover. When you place a mouse cursor over an image, it is being replaced with another one.

Image rollover effect works on desktop devices only. Other users will see the primary image. It can be applied to any image you add in email except for the banner one.

How to implement an image rollover effect with Stripo:

1. upload image
2. in the settings panel, toggle the “Rollover effect” button
3. upload the second image — edit it if necessary
4. insert URL link — it will be tied to both images
5. enter the “Alternate text”
6. set alignment and size of the image

To learn more about how image rollover effect can be used read this article.

In case you turn on this control while configuring the plugin, it will be added to the set of controls for structures, stripes and basic blocks (e.g. “Image’, “Text”, “Button”, etc.) in the Padding section and will appear like this:

When a customer selects any structure or block in the editor and then decides to set up individual padding for mobile, all they need to do is activate this control and enter values — this structure or block will be displayed with the specified padding values on mobile devices.

In case you turn on this control while configuring the plugin, it will be added to the set of controls for every basic block (e.g. “Image’, “Text”, “Button”, etc.), containers, structures and stripes and will appear like this:

When a customer selects any of the elements in the editor and then decides not to display this element on mobile or on desktop only, all they need to do is activate this control and this is it — this element won’t be displayed when the email is opened on mobile devices or on desktop respectively.

In case you turn on this control while configuring the plugin, it will be added to the set of structure controls only if there are 2 containers in it (the control will be hidden for structures with 1 or more than 2 containers inside) and will appear like this:

Please be informed that by default this control is turned off and also this control won’t be active in case if a customer turns off the “Adaptive structure” control.

This control allows specifying which container should be displayed at the top and which one at the bottom for mobile version of email template.

In case a customer turns on the “Container inversion on mobile” control, the containers will be placed on mobile the following way:

1. the first container on the desktop will be displayed under the second container on mobile;
2. the second container on the desktop will be displayed above the first one on mobile.

In case you turn on this control while configuring the plugin, the mobile icon will be added to the Alignment control of every basic block (e.g. “Image”, “Text”, “Button”, etc.) that have the “Alignment” control and will appear like this:

By default this icon is not activated, which means that selected alignment is relevant for desktop version, yet will be the same for mobile version if we do not specify another value.

To specify another value we should click on ‘mobile’ icon, it becomes activated (clicked), and then choose another alignment by clicking on proper icon here

To switch back on desktop version it is enough to click again on ‘mobile’ icon (it gets its default state when it’s non-clicked).

In case you turn on this control while configuring the plugin, it will be added to set of stripe’s controls and will appear like this:

It allows setting the border for content area of a selected stripe. It is possible to configure the border line type (straight, dashed, dotted line), it’s color and width for all sides or for a particular one (like only on left side or on the top, etc.)

In case you turn on this control while configuring the plugin, it will be added to the set of structure’s controls and will appear like this:

This control allows setting up the background color for the selected structure.

In case you turn on this control while configuring the plugin, it will be added to set of container’s controls and will appear like this:

It is obvious from the name, this control allows setting up the background color for the selected container.

In case you turn on this control while configuring the plugin, it will be added to the set of structure’s controls and will appear like this:

This control allows setting up any image as a background for a selected structure. It enables to configure the alignment and provides ability to repeat a chosen image.

In case you turn on this control while configuring the plugin, it will be added to the set of container’s controls and will appear like this:

This control allows setting up any image as a background for a selected container. It enables to configure the alignment and provides the ability to repeat chosen image.

In case you turn on this control while configuring the plugin, it will be added to the set of structure’s controls and will appear like this:

It allows adding a new or remove any existing container within a selected structure (it is possible to add up to 8 containers in 1 structure). This control also allows changing the container’s width and indents between them.

In case you turn on this control while configuring the plugin, the extra ‘Link’ control will be added to the set of Image block controls (as well as for the Menu, Banner blocks, etc) and will appear like this:

It allows specifying/replacing the URL to the image without making any changes to the HTML code. This feature is useful in case a customer doesn’t want to place the image in your storage and simply wants to host it elsewhere (on Internet site or any own storage). All they have to do is click on this “Link” control and replace the image URL with required one in the “Image path” field.

This option provides ability to activate smart properties to containers, structures and stripes. When this control is activated while configuring the plugin, and customer selects any container (structure or stripe) the new ‘Data” tab will be displayed at the top above set of controls.

In this tab a customer has an ability to activate smart properties for a selected element and perform its configurations. Please read more about this here – https://stripo.email/blog/smart-elements-reducing-time-creating-similar-letters-automating/.

Support of AMP HTML Mime type

This March, Google released its AMP for emails. And as of July 2, it is available even for the G-Suite users and is “on” by default for all Gmail’s users. It allows senders to include AMP components inside rich engaging emails, making modern app functionality available within the email. This dynamic email format provides a subset of AMPHTML components for use in email messages, that allows recipients of AMP emails to interact dynamically with content directly in the message.

Since June 18, 2019, Stripo supports creating a new AMP HTML format of email template in the editor. To provide this option to your customers you may activate the “Support of AMP HTML Mime type” within your plugin configuration page. When it is activated and the customer selects any block or container (structure or stripe) the new control will be added to the settings panel and will appear like this:

By default, all elements will be included into 2 versions of an email template: a traditional HTML version and AMP HTML version. But customer has a choice to include any element only to a particular version, for example, only to HTML or only to AMP HTML version. In this case, that element will be highlighted with orange border and tooltip that indicates in which version that element is included. You can read more about how to build amp emails with Stripo here – https://stripo.email/blog/how-to-build-amp-emails-with-stripo/

Please be advised, if the email template has at least one element that is included to AMP version (or if it has a custom code with AMP components), then when you call the compileEmail JS function or compress method from your server, in addition to HTML version in response you will get AMP HTML version of your email template. Go to Plugin Invocations section for more details.

Image editor

This option helps you to enable or disable the image editor embedded into Stripo Plugin. It helps to apply different effects to images, change their sizes, shapes, etc.

When it is activated and the customer selects any image within email template the new control will be added to the settings panel and will appear like this:

Plugin notifications

When plugin needs to show message to user it calls one of these functions:

{
    "notifications": {
        "info": message => console.log(message),
        "error": message => console.error(message),
        "success": message => console.log(message),
        "warn": message => console.log(message),
        "loader": message => console.log(message),
        "hide": message => console.log(message)
    }
}

You need to override these functions to show messages in correct place and styled the way you wish.

Server Configuration

The set of server-side settings can be configured in the Server settings’ tab from the application details page of the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

You can find the explanations of each of Server Settings controls with code samples below.

Permissions checker API

Make sure only your users have the rights to edit emails in your application. Enable operation permissions checker to prevent third-party people from pretending to be who they are not!

This means that Stripo plugin will not perform any server side operation (load/save/update...) without permissions from your end. To enable this feature, you need to implement this backend endpoint on your end.

{
    "POST": "/",
    "Host": "YOUR_PERMISSIONS_CHECKER_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "pluginId": "YOUR_PLUGIN_ID",
        "uiData": {
            "emailId": "123",
            "someAnotherIdentifier": "456",
            ...
        },
        "requestPermissions":
        [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    },
    "Response": {
        "grantPermissions": [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    }
}

REQUEST PARAMETERS:

RESPONSE PARAMETERS:

When choosing Permissions Checker API option, you have to fill out the form to establish connection with your backend. This is a description of the form fields with specifications regarding what information you will need to provide:

The Basic Authentication is used to send these requests.

Autosaving feature

Enable this feature to receive a fresh version of HTML and CSS code at your backend every time a change has been done to the code by a user.

You need to implement this backend endpoint:

{
    "POST": "/",
    "Host": "YOUR_BACKEND_AUTO_SAVE_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "key": "plId_YOUR_PLUGIN_ID_emailId_YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "emailId": "YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "html": "YOUR_HTML_CODE",
        "css": "YOUR_CSS_CODE",
        "width": "EMAIL_WIDTH",
        "height": "EMAIL_HEIGHT"
    },
    "Response status": "200 OK"
}

The Basic Authentication is used to send these requests, so please be sure that you have specified correct Login, Password and API URL on the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

REQUEST PARAMETERS:

Version history and restoring email templates from previous revisions

This option enables to provide ability to your customers to be able to view changes of an open email template in the editor, as well as the function to restore the current version of the email template from earlier versions. You can place inside your application the link (trigger), by clicking on which the mode of viewing the history of changes of an open email template can be activated.

When this mode is activated your customers can track all changes displayed in the Settings Panel area. As soon as they click on particular change, they are able to restore opened email template to the selected state.

Please note: the editor won't display the user name if it was not passed as one of the parameters while the plugin initialization.

To activate version history feature add this config parameters (see “Plugin configuration” section):

{
    "userFullName": "YOUR_PLUGIN_USER_NAME",
    "versionHistory": {
        "changeHistoryLinkId": "YOUR_LINK_ELEMENT_ID",
        "onInitialized": "function(lastChangeInfoText)" {
            // Do any additional actions here when version history is initialized
        }
    }
}

If you do not use the Auto-saving feature insight the Server settings you should independently create the notes to the History.

For doing this please add this function and call this method every time a template is saved on your side or when you want the corresponding entry to appear in the Version History:

function saveVersionHistoryPoint(onSaveCallback)
{
    if (window.StripoApi.createVersionHistoryPointAsync)
{
     	   window.StripoApi.createVersionHistoryPointAsync(onSaveCallback);
    }
   else {
        // Deprecated
        window.StripoApi.createVersionHistoryPoint();
        onSaveCallback();
    }
}

This function will create visible endpoints in the Version History and update the data of the last changes. You can independently choose where it should be applied, we recommend you use it every time after your customer clicks to the "Save" button.

If an auto-saving feature is activated and configured, then all changed made in the editor will trigger the request to our end with micro patches (those particular changes) in order to save them in our DB.

As soon as they are saved, our server will send the request to specified by your end-point with the full changed HTML and CSS in order to replace the old version with a new one in your DB. In total, every change made by a user in the editor will be saved in your DB for that particular email and you have only the final most up-to-date version for the event template, opened in the editor.

If this feature is not activated, then a user has to click on the Save button manually within your app and you should call the getTemplate function to take out modified HTML and CSS from the editor in order to save in within your DB.

Plugin Invocations

Stripo Plugin has the Javascript API and backend API.

Stripo Plugin JS API can be accessed via window.StripoApi js object.

The list of available JS API functions:

How to call the showAmpErrorsModal function

Here is an example on how to call the “showAmpErrorsModal” function

showAmpErrorsModal(
	ampErrors,
	[
		{
			text: 'Preview',
			action: () => {console.log('"Preview" button clicked');}
		}
	],
	() => {console.log('"Close" button clicked');},
	() => {console.log('"Fix in Code Editor" button clicked');}
)

If you have the option set to display the code editor (codeEditorButtonId), then the 'Fix in Code Editor' button will also be displayed:

When this button is clicked, the modal window will be closed and the code editor will be opened instead. If you need to process something else by clicking on this button, then pass the 4th parameter to this function.

When the 'Close' button is clicked, you can add a callback function with the 3rd parameter as well.

By clicking on the red badge displayed on the code editor panel, the previous AMP errors will be displayed.

To re-initialize the validation check again the customer has to click on the “Repeat check” button.

In case if there are no errors received after validation check is completed, the editor will display the success message in the modal window as follows:

If you want to display your custom buttons in this modal window, be sure you have passed them to the second parameter of “showAmpErrorsModal” function. In our example above, we passed the “review” button which triggers opening the preview page on external application.

If the second parameter is empty then the only “Close” button will be displayed.

Stripo Plugin Backend API

Stripo Plugin Backend API endpoint allows inlining CSS styles into HTML code and prepare HTML for sending to clients.

POST: /api/v1/cleaner/v1/compress
Host: https://plugins.stripo.email
Content-Type: application/json
Header: ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN
Accept: application/json
Body: {html:YOUR_HTML_CODE, css:YOUR_CSS_CODE, minimize:true}
Response: {html:HTML_READY_TO_BE_SENT}

To get YOUR_AUTH_TOKEN please take a look at this section.

REQUEST PARAMETERS:

Please be advised, in case if your email template contains AMP elements or components then in response you will see the ampHtml parameter, that contains the html code of AMP HTML Mime type.

In case if AMP HTML is invalid then you will get also the ampErrors parameter that contains the error descriptions (array of strings).

Request:
curl -X POST https://plugins.stripo.email/api/v1/auth -k -H "Content-Type: application/json" -H "Accept: application/json" --data "{\"pluginId\":\"YOUR_PLUGIN_ID\",\"secretKey\":\"YOUR_SECRET_KEY\"}" -i

Response:
{"token":"YOUR_AUTH_TOKEN"}

Request:
curl -X POST https://plugins.stripo.email/api/v1/cleaner/v1/compress -k -H "Content-Type: application/json" -H "Accept: application/json" -H "ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN" --data "{\"html\":\"Some html\",\"css\":\"body {color: green}\",\"minimize\":true}" -i

Response:
{"html":"Some html"}

Roles and access managements

Soon we will add the ability to manage the roles you can assign to any user when initializing the editor.

Currently, in the system, there are only 2 roles preset by default:

• Admin
• User

You can use these roles while configuring access levels to the folders created in the Image Gallery and in the Library of modules. Pass correct role during authentication (see “Plugin authentication” section) to enable him/her to write data in one or another folder of the Image Gallery or the Library of modules.

Role values:

Custom Components

External Images Library

In case you want to display your own component with external file system for images in the pop-up window instead of Stripo Image Library you can define “externalImagesLibrary” param during plugin initialization as follows:

window.Stripo.init({
   ...,
   externalImagesLibrary: {
        openLibrary(onImageSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onImageSelectCallback({
                     originalName: 'YOUR_FILE_NAME.png',
                     resolution: '600 x 410 px',
                     size: '169.20 kb',
                     url: 'https://YOUR_STORAGE_URL/YOUR_FILE.png'
                  })
               when user select the image from external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }
});

Please find a code example here to see how it works.

External Video Library

In case you want to display your own component with external list of videos in the pop-up window, which users can pick up while working with Video blocks, you can define “externalVideosLibrary” param during plugin initialization as follows:

window.Stripo.init({
  ...,
  externalVideosLibrary: {
      buttonText: 'YOUR BUTTON NAME',
      open: openLibrary(onVideoSelectCallback, onCancelCallback) {
          /* Put your logic here.
             Call
                onVideoSelectCallback({
                  originalVideoName: 'YOUR VIDEO NAME',
                  originalImageName: 'YOUR IMAGE NAME',
                  urlImage: 'https://YOUR_STORAGE_IMAGE_URL.png',
                  urlVideo: 'https://your_storage_url/YOUR_FILE',
                  hasCustomButton: true || false
                })
             when user select the video from external library.
             Call
                onCancelCallback()
             when user close the library without video selection.
          */
      }
  }
});

Please find a code example here to see how it works.

File picker for links

In case if you want to add your own control for selecting a file from external file system in the pop-up window to be linked with the existing “Link” control of every basic block, you can define “externalFilesLibrary” param during plugin initialization as follows:

window.Stripo.init({
  ...,
  externalFilesLibrary: {
        buttonText: 'YOUR BUTTON NAME',
        open: openLibrary(onFileSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onFileSelectCallback('https://YOUR_STORAGE_FILE_URL')
               when user select the file from external library.
               Call
                  onCancelCallback()
               when user close the library without file selection.
            */
        }
    }
});

Please find a code example here to see how it works.

Smart Modules

To display your own component with an external data list in a pop-up window that users can choose to dynamically retrieve data for smart modules, you can define the parameter “externalSmartElementsLibrary” during the initialization of the plugin:

window.Stripo.init({
   ...,
   externalSmartElementsLibrary: {
        openLibrary(onDataSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onDataSelectCallback({
                	key: value
})
               when the user selects the data from the external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }

Please find a code example here to see how it works.

AMP-Form Services

This parameter is an array of objects with "value" and "label" fields which used for collecting data form the AMP-Form block. “Label” is the name of the service shown in the editor, “Value” is an endpoint for submitting forms.

  "ampFormServices": [
    {
      "label": "My endpoint 1",
      "value": "https://my-endpoint1.net"
    },
    {
      "label": "My endpoint 2",
      "value": "https://my-endpoint2.net"
    }
  ]

This is how a predefined list of services looks like in the editor.

Editor extensions

In case you want to create your own editor blocks, flexibly customize their behavior and manage email layout, you can use the Stripo editor extensions. First, create your own extension following the steps below:

1. Checkout https://github.com/ardas/stripo-plugin-samples repository
2. Navigate to preferred extension example in /extensions folder
3. Install dependencies:
   npm i
4. Replace sample extension code with your logic
5. Compile this code
   npm run build

Ready-to-use code will be stored in the dist folder. Then store the compiled extension files on your hosting. When initializing the Stripo editor, insert the code sample given below into the parameters:

  window.Stripo.init({
       ...,
       "extensions": [
           {
             "globalName": "YourExtensionName",
             "url":"https://your.hosting/main.hash.extension.js"
           }
         ]
   });

Please find a code example & detailed guidelines by this link.

Sample Code

Using this simple client-side example you can try out Stripo Plugin:

• Get “PLUGIN_ID” and “SECRET_KEY” values by signing up here and creating a new plugin.
• Download the client-side code example.
• Open index.html with code editor.
• Replace “YOUR_PLUGIN_ID” and “YOUR_SECRET_KEY” with your values.
• Save the file.
• Open it in your browser and enjoy the process of email creation.

IMPORTANT: client-side example is created just to play with Stripo Plugin editor and can NOT be used in production. It is insecure and your "Secret Key" can be stolen. Keep your "Secret Key" on your backend and do not tell it to anyone. See plugin authentication section to implement authentication correctly.

Appendix A. Helpers

Configuration of AWS S3 storage

To create custom AWS S3 storage do the following:

1. Create Amazon AWS account.
2. Create IAM user with S3 bucket permissions
   

3. Create IAM policy:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "s3:ListBucket",
               "Resource": "arn:aws:s3:::bucketname"
           },
           {
               "Sid": "VisualEditor1",
               "Effect": "Allow",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::bucketname/*"
           },
           {
               "Sid": "VisualEditor2",
               "Effect": "Allow",
               "Action": [
                   "s3:PutAnalyticsConfiguration",
                   "s3:GetObjectVersionTagging",
                   "s3:CreateBucket",
                   "s3:ReplicateObject",
                   "s3:GetObjectAcl",
                   "s3:DeleteBucketWebsite",
                   "s3:PutLifecycleConfiguration",
                   "s3:GetObjectVersionAcl",
                   "s3:DeleteObject",
                   "s3:GetIpConfiguration",
                   "s3:GetBucketWebsite",
                   "s3:PutReplicationConfiguration",
                   "s3:GetBucketNotification",
                   "s3:PutBucketCORS",
                   "s3:GetReplicationConfiguration",
                   "s3:ListMultipartUploadParts",
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:PutBucketNotification",
                   "s3:PutBucketLogging",
                   "s3:GetAnalyticsConfiguration",
                   "s3:GetObjectVersionForReplication",
                   "s3:GetLifecycleConfiguration",
                   "s3:ListBucketByTags",
                   "s3:GetInventoryConfiguration",
                   "s3:GetBucketTagging",
                   "s3:PutAccelerateConfiguration",
                   "s3:DeleteObjectVersion",
                   "s3:GetBucketLogging",
                   "s3:ListBucketVersions",
                   "s3:RestoreObject",
                   "s3:ListBucket",
                   "s3:GetAccelerateConfiguration",
                   "s3:GetBucketPolicy",
                   "s3:GetObjectVersionTorrent",
                   "s3:AbortMultipartUpload",
                   "s3:GetBucketRequestPayment",
                   "s3:GetObjectTagging",
                   "s3:GetMetricsConfiguration",
                   "s3:DeleteBucket",
                   "s3:PutBucketVersioning",
                   "s3:ListBucketMultipartUploads",
                   "s3:PutMetricsConfiguration",
                   "s3:GetBucketVersioning",
                   "s3:GetBucketAcl",
                   "s3:PutInventoryConfiguration",
                   "s3:PutIpConfiguration",
                   "s3:GetObjectTorrent",
                   "s3:PutBucketWebsite",
                   "s3:PutBucketRequestPayment",
                   "s3:GetBucketCORS",
                   "s3:GetBucketLocation",
                   "s3:ReplicateDelete",
                   "s3:GetObjectVersion"
               ],
               "Resource": "arn:aws:s3:::bucketname/*"
           },
           {
               "Sid": "VisualEditor3",
               "Effect": "Allow",
               "Action": [
                   "s3:ListAllMyBuckets",
                   "s3:HeadBucket",
                   "s3:ListObjects"
               ],
               "Resource": "*"
           }
       ]
   }

   Please be advised that you should replace "bucketname" value with the name of your bucket created in your AWS account

   
   
4. Assign created policy to IAM user:
   
5. Create S3 bucket with necessary custom name and in necessary region:
   
6. Choose Static website hosting and index document index.html:
   
7. Set Bucket permission policy:
   

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "PublicReadGetObject",
               "Effect": "Allow",
               "Principal": "*",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::bucketname/*"
           }
       ]
   }
   

   Please be advised that you should replace "bucketname" value with the name of your bucket created in your AWS account

8. Uncheck List objects from bucket permissions:
   

9. Add settings to web server, e.g. nginx:

   location /content {
     add_header 'Access-Control-Allow-Origin' '*';
     proxy_pass  https://s3-eu-west-1.amazonaws.com/bucketname;
     proxy_redirect off;
   }
   

10. Enter “YOUR_DOMAIN_ADDRESS/content” as “Base Download URL” when configure plugin settings.