Revision as of 20:29, 5 May 2017

Custom fields allow you to collect additional information from your clients. WHMCS allows you to setup an unlimited number of customer fields which apply to clients, individual products & services and/or support departments. They can be set as either public or admin only for private use.

Common examples are questions like how did you find out site, do you want to join the mailing list, VAT/Tax Number, etc...

Supported Field Types

• Text Box - for text entry
• Dropdown Menu - for a selection of options to choose from
• Tick Box - for a yes/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 Setup > Custom Client Fields. These can be set to Show on Order Form if you want the client to enter them or left as admin area only for private entries. The client can view and edit the field values from the client area unless they are set to admin only.

Product Custom Fields

Products you create can also have custom fields added to them which are then shown to the user during the order process. This allows you to collect further information specific to an individual product. These are set when configuring a product in Setup > Products/Services > Products/Services > Edit > Custom Fields tab . Some modules require specific fields are setup and will be explained in the documentation for that module.

Support Custom Fields

Custom fields for support are set per department and allow you to ask users for additional information when opening tickets. This is often used for things such as current usernames & passwords, etc... These are configured in Setup > Support > Support Departments > Edit > Custom Fields tab

Displaying Custom Fields on Invoices

There are times when you might want custom fields to appear on invoices. Just 2 examples of what you might find this useful for are:

• If you have a client custom field for a Tax ID or VAT Number
• If you have a product custom field containing a Username or Reference for the clients product

So how do you do it? Well it's really simple. Both the client & product field types support this, and to enable it all you need to do is tick the checkbox labelled Show on Invoice where you configure the custom fields (either in Setup > Client Custom Fields or the Custom Fields tab of the product config).

In the case of client custom fields, they will then be shown under the name & address information on the invoice, and in the case of product custom fields they show as part of the line item descriptions for those products.

Please note that if "Store Client Data Snapshot" is enabled under Setup > General Settings > Invoices tab and you create or edit a custom field after the invoice has been created, any changed values or new fields will not be reflected when viewing it. However future invoices will show them.

Displaying Custom Fields in Emails

Custom fields can be displayed in email templates using merge fields. The relevant documentation can be found at Email_Templates#Merge_Fields.

Displaying Custom Fields on Pages

To display custom fields on service-related pages, the merge fields take the following format:

{$client_custom_field_fieldnamehere}

Where fieldname is the name of the custom field all in lowercase and with no spaces. Eg: IP Address would be:

{$service_custom_field_ipaddress}

Multi-line Text Areas

For text area custom fields, data can be entered on multiple lines. By default it will be displayed in merge fields on a single line. To have the custom field data displayed as it was entered into the field, the following merge field can be used:

{$client_custom_field_fieldnamehere|nl2br}
or
{$service_custom_field_ipallocation|nl2br}

Searching Custom Field Values

The values entered into custom client and product fields can be searched from the appropriate list page. Custom client fields can be searched via Clients > View/Search Clients > Search/Filter tab whilst custom product fields can be searched via Clients > Products/Services > Search/Filter tab.

Friendly Display Names

On occasion a module may require a custom field value to be formatted in a certain way, but this might not be very easy for visitors to understand. WHMCS can display a friendly name to visitors on the order form, emails and invoices, but 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 take. The user won't be allowed to proceed until it passes the validation rule. Some common examples you might want:

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, alpha-numeric, and allowing 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.