HistoryDataModel

HistoryDataModel is a general name for data related to a timeline event. Backend prepares such data, for the frontend to properly render this event. Most frequently, this data contains modified records from TimelineEntry, with added/deleted/updated specific fields.

Historically, controller prepares view data for an event, associated with a specific entity using the method prepareHistoryDataModel.

For example, record with ASSOCIATED_ENTITY_TYPE_ID === \CCrmOwnerType::Deal will be processed in \Bitrix\Crm\Timeline\DealController::prepareHistoryDataModel.

API was created from the namespace \Bitrix\Crm\Timeline\HistoryDataModel to separate event registration responsibility from responsibility to prepare data for display within a timeline smart processes. In the future, HistoryDataModel preparation to new API will be dedicated from the legacy controllers legacy. New technique is recommended for use when creating new controllers.

General operation logic

Entry point is the class HistoryDataModel\Maker. Its method prepareHistoryDataModel can get the required data. The signature os identical to the old method.

Based on the received data, object HistoryDataModel\Presenter is collected Inside HistoryDataModel\Maker. This object directly prepares HistoryDataModel.

Presenter and EntityImplementation

HistoryDataModel data to be included, depends on the event type (conversion, creating an element, its updates) and on the entity type, included into the event (Deal, Quote, SPA). Previously, such variety was implemented due to each entity having its own controller, that checked event type via if-else. To simplify the code usage and adding new types of events/entities, the new API realizes the data variety using the "Bridge pattern" Bridge — is a structural design pattern that separates one of several classes into two standalone hierarchies: abstracts and implementations, allowing mutual interchangeability. .

Note: Subsequent explanation uses terminology from abovementioned pattern description.

The class Presenter - is an "abstract". Object of this class executes the main data preparation work. For some types of events it can have a descendant (Presenter\Creation, Presenter\Conversion), which can separately process the data in this event environment (set various titles, descriptions and etc.).

In case, such event type doesn't have a special descendant and it's processed by the Presenter base class (in this case, it acts as Null-object).

The class EntityImplementation - is an "implementation". Object of this class is implemented to "customize" HistoryDataModel depending on the entity type. This can both for getting entity-dependant data, for example an element title (specific name for a deal, quote and etc.), brief description of element or entity type, human-readable field (ASSIGNED_BY_ID -> "Responsible"). This class can have descendants for a specific entity type (for example, for a deal), modifying the parent's behaviour. In case, no special descendant exist for an entity type, uses the base class EntityImplementation (once again, it acts as Null-object).

This way, all possible variants of how HistoryDataModel can be collected for a frontend, it's divided into two hierarchies of classes which branch out independently from each other. If required, you can modify the restoration event processing by creating the class Presenter\Restore. And if you need to update the description for an order, create the class EntityImplementation\Order.