#Потік подій

#Вступ

Якщо ви хочете запускати певні власні дії при зміні форми, ви можете скористатися потоком подій. Окрім форм, сторінки, блоки, кнопки та поля також можуть використовувати потоки подій для налаштування власних операцій.

#Як використовувати

Нижче наведено простий приклад, щоб пояснити, як налаштувати потік подій. Давайте реалізуємо зв'язок між двома таблицями: при натисканні на певний рядок у лівій таблиці дані в правій таблиці автоматично фільтруватимуться.

Кроки налаштування наступні:

1. Натисніть іконку «блискавка» у верхньому правому куті блоку лівої таблиці, щоб відкрити інтерфейс налаштування потоку подій.
2. Натисніть «Додати потік подій (Add event flow)», у полі «Подія-тригер (Trigger event)» виберіть «Клік по рядку (Row click)», що означає запуск при натисканні на рядок таблиці.
3. Налаштуйте «Час виконання (Execution timing)», який використовується для керування черговістю цього потоку подій відносно вбудованих системних процесів. Зазвичай можна залишити значення за замовчуванням; якщо ви хочете вивести повідомлення або виконати перехід після завершення вбудованої логіки, виберіть «Після всіх потоків (After all flows)». Більше пояснень дивіться нижче у розділі Час виконання.
4. «Умова-тригер (Trigger condition)» використовується для налаштування умов, за яких потік подій буде запущено. У цьому прикладі нам не потрібно налаштовувати умови, оскільки потік має спрацьовувати при будь-якому кліку по рядку.
5. Наведіть курсор на «Додати крок (Add step)», щоб додати кроки операцій. Виберіть «Встановити область даних (Set data scope)», щоб налаштувати область даних для правої таблиці.
6. Скопіюйте UID правої таблиці та вставте його в поле «UID цільового блоку (Target block UID)». Нижче одразу з'явиться інтерфейс налаштування умов, де ви зможете визначити область даних для правої таблиці.
7. Давайте налаштуємо умову, як показано на малюнку нижче:
8. Після налаштування області даних необхідно оновити блок, щоб відобразити результати фільтрації. Далі налаштуємо оновлення блоку правої таблиці. Додайте крок «Оновити цільові блоки (Refresh target blocks)» і введіть UID правої таблиці.
9. Нарешті, натисніть кнопку збереження в нижньому правому куті, і налаштування буде завершено.

#Детально про події

#Перед рендерингом (Before render)

Універсальна подія, яку можна використовувати на сторінках, у блоках, кнопках або полях. У цій події можна виконувати ініціалізаційну роботу. Наприклад, налаштовувати різні області даних залежно від різних умов.

#Клік по рядку (Row click)

Ексклюзивна подія для блоків таблиць. Запускається при натисканні на рядок таблиці. При спрацьовуванні в контекст додається «Запис натиснутого рядка (Clicked row record)», який можна використовувати як змінну в умовах та кроках.

#Зміна значень форми (Form values change)

Ексклюзивна подія для блоків форм. Запускається при зміні значення поля форми. В умовах та кроках можна отримати значення форми через змінну «Поточна форма (Current form)».

#Клік (Click)

Ексклюзивна подія для кнопок. Запускається при натисканні на кнопку.

#Час виконання

У налаштуваннях потоку подій є два поняття, які легко сплутати:

• Подія-тригер: коли починається виконання (наприклад: Перед рендерингом, Клік по рядку, Клік, Зміна значень форми тощо).
• Час виконання: у яке місце вбудованого процесу слід вставити ваш власний потік подій після того, як відбулася подія-тригер.

#Що таке «вбудовані процеси / вбудовані кроки»?

Багато сторінок, блоків або операцій самі по собі мають набір вбудованих системних процесів обробки (наприклад: надсилання форми, відкриття модального вікна, запит даних тощо). Коли ви додаєте власний потік подій для тієї самої події (наприклад, «Клік»), «Час виконання» визначає:

• чи виконати ваш потік подій спочатку, чи спочатку виконати вбудовану логіку;
• або вставити ваш потік подій до чи після певного кроку вбудованого процесу.

#Як розуміти варіанти часу виконання в інтерфейсі?

