Документация для разработчиков
Документация для разработчиков Документация по 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
Наверх