Setka Editor API Integration with Style Manager

Integration with Style Manager

Before you start

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

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.

Screen_Shot_2019-01-23_at_12.37.43.png

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, on editor.setka.io: 

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

 

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

To get style and editor files, configured on editor.serka.io, make the following request with your license key:

GET https://editor.setka.io/api/v1/custom/builds/current?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"
 }
 ],
 "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"
 }
 ]
}

Description for the received set of files:

  • JS файл of the editor (from the GET-request sample above: https://ceditor.setka.io/editor.v.1.2.3.min.js) — JavaScript of the Setka WYSIWYG Editor.
  • Editor CSS file (from the GET-request sample above: https://ceditor.setka.io/editor.v.1.2.3.min.css) — editor interface style file.
  • JSON config file (from the GET-request sample above: https://ceditor.setka.io/company.v.1.2.3.json) — required for a proper launch of the Setka Editor tool. Contains all the info on styles configured in the Style Manager.
  • CSS file of your styles (from the GET-request sample above: https://ceditor.setka.io/company.v.1.2.3.min.css) — CSS rules for all the styles and grids of a company, created in the Style Manager.
  • public.js file (from the GET-request sample above: https://ceditor.setka.io/public.v.1.2.3.js) — file with scripts to launch interactive elements of a post (animations and galleries).
  • 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 must be handled to editor initialization.

 

Step 2. Storing and processing Setka Editor files

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

Option 1. Store received links to resources in the database and dynamically include them on editor and preview pages. Change them to new ones after each update request.

IMPORTANT NOTE: Style Manager API should not be requested for files each time the post page is opened, because files are changed only on changes in Style Manager or on a new release of the editor tool. 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 the validation.

 

Option 2. If you want Setka Editor files to be grabbed from your server or CDN, with no dependencies on Setka CDN, you can download the files by links 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 (see step 4) you will need to download new versions and replace old files.

If you are going to keep the data on your own supply, you will need to take several actions to get additional files and store them correctly:

1. Get additional files via API https://editor.setka.io/api/v1/wordpress/files.json?token=your-license-key:

  • Custom fonts (if you have uploaded .woff fonts into your styles in the Style Manager);
  • Icons (if you have uploaded them or gathered from Noun Project library, into your styles in the Style Manager).

You need to request fonts and styles each time you add them to the Style Manager. It can be done on getting each new CSS file version and on API requests with your license key.

2. Download files of custom fonts and icons on your server or CDN (in any structure you like). 

3. Replace absolute paths in the JSON config file that are referred to a Setka Editor domain, with the absolute paths to icons on your domain or CDN.

For instance: you will need to replace the https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg path with https://example.com/assets/icons/icon.svg

 

 

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

Setka Editor files should be launched as on the post editing page (for the operation of the editor tool), as also on the post preview page (to connect Setka Editor styles to the content you have issued).

Files to be connected on the post editing page:

  • JS file of the editor
  • CSS file of the editor
  • JSON config file
  • CSS file of your styles.

Files to be connected on the post preview page:

  • public.js file
  • CSS file of your styles.

 

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

If you have changed something in a style on editor.setka.io, and want to see these changes in the editor of a CMS, and also receive editor updates regularly, you will need to receive updated file versions from editor.setka.io. Setka Editor will address a URL, specified in the "Editor config url" field on the CMS Integration page (e.g., test.com/setka_editor_config) with the following request:

POST test.ru/setka_editor_config

A sample of the request from editor.setka.io:

 

{
  "token": "123456",
  "data": {
    "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/theme.v.1.2.3.min.css",
        "filetype": "css",
      },
      {
        "id": 1,
        "url": "https://ceditor.setka.io/theme.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"
      }
    ]
  }
}

 

Useful links:

API Errors

Errors that Setka Editor API may give:

1. HTTP/1.1401Unauthorized

{
 "error": "Not authorized!"
}

The error appears if you make a request with an incorrect license key (token).

2. HTTP/1.1422UnprocessableEntity

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

The error appears if you have formed an incorrect request.

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

 

Custom integration: