use iframe

Подготовка текста с использование инструментов Литеры 5

Для воплощения этого сценария работы в API Литеры имеются следующие функции:

• POST check - инициация процесса проверки и получение URL с редактором Литеры
• GET iframe - редактор Литеры с проверяемым текстом и начатой проверкой

Так же на сайте партнёра необходимо реализовать следующие методы:

• POST on-save-corrected - сохранение результатов работы над текстом
• POST on-iframe-failure - обработка непредвиденных ошибок в редакторе Литеры
• GET return-to-cms - переход пользователя к работе с текстом на сайте партнёра
• POST on-initial-stats - обработка предварительных результатов первичной проверки

Общее описание процесса

Для интеграции по этому сценарию программистам Сайта партнёра нужно выполнить следующие мероприятия:

• На странице редактирования текста на сайте партнёра добавить кнопку "Проверить", которая будет начинать процесс. По нажатию на эту кнопку сервер сайта партнёра будет получать ссылку на редактор Литеры с начатой проверкой.
• Получив ссылку на редактор Литеры, необходимо передать управление пользователя на работу с этой ссылкой. Для этого есть следующие возможности:
  • Перенаправить основное окно браузера пользователя на полученную ссылку с редактором Литеры
  • Открыть новое окно браузера с полученной ссылкой
  • Показать пользователю iframe с полученной ссылкой, встроив таким образом редактор Литеры непосредственно в страницу сайта
• Реализовать серверные методы сайта для обработки результатов работы с текстом в редакторе Литеры

На стороне Литеры

Это методы API предоставляемые сервером Литеры.

POST check

При помощи этого метода можно начать процесс проверки и получить одноразовую ссылку на редактор Литеры с начатой проверкой.

Параметры запроса

Документ для проверки

Набор параметров характеризующих текст для проверки на Сайте партнёра и позволяющих связать его с документом Литеры и в обратную сторону.

• token - Этот параметр нужен для того, чтобы идентифицировать текст на сайте партнёра. По окончании работы над документом указанное здесь значение будет передано в функцию POST on-save-corrected на сайте партнёра. Это может быть информация закодированная в строку, например ${userId}-${documentId} или же можно в базе данных создать некоторую запись с детальными параметрами, а в качестве значения параметра token указать только номер этой записи. В любом случае по этому параметру должно быть возможно определить чего делать на сайте с полученным из редактора Литеры текстом.
• document - Идентификатор документа в Литере. Если указан, то будет продолжена работа над тем же самым документом, если нет, то будет создан новый документ. Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в Литере5 с документом может работать только один пользователь. Поэтому несмотря на то, что в CMS с документом могут работать различные пользователи, при работе с одним и тем же документом в API имеет смысл передавать в login не идентификатор текущего пользователя CMS Партнёра, а идентификатор пользователя создавшего данный документ в Литере5 (того пользователя в результате проверки которого был выдан этот document). В противном случае API выдаст ошибку о недостатке прав пользователя на работу с документом.
• name - Название документа (title, subject) для использования в отчётах веб-интерфейса Литеры. Не проверяется. Если не указано, то будет сформировано автоматически из текста.
• html - Собственно текст для проверки в формате html. Если указан document, и не указан html, тогда откроется редактор с последней версией документа сохранённого в Литере. Если же текст указан, то он заместит собой текст выбранного document или инициирует процесс создания нового документа. Либо document либо html должно быть обязательно указано. Для того, чтобы в редакторе показывались иллюстрации к тексту, нужно в поле src тэга img указывать абсолютный сетевой путь к файлу иллюстрации. Если вам необходимо сохранить какие-то дополнительные атрибуты тэгов, то их можно сохранить в атрибутах с префиксом data-litera5-api-. Например, в вашей базе данных хранятся относительные пути к иллюстрациям, или пути с переменными чтобы редактор смог корректно отобразить иллюстрации в атрибут src нужно поместить абсолютную ссылку, но хочется сохранить и внутреннюю ссылку, её можно поместить в атрибут data-litera5-api-src при отправке на проверку и восстановить из этого атрибута при получении результатов. Если возникает необходимость исключить из проверки какие-то части текста, например, примеры кода программ, сложные таблицы, галереи изображений и тому подобное, то для этого нужно поместить соответствующие блоки html в <div></div> с одним из следующих атрибутов:
  • data-litera5-nocheck – когда нужно исключить содержимое элемента из проверки.
  • data-litera5-hidden – когда нужно исключить содержимое элемента из проверки и вообще не показывать его пользователю

Дополнительные поля для проверки

Бывает так, что в программах подготовки текстов документ как бы состоит из несколько кусочков, которые расположены в отдельных полях формы редактирования и хранятся в самостоятельных полях базы данных. Но по сути - это некоторые дополнительные текстовые поля которые желательно бы проверить и откорректировать одновременно с основным текстом документа. Для этого в Литере существует возможность добавить в проверку дополнительные поля. Вот как будет выглядеть редактор Литеры с заполненными дополнительными полями:

• title - Заголовок документа для проверки
• description - Краткое описание страницы для проверки
• keywords - Ключевые слова для проверки
• custom - Здесь можно задать любые дополнительные текстовые поля, которые нужно проверить и откорректировать вместе с основным проверяемым текстом.
  Важно! На проверку этих дополнительных полей желательно передавать именно html, а не простой текст. Простой текст лучше обернуть тэгом <p></p>. Это связано с особенностями реализации дополнительных полей в редакторе. На деле – это обычные <div></div> визуально оформленные специальным образом. Если внутри такого <div> будет находиться элемент <p>, то при нажатии клавиши Enter редактор создаст новый параграф в элементе <p> внутри элемента <div>. Если же разместить текст непосредственно внутри <div> без дополнительного элемента <p>, то при нажатии клавиши Enter, редактор сдублирует элемент <div> в котором располагался текст. Поэтому, если текст для проверки в дополнительных полях будет передан без обёртки в html тэги, то он будет обёрнут в тэг <p> принудительно. Необходимо иметь это ввиду при обработке результатов. Для того, чтобы пользователь видел какое именно дополнительное поле он редактирует можно добавить текстовую метку с описанием поля. Текстовая метка располагается над выделенным блоком дополнительного поля. Текстовые метки реализованы при помощи CSS. Поэтому если вам нужно подписать свои произвольные дополнительные поля, то нужно будет

Ответ сервера Литеры

В результате обращения к методу POST check сервер Сайта партнёра получает два значимых результата:

• document - Идентификатор документа в системе Сайта созданный в результате запроса. Его можно использовать в будущем при повторных доработках текста.
• url - Одноразовая ссылка на редактор Литеры документа переданного в запросе, которую можно открывать в новом окне, или в IFRAME на Сайте Партнёра. К полученному в этом параметре значению нужно будет добавить базовый URL сервера Литеры, чтобы получить полную ссылку. В случае с облачной Литерой - это будет https://litera5.ru, а в случае автономной установки - адрес вашего локального сервера Литеры.

> Формальное описание метода...

GET iframe

Именно ссылка на этод метод будет получена в результате обращения к функции POST check. Это одноразовая ссылка редактора документа с возможностью проверки и корректировки, с которым могут работать пользователи. Ссылка жёстко связана с проверкой определённого текста определённым пользователем Литеры. Время действия такой одноразовой ссылки органичено одними сутками. В зависимости от актуального состояния конкретной ссылки результат попытки её использования будет различным. Вот внутренняя модель состояний такой одноразовой ссылки:

> Формальное описание метода...

На стороне Сайта партнёра

POST on-save-corrected

Вызовом этого метода завершается работа над текстом в редакторе Литеры. В нём необходимо воплотить сохранение отредактированного документа в системе Сайта партнёра и перенаправить пользователя на дальнейшую работу с текстом на Сайте партнёра. В ответ на вызов этого метода нужно вернуть URL на страницу GET return-to-cms. Это сделано для того, чтобы при использовании ссылки GET iframe в отдельной вкладке/окне была возможность передать управление на Сайт партнёра.

