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

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

Содержание:

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

Шаги интеграции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Интеграция с Setka Editor при невозможности запуска файлов с CDN Setka Editor

 

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

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

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

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

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

Все стили и системы сеток в рамках компании располагаются на 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

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

да

да

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» в Style Manager)
    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 на страницу редактирования поста.

 

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

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

Для получения 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',
  
            // разные размеры картинок для атрибута "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);
    }
  

 

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

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

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

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


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

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

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

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


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

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

Если вы запускаете редактор в 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 Style Manager вы сохраняете файлы стилей и редактора у себя на платформе, часть внутреннего функционала редактора (Типограф, база бесплатных изображений 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
  

 

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