自定义字段¶

MRBS 1.12.2 可以识别额外的数据库列，并将其作为预订、房间和用户字段。因此，自定义字段属于数据库模式扩展，并不是会自动创建列的配置项。

!!! warning “先备份”

备份数据库并在非生产实例上测试更改。 MRBS 升级不会创建、迁移或删除特定于站点的列。

支持自定义字段的地方¶

数据库表	目的	重要规则
`entry`	个人预订的额外数据	将相同的列添加到 `repeat`
`repeat`	定期预订的模板数据	保持名称、类型、长度、可为空性和默认值与 `entry` 相同
`room`	额外的房间或资源属性	显示和编辑房间数据
`users`	额外的用户个人资料数据	仅与数据库身份验证一起使用

没有相同的 repeat 列的 entry 列会导致重复预订操作失败。将这一对视为一个架构更改。

列名中只能使用字母、数字和下划线。为了与 PostgreSQL 兼容，请以字母或下划线开头。更喜欢稳定的小写名称，例如 participant_count 或 catering。

支持的数据库类型¶

SQL类型	MRBS控制
`TEXT`	多行文本
`VARCHAR`	文本输入或多行文本，取决于其最大长度
`DATE`	日期输入
`DECIMAL` / `NUMERIC`	数字输入
`INT`	整数输入
`SMALLINT` / `TINYINT`	复选框，解释为布尔值

将 SMALLINT 用于PostgreSQL 上的布尔自定义字段和MySQL 上的TINYINT。自动自定义字段处理不支持其他列类型。

将字段添加到架构中¶

这些示例假定默认的 mrbs_ 表前缀。如果 $db_tbl_prefix 有其他值，则替换它。

预订字段¶

此示例添加了可选的餐饮选择：

ALTER TABLE mrbs_entry
  ADD COLUMN catering VARCHAR(32) DEFAULT NULL;

ALTER TABLE mrbs_repeat
  ADD COLUMN catering VARCHAR(32) DEFAULT NULL;

这两个语句都适用于 MySQL 和 PostgreSQL。在打开预订表格之前验证两个表中的结果定义。

房间复选框¶

MySQLPostgreSQL

ALTER TABLE mrbs_room
  ADD COLUMN coffee_machine TINYINT NOT NULL DEFAULT 0;

ALTER TABLE mrbs_room
  ADD COLUMN coffee_machine SMALLINT NOT NULL DEFAULT 0;

在 MRBS 1.12.2 中，创建新行时使用数据库默认值。谨慎选择默认值，尤其是必填字段和复选框。

为该字段提供翻译标签¶

如果没有覆盖，MRBS从列名中派生标签。在 config.inc.php 中为每种活动语言定义一个标签：

$vocab_override['en']['entry.catering'] = 'Catering';
$vocab_override['de']['entry.catering'] = 'Verpflegung';
$vocab_override['fr']['entry.catering'] = 'Restauration';
$vocab_override['es']['entry.catering'] = 'Catering';

对于entry/repeat对，仅定义entry.catering；不需要 repeat.catering 令牌。房间和用户字段使用诸如room.coffee_machine和users.phone之类的令牌。

有关词汇覆盖、语言文件和翻译的帮助页面，请参阅文本和翻译。

选择输入行为¶

固定选择¶

$select_options 用选择列表替换自由输入：

$select_options['entry.catering'] = array(
    ''  => 'Please select',
    'c' => 'Coffee',
    's' => 'Sandwiches',
    'h' => 'Hot lunch',
);

对于关联数组，MRBS 存储键 (c) 并显示、搜索和报告值 (Coffee)。这允许改变措辞而无需重写存储的数据。

避免仅包含数字的键：PHP将类似整数的字符串键转换为整数，因此MRBS可能会将数组解释为索引数组。当必须开始取消选择强制选择时，请包含一个空选择。

entry.name、entry.description、自定义 entry 字段和自定义 users 字段支持$select_options。配置的选项标题是站点范围的字符串；字段标签本身可以使用$vocab_override进行翻译。

自由输入的建议¶

使用 $datalist_options 获取建议，同时仍然接受另一个值：

$datalist_options['entry.catering'] = array(
    'Coffee',
    'Sandwiches',
    'Hot lunch',
);

它支持与$select_options相同的字段。对于关联数据列表，存储的密钥可能会让用户感到惊讶，因此在使用之前测试其行为。

必填字段、私有字段和验证字段¶

使字段在任何地方都是必填的：

$is_mandatory_field['entry.catering'] = true;

或者仅在数据库 ID 为 1 和 3 的区域中：

$is_mandatory_field['entry.catering'] = array(1, 3);

特定区域的强制规则仅适用于entry字段。提交前必须选中必填复选框。

entry 和 users 支持私有自定义字段：

$is_private_field['entry.internal_notes'] = true;
$is_private_field['users.phone'] = true;

仅当启用并配置私人预订时，这才能保护该值。测试每个相关角色；不要使用 UI 隐私来替代最小化敏感数据。

模式验证当前仅限于自定义 users 文本字段：

$pattern['users.zip_code'] = '^[0-9]{5}(?:-[0-9]{4})?$';
$vocab_override['en']['users.zip_code.oninvalid'] =
    'Enter a ZIP code such as 12345 or 12345-6789';

输入文本字段可以有翻译的占位符：

$vocab_override['en']['entry.catering.placeholder'] =
    'State allergies or special requirements';

客户端模式可以改善反馈，但不会将字段变成秘密或不受信任标记的安全场所。

控制字段顺序¶

将预订字段显式放置在创建和查看页面中：

$edit_entry_field_order = array(
    'name',
    'catering',
    'description',
);

未列出的字段按正常顺序附加。自定义字段也可以放置在报告搜索表单中：

$report_search_field_order = array(
    'report_start',
    'report_end',
    'catering',
    'roommatch',
);

完整示例¶

将 catering 添加到两个预订表后：

$vocab_override['en']['entry.catering'] = 'Catering';
$vocab_override['de']['entry.catering'] = 'Verpflegung';
$vocab_override['fr']['entry.catering'] = 'Restauration';
$vocab_override['es']['entry.catering'] = 'Catering';

$select_options['entry.catering'] = array(
    ''  => '—',
    'c' => 'Coffee',
    's' => 'Sandwiches',
    'h' => 'Hot lunch',
);

$is_mandatory_field['entry.catering'] = array(1, 3);
$edit_entry_field_order = array('name', 'catering', 'description');
$report_search_field_order = array(
    'report_start',
    'report_end',
    'catering',
);

此示例中的选项标题在每种 UI 语言中都保持相同。如果需要翻译的选项标题，请设计和测试特定于站点的扩展，而不是假设 $select_options 自动翻译它们。

更改、删除和升级¶

在缩短列或更改其类型之前，请检查现有值并测试转换。在删除字段之前，请删除其配置引用、部署该更改、确认应用程序正常工作，然后才通过正常的数据库更改过程删除该列。对于预订字段，请更改 entry 和 repeat。

记录站点操作文档中的每个自定义列，并在每次 MRBS 升级后重新检查。标准 MRBS 模式脚本不拥有这些列。

验证清单¶

每个预订字段的 entry 和 repeat 定义均相同。
创建、编辑、查看、复制和删除预订作品。
可以正确编辑重复出现的系列和一次出现的情况。
数据库默认值应用于新记录。
必需、私有、选择、数据列表和验证行为按角色和区域工作。
标签以每种配置的语言显示。
搜索、报告、电子邮件、日历导出和导入/导出显示安全值。
房间和用户管理仅显示预期字段。
备份和恢复过程包括扩展模式。