Custom User Fields

Custom user fields let you define additional information or preferences that you want to collect from users. These values can be displayed with messages or in profiles, used for internal data, or even to change behaviors in XenForo through template changes.

Defining a Custom User Field

Custom user fields can be created via the Custom User Fields section of the Users tab in the admin control panel.

To create a field, you must first pick an identifier that cannot be changed after the field is created. This identifier can only contain alphanumeric characters and is used to programmatically access the value of a field (such as via a template).

The display location of the field controls the page in the user's account where the value will be edited. Fields that are defined as preferences will never appear on the user's profile page. Otherwise, the field will appear in the appropriate section of the profile (depending on general options).

If you add a required field after a user registers, they will not be prompted to fill this field when browsing.

The General Options tab also provides a number of more advanced options that you can set to control the field. If the field is required, a value will have to be entered/selected when a user registers or attempts to edit the appropriate section of their account.

Field Types

Fields break down into two types:

  1. Text fields - these are free form fields where the users can type any value they wish.
  2. Choice fields- these fields have a defined set of options which the users select from. These include drop down menus, radio buttons, and checkboxes. Drop downs and radio buttons allow only a single selection; checkboxes and multiple-choice drop downs allow a selection of any number of options.

Text Fields

If you have selected a text field, the Options for Text Fields tab will apply. Here, you can limit the maximum length and the format of the field.

If you select the regular expression format, the regular expression you just need to enter the regular expression body. By default, this is case sensitive.

If you select the PHP callback, your callback will receive three values: $field, the field definition; $value, the field value (by reference); and $error, a holder for any error message (by reference).

Choice Fields

When selecting a choice field, you must define the available fields via Options for Choice Fields. Each choice consists of two parts:

  • The value - this is a unique identifier for the choice. This may only contain alphanumeric characters. When accessing the data programmatically, this is the value that will be returned.
  • The text - this is the printable value for the choice that the users will see in the user interface. This creates a phrase that can then be varied per language.

Custom Display Formatting

Normally, custom fields value that are shown in the user interface will simply display the value for the field (either the text entered by the user or the text value of a choice). However, you can override this by specifying the Value Display HTML value. This takes a string of HTML and formats the custom field value with it before displaying. You need to use specific tokens to display the value entered by the user:

  • {$value} - the printable (text) value of the field.
  • {$valueUrl} - the same as {$value} except that the value has been encoded for use in a URL.
  • {$choice} - the choice "value". This will be blank for text fields.
  • {$fieldId} - the ID string of the field selected when it was created.

Note that if the user has not entered a value or selected a choice for the field, the field will never be displayed.

Field Values in Templates

If you wish to access the value of a field within a template, such as for the current visitor, you may use:

{$visitor.customFields.fieldId}

Where the fieldId was selected when the field was created.

The value contained here will be the text entered by the user for a text field or the choice value for a choice field. If the choice field is a multiple choice field, to check for the presence of a particular choice, look for:

{$visitor.customFields.fieldId.choiceValue}

In some templates, you may be able to access the custom field information of the user in that context, such as when viewing a post or a user's profile. The exact variable name may vary, but the above concepts still apply. In many cases, you can refer to $user rather than $visitor.