Bitrix API

CUserTypeEntity extends CAllUserTypeEntity

This class is used to manage metadata of user properties.

Selections, Deletion, Addition, and Update of metadata in the b_user_field table.

create table b_user_field ( ID int(11) not null auto_increment, ENTITY_ID varchar(50), FIELD_NAME varchar(50), USER_TYPE_ID varchar(50), XML_ID varchar(255), SORT int, MULTIPLE char(1) not null default 'N', MANDATORY char(1) not null default 'N', SHOW_FILTER char(1) not null default 'N', SHOW_IN_LIST char(1) not null default 'Y', EDIT_IN_LIST char(1) not null default 'Y', IS_SEARCHABLE char(1) not null default 'N', SETTINGS text, PRIMARY KEY (ID), UNIQUE ux_user_type_entity(ENTITY_ID, FIELD_NAME) ) ------------------ ID ENTITY_ID (example: IBLOCK_SECTION, USER ....) FIELD_NAME (example: UF_EMAIL, UF_SOME_COUNTER ....) SORT -- used to do check in the specified order BASE_TYPE - String, Number, Integer, Enumeration, File, DateTime USER_TYPE_ID SETTINGS (blob) -- to store some settings which may be useful for an field instance [some base settings comon to all types: mandatory or no, etc.]

b_user_field

  • ID int(11) not null auto_increment
  • ENTITY_ID varchar(50)
  • FIELD_NAME varchar(20)
  • USER_TYPE_ID varchar(50)
  • XML_ID varchar(255)
  • SORT int
  • MULTIPLE char(1) not null default 'N'
  • MANDATORY char(1) not null default 'N'
  • SHOW_FILTER char(1) not null default 'N'
  • SHOW_IN_LIST char(1) not null default 'Y'
  • EDIT_IN_LIST char(1) not null default 'Y'
  • IS_SEARCHABLE char(1) not null default 'N'
  • SETTINGS text
  • PRIMARY KEY (ID),
  • UNIQUE ux_user_type_entity(ENTITY_ID, FIELD_NAME)
create table b_user_field_lang ( USER_FIELD_ID int(11) REFERENCES b_user_field(ID), LANGUAGE_ID char(2), EDIT_FORM_LABEL varchar(255), LIST_COLUMN_LABEL varchar(255), LIST_FILTER_LABEL varchar(255), ERROR_MESSAGE varchar(255), HELP_MESSAGE varchar(255), PRIMARY KEY (USER_FIELD_ID, LANGUAGE_ID) )

b_user_field_lang

  • USER_FIELD_ID int(11) REFERENCES b_user_field(ID)
  • LANGUAGE_ID char(2)
  • EDIT_FORM_LABEL varchar(255)
  • LIST_COLUMN_LABEL varchar(255)
  • LIST_FILTER_LABEL varchar(255)
  • ERROR_MESSAGE varchar(255)
  • HELP_MESSAGE varchar(255)
  • PRIMARY KEY (USER_FIELD_ID, LANGUAGE_ID)

Table of Contents

Methods

Add()  : int
Function to add a user property.
CheckFields()  : bool
Function to validate metadata values of user properties.
CreatePropertyTables()  : mixed
Delete()  : CDBResult|false
Function to delete a user property and all its values.
DropEntity()  : CDBResult
Function to delete ALL user properties of an entity.
Fetch()  : array<string|int, mixed>
Fetch function.
GetByID()  : array<string|int, mixed>
Function to fetch metadata of a user property.
GetList()  : CDBResult
Function to fetch metadata of user properties.
Update()  : bool
Function to modify metadata of a user property.

Methods

Add()

Function to add a user property.

public Add(array<string|int, mixed> $arFields[, bool $bCheckUserType = true ]) : int

First, the instance method CheckFields is called (i.e., $this->CheckFields($arFields) ).

If the validation is successful, a check is performed to see if such a field already exists for the given entity.

Then, if necessary, tables of the form b_uts_[ENTITY_ID] and b_utm_[ENTITY_ID] are created.

After that, the metadata is saved in the database.

Only after this, the structure of the table b_uts_[ENTITY_ID] is modified.

Array arFields:

  • ENTITY_ID - entity
  • FIELD_NAME - the actual column name in the database where the property values will be stored.
  • USER_TYPE_ID - property type
  • XML_ID - identifier for use in import/export
  • SORT - sort order (default 100)
  • MULTIPLE - multiplicity flag Y/N (default N)
  • MANDATORY - mandatory value input flag Y/N (default N)
  • SHOW_FILTER - whether to show in the admin list filter and what type to use. see below.
  • SHOW_IN_LIST - whether to show in the admin list (default Y)
  • EDIT_IN_LIST - allow editing in forms, but not in API! (default Y)
  • IS_SEARCHABLE - field participates in search (default N)
  • SETTINGS - array with property settings dependent on the property type. They are "cleaned" through the type handler PrepareSettings.
  • EDIT_FORM_LABEL - array of language messages in the form array("ru"=>"привет", "en"=>"hello")
  • LIST_COLUMN_LABEL
  • LIST_FILTER_LABEL
  • ERROR_MESSAGE
  • HELP_MESSAGE

