README

允许创建带有用户设置的行政页面。提供用于创建选项卡和字段的便捷API，这使得可以与迁移模块一起使用。事件允许在设置设置值或添加/删除/更新选项卡或字段时进行更改。

模块描述

本模块解决为项目添加设置的问题。例如：启用/禁用、实现某些功能的时间、文本。设置中的字段类型受用户字段类型的限制，即您可以轻松为设置添加自己的字段类型。

模块优势

可以将用户设置页面的链接放置在任何主要部分中。还可以设置页面名称和用户设置链接的名称；
可以在模块设置中添加选项卡和在选项卡中添加字段；
为选项卡和字段提供排序，允许在用户设置页面中设置它们的布局；
模块的字段是用户字段，这使得可以添加任何可用的用户字段类型（字符串、日期等）；
支持设置的多值；
提供了灵活的权限设置，用于查看/编辑用户设置和查看/编辑字段、选项卡；
可以为选项卡指定名称和标题，为字段指定名称和提示；
使用API可以轻松添加选项卡或字段，这允许编写迁移；
事件系统允许在设置设置值或添加/删除/更新选项卡或字段时进行更改。

支持的字段类型列表

默认情况下，您将获得以下字段类型

地址；
资源预订；
视频；
是/否；
日期；
日期和时间；
金钱；
调查；
电子邮件；
信息块部分的关联；
highload块元素的关联；
信息块元素的关联；
链接内容；
列表；
链接；
字符串；
文件；
整数；
数字；
模板。

本列表适用于模块发布时“1С-Битрикс: Управление сайтом”"Бизнес"版本

模块图像

添加新选项卡

添加用户设置字段

编辑用户设置

用户设置外观

从1С-Битрикс市场安装模块

可以从1С-Битри克斯市场安装模块 "用户设置"

在安装模块之前，如果尚未安装，则应安装模块 "composer依赖安装包装器"。模块对于通过composer安装依赖项是必需的。

之后，模块就像任何市场模块一样安装和删除。

通过composer安装模块

在项目的composer.json文件中，您需要在

在require块中指定安装程序 "fi1a/installers": "^2.0；
在require块中指定模块 "fi1a/usersettings": "^2.0"；
指定1С-Битрикс的路径（bitrix-dir），以便在安装fi1a/installers时复制模块。

项目composer.json文件示例

{
  "name": "fi1a/project",
  "type": "project",
  "license": "MIT",
  "authors": [
    {
      "name": "Fi1a",
      "email": "fi1a@icloud.com"
    }
  ],
  "require": {
    "fi1a/installers": "^2.0",
    "fi1a/usersettings": "^2.0"
  },
  "extra": {
    "bitrix-dir": "../bitrix"
  }
}

然后，使用命令composer install执行安装。

如果您尚未连接composer autoload.php，则必须在local/php_interface/init.php文件中连接它。

require_once __DIR__ . '/../vendor/autoload.php';

如果未通过composer安装模块，则需要从1C-Битрикс的行政界面安装（市场 > 已安装解决方案 > "用户自定义设置 (fi1a.usersettings)" 模块）。

安装后，请检查模块文件和文件夹的读取权限。

支持迁移

从版本1.2.0开始，模块支持迁移 "开发者迁移" (sprint.migration)

添加了助手 \Fi1a\UserSettings\SprintMigration\Helpers\UserSettingsHelper 和构建器 \Fi1a\UserSettings\SprintMigration\Builders\UserSettingsBuilder

使用助手

public function up()
{
    $helper = $this->getHelperManager();

    $helper->UserSettings()->saveTab("TAB", array (
        'ACTIVE' => '1',
        'CODE' => 'TAB',
        'SORT' => '500',
        'LOCALIZATION' => [
            'ru' => [
                'L_NAME' => 'Вкладка',
                'L_TITLE' => 'Вкладка',
            ],
            'en' => [
                'L_NAME' => 'Tab',
                'L_TITLE' => 'Tab',
            ],
        ],
    ));
}

创建迁移可在模块 "开发者迁移" (sprint.migration) 的管理迁移页面上的 "工具" > "用户自定义设置" 分区中完成。

处理字段值

\Fi1a\UserSettings\Option 类用于处理字段值。该类实现了Singleton模式，要获取类的实例应使用 getInstance() 方法。

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

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

$option = Option::getInstance();

获取字段值

要按字符代码获取字段值，需要使用 get(string $key, $default = null) 方法。

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

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

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

getAll(): array 方法用于获取所有用户字段值。

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

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

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

设置字段值

使用 set(string $key, $value): \Bitrix\Main\Result 方法设置字段值。该方法实现了字段值的验证。该方法返回 \Bitrix\Main\Result 类的实例，可以通过 isSuccess() 方法检查安装值时是否存在错误。

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

Loader::includeModule('fi1a.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');

重置值缓存

在更改结构或设置值时，缓存会自动清除。在不是通过模块API更改的情况下，可以使用 clearCache(): bool 方法强制清除缓存。

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

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

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

选择、添加、更新、删除选项卡

选项卡的处理通过三个类实现

\Fi1a\UserSettings\TabMapper — 用户自定义设置选项卡的映射器；
\Fi1a\UserSettings\Tab — 用户自定义设置中的选项卡类；
\Fi1a\UserSettings\TabCollection — 用户自定义设置选项卡实例的集合。

下面将详细介绍它们。

添加选项卡

