Falcon Space. Работа с сущностями

Введение в сущности

Сущность - это некий объект, который должен иметь возможность последовательно менять свой статус.

При этом возможна реализация разграничения полномочий на смену статуса между ролями. А также автоматизация дополнительных функционалов при смене статуса сущностью (например, отправка уведомлений, формирование неких других объектов, добавление комментариев, и т. д.).

В системе автоматически ведется лог изменения статусов сущности.

Реализация механизма Сущности

Будем рассматривать на примере. Допустим есть такой объект в нашей системе как Проект. Мы хотим реализовать Проект как Сущность.

1. Создание новой сущности, описание возможных статусов

В меню Компоненты / Сущности добавим запись о новой сущности Проект, указав её код project. При этом в БД добавится новая запись в системную таблицу as_en_entities.

Далее перейдем на страницу со статусами новой сущности и добавим там последовательно все необходимые статусы. Физически статусы сущности хранятся в системной таблице as_en_statuses.

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

Обязательно указывайте номер по порядку для статуса, а также цвет.

Далее необходимо заполнить возможные переходы из каждого статуса в меню Доступные статусы.

Например, из статуса Черновик проект можно перевести только в статус Опубликован, либо в Аннулирован. Причем право на выполнение этого перехода есть только у роли customer. На кнопках выбора следующих статусов будет написано соответственно Опубликовать и Аннулировать.

2. Экземпляры сущности

Сама сущность Проект - это одна запись в таблице as_en_entities с кодом project.

Экземпляры сущности, например, Проект №1, Проект №2, Проект №3, и т. д., будут храниться в таблице as_en_entityInstances.

В первом пункте мы создали сущность Проект. Необходимо теперь привязать это понятие к нашим проектам в базе данных. Делается это следующим образом.

Допустим наши проекты и вся информация по ним лежит в таблице au_projects. Теперь необходимо добавить в эту таблицу еще одно поле - instanceID. Это будет внешний ключ к таблице as_en_entityInstances. Таким образом, создастся связь типа “один к одному” между au_projects и as_en_entityInstances.

Перечень экземпляров сущности, в нашем случае - перечень конкретных проектов, выводятся на страницу с помощью обычного сниппета таблицы

<div class="as-dashboard" data-code="forAdmin"></div>


Разумеется, необходимо предварительно реализовать в системе таблицу projects.

3. Добавление нового экземпляра сущности

Самый простой способ создания нового экземпляра сущности - это реализация FastCreate в таблице с перечнем экземпляров данной сущности.

Например, в таблице проектов projects быстрым созданием по названию будет создаваться новый проект. При этом необходимо в crud_projects_fastCreate прописать вставку новой записи не только в au_projects, но и предварительно вставку новой записи в as_en_entityInstances. И только потом с полученным новым instanceID вставлять новую запись в au_projects.

4. Страница экземпляра сущности

Для формирования страницы для работы с отдельным экземпляром сущности необходимо предварительно создать форму объекта, который выступает сущностью. Форма объекта, как обычно, будет содержать поля объекта для просмотра или редактирования.

В нашем случае создадим форму entityProject для управления полями объекта Проект.

После этого создадим страницу для экземпляра сущности, на которой расположим сниппеты:

  • Обычный сниппет формы:
    <div class="as-form" data-code="{formCode}" data-itemid="falcon-space--rabota-s-sushchnostyami"></div>
  • Cниппет для управления статусами экземпляра сущности:
    <div class="entity" data-code="{entityCode}" data-itemid="falcon-space--rabota-s-sushchnostyami" data-type="item"></div>

Пример оформления страницы для экземпляра сущности Проект:

Таким образом, указатель текущего статуса и кнопки для доступных дальнейших переходов будут расположены в правой колонке от формы проекта:

5. Переход от страницы с перечнем сущностей к странице с выбранным экземпляром

Очень важно правильно настроить переход на страницу выбранного экземпляра сущности из таблицы с перечнем. Тут есть следующий нюанс.