In case of an error, catch the application exception!

Values for SHOW_FILTER:

  • N - do not show
  • I - exact match
  • E - mask
  • S - substring
Parameters
$arFields : array<string|int, mixed>

Metadata of the new property

$bCheckUserType : bool = true
Return values
int —
  • identifier of the added property, false - if the property was not added.

CheckFields()

Function to validate metadata values of user properties.

public CheckFields(int $ID, array<string|int, mixed> $arFields[, bool $bCheckUserType = true ]) : bool

Called in Add and Update methods to check the correctness of the entered values.

Validations:

  • ENTITY_ID - required
  • ENTITY_ID - no more than 50 characters
  • ENTITY_ID - must not contain any characters other than 0-9, A-Z, and _
  • FIELD_NAME - required
  • FIELD_NAME - at least 4 characters
  • FIELD_NAME - no more than 50 characters
  • FIELD_NAME - must not contain any characters other than 0-9, A-Z, and _
  • FIELD_NAME - must start with UF_
  • USER_TYPE_ID - required
  • USER_TYPE_ID - must be registered

In case of an error, catch the application exception!

Parameters
$ID : int
  • property identifier. 0 - for new.
$arFields : array<string|int, mixed>

Property metadata

$bCheckUserType : bool = true
Return values
bool —

false - if any validation fails.

CreatePropertyTables()

public CreatePropertyTables(mixed $entity_id) : mixed
Parameters
$entity_id : mixed

Delete()

Function to delete a user property and all its values.

public Delete(int $ID) : CDBResult|false

First, the property metadata is deleted.

Then, all values of multiple properties are deleted from the table of the form b_utm_[ENTITY_ID].

After that, the column is dropped from the table of the form b_uts_[ENTITY_ID].

Parameters
$ID : int

Property identifier

Return values
CDBResult|false —
  • result of the last query executed by the function.

DropEntity()

Function to delete ALL user properties of an entity.

public DropEntity(string $entity_id) : CDBResult

First, the property metadata is deleted.

Can be called, for example, when deleting an infoblock.

Then, the tables of the form b_utm_[ENTITY_ID] and b_uts_[ENTITY_ID] are dropped.

Parameters
$entity_id : string

Entity identifier

Return values
CDBResult —
  • result of the last query executed by the function.

Fetch()

Fetch function.

public Fetch() : array<string|int, mixed>

Deserializes the SETTINGS field.

Return values
array<string|int, mixed> —

Returns false in case of the last record in the selection.

GetByID()

Function to fetch metadata of a user property.

public static GetByID(int $ID) : array<string|int, mixed>

Returns an associative array of metadata that can be passed to Update.

Parameters
$ID : int

Property identifier

Tags
static
Return values
array<string|int, mixed> —

If the property is not found, false is returned

GetList()

Function to fetch metadata of user properties.

public static GetList([array<string|int, mixed> $aSort = [] ][, array<string|int, mixed> $aFilter = [] ]) : CDBResult

Returns CDBResult - a selection based on filter and sorting.

The aSort parameter defaults to array("SORT"=>"ASC", "ID"=>"ASC").

If LANG is passed in aFilter, language messages are additionally selected.

Parameters
$aSort : array<string|int, mixed> = []

Associative array for sorting (ID, ENTITY_ID, FIELD_NAME, SORT, USER_TYPE_ID)

$aFilter : array<string|int, mixed> = []

Associative array for filtering with strict matching (equals) (ID, ENTITY_ID, FIELD_NAME, USER_TYPE_ID, SORT, MULTIPLE, MANDATORY, SHOW_FILTER)

Tags
static
Return values
CDBResult

Update()

Function to modify metadata of a user property.

public Update(int $ID, array<string|int, mixed> $arFields) : bool

It should be noted that for the sake of faster development, it was decided not to implement the same flexibility as in infoblocks (we will do without alters and other things for now).

First, the instance method CheckFields is called (i.e., $this->CheckFields($arFields) ).

After that, the metadata is saved in the database.

Array arFields (only what can be changed):

  • SORT - sort order
  • MANDATORY - mandatory value input flag Y/N
  • SHOW_FILTER - flag to show in the list filter Y/N
  • SHOW_IN_LIST - flag to show in the list Y/N
  • EDIT_IN_LIST - allow editing the field in admin forms or not Y/N
  • IS_SEARCHABLE - search flag Y/N
  • SETTINGS - array with property settings dependent on the property type. They are "cleaned" through the type handler PrepareSettings.
  • EDIT_FORM_LABEL - array of language messages in the form array("ru"=>"привет", "en"=>"hello")
  • LIST_COLUMN_LABEL
  • LIST_FILTER_LABEL
  • ERROR_MESSAGE
  • HELP_MESSAGE

In case of an error, catch the application exception!

Parameters
$ID : int

Property identifier

$arFields : array<string|int, mixed>

New property metadata

Return values
bool —
  • true if the update is successful, false otherwise.

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results