• Перед всіма потоками (за замовчуванням): виконується першим. Підходить для «перехоплення/підготовки» (наприклад, валідація, підтвердження дії, ініціалізація змінних тощо).
• Після всіх потоків: виконується після завершення вбудованої логіки. Підходить для «завершення/зворотного зв'язку» (наприклад, показ повідомлення, оновлення інших блоків, перехід на сторінку тощо).
• Перед вказаним потоком / Після вказаного потоку: більш точна точка вставки. Після вибору потрібно вказати конкретний «вбудований процес».
• Перед кроком вказаного потоку / Після кроку вказаного потоку: найточніша точка вставки. Після вибору потрібно одночасно вказати «вбудований процес» та «крок вбудованого процесу».

Порада: якщо ви не впевнені, який вбудований процес або крок обрати, пріоритетно використовуйте перші два варіанти («Перед» або «Після»).

#Детально про кроки

#Власна змінна (Custom variable)

Використовується для створення власної змінної з подальшим використанням у контексті.

#Область дії

Власні змінні мають область дії. Наприклад, змінна, визначена в потоці подій блоку, може бути використана лише в цьому блоці. Якщо ви хочете, щоб змінна була доступна у всіх блоках поточної сторінки, її потрібно налаштувати в потоці подій сторінки.

#Змінна форми (Form variable)

Використання значення певного блоку форми як змінної. Налаштування наступні:

• Variable title: Заголовок змінної
• Variable identifier: Ідентифікатор змінної
• Form UID: UID форми

#Інші змінні

Підтримка інших змінних буде додана згодом, слідкуйте за оновленнями.

#Встановити область даних (Set data scope)

Встановлення області даних цільового блоку. Налаштування наступні:

• Target block UID: UID цільового блоку
• Condition: Умова фільтрації

#Оновити цільові блоки (Refresh target blocks)

Оновлення цільових блоків, дозволяє налаштувати кілька блоків одночасно. Налаштування наступні:

• Target block UID: UID цільового блоку

#Перехід за URL (Navigate to URL)

Перехід за певною URL-адресою. Налаштування наступні:

• URL: Цільова URL-адреса, підтримує використання змінних
• Search parameters: Параметри запиту в URL
• Open in new window: Якщо позначено, при переході відкриється нова сторінка браузера

#Показати повідомлення (Show message)

Глобальне відображення інформації про зворотний зв'язок операції.

#Коли використовувати

• Може надавати інформацію про успіх, попередження або помилки.
• Відображається зверху по центру та автоматично зникає; це легкий спосіб сповіщення, який не перериває роботу користувача.

#Налаштування

• Message type: Тип повідомлення
• Message content: Зміст повідомлення
• Duration: Тривалість відображення у секундах

#Показати сповіщення (Show notification)

Глобальне відображення сповіщень та нагадувань.

#Коли використовувати

Відображення сповіщень у чотирьох кутах системи. Часто використовується у таких випадках:

• Досить складний зміст сповіщення.
• Сповіщення з інтерактивними елементами, що пропонують користувачеві подальші дії.
• Активне розсилання системою.

#Налаштування

• Notification type: Тип сповіщення
• Notification title: Заголовок сповіщення
• Notification description: Опис сповіщення
• Placement: Позиція, доступні варіанти: вгорі ліворуч, вгорі праворуч, внизу ліворуч, внизу праворуч

#Виконати JavaScript (Execute JavaScript)

Виконання коду JavaScript.

#Приклад

#Форма: виклик стороннього API для заповнення полів

Сценарій: запуск потоку подій у формі для запиту до стороннього API та автоматичне заповнення полів форми отриманими даними.

Кроки налаштування:

1. Відкрийте налаштування потоку подій у блоці форми та додайте новий потік;
2. У полі «Подія-тригер» виберіть «Перед рендерингом (Before render)»;
3. У полі «Час виконання» виберіть «Після всіх потоків (After all flows)»;
4. Додайте крок «Виконати JavaScript (Execute JavaScript)», вставте та відредагуйте наступний код:

const res = await ctx.api.request({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/users/2',
  skipNotify: true,
  // Примітка: ctx.api за замовчуванням включає поточну авторизацію NocoBase/користувацькі заголовки
  // Тут ми перевизначаємо його "порожнім Authorization", щоб уникнути надсилання токена третій стороні
  headers: {
    Authorization: 'Bearer ',
  },
});

const username = res?.data?.username;

// замініть на реальну назву поля
ctx.form.setFieldsValue({ username });