Перейти к содержанию

Разработка пользовательских блоков

Определения

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

  • Граф - место, где создаются блоки, с последующим их расчетом
  • Блок - элемент, который имеет свою структуру и свой код выполнения
  • Системные блоки - блоки, которые предустановлены в системе
  • Пользовательский блок - нестандартный блок (плагин), который создал пользователь
  • Визуализатор - блок, у которого есть визуальное отображение
  • Пресет - место, где отображаются визуализаторы
  • Расчет блока - выполнение кода, за который отвечает блок
  • Манифест - описание блока
  • Компонент - код блока, которые описывает его работу
    • component.py - код написанный на python, и реализует backend составляющую работы блока
    • component.js - код написанный на javaScript, и реализует визуальное отображение блока

Язык и среда разработки

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

  • Python (можно использовать IDE/Редакторы такие, как PyCharm, VSCode, Vim/NVim, блокнот)
  • JavaScript (можно использовать IDE/Редакторы такие, как Vim, VSCode, Atom Editor, блокнот)

Версионирование

Для успешной разработки новых блоков потребуются навыки работы с системой управления версиями Git.

Подключение к репозиторию пользовательских блоков

Разработка пользовательских блоков происходит в репозитории http://gitlab.int.bittechno.ru/bit/vismind-library.

Для начала работы с репозиторием клонируем его к себе командой clone

git clone http://gitlab.int.bittechno.ru/bit/vismind-library.git

Разработку нового блока рекомендуется делать в отдельной ветке. Ветку создавать от ветки develop

git checkout -b 'название_ветки' origin/develop

Подготовка проекта

Для того что бы создать новый блок, необходимо создать проект в директории ./library.

  • Создаем новую директорию, где имя будет состоять из тега блока и приставки vismind (Пример: vismind-<tag-блока>).
  • В созданную папку копируем файлы из папки library\vismind-template
    • Можно скопировать только Makefile и .env.example (см. раздел "Работа с Makefile")
    • Либо скопировать все файлы

Работа с Makefile

Чтобы работать с Makefile, необходимо взять шаблон .env.example из репозитория с пользовательскими блоками, назвать его .env и установить следующие параметры:

  • AUTHOR_NAME - имя автора, который разрабатывает блок
  • PACKAGE_TAG - тег блока
  • PACKAGE_NAME - название блока
  • PACKAGE_VERSION - версия блока

Makefile с Windows

Работать с Makefile в windows можно под wsl.

Из командной строки можно вызывать инициализацию проекта ($ make initialize) или же создать конкретные файлы, такие как:

  • Шаблон манифеста ($ make manifest)
  • Файл с backend'ом блока ($ make python-component)
  • Файл с логикой визуализатора ($ make javascript-component)
  • Файл с зависимостями проекта ($ make docs)
  • Файл с зависимостями проекта ($ make python-dependencies)

Сборка в .tar

Для того чтобы собрать блок в .tar архив для последующего импорта в приложения, необходимо вызывать ($ make build)

Разработка блока

Разработка блока состоит из:

Разработка визуализаторов

Если блок является визуализатором, необходимо указать это в манифесте (visualizer), в .tar обязателен component.js (нативный .js либо min.js если используется фреймворк)

Публикация блока в приложении

  • Собрать .tar архив (с помощью Makefile или средствами операционной системы). В архиве должны быть только файлы: manifest.json, component.py и component.js (если блок визуализатор)
  • Опубликовать с помощью апи
    • Уточняем у администратора адрес сервиса для библиотеки пользовательских блоков (Например: http://test.int.bittechno.ru:37106)
    • Заходим на страницу с описанием апи (http://test.int.bittechno.ru:37106/docs)
    • В разделе "Components" находим POST api /v1/components
    • Нажимаем кнопку "Try it out"
    • В разделе "Request body" для параметра file выбираем собранный .tar архив
    • Нажимаем кнопку "Execute"
    • В "Responses" смотрим ответ от api. В ответе будет статус "Created"/"Updated" или описание ошибки
  • Опубликовать с помощью веб сервиса
    • Уточняем у администратора адрес библиотеки пользовательских блоков (Например: http://test.int.bittechno.ru:37107)
    • На главной странице нажать кнопку 'Загрузить', выбрать нужный .tar

Версии пользовательских блоков

Если версия блока на сервисе уже есть, то обновить версию на сервисе не получится. Надо либо поднять версию блока, либо сначала удалить версию с сервиса, а потом ее опубликовать.