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

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

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

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

Все стили и системы сеток в рамках компании располагаются на CDN Setka (ceditor.setka.io) в виде CSS-файла со стилями и JSON-файла с мета-информацией для использования в редакторе.

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

Файл	Описание	На странице редактирования поста	На странице просмотра поста
editor.v.1.2.3.min.js	Основной файл редактора	да
editor.v.1.2.3.min.css	Стили интерфейса редактора	да
company_name.v.1.2.3.min.css	Стили издания, сгенерированные в Управлении дизайн системой	да	да
company_name.v.1.2.3.json	JSON с мета-данными, необходимыми для работы редактора	да
public.v.1.2.3.js	JS-код, необходимый для работы интерактивных возможностей редактора (галереи, анимации)		да

Шаги интеграции редактора

Чтобы полноценно использовать Setka Editor, необходимо выполнить 4 основных шага интеграции:

1. Подключить необходимые файлы на страницу редактирования поста и добавить код инициализации редактора

2. Подключить необходимые файлы на страницу просмотра поста

3. Настроить сохранение HTML-кода постов в БД и загрузку обратно в редактор

4. Научить редактор загружать и удалять картинки на вашем сервере

1. Инициализация редактора

Пример кода инициализации редактора.


    // 1. Задаем пути к файлам редактора
    // (на CDN Setka Editor или своем сервере):
      
    // Основной файл редактора
    const EDITOR_JS_URL =
    'https://ceditor.setka.io/path/to/editor.v.1.2.3.min.js';
    
    // Стили интерфейса редактора
    const EDITOR_CSS_URL =
    'https://ceditor.setka.io/path/to/editor.v.1.2.3.min.css';
    
    // Стили компании
    const COMPANY_CSS_URL =
    'https://ceditor.setka.io/path/to/company_name.v.1.2.3.min.css';
    
    // Мета-данные компании
    const COMPANY_JSON_URL =
    'https://ceditor.setka.io/path/to/company_name.v.1.2.3.json';
    
    // 2. Определяем контейнер на странице,
    // где будет инициализирован редактор
    const CONTAINER = '.setka-editor-container';
    
    // 3. Указываем публичный токен (public_token) компании
    // для запросов к API editor.setka.io
    // (он находится в разделе «CMS Integration» в Управлении дизайн системой)
    const PUBLIC_TOKEN = 'my_public_token_123456';
    
    // 4. Подключаем файлы редактора на страницу:
    const editorCSS = document.createElement('link');
    editorCSS.rel = 'stylesheet';
    editorCSS.href = EDITOR_CSS_URL;
    document.head.appendChild(editorCSS);
    
    const companyCSS = document.createElement('link');
    companyCSS.rel = 'stylesheet';
    companyCSS.href = COMPANY_CSS_URL;
    document.head.appendChild(companyCSS);
    
    const editorJS = document.createElement('script');
    editorJS.async = true;
    editorJS.src = EDITOR_JS_URL;
    editorJS.onload = initSetkaEditor;
    document.head.appendChild(editorJS);
    
    async function initSetkaEditor() {
      // 5. Загружаем JSON с мета-данными компании
      const res = await fetch(COMPANY_JSON_URL);
      const json = await res.json();
    
      // 6. Задаем параметры инициализации редактора
      const config = {
        ...json.config,
        container: CONTAINER,
        public_token: PUBLIC_TOKEN,
      };
    
      const { assets } = json;
    
      // 7. Запускаем редактор
      SetkaEditor.start(config, assets);
    }

Важно: в данный момент возможен запуск только одного экземпляра Setka Editor на странице.

Чтобы остановить и удалить запущенный ранее редактор со страницы, вызовите метод:


    SetkaEditor.stop()

2. Подключение файлов на страницу просмотра поста

Для корректного отображения постов на внешние страницы сайта нужно подключить следующие файлы:

company_name.v.1.2.3.min.css — CSS-стили поста

public.v.1.2.3.js — JS-код для запуска интерактивных элементов (галереи, анимации,примечания и др.)

Важно: не подключайте файл public.js на страницу редактирования поста.

Как получить JSON поста

SetkaEditor.getJSON()

Метод доступен только при ключеJSONExport

Как получить assets (images, layouts, symbols, themes)

SetkaEditor.getAssets()

Как получить текущий стиль поста

SetkaEditor.getCurrentTheme()

Как получить текущую сетку поста

SetkaEditor.getCurrentLayout()

3. Сохранение HTML-кода в БД и загрузка обратно в редактор

Как задать содержимое поста

SetkaEditor.setHTML(HTML)

где HTML - required string

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

Для получения HTML-кода поста из редактора существует специальный метод:


    SetkaEditor.getHTML();

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

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

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


    async function initSetkaEditor() {
      // ...
    
      // Загружаем из БД содержимое поста
      const postContent = await loadPostContentFromDB();
    
      // ...
    
      // Запускаем редактор
      SetkaEditor.start(config, assets);
    
      // Кладем в редактор содержимое поста из БД
      SetkaEditor.replaceHTML(postContent);
    }

Важно: не помещайте HTML-код поста на страницу редактирования этого поста. Если в коде содержатся теги <script> или <iframe>, то они будут исполнены браузером, а также к элементам внутри редактора могут примениться стили анимаций.

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

4. Работа с картинками

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

Чтобы Setka Editor мог работать с картинками на вашем сервере, необходимо сделать следующее:

1. Создать на своем сервере API для операций с картинками или использовать уже существующее. Реализация API остается полностью на ваше усмотрение.

2. Написать JavaScript-функции для взаимодействия с API (примеры функций приведены ниже).

3. Указать эти функции при инициализации редактора:


    async function initSetkaEditor() {
      // ...
      config.onFileUpload = uploadFile;
      config.onFileRemove = removeFile;
      config.onFileUpdate = updateFile;
      // ...
      SetkaEditor.start(config, assets);
    }

Редактор поддерживает атрибут srcset для картинок, поэтому вы можете генерировать разные размеры изображения и передавать их в ключе sizes при старте редактора и при загрузке новых картинок. В результате на странице просмотра поста автоматически подгрузится изображение той ширины, которая подходит для ширины браузера пользователя.

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


    // Задаем функцию-коллбэк для загрузки файла
    // Она получает в качестве аргумента объект file
    // и должна возвращать промис
    function uploadFile(file) {
      return new Promise(async (resolve, reject) => {
        try {
          // Загружаем файл на сервер, в облако, etc.
          // любым удобным способом: fetch, axios, ...
          const res = await uploadFileToServer(file);
          if (res.status !== 200) {
            reject({ message: res.statusText });
          }
    
          const json = await res.json();
    
          // Резолвим промис объектом с необходимыми свойствами
          resolve({
            // id сохраненной картинки на сервере
            id: 'abc-def-123-456',
  
            // имя файла картинки
            name: 'image.jpg'
  
            // полный путь к картинке
            url: 'https://example.com/image.jpg',
  
            // полный путь к уменьшенной картинке (необязательно)
            thumbUrl: 'https://example.com/image_thumb.jpg',
  
            // alt-текст к картинке (необязательно)
            alt: 'alternative text',
            
            // ширина картинки (необязательно)
            width: 100,
            // высота картинки (необязательно)
            height: 100,
            
            // разные размеры картинок для атрибута "srcset" (необязательно)
            sizes: [
              { width: 100, height: 100, url: 'image-small.jpg' },
              { width: 400, height: 400, url: 'image-medium.jpg' },
              { width: 1000, height: 1000, url: 'image-large.jpg' },
            ]
          });
        }
        catch (ex) {
          reject({ message: ex });
        }
      }
    }

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


    // Задаем функцию-коллбэк для удаления файла
    // Она получает в качестве аргумента id файла
    // и должна возвращать промис
    function removeFile(id) {
      return new Promise(async (resolve, reject) => {
        try {
          // Удаляем файл с сервера
          const res = await removeFileFromServer(id);
    
          // Если удаление прошло успешно, резолвим промис
          if (res.status === 200) {
            resolve();
          }
    
          // Если что-то пошло не так, реджектим промис
          else {
            reject({ message: res.statusText });
          }
        }
        catch (ex) {
          reject({ message: ex });
        }
      }
    }

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


    // Задаем функцию-коллбэк для редактирования файла
    // Она получает в качестве аргумента id файла
    // и объект props с обновленными свойствами файла,
    // и должна возвращать промис
    function updateFile(id, props) {
      return new Promise(async (resolve, reject) => {
        try {
          // Обновляем файл на сервере
          const res = await updateFileOnServer(id, props);
    
          // Если обновление прошло успешно, резолвим промис
          if (res.status === 200) {
            resolve();
          }
    
          // Если что-то пошло не так, реджектим промис
          else {
            reject({ message: res.statusText });
          }
        }
        catch (ex) {
          reject({ message: ex });
        }
      }
    }

Запуск редактора с набором картинок

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


    async function initSetkaEditor() {
      // ...
      
      // Достаем картинки из БД и формируем массив в нужном формате:
      const postImages = [
        {
          // id сохраненной картинки на сервере
          id: 'abc-def-123-456',
    
          // имя файла картинки
          name: 'image.jpg'
    
          // полный путь к картинке
          url: 'https://example.com/image.jpg',
      
          // полный путь к уменьшенной картинке (необязательно)
          thumbUrl: 'https://example.com/image_thumb.jpg',
    
          // alt-текст к картинке (необязательно)
          alt: 'alternative text',
    
          // разные размеры картинок для атрибута "srcset" (необязательно)
          sizes: [
            { width: 100, height: 100, url: 'image-small.jpg' },
            { width: 400, height: 400, url: 'image-medium.jpg' },
            { width: 1000, height: 1000, url: 'image-large.jpg' },
          ]
        }
      ];
      
      // Добавляем картинки к ресурсам редактора
      assets.images = postImages;
      
      // Запускаем редактор
      SetkaEditor.start(config, assets);
    }

Как получить изображения из панели

SetkaEditor.getImages()

Интеграция с хранилищами изображений

В Setka Editor вы можете не только загружать картинки в пост вручную с компьютера или выбирать из библиотеки картинок Unsplash, но также сделать интеграцию со своим хранилищем изображений в вашей CMS. Эта интеграция позволит вам выбирать и использовать в новых Setka Editor постах изображения из ранее загруженных в хранилище. После того, как вы реализуете интеграцию, в источниках подгрузки картинок в правую панель редактора появляется дополнительный пункт "Media Library" (вы можете задать любое название интеграции с вашим хранилищем изображений).

По нажатию на него открывается попап с изображениями и поиском по ним. Вы можете управлять тем, какой набор картинок будет по умолчанию отображаться в попапе. К примеру, вы можете по умолчанию не выводить туда изображения или вывести самые часто используемые изображения или набор изображений по определенному поисковому запросу. Поиск должен быть реализован на стороне вашей CMS.

После того, как изображение выбрано в попапе, оно подгружается в правую панель редактора и с ним можно работать как с обычным изображением, загруженным в пост стандартным способом.

Пример, как это работает в нашей встроенной интеграции с медиа-библиотекой на WordPress:

Описание интеграции

```
isSearchable: true | false
```
отвечает за отображение поиска в интерфейсе;
```
title: { en: String, ru: String }
```
отвечает за названия интеграции в интерфейсе;
```
onLoadImages: async function() {}
```
функция, которая вызывается при загрузке изображений в редакторе;
```
onFetchImages: async function() {}
```
функция, которая загружает изображения, вставленные в пост.

Полный пример интеграции:

const getGiphy = id => loadXHR(`${GIPHY_BASE_URL}/${id}?api_key=${GIPHY_API_KEY}`);
customMediaLibrary: {
  isSearchable: true,
  title: { en: 'Giphy', ru: 'Гифи' },
  onLoadImages: async ({ imagesLoaded, searchValue }) => {
    const response = await searchGiphy(searchValue, 10, imagesLoaded);
    const images = response.data.map(item => ({
      id: item.id,
      filename: item.title || 'Untitled',
      url: item.images.original.url
    }));
    return images;
  },
  onFetchImages: async imagesIds => {
    const responses = await Promise.all(imagesIds.map(id => getGiphy(id)));
    const images = responses
      .filter(Boolean)
      .map(item => item.data)
      .map(item => ({ id: item.id, filename: item.title, url: item.images.original.url }));
    return images;
  }
}

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

Как задать стиль поста

SetkaEditor.setTheme(id)

где id — required number

Как задать сетку поста

SetkaEditor.setLayout(id)

где id — required number

Как задать отступ для шапки Setka Editor

Если у вас на странице уже есть «прилипающий» при прокрутке блок (например, верхняя панель с навигацией), вы можете задать отступ для шапки Setka Editor, чтобы панели не накладывались друг на друга.

Размер отступа должен быть равен высоте вашей верхней или нижней «прилипающей» панели, соответственно.


    // верхний отступ для верхней панели редактора
    config.headerTopOffset = 55;

    // нижний отступ для нижней панели редактора
    config.footerBottomOffset = 20;

Как отслеживать изменения в редакторе

Чтобы подписаться на изменения контента поста в редакторе, используйте функцию-коллбэк onPostContentChange:


    config.onPostContentChange = () => {
      console.log('Post content has changed');
    }

Как получить статус редактора

Код возвращает true/false в зависимости от того, запущен ли сейчас редактор

SetkaEditor.isRunning()

Как получить состояние редактора

SetkaEditor.getState()

Как получить конфигурацию редактора

SetkaEditor.getConfig()

Запуск редактора внутри контейнера с внутренней прокруткой

Если вы запускаете редактор в DOM-контейнере с внутренней прокруткой, то для корректного «прилипания» верхней и нижней панелей к границам этого контейнера нужно передать его CSS-селектор в параметре scrollingElement:

config.scrollingElement = '.scrolling-element';

Значение по умолчанию — window.document.

Как добавить свои стили или скрипты в превью редактора

Чтобы добавить свои стили или скрипты в режиме превью редактора (открывающемуся по нажатию клавиши Tab), используйте ключи previewCSS (для стилей) и previewJS (для скриптов), содержащие массивы с путями к необходимым файлам:


    config.previewCSS = ['https://example.com/styles.css'];
    config.previewJS = ['https://example.com/script.js'];

Работа с функциями редактора без запросов к сторонним CDN

Даже если в процессе работы с API Управление дизайн системой вы сохраняете файлы стилей и редактора у себя на платформе, часть внутреннего функционала редактора (Типограф, база бесплатных изображений Unsplash, редактор изображений, интеграция с Библиотекой файлов на WordPress) всегда подгружается с CDN Setka Editor. Если ваша платформа запрещает обращение к файлам на сторонних ресурсах, необходимо дополнительно сохранить эти файлы к себе и подключить их при инициализации редактора. Обратите внимание, что файлы должны лежать по ссылке без редиректа. Файлы внутреннего функционала редактора можно получить, связавшись со службой поддержки support@setka.io или в чате Intercom.

Для подключения этих файлов, при инициализации редактора воспользуйтесь ключом featureRootURL. В нем необходимо передать путь к папке на вашем сервере, где располагаются файлы:


    config.featureRootURL = 'https://www.example.com/assets/';

После чего редактор будет запрашивать файлы по адресам вида:


    https://www.example.com/assets/typograph/0.1.0/i_typograph.js
    https://www.example.com/assets/unsplash/0.1.0/i_unsplash.js

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

С чего начать кастомную интеграцию
Интеграция с Управлением дизайн системой
Инициализация Setka Post Editor (JavaScript)

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

Содержание:

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