Документация для разработчиков
Документация для разработчиков Документация по D7 Документация по REST Пользовательская документация
Темная тема

EditorAdapter

Общее


Универсальный редактор (компонент bitrix:ui.form и его наследник bitrix:crm.entity.editor) играет важную роль в отрисовке интерфейсов CRM.

Подготовить параметры этого компонента может быть не так просто, особенно, если элемент имеет много полей.

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

Каждый тип сущности имеет свои особенности при работе с полями (как минимум, отличается набор "комплексных полей").

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

Жизненный цикл при работе с этим сервисом выглядит следующим образом:

  • Объект конфигурируется, получая на вход описание дополнительных полей методом addEntityField (которые формируются, как правило, статическими методами этого же класса).
  • Вызывается метод processByItem, в котором происходит подготовка необходимых данных.
  • Добавляются дополнительные данные для редактора методом addEntityData.
  • Обработанные данные получаются из методов getEntityFields и getEntityData и передаются в универсальный редактор.

Методы

Метод Описание С версии
public function __construct
(Field\Collection $fieldsCollection, array $dependantFieldsMap = [])
  • $fieldsCollection - коллекция полей;
  • $dependantFieldsMap - массив зависимых полей, где ключ - это код комплексного поля, а значение - массив полей из коллекции, которые в него входят.
Этим методом не рекомендуется пользоваться напрямую, лучше воспользоваться соответствующим методом фабрики Service\Factory::getEditorAdapter(). 
public function hasData(): bool
 Вернет true, если метод processByItem был вызван хотя бы раз. 
public static function isProductListEnabled(): bool
 Вернет true, если доступен новый грид товаров. 
public function addEntityField(array $field): self
 Добавит дополнительные данные о поле $field. Метод должен вызываться до processByItem. 
public function addEntityData($name, $value): self
 Добавит дополнительные данные $value о имени $name. Метод должен вызываться после processByItem. 
public static function getClientField
(string $title, ?string $fieldName = null, ?string $fieldDataName = null): 
array
  • $title - языковое название поля;
  • $fieldName - код поля. По умолчанию CLIENT;
  • $fieldDataName - название ключа, по которому в дополнительных данных будет передана информация о составе этого поля (данные о компании и контакте).
Вернет описание поля "Клиент". 
public static function getParentField
(string $title, int $parentEntityTypeId, ?string $context = null): 
array
  • $title - языковое название поля;
  • $parentEntityTypeId - идентификатор типа CRM родителя;
  • $context - контекст для селектора.
Вернет описание поля с селектором родителя. 
public static function getProductRowSummaryField
(string $title, ?string $fieldName = null): array
  • $title - языковое название поля;
  • $fieldName - код поля. По умолчанию PRODUCT_ROW_SUMMARY.
Вернет описание поля "Товары". 
public static function getOpportunityField
(string $title, ?string $fieldName = null): array
  • $title - языковое название поля;
  • $fieldName - код поля. По умолчанию OPPORTUNITY_WITH_CURRENCY.
Вернет описание поля типа "Сумма с валютой". 
public static function getUtmField
(string $title, ?string $fieldName = null): array
  • $title - языковое название поля;
  • $fieldName - код поля. По умолчанию UTM.
Вернет описание поля типа "UTM-метки". 
public static function getLocationFieldDescription
(Field $field): array
 Вернет описание поля типа "Местоположение" по объекту этого поля. 
public static function getProductRowProxyController
(string $productEditorId, ?string $fieldName = 'PRODUCT_ROW_PROXY'): 
array
  • $productEditorId - идентификатор грида товаров;
  • $fieldName - код контроллера. По умолчанию PRODUCT_ROW_PROXY.
Вернет описание для контроллера передачи данных о товарах внутри карточки. 
public static function getProductListController
(string $productListId, string $currencyId, 
?string $fieldName = self::CONTROLLER_PRODUCT_LIST): array
  • $productEditorId - идентификатор грида товаров;
  • $currencyId - идентификатор валюты;
  • $fieldName - код контроллера. По умолчанию PRODUCT_LIST.
Вернет описание для контроллера списка товаров. 
public static function prepareEntityUserFields
(array $userFields, array $visibilityConfig, int $entityTypeId, 
int $entityId, string $fileHandlerUrl = ''): array
  • $userFields - массив с описанием настроек пользовательских полей;
  • $visibilityConfig - настройки видимости;
  • $entityTypeId - идентификатор типа CRM;
  • $entityId - идентификатор элемента;
  • $fileHandlerUrl - путь к файлу, отвечающему за отображение пользовательских полей типа "Файл".
Вернет массив с описанием всех пользовательских полей для универсального редактора. 
public function getClientEntityData(): array
 Вернет данные для поля типа "Клиент". Эти данные будут доступны после вызова метода processByItem. 
