Setka Editor API Integration with Style Manager

Integration with Style Manager

Table of content

Before you start

1. Initial sync. Receiving Setka Editor files to connect them to your CMS

Description of a received set of files

theme_files array

content_editor_files array

standalone_styles file array

API request with additional parameters

Description of a received files array

amp_styles file array

API request for specific files array

List of available files

Step 2. Storing and processing Setka Editor files

1. Storing links to resources, dynamic linking to Setka CDN

2. Storing resources on your server or CDN

After files download

Step 3. Connecting Setka Editor files to the pages of your site

On a post editing page

On a post preview page

Public.js additional initialization parameters

A choice of page scrolling container

Enabling polyfills

On AMP pages

Step 4. Receiving style updates from the Style Manager and new editor versions

Receiving compressed files (.gz)

API Errors

Links that might be useful

More about custom integration

 

Before you start

Before starting the integration, make sure that Editor config url field is specified in your Style Manager account (CMS Integration tab), for Setka Editor to work on your domain:

9373ed2600.png

Editor config url is a link on which you will receive the latest version of the editor and updates for styles, created in the Style Manager. On initial sync you will also receive a public_token, which is required for several editor functions to work, e.g. for commenting and inserting embeds via URL.

Requests to editor.setka.io should contain your license key (hereinafter, in request samples, it is marked as your-license-key). You can get the license key on your account's CMS Integration page in your account:

Setka_Editor_Style_Manager___create_more_beautiful_content_quickly_and_easily_2019-01-23_16-00-37_1_.png

1. Initial sync. Receiving Setka Editor files to connect them to your CMS

Note: an article for users of the previous API version

To get style and editor files, configured in your account, make the following request with your license key:

GET https://editor.setka.io/api/v2/integration?token=your-license-key

 Response sample:

       {
          "public_token": "123456789123456789123456789",
          "plugins": [
            {
              "url": "https://ceditor.setka.io/public.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "content_editor_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.min.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "theme_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/public.v.1.2.3.json",
              "filetype": "json",
              "md5": "asdfasdfasdf"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          }
        }
        

 

Description for the received set of files:

 

File

URL

Description

public_token

 

Public key (public_token) — a public ID of the company, used to send auxiliary requests from the editor to the Style Manager. You can receive it in response to initial synchronization or copy it from your CMS Integration page. The public key needs to be handled to editor initialization.

plugins

https://ceditor.setka.io

/public.v.1.2.3.js

Scripts to launch interactive elements of a post (animations and galleries)

content_editor_files

 

An array of files for the editor

theme_files

 

An array of files responsible for posts display. Includes a general style file and an editor config file

standalone_styles

 

An array of CSS files and rules for all the styles and grids of a company, created in the Style Manager

 

Array of content_editor_files

Type

URL

Description

CSS

https://ceditor.setka.io

/company.v.1.2.3.min.css

editor interface style file

JS

https://ceditor.setka.io

/company.v.1.2.3.min.js

JavaScript of the Setka WYSIWYG Editor

 

Array of theme_files

Type

URL

Description

CSS

https://ceditor.setka.io

/company.v.1.2.3.min.css

Rules for all the styles and grids of a company, created in Style Manager

JSON

https://ceditor.setka.io

/public.v.1.2.3.json

Required for a proper launch of the Setka Editor tool. Contains all the info on styles configured in Style Manager

 

Array of standalone_styles 

To have your post reflected correctly, enable 3 CSS-files from standalone_styles array of files:

File

URL

Description

common

https://ceditor.setka.io

/common_css/common_css_1.css

Common rules for Setka Editor styles

themes

https://ceditor.setka.io/clients

/company/css/1.css

A style for a specific post

layouts

https://ceditor.setka.io/clients

/company/layout_option_builds/1/1.css

Grid system used for your posts

 

API request with additional parameters

To make an API request for the additional files use an options parameter:
 

GET https://editor.setka.io/api/v2/integration?token=your-license-key
&options=amp,fonts,icons

Response sample:

{
          "public_token": "123456789123456789123456789",
          "plugins": [
            {
              "url": "https://ceditor.setka.io/public.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "content_editor_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "theme_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/editor.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/public.v.1.2.3.json",
              "filetype": "json",
              "md5": "asdfasdfasdf"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          },
          "amp_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1_amp.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/theme_builds/1/2.css",
                "filetype": "css",
                "fonts": [
                  "https://fonts.googleapis.com/css?family=Open+Sans:400,700%7COpen+Sans+Condensed:400,400i,700&subset=cyrillic&display=swap"
                ]
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/1/layout_option_builds/1/2.css",
                "filetype": "css"
              }
            ]
          },
          "icons": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/clients/company/css/assets/1/img/icon-name.png",
              "filetype": "image"
            }
          ],
          "fonts": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/clients/company/css/assets/fonts/1/font-name.woff",
              "filetype": "font"
            }
          ]
        

 

