Before you start
Before starting the integration, make sure that the Editor config url field is specified in your Content Design System Manager (CDSM) 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 CDSM. 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, on editor.setka.io:
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 file 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 CDSM. - 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 CDSM. - 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 CDSM. 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: Content Design System Manager API should not be requested for files each time the post page is opened, because files are changed only on changes in CDSM 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 CDSM);
- Icons (if you have uploaded them or gathered from the Noun Project library, into your styles in the CDSM).
You need to request fonts and styles each time you add them to the CDSM. It can be done by 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 Content Design System 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:
- Receiving compressed files (.gz)
In all the methods mentioned above, the links to uncompressed resources are handed. CDN also distributes the compressed versions. They can be obtained by requesting resources with a special accept-encoding header. E.g: curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.v.1.2.3.min.js -
The main domain to request and receive editor and styles: https://editor.setka.io
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:
- Introduction to Custom Integration
- Integration with Stye Manager
- Setka Post Editor initialization (JavaScript)