HistoryDataModel

HistoryDataModel - это общее название для данных о каком-то событии таймлана. Их подготавливает backend для того, чтобы фронт мог правильно отрисовать это событие. Чаще всего эти данные представляют собой модифицированные записи из TimelineEntry, в которых добавлены/удалены/изменены некоторые поля.

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

Например, запись с ASSOCIATED_ENTITY_TYPE_ID === \CCrmOwnerType::Deal будет обработана в \Bitrix\Crm\Timeline\DealController::prepareHistoryDataModel.

Чтобы отделить ответственность регистрации событий от ответственности подготовки данных для отображения, в рамках работы над таймлайном смарт-процессов был написан API из пространства имен \Bitrix\Crm\Timeline\HistoryDataModel. В будущем планируется выделить из старых контроллеров подготовку HistoryDataModel в новое API. При написании новых контроллеров рекомендуется использовать новый механизм.

Общая логика работы

Точкой входа является класс HistoryDataModel\Maker. Через его метод prepareHistoryDataModel можно получить необходимые данные. Сигнатура идентична старому методу.

Внутри HistoryDataModel\Maker на основе полученных данных происходит сборка объекта HistoryDataModel\Presenter, который, собственно, и занимается подготовкой HistoryDataModel.

Presenter и EntityImplementation

То, какие конкретно данные нужно включить в HistoryDataModel, зависит от типа события (конвертация, создание элемента, его изменения) и от типа сущности, про которую идет речь в событии (Сделка, Предложение, Смарт-процесс). Раньше данная вариативность реализовывалась за счет того, что на каждую сущность был свой контроллер, внутри которого через if-else проверялся тип события. Чтобы упростить переиспользование кода и добавление новых типов событий/сущностей, в новом API вариативность реализуется с помощью паттерна "Мост" Мост — это структурный паттерн проектирования, который разделяет один или несколько классов на две отдельные иерархии — абстракцию и реализацию, позволяя изменять их независимо друг от друга.

Подробнее на refactoring.guru. .

Примечание: Дальнейшее объяснение использует термины из описания вышеуказанного паттерна.

Класс Presenter (презентатор) - это "абстракция". Объект данного класса выполняет основную работу по подготовке данных. Для некоторых типов события у него может быть наследник (Presenter\Creation, Presenter\Conversion), который может как-то по-особенному обработать данные в специфике этого события (задать разные заголовки, описания и т.п.).

В случае, если для какого-то типа события нет специального наследника, то его обрабатывает базовый класс Presenter (в этой ситуации он выступает как Null-object).

Класс EntityImplementation - это "реализация". Объект данного класса используется для того, чтобы "кастомизировать" HistoryDataModel в зависимости от типа сущности. Это может быть получение сущносте-зависимых данных, например заголовка элемента (название конкретной сделки, предложения и т.п.), краткого описания элемента или типа сущности, человекочитаемого названия поля (ASSIGNED_BY_ID -> "Ответственный"). У данного класса могут быть наследники для какого-то конкретного типа сущности (например, для сделки), модифицирующие поведение родителя. В случае, если для типа сущности нет специального наследника, то используется базовый класс EntityImplementation (опять-таки, он выступает как Null-object).

Таким образом, все возможные варианты того, как конкретно нужно собрать HistoryDataModel для фронта, разбиваются на две иерархии классов, которые разрастаются независимо друг от друга. При необходимости модифицировать обработку события восстановления, создается класс Presenter\Restore. А если нужно изменить описание для заказа, создается класс EntityImplementation\Order.