Description of a received array of files

File

URL

Description

amp_styles

 

An array of files needed to reflect posts correctly on AMP pages

icons

https://ceditor.setka.io/clients

/company/css/assets

/1/img/icon-name.png

Icons that are uploaded in your style. You should download these files only if the style is hosted on your server. Icons are downloaded via Setka CDN by default in a General or Separated style files, no additional actions needed 

fonts

https://ceditor.setka.io/clients

/company/css/assets

/fonts/1/font-name.woff

Custom .woff fonts uploaded into your styles in the Style Manager.You should download these files only if the style is hosted on your server. Icons are downloaded via Setka CDN by default in a General or Separated style files, no additional actions needed 

 

amp_styles array of files

File

URL

Description

common

https://ceditor.setka.io

/common_css/common_css_1_amp.css

Common rules for AMP pages styles

themes

https://ceditor.setka.io

/clients/company/theme_builds/1/2.css

A style for a specific post

layouts

https://ceditor.setka.io

/clients/1/layout_option_builds/1/2.css

Grid system used for your posts

 

API request for specific arrays of files

To get the needed array of files add select parameter to your request, then enumerate these files separated by commas:

GET https://editor.setka.io/api/v2/integration?token=your-license-key
&select=plugins,editor,theme,standalone,amp,fonts,icons

 

List of available files

File Type Description
plugins JS Scripts that help running interactive elements of your posts
content_editor_files JS, CSS JS and CSS editor files
theme_files JSON, CSS JSON config file and a concatenated CSS file
standalone_styles CSS Separate style files
amp_styles CSS AMP styles
fonts WOFF Custom fonts
icons PNG, SVG Icons

 

Step 2. Storing and processing Setka Editor files 

There are 2 ways to store and process resources, received from Setka Editor.

 

1. Storing links to resources, dynamic linking to Setka CDN

You can receive links to resources via API and save them to your database. Dynamically link resources to editor and preview pages. Update the links once there is a request for it. 

 

Important: do not send Style Manager API requests each time you open your post. There are two cases when files can be changed:

1. When updating styles through Style Manager

2. When a new version of the editor is released

We recommend saving links in a database and updating them only if it is necessary. On getting a new set of files from editor.setka.io, make sure that it is valid. Delete the old style file and connect the new one only after validation. 

 

2. Storing resources on your server or CDN

If you want Setka Editor files to be grabbed from your server or CDN, with no dependencies on Setka CDN, you can use links to download them and put them into a public directory of the project. Then you will be able to markup paths to files on required pages.

After the file update request (Step 4) you will need to download new versions and replace old files.

Files can be saved to your server or CDN:

File Description
theme_files JSON config file and a concatenated CSS file
standalone_styles Standalone styles
amp_styles AMP styles
fonts Custom fonts
icons Icons

Download custom fonts and icons to your server or CDN in any structure preferable for you.

 

After files download:

1. JSON config file: replace absolute paths that are referred to a Setka Editor domain, with the absolute paths to icons on your domain or CDN

Example:

If the path leads to https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg,  replace it with https://yourdomain.com/assets/icons/icon.svg

2. Replace absolute paths for fonts in a concatenated or separate CSS file with the ones that lead to your CDN instead of Setka Editor domain

Example:

If the path leads to https://ceditor.setka.io/clients/file-ID/css/assets/fonts/client-ID/font.woff, replace it with https://yourdomain.com/assets/fonts/font.woff.

 

Step 3. Connecting Setka Editor files to the pages of your site

Setka Editor files should be launched both on the post editing page (for the operation of the editor tool), and on the post preview page (to connect Setka Editor styles to your content).

 

