Data providers

General

Data providers

Data provider is a PHP class allowing to dynamically load entity data from backend.

It's sufficient to define entity IDs in the option entities, which, when available, cause the dialog to execute a query from backend when opening the dialog to ultimately get data from corresponding providers. Providers can add new items, tabs as well as footer to dialog.

const button = document.getElementById('button');
const dialog = new Dialog({
    targetNode: button,
    enableSearch: true,
    context: 'MY_MODULE_CONTEXT',
    entities: [
        {
            id: 'user', // users
        },
        {
            id: 'department', // company structure: select users only
        },
    ],
});

dialog.show();

In addition to first-hand data loading, provider can:

• Execute item search, with search phrase input.
• Define global entity settings (default external appearance, search settings and etc.).
• Dynamically load child items of tree-type entities.

Registration

Registering data provider requires defining the structure below in the module settings file (the .settings.php file in folder root of your module) in the key ui.entity-selector.

<?php

// file /my-module/.settings.php

return [
  'ui.entity-selector' => [
    'value' => [
      'entities' => [
        [
          'entityId' => 'my-module-entity',
          'provider' => [
            'moduleId' => 'my-module',
            'className' => '\\Vendor\\MyModule\\Integration\\UI\\EntitySelector\\MyProvider'
          ],
        ],
      ],
      'extensions' => ['my-module.entity-selector'],
    ],
    'readonly' => true,
  ]
];

Each module can have several data providers and the key entities defines array with entity data. The option entityId defines a unique entity ID and provider sets a full path to PHP class.

Additionally, the option extensions can indicate the extension with configurable entity global settings, as well as JavaScript classes for additional dialog features (for example, for creating custom footer or tab stub).

Global entity settings

Defining entity settings at the global level uses the extension configuration. Such config format allows to flexibly set up options for entities: you can use custom PHP-code, language phrases and etc.

You need to include array with entity settings in the option entities, defined in the settings key.

<?php

// File /js/my-module/entity-selector/config.php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true)
{
    die();
}

if (!\Bitrix\Main\Loader::includeModule('my-module'))
{
    return [];
}

return [
  'settings' => [
    'entities' => [
      [
        'id' => 'my-module-entity',
        'options' => [
          'dynamicLoad' => true, // defines dynamic data load from backend
          'dynamicSearch' => true, // defines dynamic search
          
          // Sets additional fields for search
          'searchFields' => [
            [ 'name' => 'position', 'type' => 'string' ],
            [ 'name' =>  'email', 'type' => 'email' ]
          ],
          // Item external appearance
          'itemOptions' => [
            'default' => [
              'supertitle' => 'My supertitle',
              'avatar' => '/path/to/image.svg', // item avatar by default
              'link' =>  '/service/entity/#id#/',
              'linkTitle' => 'learn more',
            ],
            'inactive' => [ // for items with entityType='inactive' with displayed 'Inactive' badge
                'badges' => [
                  [
                    'title' => 'Inactive',
                    'textColor' => '#828b95',
                    'bgColor' => '#eaebec',
                  ]
                ],
            ],
          ],
          // External item view in widget TagSelector
          'tagOptions' => [
            'default' => [
              'textColor' => '#1066bb',
              'bgColor' => '#bcedfc',
              'avatar' => '/path/to/image.svg', // item avatar in widget TagSelector by default
            ],
            'inactive' => [
              'textColor' => '#5f6670',
              'bgColor' => '#ecedef',
            ],
          ],

          // Additional badge settings
          'badgeOptions' => [
            [
              'title' => 'В отпуске',
              'bgColor' => '#b4f4e6',
              'textColor' => '#27a68a',
              'conditions' => [
                'isOnVacation' =>  true
              ],
            ],
          ],
        ],
      ],
    ]
  ]
];

Entity settings format (options) with similar structure as EntityOptions for JavaScript class Entity.

export type EntityOptions = {
  dynamicLoad?: boolean,
  dynamicSearch?: boolean,
  itemOptions?: { [key: string]: any },
  tagOptions?: { [key: string]: any },
  badgeOptions?: ItemBadgeOptions[],
  searchable?: boolean,
  searchFields?: SearchField[],
  searchCacheLimits?: [],
};

Provider class

Provider class must be descendant for abstract class BaseProvider.

class MyProvider extends Bitrix\UI\EntitySelector\BaseProvider
{
  public function __construct(array $options = [])
  {
    parent::__construct();
  }

  public function isAvailable(): bool
  {
    // TODO: Implement getItems() method.
  }

  /**
   * @param array $ids
   *
   * @return Item[]
  */
  public function getItems(array $ids) : array
  {
    // TODO: Implement getItems() method.
  }

  /**
   * @param array $ids
   *
   * @return Item[]
  */
  public function getSelectedItems(array $ids) : array
  {
    // TODO: Implement getSelectedItems() method.
  }
}

Descendant class requires implementation of the following methods:

• isAvailable — defines provider availability for use.
• getItems — returns items by specified identifiers.
• getSelectedItems - returns data by specified identifiers for preselected items.

Re-defining the rest of methods is optional.

• fillDialog — fills dialog with data (items, tabs, footer).
• getChildren — loads child items of tree-type entities into dialog.
• doSearch — executes item search.
• handleBeforeItemSave — called before saving item in the "Recent" list. Allows to cancel the saving action.