7.2.2. Custom Field Definition

⁠7.2.2. Custom Field Definition

The definition of a custom field includes the following logical attributes:

Caption variable name. This value is supplied to the lang_get() API; it is therefore mandatory to set this to a valid PHP identifier (i.e. only letters, numbers and underscores; no spaces) if you intend to translate the field label (see Section 7.2.5, “Localizing Custom Field Names”).
Note
If the specified variable is not found in the language files or in custom_strings_inc.php, then it will be displayed as-is.
Custom field type, can be one of:
- string, for strings of up to 255 characters.
- numeric, for numerical integer values.
- float, for real (float / double) numbers.
- email, for storing email addresses.
- enumeration is used when a user selects one entry from a list. The user interface for this type is a combo-box.
- checkbox is like enumeration, but the options are shown as checkboxes and the user is allowed to tick more than one item.
  The default value and the possible value can contain multiple values like RED|YELLOW|BLUE.
- radio is like enumeration, but the list is shown as radio buttons and the user is only allowed to tick a single option.
  The possible values can be RED|YELLOW|BLUE, and default YELLOW.
  Note
  The default value can't contain multiple values.
- list is like enumeration but the list is shown as a list box where the user is only allowed to select one option.
  The possible values can be RED|YELLOW|BLUE, and default YELLOW.
  Note
  The default value can't contain multiple values.
- multi-selection list is like enumeration, but the list is shown as a list box where the user is allowed to select multiple options.
  The possible values can be RED|YELLOW|BLUE, and default RED|BLUE.
  Note
  Multiple values are allowed as default.
- date, for date values.
  The default value can be empty, a numeric UNIX timestamp, or a date in a valid format, including relative indications such as tomorrow, next week, last month, +3 days, last day of this month, etc.
  Note
  The legacy format where the dynamic date had to be wrapped in curly brackets (e.g. {tomorrow}) is still supported for backwards-compatibility, but no longer necessary. This is considered a deprecated feature, that will be removed in a future released of MantisBT.
Possible values for the Custom Field (e.g. RED|YELLOW|BLUE). Use the pipe (|) character to separate the enumeration's values. It is possible for one of the values to be empty (e.g. |RED|YELLOW|BLUE, note the leading |).
The set of values can also be calculated at runtime. For example, =versions would automatically resolve into all the versions defined for the current project. See Section 7.2.7, “Dynamic values for Enumeration Custom Fields” for more information.
Default value - see details above for a sample default value for each type.
Minimum/maximum length for the custom field value (use 0 to disable). Note that these metrics are not really relevant to custom fields that are based on an enumeration of possible values.
Regular expression to use for validating user input (use PCRE syntax).
Read Access level: Minimum access level for users to be able to see the value of the custom field.
Write Access level: Minimum access level for users to be able to edit the value of the custom field.
Display when reporting issues? - If this custom field should be shown on the Report Issue page.
Display when updating issues? - If this custom field should be shown on the Update Issue page.
Display when resolving issues? - If this custom field should be shown when resolving an issue. For example, a "root cause" custom field would make sense to set when resolving the issue.
Display when closing issues? - If this custom field should be shown when closing an issue.
Required on Report - If this custom field is a mandatory field on the Report Issue page.
Required on Update - If this custom field is a mandatory field on the Update Issue page.
Required on Resolve - If this custom field is a mandatory field when resolving an issue.
Required on Close - If this custom field is a mandatory field when closing an issue.

If the value of a custom field for a certain defect is not found, the default value is assumed.