Documentation

Field

Общее


Different CRM entity types have fields with various codes, but similar (business) logic.

To avoid duplicating calls of different code portions in operations of various types in the new API it was decided to create an dedcated class hierarchy.

Descendant class name is specified in factory in the method getFieldsSettings().

When descendant is not specified, base class is used anyways.

Checking attributes and executing the logic is performed in corresponding methods for operations.

There is no sense to directly call methods, executing the logic outside the operations. However, some other methods can be useful.

Be advised, that this call is used when handling only the fields that have a "physical" column in the element table.

The element table can have specific fields (for example, "Customer" field), not included into the collection of field types. Handling them is performed only at the level of interface.

Attributes


Each field can have a set of attributes defining basic parameters of field behaviour.

  • \CCrmFieldInfoAttr::Hidden - Field is unavailable in REST and is ignored when merging duplicates.
  • \CCrmFieldInfoAttr::NotDisplayed - Field is not displayed in the details interface (but can be available in lists).
  • \CCrmFieldInfoAttr::ReadOnly - Field value cannot be updated by user.
  • \CCrmFieldInfoAttr::Immutable - Field value can be completed by user only when creating.
  • \CCrmFieldInfoAttr::UserPKey - Field is primary key. Rarely used.
  • \CCrmFieldInfoAttr::Required - Field is required.
  • \CCrmFieldInfoAttr::Multiple - Field is multiple.
  • \CCrmFieldInfoAttr::Dynamic - Field is a custom field.
  • \CCrmFieldInfoAttr::Deprecated - Field marked as deprecated (printed in REST).
  • \CCrmFieldInfoAttr::Progress - Field contains information about element stage. Rarely used .
  • \CCrmFieldInfoAttr::HasDefaultValue - Field has default value.
  • \CCrmFieldInfoAttr::AutoGenerated - Field value is generated automatically when creating an element.
  • \CCrmFieldInfoAttr::Unique - Field value must be unique within table of elements.
  • \CCrmFieldInfoAttr::CanNotBeEmptied - When user clears value from this field, this update is not applied and when saved is reset to initial status.

Methods


Method Description Available from version
public function __construct
(string $name, array $description)

  • $name - field code as named in the element table;
  • $description - array with field description with following structure:
    • TYPE - field type, possible values are listed in the constants of class TYPE_*;
    • TITLE - field title;
    • ATTRIBUTES - array with listed field attributes;
    • SETTINGS - array with additional settings for arbitrary structure field;
    • USER_FIELD - array with additional settings for arbitrary structure field;
    • SETTINGS - description of custom field settings, when this field is a custom field.
Constructor. It's not recommended to call it directly, use the factory methods for getting the fields.
public function isValueCanBeChanged(): bool
Returns true, when the field value can be modified by the user (checks for available attributes \CCrmFieldInfoAttr::ReadOnly and \CCrmFieldInfoAttr::Immutable).
public function processWithPermissions
(Item $item, UserPermissions $userPermissions): Result
This method must execute additional access permission and logic checks for this field. For example, it is defined in the class of the "Responsible" field type and "Open for all".
public function process(Item $item, 
Context $context = null): Result
Main methods, called before saving an element when executing an operation.
public function processAfterSave
(Item $itemBeforeSave, Item $item, Context $context = null): 
FieldAfterSaveResult
Method, implementing additional logic to be processed after saving the element.
This methods shall not call the saving of element directly, new field values must be placed to FieldAfterSaveResult.
public function isItemValueEmpty(Item $item): bool
Returns true, when $item has this field value as empty.
public function isValueEmpty($fieldValue): bool
Returns true, when $fieldValue is deemed as empty.
public function getName(): string
Returns field code.
public function setName(string $name): Field
Writes new code for the field $name.
public function getTitle(): string
Returns field name.
public function setTitle(string $title): self
Writes new code for field $title.
public function getType(): string
Returns field type.
public function setType(string $type): Field
Writes new field $type.
public function getAttributes(): array
Returns set of field attributes.
public function setAttributes(array $attributes): Field
Writes new set of field $attributes (re-writes completely).
public function getSettings(): array
Returns set of field settings.
public function setSettings(array $settings): Field
Writes new set of $settings field.
public function isUserField(): bool
Returns true, when field is a custom.
public function getUserField(): array
Returns description of custom field settings.
public function isAutoGenerated(): bool
Returns true, when field value is generated automatically.
public function isMultiple(): bool
Returns true, when field is multiple.
public function isDisplayed(): bool
Returns true, when field must be displayed in element details.
public function isRequired(): bool
Returns true, when field is required.
public function toArray(): array
Returns array with description of field parameters; structure is similar to the constructor $description argument.
public function isFileUserField(): bool
Returns true, when field is custom with "file" base type.
public function getValueNotValidError(): Error
Returns error on incorrectly completed field.
public static function getRequiredEmptyError
(string $fieldName, ?string $title = null): Error
  • $fieldName - код поля;
  • $title - название поля.