On a post editing page:

  • content_editor_files — JS и CSS editor files
  • theme_files — JSON config file and a concatenated CSS file of your styles

 

On a post preview page

  • plugins — scripts to launch interactive post elements (animations and galleries)
  • theme_files  style files
  • concatenated CSS file for styles from theme_files (if there are 1 or 2 styles in your Style Manager) and standalone_styles (if there are many styles in your account and the common style is too large)

 

Note: to use separate styles, there are 3 files from standalone_styles array needed:

  • common common rules of Setka Editor styles
  • themes  a style of a specific post. Take a style ID into your account when saving it to metadata on your stack.
  • layouts  grid system used for your content. Take a grid system ID into your account when saving it to metadata on your stack.

 

Public.js additional initialization parameters

A choice of page scrolling container

If a page scrolling container is not a window but some other DOM-element, send the following parameter to initialization:
window.SEPublicConfig = {
$scrollingElement: document.querySelector(‘.scrollable-area’)
};
Where .scrollable-area is a container where page scrolling occurs.
 

Enabling polyfills

To optimize the size of public.js file, since version 2.11.21, we don't include a polyfill for ResizeObserver and Web Animations API into it by default. If visitor's browser does not support any of these APIs, public.js will automatically load the polyfill from Setka CDN before initialization.

To enable custom polyfills, pass this parameter into the initialization:

window.SEPublicConfig = {
polyfillsPath: 'https://ceditor.setka.io/editor-polyfill/polyfills.pylyfillid.min.js'
};

Where polyfillsPath is an absolute polyfill URL.

 

On AMP pages

AMP does not allow to connect separate style files to pages. In order to do that you need to save files' content and connect it to common files of AMP pages styles

 Note: there are 3 files from amp-styles array of files that need to be saved: 

  • common  common rules of AMP pages styles
  • themes  a style of a specific post. Take a style ID into account when saving it to metadata on your stack
  • layouts  grid system used for your content. Take a grid ID into account when saving it to metadata on your stack

 

Step 4. Receiving style updates from the Style Manager and new editor versions

If you have applied any changes to your styles from your account and you want to have these changes to be reflected in the editor integrated with your CMS, as well as you would like to receive new versions of the editor on a regular basis, you need to receive updates from editor.setka.io.

Setka Editor will address a URL, specified in the Editor config url field on the CMS Integration page (e.g., yourdomain.com/setka_editor_config) with the following request:

POST yourdomain.com/setka_editor_config

 

A request sample from editor.setka.io:

 
        {
          "public_token": "123456789123456789123456789",
          "plugins": [
            {
              "url": "https://ceditor.setka.io/public.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "theme_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/company.v.1.2.3.json",
              "filetype": "json",
              "md5": "asdfasdfasdf"
            }
          ],
          "content_editor_files": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/editor.v.1.2.3.min.css",
              "filetype": "css",
              "md5": "asdfasdfasdf"
            },
            {
              "id": 1,
              "url": "https://ceditor.setka.io/editor.v.1.2.3.min.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          },
          "amp_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1_amp.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/theme_builds/1/1.css",
                "filetype": "css",
                "fonts": [
                  "https://fonts.googleapis.com/css?family=Open+Sans:400,700%7COpen+Sans+Condensed:400,400i,700&subset=cyrillic&display=swap"
                ]
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/1/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          }
        }
        

If icons and fonts are stored on your server or CDN, you will have to make an API request for them yourself.

Receiving compressed files (.gz)

In all the above mentioned methods you receive links to uncompressed resources. You can receive compressed versions from CDN by identifying an Accept-Encoding  heading in a request.

E.g.:

curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.v.1.2.3.min.js

 

API Errors

Errors that Setka Editor API may return:

1. HTTP/1.1401Unauthorized

 {
              "error": "Not authorized!"
            }
            

The error occurs as a result of a request with an incorrect license key (token).

 

HTTP/1.1 422 Unprocessable Entity

 {
              "errors": {
                "code": ["can't be blank"],
                "name": ["can't be blank"]
              }
            }
            

The error appears as a result of an incorrect request.

You can contact our support team on any error. We will be glad to help! 

 

Links that might be useful

 

More about custom integration: