Интерфейс из бандла

Иногда возникает необходимость использовать разрабатываемые вне платформы интерфейсы разметки. Такие интерфесы могу быть созданы с использованием любых технологий.

Бандл — это html-файл, внутри которого находится содержимое файлов css и js.

Подготовка бандла

Для сборки html-файла со всеми ресурсами вы можете использовать любой удобный способ или воспользоваться скриптом:

  1. Для использования скрипта вам потребуется node.js.

  2. Разместите скрипт в той же директории, что и папка build.

  3. Запустите в консоли команду node prepareBuild.js.

После успешного выполнения скрипта в той же директории, где находится скрипт, будет сгенерирован файл index.html со всеми ресурсами внутри.

  • Скрипт работает только для файлов, которые указаны в тегах <script> и <link> в вашем html-файле.

  • По умолчанию путь до директории с билдом — ./build. Вы можете изменить его, задав новый путь в качестве аргумента node prepareBuild.js ./new_path_to_build.

Загрузка бандла

Чтобы загрузить бандл, нажмите на кнопку Загрузить Bundle:

upload bundle

Перед вами появится модальное окно, в котором вы можете:

  • загрузить новый html-файл. В этом случае произойдет обновление всех полей интерфейса

  • обновить существующий html-файл. В таком случае обновления полей интерфейса не произойдет. Обновится лишь содержимое по ссылке указанной в поле bundleSrc в секции CONFIG

upload bundle modal

Все бандлы загружаются в датасет с именем interface_bundles. Если такого датасета не существует, то он будет создан автоматически

Использования API в бандлах

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

Example data
{
    "context": [...]
}

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

Config
{
    "entities": [...]
}

Для общения основного приложения TagMe со сторонним приложением используется внутренний API, который будет доступен через window.parent.tmAPI. API используется для получения данных задачи, валидации и отправке результат разметки и показа ошибок.

Свойства

  • task — содержит данные задания: из реальных данных с платформы или из Example data.

Параметр Обязательность Описание

data

Да

Данные для задания. Уникальное для каждого задания

config

Да

Конфигурация интерфейса проекта. Заполняется в поле CONFIG

meta

Да

Дополнительная информация о задании

token

Нет

Токен задания. Используется для запросов к стораджу. Имеет значение только на экране разметки.

premarkup

Да

Предразметка задания. Уникальное для каждого задания

  • task.meta

Параметр Обязательность Описание

userId

Да

id пользователя

taskId

Нет

id задачи

stage

Да

Экран разметки. Возможные значения "preview", "preview_task", "prepare_task", "result", "markup"

isControlAnswer

Нет

На экране "result" показывает контрольное это задание или нет.

Методы

  • onSubmit - функция, которая вызывается перед отправкой результата для получения данных из бандла. Ожидает объект в качестве возвращаемого значения.

  • onValidate - функция, которая вызывается перед отправкой результата. Проверяет валидность результирующих данных. Ожидаемые занчения: true если данные валидные, string если данные не валидные и есть текст ошибки валидации, false если данные не валидные (будет показана дефолтная ошибка валидации)

  • saveMarkupToStorage - функция, сохраняющая текущий результат разметки в localStorage. Сохраненный результат будет использоваться в качестве предразметки.

Пример
    window.parent.tmAPI.onValidate =  () => {
        if (typeof values !== 'object') return "Не верный формат данных"

        if (Object.values(values).some((value) => value === undefined)) {
            return "Вы оценили не все параметры!"
        }

        return true
    }

    window.parent.tmAPI.onSubmit = () => {
        return result_from_bundle
    }

  • setError(error) — устанавливает ошибку, в качестве параметра принимает объект, содержащий 3 поля:

    • message — заголовок ошибки;

    • description — описание ошибки;

    • details — дополнительные данные об ошибке.

    • stack — stack trace ошибки.

Пример
    window.parent.tmAPI.setError({
            message: 'При формировании задания произошла ошибка',
            description:
                'Мы пометим, что это задание привело к ошибке, и проигнорируем его в результатах.\n Пожалуйста, перейдите к следующему заданию',
            stack: error.stack,
            details: {
                name: error.name,
                message: error.message,
                componentStack: error.componentStack
            }
        })
bundle error
Пример результата разметки при ошибке
{
  "result": {
    "error": {
      "message": "При формировании задания произошла ошибка",
      "description": "Мы пометим, что это задание привело к ошибке, и проигнорируем его в результатах.\n Пожалуйста, перейдите к следующему заданию",
      "details": {
        "name": "Error",
        "message": "Synthetic error",
        "componentStack": "\n    at Bi (about:srcdoc:62:57436)\n    at Md (about:srcdoc:62:58715)\n    at div\n    at Od (about:srcdoc:62:57519)"
      },
      "stack": "Error: Synthetic error\n    at about:srcdoc:62:57457\n    at al (about:srcdoc:62:24194)\n    at Jn (about:srcdoc:62:42084)\n    at wd (about:srcdoc:62:40937)\n    at Sn (about:srcdoc:62:39999)\n    at Fi (about:srcdoc:62:36680)\n    at vn (about:srcdoc:60:3267)\n    at about:srcdoc:62:34080"
    }
  },
  "status": "error"
}

Все не перехваченные ошибки внутри приложения перехватываются на уровне iframe.