Документация по фронтенду
Схема API
Эта схема показывает, как данные проходят через приложение от и до API.
Сигналы
Система сигналов - это механизм, который VST Utils использует для настройки приложения.
Давайте посмотрим, как это работает.
Очень часто вам нужно что-то изменить после того, как произошло какое-то событие. Но как вы можете узнать о этом событии? А что, если вам нужно знать об этом событии в нескольких блоках кода?
Чтобы решить эту проблему, VST Utils использует систему сигналов, где:
вы можете отправить какой-то сигнал, который сообщит всем подписчикам, что произошло какое-то событие, и передать некоторые данные/переменные из контекста, где произошло это событие;
вы можете подписаться на какой-то сигнал, который уведомит вас о каком-то событии, и вы также можете передать некоторый обратный вызов (обработчик), который может делать что-то с данными/переменными, которые были переданы из контекста, где произошло событие.
Генерация сигнала
Чтобы сгенерировать сигнал, вам нужно написать следующее в своем коде:
tabSignal.emit(name_of_signal, context);
где:
name_of_signal - строка, которая хранит имя сигнала (события);
context - некоторая переменная любого типа, которая будет передана в обратный вызов (обработчик) во время подключения к этому сигналу.
Пример генерации сигнала:
let app = {
name: 'example of app';
};
tabSignal.emit('app.created', app);
Подключение к сигналу
Чтобы подключиться к какому-то сигналу, вам нужно написать следующее в своем коде:
tabSignal.connect(name_of_signal, callback);
где:
name_of_signal - строка, которая хранит имя сигнала (события);
callback - функция, которая может выполнять действия с переменными, которые будут переданы из контекста события в этот обратный вызов в качестве аргументов.
Пример подключения к сигналу:
/* ... */
function callback(app) {
app.title = 'example of app title';
}
tabSignal.connect('app.created', callback);
/* ... */
Список сигналов в VST Utils
VST Utils имеет несколько сигналов, которые генерируются во время работы приложения. Если вам нужно настроить что-то в вашем проекте, вы можете подписаться на эти сигналы и добавить функцию обратного вызова с желаемым поведением. Также вы можете генерировать свои сигналы в своем проекте.
openapi.loaded
Имя сигнала: «openapi.loaded».
Аргумент контекста: openapi - {object} - OpenAPI-схема, загруженная из API.
Описание: Этот сигнал генерируется после загрузки схемы OpenAPI. Вы можете использовать этот сигнал, если вам нужно что-то изменить в схеме OpenAPI, прежде чем она будет разобрана.
resource.loaded
Имя сигнала: «resource.loaded».
Аргумент контекста: Нет.
Описание: Этот сигнал генерируется после успешной загрузки всех статических файлов и их добавления на страницу.
app.version.updated
Имя сигнала: «app.version.updated».
Аргумент контекста: Нет.
Описание: Этот сигнал генерируется во время загрузки приложения, если VST Utils обнаруживает, что версия вашего проекта была обновлена.
app.beforeInitRouter
Имя сигнала: «app.beforeInitRouter».
Аргумент контекста: obj - {object} - Объект со следующей структурой: {routerConstructor: RouterConstructor}, где routerConstructor - это экземпляр RouterConstructor.
Описание: Этот сигнал генерируется после создания экземпляра RouterConstructor и перед созданием приложения.
app.beforeInit
Имя сигнала: «app.beforeInit».
Аргумент контекста: obj - {object} - Объект со следующей структурой: {app: app}, где app - это экземпляр класса App.
Описание: Этот сигнал генерируется после инициализации переменной приложения (разбор схемы OpenAPI, создание моделей и представлений), но перед тем, как приложение будет смонтировано на страницу.
app.afterInit
Имя сигнала: «app.afterInit».
Аргумент контекста: obj - {object} - Объект со следующей структурой: {app: app}, где app - это экземпляр класса App.
Описание: Этот сигнал генерируется после того, как приложение было смонтировано на страницу.
app.language.changed
Имя сигнала: «app.language.changed».
Аргумент контекста: obj - {object} - Объект со следующей структурой: {lang: lang}, где lang - это код примененного языка.
Описание: Этот сигнал генерируется после изменения языка интерфейса приложения.
models[model_name].fields.beforeInit
Имя сигнала: «models[» + model_name + «].fields.beforeInit». Например, для модели пользователя: «models[User].fields.beforeInit».
Контекстный аргумент: fields - {object} - Объект с парами ключ-значение, где ключ - имя поля, значение - объект с его опциями. На данный момент поле - просто объект с опциями, это не экземпляр guiFields.
Описание: Этот сигнал генерируется перед созданием экземпляров guiFields для полей модели.
models[model_name].fields.afterInit
Имя сигнала: «models[» + model_name + «].fields.afterInit». Например, для модели пользователя: «models[User].fields.afterInit».
Контекстный аргумент: fields - {object} - Объект с парами ключ-значение, где ключ - имя поля, значение - экземпляр guiFields.
Описание: Этот сигнал генерируется после создания экземпляров guiFields для полей модели.
models[model_name].created
Имя сигнала: «models[» + model_name + «].created». Например, для модели пользователя: «models[User].created».
Контекстный аргумент: obj - {object} - Объект со следующей структурой: {model: model}, где model - созданная модель.
Описание: Этот сигнал генерируется после создания объекта модели.
allModels.created
Имя сигнала: «allModels.created».
Контекстный аргумент: obj - {object} - Объект со следующей структурой: {models: models}, где models - объект, хранящий объекты моделей.
Описание: Этот сигнал генерируется после создания всех моделей.
allViews.created
Имя сигнала: «allViews.created».
Контекстный аргумент: obj - {object} - Объект со следующей структурой: {views: views}, где views - объект со всеми экземплярами представлений.
Описание: Этот сигнал генерируется после создания всех экземпляров представлений с установленными свойствами actions / child_links / multi_actions / operations / sublinks.
routes[name].created
Имя сигнала: «routes[» + name + «].created». Например, для представления /user/: «routes[/user/].created».
Контекстный аргумент: route - {object} - Объект со следующей структурой: {name: name, path: path, component: component}, где name - имя маршрута, path - шаблон пути маршрута, component - компонент, который будет отображаться для текущего маршрута.
Описание: Этот сигнал будет генерироваться после формирования маршрута и добавления его в список маршрутов.
allRoutes.created
Имя сигнала: «allRoutes.created».
Контекстный аргумент: routes - {array} - Массив объектов маршрутов со следующей структурой: {name: name, path: path, component: component}, где name - имя маршрута, path - шаблон пути маршрута, component - компонент, который будет отображаться для текущего маршрута.
Описание: Этот сигнал генерируется после формирования всех маршрутов и добавления их в список маршрутов.
<${PATH}>filterActions
Имя сигнала: «<${PATH}>filterActions».
Контекстный аргумент: obj - {actions: Object[], data} - Actions - массив объектов действий. Data представляет данные текущего экземпляра.
Описание: Этот сигнал будет выполнен для фильтрации действий.
<${PATH}>filterSublinks
Имя сигнала: «<${PATH}>filterSublinks».
Контекстный аргумент: obj - {sublinks: Object[], data} - Sublinks - массив объектов подссылок. Data представляет данные текущего экземпляра.
Описание: Этот сигнал будет выполнен для фильтрации подссылок.
Field Format
Файловые форматы
Часто при создании нового приложения разработчикам нужно создавать общие поля некоторых базовых типов и форматов (строка, булево, число и так далее). Создание каждый раз подобной функциональности довольно скучно и неэффективно, поэтому мы попытались решить эту проблему с помощью VST Utils.
VST Utils содержит набор встроенных полей наиболее распространенных типов и форматов, которые могут использоваться в различных случаях. Например, когда вам нужно добавить какое-то поле в веб-форму, которое должно скрывать значение вставленного значения, просто установите соответствующий формат поля на password вместо string, чтобы вместо фактических символов отображались звездочки.
Все доступные классы полей хранятся в переменной guiFields.На данный момент в VST Utils 44 формата полей:
base - базовое поле, все остальные поля наследуются от этого поля;
string - строковое поле для вставки и представления коротких значений „string“;
textarea - строковое поле для вставки и представления длинных значений „string“;
number - числовое поле для вставки и представления значений „number“;
integer - числовое поле для вставки и представления значений формата „integer“;
int32 - числовое поле для вставки и представления значений формата „int32“;
int64 - числовое поле для вставки и представления значений формата „int64“;
double - числовое поле для вставки и представления значений формата „double“;
float - числовое поле для вставки и представления значений формата „float“;
boolean - логическое поле для вставки и представления значений „boolean“;
choices - строковое поле с жестким набором предопределенных значений, пользователь может выбрать только одно из доступных значений;
autocomplete - строковое поле с набором предопределенных значений, пользователь может либо выбрать одно из доступных значений, либо ввести свое собственное значение;
password - строковое поле, скрывающее вставленное значение знаками „*“
file - строковое поле, способное считывать содержимое файла;
secretfile - строковое поле, которое может считать содержимое файла, а затем скрыть его при отображении;
binfile - строковое поле, которое может считать содержимое файла и преобразовывать его в формат „base64“;
namedbinfile - поле в формате JSON, которое принимает и возвращает JSON с 2 свойствами: name (строка) - имя файла и content (строка base64) - содержание файла;
namedbinimage - поле в формате JSON, которое принимает и возвращает JSON с 2 свойствами: name (строка) - имя изображения и content (строка base64) - содержание изображения;
multiplenamedbinimage - поле в формате JSON, которое принимает и возвращает массив объектов, состоящих из 2 свойств: name (строка) - имя изображения и content (строка base64) - содержание изображения;
multiplenamedbinimage - поле в формате JSON, которое принимает и возвращает массив объектов, состоящих из 2 свойств: name (строка) - имя изображения и content (строка base64) - содержание изображения;
text_paragraph - строковое поле, представленное в виде текстового абзаца (без каких-либо вводов);
plain_text - строковое поле, сохраняющее все непечатные символы во время представления;
html - строковое поле, содержащее различные теги HTML и отображающее их во время представления;
date - поле даты для вставки и представления значений „date“ в формате „YYYY-MM-DD“;
date_time - поле даты для вставки и представления значений „date“ в формате „YYYY-MM-DD HH:mm“;
uptime - строковое поле, которое преобразует продолжительность времени (количество секунд) в один из наиболее подходящих вариантов (23:59:59 / 01d 00:00:00 / 01m 30d 00:00:00 / 99y 11m 30d 22:23:24) в зависимости от его размера;
time_interval - числовое поле, которое преобразует время из миллисекунд в секунды;
crontab - строковое поле, которое имеет дополнительную форму для создания расписания в формате „crontab“;
json - поле в формате JSON, во время представления использует другие guiFields для представления текущих свойств поля;
api_object - поле, используемое для представления некоторого экземпляра модели из API (значение этого поля - все данные экземпляра модели). Это только для чтения поле;
fk - поле, используемое для представления некоторого экземпляра модели из API (значение этого поля - первичный ключ экземпляра модели). Во время режима редактирования у этого поля есть строгий набор предопределенных значений для выбора;
fk_autocomplete - поле, используемое для представления некоторого экземпляра модели из API (значение этого поля - первичный ключ экземпляра модели или некоторая строка). Во время режима редактирования пользователь может либо выбрать одно из предопределенных значений из списка автозаполнения, либо ввести свое собственное значение;
fk_multi_autocomplete - поле, используемое для представления некоторого экземпляра модели из API (значение этого поля - первичный ключ экземпляра модели или некоторая строка). Во время режима редактирования пользователь может либо выбрать одно из предопределенных значений из модального окна, либо ввести свое собственное значение;
color - строковое поле, которое сохраняет шестнадцатеричный код выбранного цвета;
inner_api_object - поле, которое связано с полями другой модели;
api_data - поле для представления некоторых данных из API;
dynamic - поле, которое может изменять свой формат в зависимости от значений окружающих полей;
hidden - поле, скрытое от представления;
form - поле, объединяющее несколько других полей и сохраняющее их значения как один JSON, где key - имя поля формы, value - значение поля формы;
button - специальное поле для формы, имитирующее кнопку в форме;
string_array - поле, преобразующее массив строк в одну строку;
string_id - строковое поле, предназначенное для использования в URL как ключ „id“. Он имеет дополнительную проверку, которая проверяет, что значение поля не равно некоторым другим ключам URL (new/ edit/ remove).
Настройка макета с использованием CSS
Если вам нужно настроить элементы с помощью CSS, у нас есть некоторая функциональность для этого. К корневым элементам EntityView (если он содержит ModelField), ModelField, ListTableRow и MultiActions применяются классы в зависимости от полей, которые они содержат. Классы формируются для полей типов «boolean» и «choices». Кроме того, классы применяются к кнопкам операций и ссылкам.
- Правила генерации классов:
EntityView, ModelField и ListTableRow- field-[field_name]-[field-value]- Пример:
«field-active-true» для модели, содержащей поле «boolean» с именем «active» и значением «true»
«field-tariff_type-WAREHOUSE» для модели, содержащей поле «choices» с именем «tariff_type» и значением «WAREHOUSE»
MultiActions- selected__field-[field_name]-[field-value]- Пример:
«selected__field-tariff_type-WAREHOUSE» и «selected__field-tariff_type-SLIDE», если выбраны 2 строки
ListTableRow, содержащие поле «choices» с именем «tariff_type» и значениями «WAREHOUSE» и «SLIDE» соответственно.
Operation- operation__[operation_name]- Предупреждение
Если вы скрываете операции с использованием классов CSS и, например, все действия были скрыты, то кнопка выпадающего списка действий все равно будет видна.
Для более тщательного контроля над действиями и подссылками см. Изменение действий или подссылок
- Пример:
operation__pickup_point, если кнопка операции или ссылка имеют имя pickup_point
На основе этих классов вы можете изменять стили различных элементов.
- Несколько вариантов использования:
Если вам нужно скрыть кнопку для действия «change_category» на странице подробной информации о продукте, когда продукт неактивен, вы можете сделать это, добавив селектор CSS:
.field-status-true .operation__change_category { display: none; }
Скрыть кнопку для действия «remove» в меню
MultiActions, если выбран хотя бы один продукт со статусом «active»:.selected__field-status-true .operation__remove { display: none; }
Если вам нужно изменить цвет фона на красный для заказа со статусом «CANCELLED» на компоненте
ListView, сделайте следующее:.item-row.field-status-CANCELLED { background-color: red; }
В этом случае вам нужно использовать дополнительный класс «item-row» (Используется для напримера, вы можете выбрать другой) для указания элемента, который будет выбран в селекторе, потому что класс «field-status-CANCELLED» добавляется в различные места на странице.