选项卡类 \Fi1a\UserSettings\Tab 是 \ArrayObject 类的子类。首先需要使用工厂方法 create(array $input = []): TabInterface 获取选项卡类的实例，将所有必需的参数传递给它。该方法为静态方法。获取到 \Fi1a\UserSettings\Tab 类的实例后，调用 add(): AddResult 方法，该方法将返回一个包含 \Bitrix\Main\ORM\Data\AddResult 类的实例的结果对象。可以使用 \Bitrix\Main\ORM\Data\AddResult 类的 isSuccess($internalCall = false) 方法检查操作的成功性。

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

Loader::includeModule('fi1a.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 — 选项卡标题。

选择选项卡

主要的选择选项卡的方法是 \Fi1a\UserSettings\TabMapper 类的 getList(array $parameters = []): TabCollectionInterface 方法。该方法接受一个参数数组，其语法类似于ORM D7。该方法返回一个包含 \Fi1a\UserSettings\TabCollection 类的选项卡类集合。如果选择结果为空，则集合类将返回零个元素。

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

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

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

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

可以使用 getActive(array $parameters = []): TabCollectionInterface 方法替换上一个示例。该方法执行所有活动的选项卡选择，并允许通过传递 $parameters 参数进行额外的过滤或排序，该参数的语法类似于ORM D7。

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

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

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

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

方法 getById(int $id) 根据标识符查找标签页。与 getList(array $parameters = []): TabCollectionInterface 和 getActive(array $parameters = []): TabCollectionInterface 方法不同，它返回的不是标签页集合，而是标签页类 \Fi1a\UserSettings\Tab 的实例。如果根据标识符找不到标签页，该方法将返回 false。

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

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

$tab = TabMapper::getById(1);

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

标签页更新

要更新标签页，应使用 \Fi1a\UserSettings\Tab 类的 update(): UpdateResult 方法，该方法将以 \Bitrix\Main\ORM\Data\UpdateResult 类的实例返回结果。可以使用 \Bitrix\Main\ORM\Data\UpdateResult 类的 isSuccess($internalCall = false) 方法检查操作是否成功。

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

Loader::includeModule('fi1a.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 \Fi1a\UserSettings\TabMapper;

Loader::includeModule('fi1a.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 \Fi1a\UserSettings\TabMapper;

Loader::includeModule('fi1a.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());
    }
}

标签页删除

要删除标签页，应使用 \Fi1a\UserSettings\Tab 类的 delete(): DeleteResult 方法，该方法将以 \Bitrix\Main\ORM\Data\DeleteResult 类的实例返回结果。可以使用 \Bitrix\Main\ORM\Data\DeleteResult 类的 isSuccess($internalCall = false) 方法检查操作是否成功。

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

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

$tab = TabMapper::getById(3);

$deleteResult = $tab->delete();

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

字段选择、添加、更新、删除

字段处理通过三个类实现

\Fi1a\UserSettings\FieldMapper — 用户设置字段映射器；
\Fi1a\UserSettings\Field — 用户设置字段类；
\Fi1a\UserSettings\FieldCollection — 用户设置字段实例的集合。

下面将详细介绍它们。

字段添加

字段类 \Fi1a\UserSettings\Field 是 \ArrayObject 类的子类。首先需要使用工厂方法 create(array $input = []): FieldInterface 获取字段类实例，并将所有必要的参数传递给它。该方法为静态方法。在获取到 \Fi1a\UserSettings\Field 类的实例后，将调用 add(): AddResult 方法，该方法将以 \Bitrix\Main\ORM\Data\AddResult 类的实例返回结果。可以使用 \Bitrix\Main\ORM\Data\AddResult 类的 isSuccess($internalCall = false) 方法检查操作是否成功。

以下是一个添加字符串类型字段的示例。

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

Loader::includeModule('fi1a.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 = []): FieldCollectionInterface 类的 \Fi1a\UserSettings\FieldMapper。该方法接受与 ORM D7 语法类似的参数数组。该方法返回 \Fi1a\UserSettings\FieldCollection 类的字段集合。如果选择结果为空，则集合类将返回零个元素的数量。

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

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

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

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

可以使用 getActive(array $parameters = []): FieldCollectionInterface 方法替换上一个示例。该方法执行所有活动的字段选择，并可以通过传递类似 ORM D7 的 $parameters 参数进行额外的筛选或排序。

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

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

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

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

方法 getById(int $id) 根据标识符（不是用户字段标识符）搜索字段。与 getList(array $parameters = []): FieldCollectionInterface 和 getActive(array $parameters = []): IFieldCollection 方法不同，它返回的不是字段集合，而是字段类 \Fi1a\UserSettings\Field 的实例。如果根据标识符找不到字段，则该方法将返回 false。

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

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

$field = FieldMapper::getById(2);

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

可以使用 getByTabId(int $tabId) 方法选择标签页的所有字段。该方法将返回属于具有标识符 int $tabId 的标签页的字段集合。

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

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

$fieldCollection = FieldMapper::getByTabId(1);

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

可以使用 getByCode(string $code) 方法根据字符代码选择字段。该方法将返回具有字符代码 string $code 的字段或 false，如果未找到具有字符代码的字段。

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

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

$field = FieldMapper::getByCode('UF_FUS_FIELD');

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

字段更新

为了更新字段，应使用类 \Fi1a\UserSettings\Field 的方法 update(): UpdateResult，它将返回一个对象，该对象是类 \Bitrix\Main\ORM\Data\UpdateResult 的实例。可以通过类 \Bitrix\Main\ORM\Data\UpdateResult 的方法 isSuccess($internalCall = false) 检查操作的成功性。

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

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

$field = FieldMapper::getById(3);

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

    $updateResult = $field->update();

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

保存字段

方法 save() 根据是否存在 ID（主键）来添加或更新字段。