Documentation

EditorAdapter

General


Universal editor (component bitrix:ui.form and its descendant bitrix:crm.entity.editor) has an important role in rendering CRM interfaces.

It may not be easy to prepare parameters of this component, especially when this element has many fields.

This service was designed to unify this process. Its main objective is to prepare entity field and data descriptions for universal editor.

Each entity type has its own specifics when handling fields ("complex fields" set is differs as a minimum).

It was decided to implement an option to add extra data and field descriptions to avoid creating a separate descendant for each entity type.

This service life cycle looks as follows:

  • Object is configured by receiving description of additional fields by the method addEntityField (usually generated by static methods of the same class).
  • Call of method processByItem, preparing necessary data.
  • Add extra data for the editor by the method addEntityData.
  • Processed data are retrieved from methods getEntityFields and getEntityData and passed into universal editor.

Methods

Method Description Available from version
public function __construct
(Field\Collection $fieldsCollection, array $dependantFieldsMap = [])
  • $fieldsCollection - field collection;
  • $dependantFieldsMap - array with dependant fields, where key is complex field code and the value - array with fields from collection included into this complex field.
It's not recommended to use this method directly, it's better to use a corresponding factory method Service\Factory::getEditorAdapter(). 
public function hasData(): bool
 Returns true, the method processByItem was called at least once. 
public static function isProductListEnabled(): bool
 Returns true, when new product grid was available. 
public function addEntityField(array $field): self
 Adds extra data to $field. Method must be called before processByItem. 
public function addEntityData($name, $value): self
 Adds extra data $value about $name. Method must be called after processByItem. 
public static function getClientField
(string $title, ?string $fieldName = null, ?string $fieldDataName = null): 
array
  • $title - field title;
  • $fieldName - field code. Default: CLIENT;
  • $fieldDataName - key name, receives this field content as extra data (company and contact data).
Returns "Client" field description. 
public static function getParentField
(string $title, int $parentEntityTypeId, ?string $context = null): 
array
  • $title - field title;
  • $parentEntityTypeId - parent CRM entity type;
  • $context - context for selector.
Returns field description with parent selector. 
public static function getProductRowSummaryField
(string $title, ?string $fieldName = null): array
  • $title - field title;
  • $fieldName - field code. Default: PRODUCT_ROW_SUMMARY.
Returns "Products" field description. 
public static function getOpportunityField
(string $title, ?string $fieldName = null): array
  • $title - field title;
  • $fieldName - field code. Default: OPPORTUNITY_WITH_CURRENCY.
Returns description for the field "Amount with currency specifier". 
public static function getUtmField
(string $title, ?string $fieldName = null): array
  • $title - field title;
  • $fieldName - field code. Default: UTM.
Returns "UTM tags" field description. 
public static function getLocationFieldDescription
(Field $field): array
 Returns "Location" field description by object of this field. 
public static function getProductRowProxyController
(string $productEditorId, ?string $fieldName = 'PRODUCT_ROW_PROXY'): 
array
  • $productEditorId - product grid ID;
  • $fieldName - controller code. Default: PRODUCT_ROW_PROXY.
Returns description for controller for passing product data inside details. 
public static function getProductListController
(string $productListId, string $currencyId, 
?string $fieldName = self::CONTROLLER_PRODUCT_LIST): array
  • $productEditorId - product grid ID;
  • $currencyId - currency ID;
  • $fieldName - controller code. Default: PRODUCT_LIST.
Returns description for product list controller. 
 public static function prepareEntityUserFields
(array $userFields, array $visibilityConfig, int $entityTypeId, 
int $entityId, string $fileHandlerUrl = ''): array
  • $userFields - array with custom field settings description;
  • $visibilityConfig - visibility settings;
  • $entityTypeId - CRM entity type ID;
  • $entityId - element ID;
  • $fileHandlerUrl - path to file, responsible for showing "File" type custom fields.
Returns array with description of all custom fields for universal editor. 
public function getClientEntityData(): array
 Returns data for "Client" field type. This data will be available after calling the method processByItem. 
public static function getUtmEntityData(Item $item): string
 Returns html for rendering field with UTM tags. 
public static function getLocationFieldHtml
(Item $item, string $fieldName): ?string
  • $item - element;
  • $fieldName - field code.
Returns html for rendering "Location" field. 
public function processByItem
(Item $item, EO_Status_Collection $stages, array $componentParameters = []): 
self
  • $item - element to receive data and fields;
  • $stages - collection of stages;
  • $componentParameters - additional component parameters. They can contain:
    • mode - component operation mode (see class components \Bitrix\Crm\Component\EntityDetails\ComponentMode). Default: view \Bitrix\Crm\Component\EntityDetails\ComponentMode::VIEW;
    • componentName - component name (for example, bitrix:crm.item.details);
    • fileHandlerUrl - path to file, responsible for showing "File" type custom fields;
    • conversionWizard - class for executing conversion (if component operates in conversion mode);
    • entitySelectorContext - context for selector in fields with parents;
    • isPageTitleEditable - true, when element name can be edited in page title.
Starts processing for $item. Adding extra fields and data must be performed before calling this method. 
public function saveClientData
(Item $item, string $clientJson): Result
  • $item - element;
  • $clientJson - string in format json from universal editor from "Client" field.
Processes client data from frontend and performs necessary manipulations with element (adds/deletes associations/bindings).
This method doesn't writes updates into database. Returns object Result, where data by the key processedEntities will contain the array with processed element IDs. 
public function saveClientData
(Item $item, string $clientJson): Result
  • $item - element;
  • $clientJson - string in format json from universal editor from "Client" field.
Processes client data from frontend and performs necessary manipulations with the element (adds/deletes associations/bindings).
This method doesn't write updates into database. Returns object Result, where data by the key processedEntities will contain the array with processed element IDs. 
public function saveProductsData
(Item $item, string $productsJson): Result
  • $item - element;
  • $productsJson - string in format json from universal editor with product data.
Processes product data from frontend and writes updated data to element.
This method doesn't write updates into database. Returns object Result. 
public function saveRelations
(Item $item, array $data): void
  • $item - element;
  • $data - array with parent element data:
    • Keys must have the format PARENT_ID_ + {CRM parent type ID}, and values - parent ID;
    • Additionally can have two keys PARENT_TYPE_ID with CRM parent type ID and PARENT_ID with parent ID.
Processes data from parent fields about bindings/associations and saves changes in the database. 
public function setContext(array $context): void
 Writes context for universal editor. 
public function getContext(): array
 Returns context for universal editor. 
public static function combineConfigIntoOneSection
(array $entityConfig, string $title = null): array
  • $entityConfig - universal editor entity config;
  • $title - editor main section title.
Collects all config entities from $entityConfig into a single section with code main and $title. Returns new version of config. 
public static function markFieldsAsRequired
(array $entityFields, array $requiredFieldNames): 
array
  • $entityFieldsg - field description for universal editor;
  • $requiredFieldNames - array with required field codes.
Marks all fields from set of $requiredFieldNames in the config $entityFields as required. Returns new config version. 
public static function getParentFieldName
(int $parentEntityTypeId): string
 Returns field code for parent with $parentEntityTypeId.

Example

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();
© «Bitrix24», 2001-2024