Setka Editor API Integration Setka Post Editor initialization (JavaScript)

Setka Post Editor initialization (JavaScript)

Terms and Definitions

Style Manager: web interface for creating and editing a branded style of a publication (module grid, text and color styles, icons, etc.). You can find it at editor.setka.io.

Post: HTML code of the post wrapped in <div class=“stk-post”>...</div>.

Post style: a set of CSS rules for text styles, fonts, colors, dividers, etc. which determines a branded style of a publication. Post style is edited in Style Manager.

Post grid system: a set of CSS rules for building grid modules with columns and indents, and for adaptation to mobile devices. Post grid system is edited in Style Manager.

All styles and grid systems within one company are uploaded from Style Manager to CDN in the form of a CSS file with styles and a JSON file with meta information to be used in the editor.

 

How to launch the editor on a page

Editor requires 5 files to operate properly. These files need to be loaded in the post editing and/or view pages. 

 

File

Description

Post editing page

Post view page

editor.min.js

Main editor file

yes

 

editor.min.css

Editor UI styles

yes

 

company_name.min.css

Post styles defined in the Style Manager (fonts, colors, grids, etc.)

yes

yes

company_name.json

JSON with meta data required for work of the editor

yes

 

public.js

JS code required for work of interactive capabilities of the editor (galleries, animation)

 

yes

Below is a sample code for initialization the editor.

HTML:

<!DOCTYPE html>
<html>
  <head>

    <!-- 1. Main editor file -->
    <script
     src="https://ceditor.setka.io/path/to/editor.min.js">
    </script>

    <!-- 2. Editor UI styles -->
    <link
     rel="stylesheet"
     href="https://ceditor.setka.io/path/to/editor.min.css">

    <!-- 3. Post styles -->
    <link
     rel="stylesheet"
     href="https://ceditor.setka.io/path/to/company_name.min.css">

  </head>
  <body>

    <!-- 4. Place on the page the container for the editor -->
    <div class="stk-editor" id="setka-editor"></div>

  </body>
</html>

JavaScript:

// Load JSON with meta data
// (if JSON has been already saved in the server, load it from there)

fetch('https://ceditor.setka.io/path/to/company_name.min.json')
  .then(response => response.json())
  .then(response => {

    // Add company token from Style Manager
    const config = response.config;
    const assets = response.assets;

   // transmit public token (public_token) of company
   // (it is used for sending requests from editor to API editor.setka.io)
  config.public_token = 'my_public_token_123456';

    // Start the editor
    SetkaEditor.start(response.config, response.assets);

  })
  .catch(ex => alert(ex));

How to receive content from the editor for saving in DB

Each post created in the editor is determined by three parameters:

  1. Content
  2. Style id
  3. Grid system id

Accordingly, all these parameters are to be saved in the database.

// Returns HTML code of the post:
// <div class="stk-post">...</div>
SetkaEditor.getHTML({ includeContainer: true });

// Returns the object with the selected post style properties
// Example: { id: '2409', name: 'Newspaper', ... }
// (it is enough to save id in the database)
SetkaEditor.getCurrentTheme();

// Returns the object with the selected post grid system properties
// Example: { id: '6col_limited_940', name: '6 columns, limited', ... }
// (it is enough to save id in the database)
SetkaEditor.getCurrentLayout();

Important: you should not receive content from the editor by accessing DOM elements on the page because they contain temporary elements and attributes that are required only when working in the editor and should not remain in the saved HTML code of the post. Always use the SetkaEditor.getHTML() method.

 

How to open in the editor the post you have previously saved

To open an existing post in the editor, you are to call up the SetkaEditor.replaceHTML method upon completion of initialization of the editor.

// Take the contents of the post from the database
const postContentFromDB = '
 <div class="stk-post stk-theme_2407 stk-layout_4col_1565">
   <p>Post text</p>
 </div>
';

// Take from the database the ID of the style and the grid system
// with which the post was saved
const themeId = '2407';
const layoutId = '4col_1565';

