Установка и удаление модуля

Модуль устанавливается и удаляется, как любой модуль из маркетплейса. Без дополнительного вмешательства с вашей стороны.

Перед вызовом классов необходимо подключить модуль elpha.usersettings

        
use \Bitrix\Main\Loader;

Loader::includeModule('elpha.usersettings');
        
    

Работа со значениями полей

Класс \Elpha\UserSettings\Option предназначен для работы со значениями полей. Класс реализует паттерн Singleton и для получения экземпляра класса следует использовать метод getInstance().

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

$option = Option::getInstance();
        
    

 

Получить значение поля

Для получения значения поля по символьному коду необходимо воспользоваться методом get(string $key, $default = null).

Аргумент Описание
string $key Символьный код поля
$default Значение, которое вернется при отсутсвии значения в БД
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

// Вернется значение поля UF_CAPTCHA_SECRET, если значение не задано вернется false
Option::getInstance()->get('UF_CAPTCHA_SECRET', false);
        
    

 

Метод getAll(): array предназначен для получения значений по всем пользовательским полям.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

// Вернутся значения по всем пользовательским полям
Option::getInstance()->getAll();
        
    

 

Установить значение поля

Для установки значения поля используется метод set(string $key, $value): \Bitrix\Main\Result. В этом методе реализована валидация значения поля. Метод возвращает экземпляр класса \Bitrix\Main\Result и проверить наличие ошибки при установке значения можно методом isSuccess().

Аргумент Описание
string $key Символьный код поля
$value Новое значение поля
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

$option = Option::getInstance();

$result = $option->set('UF_CAPTCHA_SECRET', 'foo');
if (!$result->isSuccess()) {
    // В случае ошибки
    echo implode('<br>', $result->getErrorMessages());

    return;
}

// Вернется значение "foo" установленное методом "set"
$option->get('UF_CAPTCHA_SECRET');
        
    

 

Сбросить кеш значений

При изменении структуры или установки значения кеш автоматически очищается. Метод clearCache(): bool пригодится для принудительной очистки кеша при изменениях не через API модуля.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

Option::getInstance()->clearCache();
        
    

Выборка, добавление, обновление, удаление вкладок

Работа с вкладками реализуется тремя классами:

  • \Elpha\UserSettings\TabMapper — маппер вкладок пользовательских настроек;
  • \Elpha\UserSettings\Tab — класс вкладки в пользовательских настройках;
  • \Elpha\UserSettings\TabCollection — коллекция экземпляров классов вкладок пользовательских настроек;

Подробнее на них остановимся ниже.

Добавление вкладки

Класс вкладки \Elpha\UserSettings\Tab является наследником класса \ArrayObject. Для начала нужно получить экземпляр класса вкладки используя фабричный метод create(array $input = []): ITab передав в него все необходимые парамеры. Данный метод является статичным. После того как мы получили экземпляр класса \Elpha\UserSettings\Tab вызовем метод add(): AddResult, который вернет результат в виде объкта класса \Bitrix\Main\ORM\Data\AddResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\AddResult.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Tab;

Loader::includeModule('elpha.usersettings');

$tab = Tab::create([
    'ACTIVE' => 1,
    'CODE' => 'FORM_OPTIONS',
    'SORT' => 500,
    'LOCALIZATION' => [
        'ru' => [
            'L_NAME' => 'Настройки формы',
            'L_TITLE' => 'Важные настройки формы',
        ],
    ],
]);

$addResult = $tab->add();
if (!$addResult->isSuccess()) {
    echo implode('<br>', $addResult->getErrorMessages());
}
        
    

Описание полей:

  • ACTIVE — активность вкладки. Определяет будет ли выведена вкладка на странице пользовательских настроек;
  • CODE — символьный код вкладки;
  • SORT — сортировка вкладки. Определяет в какой последовательности будут выведены вкладки на странице пользовательских настроек;
  • LOCALIZATION — массив с языковыми сообщениями. Ключем является символьный код языка;
    • L_NAME — название вкладки;
    • L_TITLE — заголовок вкладки;

Выборка вкладок

Основным метод для выборки вкладок является метод getList(array $parameters = []): ITabCollection класса \Elpha\UserSettings\TabMapper. Данный метод принимает в качестве аргумента массив аналогичный синтаксису ORM D7. Метод возвращает коллекцию классов вкладок \Elpha\UserSettings\TabCollection. При пустом результате выборки класс коллекции вернется с нулевым количеством элементов.

