Custom Fields

From WHMCS Documentation

Custom fields allow you to collect additional information from your clients. WHMCS allows you to set up an unlimited number of customer fields that apply to clients, individual products and services, and support departments. You can set them as either admin-only for private use or public.

For example, you might create custom questions like how a client found your site, whether they want to join the mailing list, or their VAT/Tax Number.

Supported Field Types

  • Text Box — For a text entry.
  • Dropdown Menu — For a selection of preset options.
  • Tick Box — For a yes-or-no answer.
  • Textarea — For a long text entry of multiple lines.

Types of Custom Fields

Client Custom Fields

You can create client profile-related fields in Configuration () > System Settings > Custom Client Fields. Set these to Show on Order Form if you want the client to enter them. You can also leave them as only visible in the admin area, for private entries. The client can view and edit the field values from the client area unless you set them to admin only.

Product Custom Fields

Products that you create can also include custom fields, which the user then views during the order process. This allows you to collect further information that's specific to an individual product. You can set these when you configure a product in Configuration () > System Settings > Products/Services > Products/Services > Edit > Custom Fields. Some modules require specific fields, which you can find in the documentation for that module.

Support Custom Fields

Set custom fields for support on a per-department basis. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords. Configure these in Configuration () > System Settings > Support > Support Departments > Edit > Custom Fields.

Displaying Custom Fields on Invoices

There are times when you might want custom fields to appear on invoices. For example:

  • You have a client custom field for a Tax ID or VAT Number.
  • You have a product custom field containing a Username or Reference for the client's product.

The client and product field types support this. To enable this, check Show on Invoice when you configure the custom fields (either in Configuration () > System Settings > Client Custom Fields or the Custom Fields tab of the product configuration).

Client custom fields will display under the name and address information on the invoice. Product custom fields display as part of the line item descriptions for those products.

If you enable Store Client Data Snapshot under Configuration () > System Settings > General Settings > Invoices and then create or edit a custom field after invoice creation, the invoice won't reflect those changed values and new fields. However, future invoices will show them.

Displaying Custom Fields in Emails

You can add custom fields to email templates using merge fields. For more information, see Email Templates.

Displaying Custom Fields on Pages

To display custom fields on service-related pages, the merge fields take the following format, where fieldname is the name of the custom field, lowercase with no spaces:

{$client_custom_field_fieldnamehere}

For example, for IP address, the merge field would be:

{$service_custom_field_ipaddress}

For fields with Friendly Names, use the friendly name, rather than the machine name, to reference the field. For example, if the field name is:

CustomerType

Reference it as:

{$client_custom_field_customertype}

However, if the field name is using a friendly name, like this:

CustomerType|Type of Customer

Reference it as:

{$client_custom_field_typeofcustomer}

Multi-line Text Areas

For text area custom fields, you can enter data on multiple lines. By default, the system displays it in merge fields on a single line. To see the custom field data as it was entered in the field, use the following merge field:

{$client_custom_field_fieldnamehere|nl2br}

or

{$service_custom_field_ipallocation|nl2br}

Searching Custom Field Values

Use the appropriate list page to search for the values for custom client and product fields. You can search custom client fields via Clients > View/Search Clients > Search/Filter tab or search for custom product fields via Clients > Products/Services > Search/Filter tab.

Tip: Searching Checkboxes
To search a 'Tick Box' type custom field, enter "on" in the Custom Field Value field. This will display results that include the checked option.

Friendly Display Names

Sometimes, a module may require that you format a custom field value in a certain way, which may be hard for visitors to understand. WHMCS can display a friendly name to visitors on the order form, emails, and invoices, and still send the required machine code to the module.

Custom Field Friendly Names

To achieve this, use the format "required value|display value". For example:

  • Disk Space|Your Web Quota
  • 10000MB|10 Gigabytes
  • rbx01ssd|French Server - Solid State Drive

Regular Expression Validation

The regular expression validation rules allow you to define what value the field can accept. The system won't allow the user to proceed until it passes the validation rule. For example:

A domain name in the format "google.com":

/^([a-zA-Z0-9_-])+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,6})$/

A username between 4 and 28 characters in length, allowing only alphanumeric characters and underscores:

/^[a-z\d_]{4,28}$/i

A telephone number in the following format: (###) ###-####

/^(\(?[0-9]{3,3}\)?|[0-9]{3,3}[-. ]?)[ ][0-9]{3,3}[-. ]?[0-9]{4,4}$/

A date in the format DD/MM/YYYY:

/^\d{1,2}\/\d{1,2}\/\d{4}$/

See http://www.rexegg.com/regex-quickstart.html for a detailed guide.

You must properly escape any forward slashes in your regular expression using back slashes: \/