Returns error on required field is empty.
public function getValueNotUniqueError(): Error
Returns error that field values is not unique.

Descendants


Presently there are following existing field types:


Field Description
Field\Assigned
Responsible.
  • If user has permission to create only its "Own" elements, user (sourced from context) who performed updates will be forcefully written into the field.
  • When field is not completed, current user forcibly is written into it (taken from context).
Field\Category
Pipeline.
  • When field is updated, it's checked for correct ID of the corresponding pipeline type.
  • After saving, access permissions attributes are cleared if field is updated.
Field\Closed
Closed.
Automatically completed depending on current stage semantics.
Field\CloseDate
Date when closed.
Automatically completed with current date, if this field value is not completed and the "Closed" field value is true.
Field\CreatedBy
Created by.
Automatically completed by current user (from context) when creating. In the rest of cases, forcefully reset to the original state.
Field\CreatedTime
Time when created.
Automatically completed with current time when creating a new element.
Field\MovedBy
Moved by.
Automatically completed by current user (sourced from context) when changing stage.
Field\MovedTime
When moved.
Automatically completed with current time when changing stage.
Field\Number
Number.
  • If the field was cleared upon update, element ID is forcefully written into it.
  • When created, number is generated automatically according to numerator settings.
.
Field\Observers
Observers.
Updates contents of associated chat.
Field\Opened
Opened for all.
When user has access permission for creating/updating elements open for all, then this field has a forced true.
Field\Opportunity
Total.
When automatic total calculation is enabled, the value is calculated based on the product items via calculation service.
Field\OpportunityAccount
Total for reports.
The value is completed based in the report currency and "Total" field.
Field\PersonTypeId
Payer type.
Completed automatically based on company associated to the element.
Field\PreviousStageId
Previous stage.
Completed automatically when changing stage.
Field\Stage
Stage.
Completed automatically when changing the stage.
  • Upon changed field value, checks correct status related list of stages for current element pipeline.
  • If "Pipeline" field is updated and the new stage is not specified, the value is completed automatically by the first status of the same new pipeline semantics.
Field\TaxValue
Tax total.
Completed automatically based on the product items list via calculation service.
Field\UpdatedBy
Who updated.
Automatically completed by the current user from context.
Field\UpdatedTime
When updated.
Automatically completed by current time.

Example


use Bitrix\Crm\Service;
use Bitrix\Crm\Item;

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

$opportunityField = $factory->getFieldsCollection()->getField(
    Item::FIELD_NAME_OPPORTUNITY
);
if (
    $opportunityField->isValueEmpty($value)
    && $opportunityField->isRequired()
)
{
    $error = $opportunityField::getRequiredEmptyError(
        $opportunityField->getName(),
        $opportunityField->getTitle()
    );
}
© «Bitrix24», 2001-2022
Up