Аргумент Описание
array $parameters Параметры getList
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tabCollection = TabMapper::getList([
    'filter' => [
        'ACTIVE' => 1,
    ],
    'order' => [
        'SORT' => 'ASC',
    ],
]);

foreach ($tabCollection as $tab) {
    // Do something
}
unset($tab);
        
    

 

Предыдущий пример можно заменить с использованием метода getActive(array $parameters = []): ITabCollection. Данный метод выполняет выборку всех активных вкладок с возможностью дополнительной фильтрации или сортировки путем передачи аргумента $parameters аналогичного ORM D7.

Аргумент Описание
array $parameters Параметры getList
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tabCollection = TabMapper::getActive([
    'order' => [
        'SORT' => 'ASC',
    ],
]);

foreach ($tabCollection as $tab) {
    // Do something
}
unset($tab);
        
    

 

Метод getById(int $id) осуществляет поиск вкладки по идентификатору. В отличие от методов getList(array $parameters = []): ITabCollection и getActive(array $parameters = []): ITabCollection возвращает не коллекцию вкладок, а экземпляр класса вкладки \Elpha\UserSettings\Tab. Если вкладку не удалось найти по идентификатору, метод вернет значение false.

Аргумент Описание
int $id Идентификатор вкладки
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tab = TabMapper::getById(1);

if (false !== $tab) {
    echo $tab['ID'];
}
        
    

 

Обновление вкладки

Для обновления вкладки следует использовать метод update(): UpdateResult класса \Elpha\UserSettings\Tab, который вернет результат в виде объкта класса \Bitrix\Main\ORM\Data\UpdateResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\UpdateResult.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tab = TabMapper::getById(3);

if (false !== $tab) {
    $tab['ACTIVE'] = 0;

    $updateResult = $tab->update();

    if (!$updateResult->isSuccess()) {
        echo implode('<br>', $updateResult->getErrorMessages());
    }
}
        
    

 

Сохранение вкладки

Метод save() осуществляет добавление или обновление вкладки в зависимости от наличия значения ID (первичного ключа).

Обновление с использованием метода save()

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tab = TabMapper::getById(3);

if (false !== $tab) {
    // Вызов метода обновит вкладку
    $tab['ACTIVE'] = 1;

    $updateResult = $tab->save();

    if (!$updateResult->isSuccess()) {
        echo implode('<br>', $updateResult->getErrorMessages());
    }
}
        
    

Добавление с использованием метода save()

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tab = TabMapper::getById(3);

if (false !== $tab) {
    // Вызов метода добавит вкладку
    unset($tab['ID']);
    $tab['CODE'] = 'NEW_TAB_CODE';

    $addResult = $tab->save();

    if (!$addResult->isSuccess()) {
        echo implode('<br>', $addResult->getErrorMessages());
    }
}
        
    

 

Удаление вкладки

Для удаления вкладки следует использовать метод delete(): DeleteResult класса \Elpha\UserSettings\Tab, который вернет результат в виде объкта класса \Bitrix\Main\ORM\Data\DeleteResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\DeleteResult.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\TabMapper;

Loader::includeModule('elpha.usersettings');

$tab = TabMapper::getById(3);

$deleteResult = $tab->delete();

if (!$deleteResult->isSuccess()) {
    echo implode('<br>', $deleteResult->getErrorMessages());
}
        
    

Выборка, добавление, обновление, удаление полей

Работа с полями реализуется тремя классами:

  • \Elpha\UserSettings\FieldMapper — маппер полей пользовательских настроек;
  • \Elpha\UserSettings\Field — класс поля пользовательских настройках;
  • \Elpha\UserSettings\FieldCollection — коллекция экземпляров классов полей пользовательских настроек;

Подробнее на них остановимся ниже.

Добавление поля

Класс поля \Elpha\UserSettings\Field является наследником класса \ArrayObject. Для начала нужно получить экземпляр класса поля, используя фабричный метод create(array $input = []): IField, передав в него все необходимые парамеры. Данный метод является статичным. После того как мы получили экземпляр класса \Elpha\UserSettings\Field вызовем метод add(): AddResult, который вернет результат в виде объкта класса \Bitrix\Main\ORM\Data\AddResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\AddResult.

Ниже приведен пример добавления поля с типом строка.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\Field;

Loader::includeModule('elpha.usersettings');