Параметры запроса

Основные параметры

• html - Отредактированный текст документа. Если не указан, то это означает, что пользователь нажал кнопку "Отменить правки и вернуться в CMS", то есть решил не возвращать сделанные правки на Сайт партнёра.
• stats - JSON модель статистического отчёта (описание формата модели). Присутствует только если в настройках партнёра (POST setup) включена настройка getStats.

Дополнительные поля

• title - Отредактированный текст заголовка (если передавался в запросе)
• description - Отредактированный текст описания (если передавался в запросе)
• keywords - Отредактированный текст ключевых слов (если передавался в запросе)
• custom - Отредактированные тексты дополнительных полей (если они передавались в запросе)

Ответ сервера Сайта

• url - Ссылка на страницу Сайта Партнёра GET return-to-cms на которую будет перенаправлен пользователь в окне редактора Литеры при помощи HTTP 302 редиректа.

> Формальное описание метода...

POST on-iframe-failure

Вызовом этого метода завершается обработка ошибочных ситуаций в редакторе Литеры. В нём необходимо воплотить перенаправление пользователя на дальнейшую работу с текстом на Сайте партнёра. В ответ на вызов этого метода нужно вернуть URL на страницу GET return-to-cms.

Параметры запроса

• token - Идентификатор текста и пользователя на сайте партнёра переданный в ходе запроса POST check.

Информация для службы поддержки Литеры

Эта информация может помочь разобраться с произошедшим.

• url - URL при обработке которого произошла ошибка. Эта информация может понадобиться службе
• code - Код ошибки произошедшей при обработке одноразовой ссылки
• message - Текст сообщения об ошибке

Ответ сервера Сайта

• url - Ссылка на страницу Сайта Партнёра GET return-to-cms на которую будет перенаправлен пользователь в окне редактора Литеры при помощи HTTP 302 редиректа.

> Формальное описание метода...

GET return-to-cms

Единственная задача этого метода - это закрыть окно редактора Литеры и передать управление на страницу Сайта партнёра. Переходом на эту страницу завершается работа пользователя с редактором Литеры. И ссылку на неё нужно вернуть в методах POST on-save-corrected и POST on-iframe-failure. Ссылка на эту страницу может содержать в себе какие-то дополнительные параметры, чтобы перевести пользователя на страницу Сайта именно с тем текстом, с которым пользователь работал до перехода в редактор Литеры.

> Формальное описание метода...

POST on-initial-stats

Этот метод нужен только если вы собираетесь делать какую-то предварительную обработку результатов проверки. Для того, чтобы этот метод начал использоваться сервером Литеры, необходимо заполнить настройку onInitialStats ссылкой на этот метод Сайта. Например, можно реализовать следующий сценарий:

• когда пользователь нажимает кнопку "Проверить" на сайте, вы не сразу перенаправляете его в редактор,
• а сначала создаёте iframe с редактором Литеры,
• затем дожидаетесь результатов первичной проверки
• и если они удовлетворяют вашим критериям (вроде количества ошибок какой-либо категории), то показываете редактор Литеры пользователю,
• а если порог срабатывания не превышен, то просто удаляете этот "невидимый для пользователя" iframe, а пользователю сообщаете, что всё с его текстом и так хорошо.

Именно такой сценарий отражён на диаграмме.

Параметры запроса

• token - Идентификатор текста и пользователя на сайте партнёра, переданный в запросе POST check.
• error - Сообщение о произошедшей ошибке в ходе проверки. Одно из полей error или stats будет заполнено обязательно. И они не могут быть заполнены одновременно. Наличие сообщения об ошибке означает, что документ не смог провериться из-за каких-то проблем в Литере.
• stats - JSON модель статистического отчёта (описание модели).

Ответ сервера Сайта

• cancel - Логическое значение true - означает, что работа с документом заверена и не будет продолжена пользователем.

> Формальное описание метода...