Когда вы делаете одну из колонок таблицы ссылкой на страницу экземпляра, то под видом itemID следует передавать не id из проектной таблицы экземпляров, а именно instanceID.

Например, в случае с нашими проектами:

6. Важное замечание о логировании смены статусов

Запись о смене статуса в лог as_en_statusesLog производится автоматически только в случае естественного перевода экземпляра в следующий статус - нажатием пользователем соответствующей кнопки перевода в статус.

Если где-либо вы программно прописываете реализацию принудительного перехода экземпляра в статус, то не забывайте также вставлять соответствующую запись в as_en_statusesLog.

7. Схема БД реализации механизма сущностей

Хранимые процедуры для работы с сущностями

Процедура ДО изменения статуса

Процедура en_{entityCode}_checkStatus вызывается для выполнения необходимых проверок перед сменой статуса у экземпляра сущности.

Параметры: instanceID, fromStatusCode, toStatusCode, username

Результат Select: msg, result, bit softMode, okButtonStyle, okButtonText, cancelButtonStyle, cancelButtonText.

Параметр softMode:

  • Если softMode = 1, то это означает, что ограничение является нежестким и можно по подтверждению все равно сменить статус.
  • Если softMode = 0, то в случае невозможности сменить статус, идет сообщение об этом, без возможности принудительно сменить статус.

okButtonText,cancelButtonText - задают текст кнопки для Отмены и для Подтверждения действия.

okButtonStyle, cancelButtonStyle - задают стиль кнопки. Значения - danger, warning,success, secondary, primary, info, light

Процедура ПОСЛЕ изменения статуса

Процедура en_{entityCode}_afterChangeStatus вызывается после успешной смены статуса у экземпляра сущности.

Параметры: instanceID, statusCode, username

Результат

SELECT 1: msg, result

SELECT 2: вызовы внешних действий (почта, смс, уведомление и т.д.). См. вызов внешних действий.

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

На клиентскую сторону (в коллбек afterChangeStatus) передаются параметр Msg из хранимки (если непустой) и параметр AdditionalData как результат выполнения внешних действий.  

Процедура вывода дополнительной панели для статуса

Процедура en_{entityCode}_getStatusAdditionalToolbar содержит в себе вывод дополнительной разметки под кнопками переходов в доступные статусы.

Параметры: instanceID, entityCode, statusCode, username, langID

Результат Select: msg, result

В данном случае msg содержит строку разметки дополнительной панели.

Например, когда проект будет переведен в статус Выполнен, можно добавить в дополнительную панель кнопку “Добавить отзыв”. Тогда msg должна содержать, к примеру, вызов модальной формы на добавление отзыва исполнителю проекта.

CREATE PROCEDURE [dbo].[project]
	@instanceID int,
	@entityCode nvarchar(32),
	@statusCode nvarchar(32),
	@username nvarchar(32),
	@langID int = 1
AS
BEGIN
	if @statusCode = 'done'
           SELECT 'Добавить отзыв' Msg,
                   1 Result
        else
           SELECT '' Msg, 0 Result
END

Выглядеть это будет так:

Хранимая процедура вывода доступных статусов

По умолчанию используется стандартная процедура as_en_getAvailableStatusesForInstance.

Если вам необходима своя процедура, то вы устанавливаете режим Кастомная процедура AvailStatuses = ДА и реализуете процедуру en_{entityCode}_getAvailableStatusesForInstance (столбец SQL доступных статусов)

Как сделать JS коллбек после смены статуса 

Для этого объявляем функцию 

$(function(){
   as.entity.callbacks["{entityCode}_afterChangeStatus"]=function(data, params){
       // data - то что пришло от сервера, params - code, itemID, statusCode
   }
});

Платформа Falcon Space

Это снижение стоимости владения

за счет меньшего количества людей для поддержки

Это быстрое внесение изменений

по ходу эксплуатации программы

Это современный интерфейс

полная адаптация под мобильные устройства

Бесплатное обучение разработке на Falcon Space

Вы можете разрабатывать самостоятельно или сотрудничать с нами в плане веб-разработки на платформе Falcon Space.
Примечание

Google поиск по нашей документации