$field = Field::create([
    'ACTIVE' => '1',
    'TAB_ID' => '1',
    'UF' => [
        'FIELD_NAME' => 'UF_RECAPTCHA_SECRET',
        'USER_TYPE_ID' => 'string',
        'XML_ID' => '',
        'SORT' => '500',
        'MULTIPLE' => 'N',
        'MANDATORY' => 'N',
        'SETTINGS' => [
            'SIZE' => 60,
            'ROWS' => 1,
            'REGEXP' => '',
            'MIN_LENGTH' => 0,
            'MAX_LENGTH' => 0,
            'DEFAULT_VALUE' => '',
        ],
        'EDIT_FORM_LABEL' => ['en' => '', 'ru' => 'Приватный ключ reСaptcha v3',],
        'HELP_MESSAGE' => ['en' => '', 'ru' => 'Используется для reСaptcha v3',],
    ],
]);

$addResult = $field->add();

if (!$addResult->isSuccess()) {
    echo implode('<br>', $addResult->getErrorMessages());
}
        
    

Описание полей:

  • ACTIVE — активность поля. Определяет будет ли выведено поле на странице пользовательских настроек;
  • TAB_ID — идентификатор вкладки, которой принадлежит поле;
  • UF — массив с настройками пользовательского поля;

Выборка полей

Основным методом для выборки полей является getList(array $parameters = []): IFieldCollection класса \Elpha\UserSettings\FieldMapper. Данный метод принимает в качестве аргумента массив аналогичный синтаксису ORM D7. Метод возвращает коллекцию классов полей \Elpha\UserSettings\FieldCollection. При пустом результате выборки класс коллекции вернется с нулевым количеством элементов.

Аргумент Описание
array $parameters Параметры getList
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$fieldCollection = FieldMapper::getList([
    'filter' => [
        'ACTIVE' => 1,
    ],
    'order' => [
        'ID' => 'DESC',
    ],
]);

foreach ($fieldCollection as $field) {
    // Do something
}
unset($field);
        
    

 

Предыдущий пример можно заменить с использованием метода getActive(array $parameters = []): IFieldCollection. Данный метод выполняет выборку всех активных полей с возможностью дополнительной фильтрации или сортировки путем передачи аргумента $parameters аналогичного ORM D7.

Аргумент Описание
array $parameters Параметры getList
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$fieldCollection = FieldMapper::getActive([
    'order' => [
        'ID' => 'DESC',
    ],
]);

foreach ($fieldCollection as $field) {
    // Do something
}
unset($field);
        
    

 

Метод getById(int $id) осуществляет поиск поля по идентификатору (не по идентификатору пользовательского поля). В отличие от методов getList(array $parameters = []): IFieldCollection и getActive(array $parameters = []): IFieldCollection возвращает не коллекцию полей, а экземпляр класса поля \Elpha\UserSettings\Field. Если поле не удалось найти по идентификатору, метод вернет значение false.

Аргумент Описание
int $id Идентификатор поля
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$field = FieldMapper::getById(2);

if (false !== $field) {
    echo $field['ID'];
}
        
    

 

Для выбора всех полей вкладки можно использовать метод getByTabId(int $tabId). Метод вернет коллекцию полей принадлежащих вкладки с идентификатором int $tabId.

Аргумент Описание
int $tabId Идентификатор вкладки поля
        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$fieldCollection = FieldMapper::getByTabId(1);

foreach ($fieldCollection as $field) {
    // Do something
}
unset($field);
        
    

 

Обновление поля

Для обновления поля следует использовать метод update(): UpdateResult класса \Elpha\UserSettings\Field, который вернет результат в виде объекта класса \Bitrix\Main\ORM\Data\UpdateResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\UpdateResult.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$field = FieldMapper::getById(3);

if (false !== $field) {
    $field['ACTIVE'] = 0;

    $updateResult = $field->update();

    if (!$updateResult->isSuccess()) {
        echo implode('<br>', $updateResult->getErrorMessages());
    }
}
        
    

 

Сохранение поля

Метод save() осуществляет добавление или обновление поля в зависимости от наличия значения ID (первичного ключа).

Обновление с использованием метода save()

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$field = FieldMapper::getById(3);

if (false !== $field) {
    // Вызов метода обновит поле
    $field['ACTIVE'] = 1;

    $updateResult = $field->save();

    if (!$updateResult->isSuccess()) {
        echo implode('<br>', $updateResult->getErrorMessages());
    }
}
        
    