public static function getUtmEntityData(Item $item): string
 Вернет html для отрисовки поля с UTM-метками. 
public static function getLocationFieldHtml
(Item $item, string $fieldName): ?string
 Вернет html для отрисовки поля "Местоположение". 
public function processByItem
(Item $item, EO_Status_Collection $stages, array $componentParameters = []): 
self
  • $item - элемент, для которого необходимо получить данные и поля;
  • $stages - коллекция стадий;
  • $componentParameters - дополнительные параметры компонента. Здесь может быть:
    • mode - режим работы компонента (см. константы класса \Bitrix\Crm\Component\EntityDetails\ComponentMode). По умолчанию просмотр \Bitrix\Crm\Component\EntityDetails\ComponentMode::VIEW;
    • componentName - название компонента (например, bitrix:crm.item.details);
    • fileHandlerUrl - путь к файлу, отвечающему за отображение пользовательских полей типа "Файл";
    • conversionWizard - класс для выполнения конвертации (если компонент работает в режиме конвертации);
    • entitySelectorContext - контекст для селектора в полях с родителями;
    • isPageTitleEditable - true, если название элемента может быть отредактировано в заголовке страницы.
Запустит обработку для элемента $item. Добавление дополнительных полей и данных должно производиться до вызова этого метода. 
public function saveClientData
(Item $item, string $clientJson): Result
  • $item - элемент;
  • $clientJson - строка в формате json из универсального редактора из поля "Клиент".
Обработает данные о клиенте с фронтенда и произведет необходимые манипуляции с элементом (добавит связи / удалит связи).
Этот метод не производит запись изменений в базу данных. Вернет объект Result, где в данных по ключу processedEntities будет находиться массив идентификаторов элементов, которые были обработаны. 
public function saveClientData
(Item $item, string $clientJson): Result
  • $item - элемент;
  • $clientJson - строка в формате json из универсального редактора из поля "Клиент".
Обработает данные о клиенте с фронтенда и произведет необходимые манипуляции с элементом (добавит связи / удалит связи).
Этот метод не производит запись изменений в базу данных. Вернет объект Result, где в данных по ключу processedEntities будет находиться массив идентификаторов элементов, которые были обработаны. 
public function saveProductsData
(Item $item, string $productsJson): Result
  • $item - элемент;
  • $productsJson - строка в формате json из универсального редактора с данными о товарах.
Обработает данные о товарах с фронтенда и запишет обновленные данные в элемент.
Этот метод не производит запись изменений в базу данных. Вернет объект Result. 
public function saveRelations
(Item $item, array $data): void
  • $item - элемент;
  • $data - массив с данными о родителях элемента:
    • Ключи должны иметь вид PARENT_ID_ + {идентификатор типа CRM родителя}, а значение - ID родителя;
    • Дополнительно может быть два ключа PARENT_TYPE_ID с идентификатором типа CRM родителя и PARENT_ID с ID родителя.
Обработает данные из родительских полей о связях и сохранит изменения в базе данных. 
public function setContext(array $context): void
 Запишет контекст для универсального редактора. 
public function getContext(): array
 Вернет контекст для универсального редактора. 
public static function combineConfigIntoOneSection
(array $entityConfig, string $title = null): array
  • $entityConfig - конфигурация контролов универсального редактора;
  • $title - заголовок нового раздела редактора.
Соберет все контролы из $entityConfig в один раздел с кодом main и заголовком $title. Вернет новую версию конфига. 
public static function markFieldsAsRequired
(array $entityFields, array $requiredFieldNames): 
array
  • $entityFieldsg - описание полей для универсального редактора;
  • $requiredFieldNames - массив кодов обязательных полей.
Пометит все поля из набора $requiredFieldNames в конфиге $entityFields как обязательные. Вернет новую версию конфига. 
public static function getParentFieldName
(int $parentEntityTypeId): string
 Вернет код поля для родителя с идентификатором типа CRM $parentEntityTypeId.

Примеры

use Bitrix\Crm\Service;

$factory = Service\Container::getInstance()->getFactory(\CCrmOwnerType::Quote);

$editorAdapter = $factory->getEditorAdapter();
$editorAdapter->addEntityField([
	'name' => 'MY_FIELD' ,
	'title' => 'Title',
	'type' => 'string',
]);
$item = $factory->getItem(13);
$editorAdapter
	->processByItem($item, $factory->getStages())
	->addEntityData('MY_FIELD', 'actual_value')
;
$entityData = $editorAdapter->getEntityData();
$entityFields = $editorAdapter->getEntityFields();
© «Битрикс», 2001-2024, «1С-Битрикс», 2024