Custom fields¶

MRBS 1.12.2 can discover additional database columns and use them as fields for bookings, rooms, and users. Custom fields are therefore schema extensions, not settings that create columns automatically.

Back up first

Back up the database and test the change on a non-production instance. MRBS upgrades do not create, migrate, or remove site-specific columns.

Where custom fields are supported¶

Database table	Purpose	Important rule
`entry`	Extra data for an individual booking	Add the identical column to `repeat`
`repeat`	Template data for a recurring booking	Keep name, type, length, nullability, and default identical to `entry`
`room`	Extra room or resource properties	Displayed and edited with room data
`users`	Extra user profile data	Used only with database authentication

An entry column without an identical repeat column causes recurring booking operations to fail. Treat the pair as one schema change.

Use only letters, numbers, and underscores in a column name. For compatibility with PostgreSQL, start it with a letter or underscore. Prefer stable, lowercase names such as participant_count or catering.

Supported database types¶

SQL type	MRBS control
`TEXT`	Multi-line text
`VARCHAR`	Text input or multi-line text, depending on its maximum length
`DATE`	Date input
`DECIMAL` / `NUMERIC`	Number input
`INT`	Integer input
`SMALLINT` / `TINYINT`	Checkbox, interpreted as a Boolean value

Use SMALLINT for Boolean custom fields on PostgreSQL and TINYINT on MySQL. Other column types are not supported by the automatic custom-field handling.

Add a field to the schema¶

The examples assume the default mrbs_ table prefix. Replace it if $db_tbl_prefix has another value.

Booking field¶

This example adds an optional catering choice:

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

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

Both statements work with MySQL and PostgreSQL. Verify the resulting definitions in both tables before opening the booking form.

Room checkbox¶

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;

In MRBS 1.12.2, the database default is used when a new row is created. Choose defaults deliberately, especially for mandatory fields and checkboxes.

Give the field a translated label¶

Without an override, MRBS derives the label from the column name. Define one label per active language in 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';

For an entry/repeat pair, define only entry.catering; no repeat.catering token is needed. Room and user fields use tokens such as room.coffee_machine and users.phone.

See Text and translations for vocabulary overrides, language files, and translated Help pages.

Choose the input behavior¶

Fixed choices¶

$select_options replaces free input with a select list:

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

For an associative array, MRBS stores the key (c) and displays, searches, and reports the value (Coffee). This lets wording change without rewriting stored data.

Avoid keys that consist only of digits: PHP converts integer-like string keys to integers, so MRBS may interpret the array as indexed. Include an empty choice when a mandatory selection must start unselected.

$select_options is supported for entry.name, entry.description, custom entry fields, and custom users fields. The configured option captions are site-wide strings; the field label itself can be translated with $vocab_override.

Suggestions with free input¶

Use $datalist_options for suggestions while still accepting another value:

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

It supports the same fields as $select_options. With associative datalists, the stored key can be surprising to users, so test the behavior before use.

Mandatory, private, and validated fields¶

Make a field mandatory everywhere:

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

Or only in areas with database IDs 1 and 3:

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

Area-specific mandatory rules apply only to entry fields. A mandatory checkbox must be checked before submission.

Private custom fields are supported for entry and users:

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

This protects the value only when private bookings are enabled and configured. Test every relevant role; do not use UI privacy as a substitute for minimizing sensitive data.

Pattern validation is currently limited to custom users text fields:

$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';

Entry text fields can have translated placeholders:

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

Client-side patterns improve feedback but do not turn a field into a safe place for secrets or untrusted markup.

Control field order¶

Place booking fields explicitly in create and view pages:

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

Fields not listed are appended in their normal order. Custom fields can also be placed in the report search form:

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

Complete example¶

After adding catering to both booking tables:

$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',
);

The option captions in this example remain the same in every UI language. If translated option captions are a requirement, design and test a site-specific extension rather than assuming $select_options translates them automatically.

Change, remove, and upgrade¶

Before shortening a column or changing its type, inspect existing values and test the conversion. Before removing a field, remove its configuration references, deploy that change, confirm the application works, and only then drop the column through the normal database change process. For booking fields, change both entry and repeat.

Record every custom column in the site's operations documentation and recheck it after each MRBS upgrade. Standard MRBS schema scripts do not own these columns.

Verification checklist¶

entry and repeat definitions are identical for every booking field.
Creating, editing, viewing, copying, and deleting a booking works.
A recurring series and one occurrence can be edited correctly.
Database defaults are applied to new records.
Required, private, select, datalist, and validation behavior works by role and area.
Labels appear in every configured language.
Search, reports, email, calendar export, and import/export show safe values.
Room and user administration display only the intended fields.
Backup and restore procedures include the extended schema.