Добавление с использованием метода save()

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$field = FieldMapper::getById(3);

if (false !== $field) {
    // Вызов метода добавит поле
    unset($field['ID']);
    unset($field['UF_ID']);
    unset($field['UF']['ID']);
    $field['UF']['FIELD_NAME'] = 'UF_NEW_FIELD';

    $addResult = $field->save();

    if (!$addResult->isSuccess()) {
        echo implode('<br>', $addResult->getErrorMessages());
    }
}
        
    

 

Удаление поля

Для удаления поля следует использовать метод delete(): DeleteResult класса \Elpha\UserSettings\Field, который вернет результат в виде объкта класса \Bitrix\Main\ORM\Data\DeleteResult. Успешность выполнения операции можно проверить методом isSuccess($internalCall = false) класса \Bitrix\Main\ORM\Data\DeleteResult.

        
use \Bitrix\Main\Loader;
use \Elpha\UserSettings\FieldMapper;

Loader::includeModule('elpha.usersettings');

$field = FieldMapper::getById(3);

$deleteResult = $field->delete();

if (!$deleteResult->isSuccess()) {
    echo implode('<br>', $deleteResult->getErrorMessages());
}
        
    

События модуля

В модуле предусмотрены события, которые позволяют модифицировать данные или расширить функционал модуля. Пример использования событий:

        
use \Bitrix\Main\Event;
use \Bitrix\Main\Loader;
use \Bitrix\Main\EventManager;
use \Bitrix\Main\EventResult;
use \Elpha\UserSettings\Option;

Loader::includeModule('elpha.usersettings');

EventManager::getInstance()->addEventHandler(
    'elpha.usersettings',
    'OnOptionGet',
    function (Event $event) {
        return new EventResult(
            EventResult::SUCCESS,
            [
                'default' => 'new default value',
            ]
        );
    }
);

// Если поле имеет значение null или false, вместо 'foo' вернется значение 'new default value'
Option::getInstance()->get('UF_RECAPCHA_SECRET', 'foo');
        
    

События связанные со значениями полей

  • OnOptionGet — вызывается ДО возврата значения поля методом get(string $key, $default = null) класса \Elpha\UserSettings\Option
  • OnBeforeOptionSet — вызывается ДО установки значения поля методом set(string $key, $value): Result класса \Elpha\UserSettings\Option
  • OnAfterOptionSet — вызывается ПОСЛЕ установки значения поля методом set(string $key, $value): Result класса \Elpha\UserSettings\Option

События связанные с вкладками

  • OnBeforeTabAdd — вызывается ДО добавления новой вкладки методом add(): AddResult класса \Elpha\UserSettings\Tab
  • OnAfterTabAdd — вызывается ПОСЛЕ добавления новой вкладки методом add(): AddResult класса \Elpha\UserSettings\Tab
  • OnBeforeTabUpdate — вызывается ДО обновления вкладки методом update(): UpdateResult класса \Elpha\UserSettings\Tab
  • OnAfterTabUpdate — вызывается ПОСЛЕ обновления вкладки методом update(): UpdateResult класса \Elpha\UserSettings\Tab
  • OnBeforeTabDelete — вызывается ДО удаления вкладки методом delete(): DeleteResult класса \Elpha\UserSettings\Tab
  • OnAfterTabDelete — вызывается ПОСЛЕ удаления вкладки методом delete(): DeleteResult класса \Elpha\UserSettings\Tab

События связанные с полями

  • OnBeforeFieldAdd — вызывается ДО добавления нового поля методом add(): AddResult класса \Elpha\UserSettings\Field
  • OnAfterFieldAdd — вызывается ПОСЛЕ добавления нового поля методом add(): AddResult класса \Elpha\UserSettings\Field
  • OnBeforeFieldUpdate — вызывается ДО обновления поля методом update(): UpdateResult класса \Elpha\UserSettings\Field
  • OnAfterFieldUpdate — вызывается ПОСЛЕ обновления поля методом update(): UpdateResult класса \Elpha\UserSettings\Field
  • OnBeforeFieldDelete — вызывается ДО удаления поля методом delete(): DeleteResult класса \Elpha\UserSettings\Field
  • OnAfterFieldDelete — вызывается ПОСЛЕ удаления поля методом delete(): DeleteResult класса \Elpha\UserSettings\Field