// Load JSON with meta data
fetch('https://ceditor.setka.io/path/to/company_name.min.json')

  .then(response => response.json())

  .then(response => {

    const { config, assets } = response;

    // Specify in the config the ID of the style and the grid system
    // with which the editor is to start
    config.theme = themeId;
    config.layout = layoutId;

    // Start the editor
    SetkaEditor.start(config, assets);

    // Place to the editor the contents of the post from DB
    SetkaEditor.replaceHTML(postContentFromDB);

  })
  .catch(ex => alert(ex));

Important: Setka Editor works with its own HTML code structure. The post must be in a <div class=”stk-post”>...</div> container and must contain elements with specific classes and attributes. “Alien” elements may become non-editable or to cause an error when starting the editor. There is no point in trying to open posts in Setka Editor created in another editor or manually.

 

How to upload pictures from the editor to the server

Setka Editor interface maintains the following operations with pictures:

  1. uploading
  2. deleting
  3. alt attribute editing

In order for Setka Editor to upload images to your server, you need to write a REST API that will process requests from the editor and perform appropriate actions on the backend side.

First, you need to provide the path to REST API root when starting the editor.

// ...

/*
  All requests from the editor will be sent
  based on the root URL REST API, for example:
  /api/setka-editor/v1/images
  /api/setka-editor/v1/snippets
  /api/setka-editor/v1/…
*/
config.restApiUrl = '/api/setka-editor/v1/';

/*
  The restApiRequestPayload parameter allows you
  to add custom parameters to all requests from the editor to the REST API
  (for example, the authorization token or the post id).
*/
config.restApiRequestPayload = {
  authToken: 'qwerty123456',
  postId: 42
};

// Start the editor
SetkaEditor.start(config, assets);

REST API must be able to receive and process the following requests (see below). The editor handles the “200” response status code as success of an operation and any other status codes as an error.

 

Uploading pictures

Request

URL

/%API_ROOT%/images

Method

POST

Content type

multipart/form-data

Request body

file object with picture properties

Response

Status codes

200 — success
4xx, 5xx — error

Content type

application/json

Response body

 

{
  // id of the saved picture in the server
  "id": "abc-def-123-456",

  // path to the picture
  "url": "http://example.com/image.jpg",

  // path to scaled-down picture (optional)
  "thumbUrl": "http://example.com/image_thumb.jpg"
}

 

Deleting pictures 

Request

URL

/%API_ROOT%/images/:id

Method

DELETE

Content type

application/json

Request body

Response

Status codes

200 — success
4xx, 5xx — error

Content type

Response body

 

Updating picture properties

Request

URL

/%API_ROOT%/images/:id

Method

PUT

Content type

application/json

Request body

{
  // Updated picture properties
  "props": {
    "name": "value"
  }
}

Response

Status codes

200 — success
4xx, 5xx — error

Content type

Response body

 

Snippet saving

In the future, saving the snippets is planned to be transferred completely to the editor's side.

Request

URL

/%API_ROOT%/snippets

Method

POST

Content type

application/json

Request body

{
  // Temporary snippet id
  "id": "aac90814-6a50-406d-822a-d8849df52d51",

  // Snippet name
  "name": "My snippet"

  // Snippet HTML code
  "code": "<p>snippet text</p>",

  // Current post style id
  "themeId": "2407"
}

Response

Status codes

200 — success
4xx, 5xx — error

Content type

Response body

– 

 

How to start the editor with a set of pictures

To start the editor with a specific set of pictures in the right panel (for example, uploaded previously to a saved post), you need to pass them to the "assets" array when starting the editor in a specific format.

// ...

// Take pictures from DB and form the array in a required format:
const postImages = [

 {
   id: 'abc-def-123-456',
   name: 'kitten.jpg',
   url: 'http://example.com/path/to/kitten.jpg',
   thumbUrl: 'http://example.com/path/to/kitten-thumb.jpg',
   alt: 'Little kitten'
 },

 {
   // ...
 }

];

// Add pictures to the editor assets
assets.images = postImages;

// Start the editor
SetkaEditor.start(config, assets);

 

Additional parameters

You can initialize Setka Editor with additional parameters:

// ...get config and assets from JSON

// postWidthPresets parameter allows you to specify options
// of the post width in the "View post as" control
// at the bottom of the editor
config.postWidthPresets = [640, 800, 960];

// Show debugging information when the editor starts
config.debug = true;

// Start the editor
SetkaEditor.start(config, assets);

 

Custom integration: