API для кастомной интеграции Setka Editor Инициализация Setka Post Editor (JavaScript)

Инициализация Setka Post Editor (JavaScript)

Терминология

Style Manager — веб-интерфейс для создания и редактирования фирменного стиля издания (модульная сетка, стили текста, цвета, иконки и т.д.). Находится по адресу editor.setka.io.

Пост — HTML-код поста вместе с оберткой <div class=“stk-post”>...</div>

Стиль поста — набор CSS-правил для текстовых стилей, шрифтов, цветов, разделителей и пр., определяющих фирменный стиль издания. Редактируется в Style Manager.

Система сеток поста — набор CSS-правил для построения модульных сеток с колонками и отступами, а также адаптации под мобильные устройства. Редактируется в Style Manager.

Все стили и системы сеток в рамках компании выгружаются из Style Manager на CDN в виде CSS-файла со стилями и JSON-файла с мета-информацией для использования в редакторе.

 

Как запустить редактор на странице

Для полноценной работы редактора требуется 5 файлов, которые нужно подключить на страницы редактирования и/или просмотра поста: 

 

Файл

Описание

На странице редактирования поста

На странице просмотра поста

editor.min.js

Основной файл редактора

да

 

editor.min.css

Стили интерфейса редактора

да

 

company_name.min.css

Стили издания, сгенерированные в Style Manager

да

да

company_name.json

JSON с мета-данными, необходимыми для работы редактора

да

 

public.js

JS-код, необходимый для работы интерактивных возможностей редактора (галереи, анимации)

 

да

Ниже приведен пример кода для инициализации редактора.

HTML:

<!DOCTYPE html>
<html>
  <head>

    <!-- 1. Подключаем основной файл редактора -->
    <script
     src="https://ceditor.setka.io/path/to/editor.min.js">
    </script>

    <!-- 2. Подключаем стили интерфейса редактора -->
    <link
     rel="stylesheet"
     href="https://ceditor.setka.io/path/to/editor.min.css">

    <!-- 3. Подключаем CSS-файл со стилями издания -->
    <link
     rel="stylesheet"
     href="https://ceditor.setka.io/path/to/company_name.min.css">

  </head>
  <body>

    <!-- 4. Размещаем на странице контейнер для редактора -->
    <div class="stk-editor" id="setka-editor"></div>

  </body>
</html>

JavaScript:

// Загружаем JSON с мета-данными

// (если JSON был заранее сохранен где-то на сервере,
// достаем его оттуда)

fetch('https://ceditor.setka.io/path/to/company_name.min.json')

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

  .then(response => {

    const config = response.config;
    const assets = response.assets;

// Передаем публичный токен (public_token) компании
// (он нужен для отправки запросов из редактора в API editor.setka.io)
config.public_token = 'my_public_token_123456';

    // Стартуем редактор
    SetkaEditor.start(config, assets);

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

 

Как получить контент из редактора для сохранения в БД

Каждый пост, созданный в редакторе, определяется тремя сущностями:

  1. содержимое поста (контент)
  2. id стиля (Style)
  3. id системы сеток (Grid System)

Соответственно, в базу данных нужно сохранять все эти значения:

// Возвращает HTML-код поста вместе с обрамляющим контейнером
// <div class="stk-post">
SetkaEditor.getHTML({ includeContainer: true });

// Возвращает объект со свойствами выбранного стиля поста
// (в базу данных достаточно сохранять id)
SetkaEditor.getCurrentTheme();

// Возвращает объект со свойствами выбранной системы сеток поста
// (в базу данных достаточно сохранять id)
SetkaEditor.getCurrentLayout();

 

Важно: не следует получать контент из редактора при помощи обращения к DOM-элементам на странице, т.к. они содержат вспомогательные элементы, которые требуются только при работе в редакторе, и не должны попадать в сохраненный HTML-код поста. Всегда используйте метод SetkaEditor.getHTML().

 

Как открыть в редакторе сохраненный ранее пост

Чтобы открыть в редакторе существующий пост, нужно вызвать метод SetkaEditor.replaceHTML после окончания инициализации редактора.

// Достаем из базы данных содержимое поста
const postContentFromDB = '
 <div class="stk-post stk-theme_2407 stk-layout_4col_1565">
   <p>Текст поста</p>
 </div>
';

// Достаем из базы данных ID стиля и системы сеток,
// с которыми был сохранен данный пост

const themeId = '2407';
const layoutId = '4col_1565';

// Загружаем JSON с мета-данными
fetch('https://ceditor.setka.io/path/to/company_name.min.json')

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

  .then(response => {

    const { config, assets } = response;

    // Указываем в конфиге ID стиля и системы сеток,
    // с которыми должен стартовать редактор

    config.theme = themeId;
    config.layout = layoutId;

    // Стартуем редактор

    SetkaEditor.start(config, assets);

   // Кладем в редактор содержимое поста из БД

    SetkaEditor.replaceHTML(postContentFromDB);

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

Важно: Setka Editor работает с собственной структурой HTML-кода. Пост должен находиться в контейнере <div class=”stk-post”>...</div> и содержать элементы с определенными классами и атрибутами. «Чужеродные» элементы могут стать нередактируемыми или привести к ошибке при запуске редактора. Нет смысла пытаться открыть в Setka Editor посты, созданные в другом редакторе или вручную.

 

Как загрузить картинки из редактора на сервер

Интерфейс Setka Editor поддерживает следующие операции с картинками:

  1. загрузка
  2. удаление
  3. редактирование атрибута alt

Чтобы Setka Editor загружал картинки на ваш сервер, необходимо написать REST API, который будет обрабатывать запросы от редактора и выполнять соответствующие действия на стороне бэкенда.


Первым делом необходимо передать путь к корню REST API при запуске редактора:

// ...

/*
  Все запросы из редактора будут отправляться
  с учетом корневого URL REST API, например:
  /api/setka-editor/v1/images
  /api/setka-editor/v1/snippets
  /api/setka-editor/v1/…
*/

config.restApiUrl = '/api/setka-editor/v1/';

/*
  Параметр restApiRequestPayload позволяет добавлять
  ко всем запросам из редактора произвольные параметры
  (например, авторизационный токен или id поста).
*/

config.restApiRequestPayload = {
  authToken: 'qwerty123456',
  postId: 42
};

// Стартуем редактор
SetkaEditor.start(config, assets);

REST API должен уметь принимать и обрабатывать следующие запросы (cм. ниже). Редактор рассматривает статус-код ответа 200 как успех операции, прочие статус-коды — как ошибку.

 

Загрузка картинок

Запрос

URL

/%API_ROOT%/images

Метод

POST

Тип содержимого

multipart/form-data

Тело запроса

объект file со свойствами картинки

Ответ

Коды статуса

200 — успех
4xx, 5xx — ошибка

Тип содержимого

application/json

Тело ответа

 

{

  // id сохраненной картинки на сервере
  "id": "abc-def-123-456",

  // путь к картинке
  "url": "http://example.com/image.jpg",

  // путь к уменьшенной картинке (необязательно)
  "thumbUrl": "http://example.com/image_thumb.jpg"

}

 

Удаление картинки

Запрос

URL

/%API_ROOT%/images/:id

Метод

DELETE

Тип контента

application/json

Тело запроса

Ответ

Статус-коды

200 — успех
4xx, 5xx — ошибка

Тип содержимого

Тело ответа

 

Редактирование свойств картинки

 

Запрос

URL

/%API_ROOT%/images/:id

Метод

PUT

Тип содержимого

application/json

Тело запроса

{
  // Измененные свойства картинки
  "props": {
    "name": "value"
  }
}

Ответ

Статус-коды

200 — успех
4xx, 5xx — ошибка

Тип содержимого

Тело ответа

 

Сохранение сниппета

В будущем сохранение сниппетов планируется перенести полностью на сторону редактора.

Запрос

URL

/%API_ROOT%/snippets

Метод

POST

Тип содержимого

application/json

Тело запроса

{

  // Временный id сниппета
  "id": "aac90814-6a50-406d-822a-d8849df52d51",

  // Название сниппета
  "name": "My snippet"

  // HTML-код сниппета
  "code": "<p>snippet text</p>",

  // id текущего стиля поста
  "themeId": "2407"

}

Ответ

Статус-коды

200 — успех
4xx, 5xx — ошибка

Тип содержимого

Тело ответа

– 

 

Как запустить редактор с набором картинок

Чтобы стартовать редактор с определенным набором картинок в правой панели (например, загруженных ранее к сохраненному посту), необходимо передать их в массив assets при запуске редактора в определенном формате.

// ...

// Достаем картинки из БД и формируем массив в нужном формате:
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'
 },

 {
   // ...
 }

];

// Добавляем картинки к ресурсам редактора

assets.images = postImages;

// Стартуем редактор
SetkaEditor.start(config, assets);
 

Дополнительные параметры

Вы можете инициализировать Setka Editor с дополнительными параметрами:

// ...получаем config и assets из JSON

// Параметр postWidthPresets позволяет задавать значения ширины поста
// в переключателе «View post as» в нижней части редактора
// at the bottom of the editor
config.postWidthPresets = [640, 800, 960];

// Выводить отладочную информацию при старте редактора
config.debug = true;

// Стартуем редактор
SetkaEditor.start(config, assets);

Кастомная интеграция: