Difference between revisions of "Custom Fields"

From WHMCS Documentation
(→‎Show on Order Form)
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
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.
+
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.
  
−
Common examples are questions like how did you find out site, do you want to join the mailing list, VAT/Tax Number, etc...
+
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==
+
== Client Custom Fields ==
  
−
*Text Box - for text entry
+
Custom fields for clients display in the client's profile for admins, clients, or both and can optionally display on the order form. 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.
−
*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==
+
To add a custom field to your clients' profiles:
  
−
===Client Custom Fields===
+
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Custom Fields''' or, prior to WHMCS 8.0, '''Setup > Custom Client Fields'''.
 +
# Locate the desired custom field to edit or create a new custom field under '''Add New Custom Field'''.
 +
# Enter the requested field information and choose a field type.
 +
# Check the appropriate checkboxes to show or hide the field or require a response.
 +
# Click '''Save Changes'''.
  
−
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.
+
<div class="docs-alert-success">
 +
<span class="title">Searching</span><br />
 +
* You can search for the values from custom client fields at '''Clients > View/Search Clients''' in the '''Search/Filter''' tab.
 +
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
 +
</div>
 +
 
 +
== Product Custom Fields ==
 +
 
 +
Custom fields for products display as part of the configuration process when clients purchase a product, or you can choose to only display them in the Admin Area for purchased products. This allows you to collect further information that's specific to an individual product.
 +
 
 +
Some modules require specific fields, which you can find in the documentation for that module.
 +
 
 +
You can configure custom product fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Products and Services|Products/Services]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services'''.
 +
 
 +
<div class="docs-alert-success">
 +
<span class="title">Searching</span><br />
 +
* You can search for the values from custom product fields at '''Clients > Products/Services''' in the '''Search/Filter''' tab for the desired product group.
 +
* To search a '''Checkbox''' custom field, enter "on" in the '''Custom Field Value''' field. This will display results that include the checked option.
 +
</div>
 +
 
 +
== Support Department Custom Fields ==
 +
 
 +
Custom fields for support departments display during ticket submission, or you can optionally choose to only display them in the Admin Area. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords.
  
−
===Product Custom Fields===
+
You can configure custom support department fields in the '''Custom Fields''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''.
  
−
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.
+
== Field Types ==
  
−
===Support Custom Fields===
+
When you create a custom field, you can choose from the following field types:
  
−
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'''
+
* '''Text Box''' — For a text entry.
 +
* '''Link/URL''' — A URL. The prefix http:// will automatically be prefixed to any value entered.
 +
* '''Password''' — A value to be encrypted, will appear as a password field type in the client area.
 +
* '''Drop Down''' — A drop-down combo box for a selection of preset options.
 +
* '''Checkbox''' — For a yes-or-no answer.
 +
* '''Text Area''' — For a long text entry of multiple lines.
  
−
==Displaying Custom Fields on Invoices==
+
== Validation ==
  
−
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:
+
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
  
−
*If you have a client custom field for a Tax ID or VAT Number
+
A telephone number in the following format: (###) ###-####
−
*If you have a product custom field containing a Username or Reference for the clients product
+
/^(\(?[0-9]{3,3}\)?|[0-9]{3,3}[-. ]?)[ ][0-9]{3,3}[-. ]?[0-9]{4,4}$/
  
−
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).
+
A date in the format DD/MM/YYYY:
 +
/^\d{1,2}\/\d{1,2}\/\d{4}$/
  
−
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.
+
Numbers only (0-9, any length):
 +
/^[0-9]+$/
  
−
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.
+
See http://www.rexegg.com/regex-quickstart.html for a detailed guide.
 +
 
 +
<div class="docs-alert-warning">
 +
You must properly escape any forward slashes in your regular expression using back slashes: \/
 +
</div>
 +
 
 +
== Other Settings ==
 +
 
 +
Depending on the type of custom field you are creating, you can enable the following options:
 +
 
 +
=== Admin Only ===
 +
 
 +
Check '''Admin Only''' if you want to hide this in the Client Area.
 +
 
 +
=== Required Field ===
 +
 
 +
Check '''Required Field''' if you want to require a response.
 +
 
 +
=== Show on Order Form ===
 +
 
 +
Check '''Show on Order Form''' if you want to display this field on the order form in the Client Area when a client is registering.
 +
 
 +
=== Show on Invoice ===
 +
 
 +
Check '''Show on Invoice''' if you want this field to display on the client's invoices.
 +
 
 +
You might want to display custom fields on invoices if, for example, you have a client custom field for a Tax ID or VAT Number.
 +
 
 +
* 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''' in the '''[[Invoice Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''. 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==
 
==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]].
+
 
 +
You can add custom fields to email templates using merge fields. For more information, see [[Email_Templates#Merge_Fields|Email Templates]].
  
 
==Displaying Custom Fields on Pages==
 
==Displaying Custom Fields on Pages==
−
To display custom fields on service-related pages, the merge fields take the following format:
+
 
 +
To display custom fields on service-related pages, the merge fields take the following format, where <tt>fieldname</tt> is the name of the custom field, lowercase with no spaces:
 +
 
 +
<div class="source-cli">
 +
{$client_custom_field_fieldnamehere}
 +
</div>
 +
 
 +
For example, for IP address, the merge field would be:
 +
 
 +
<div class="source-cli">
 +
{$service_custom_field_ipaddress}
 +
</div>
 +
 
 +
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:
 +
 
 +
<source lang="php">CustomerType</source>
 +
 
 +
Reference it as:
 +
 
 +
<source lang="php">
 +
{$client_custom_field_customertype}
 +
</source>
 +
 
 +
However, if the field name is using a friendly name, like this:
  
 
<source lang="php">
 
<source lang="php">
−
{$client_custom_field_fieldnamehere}
+
CustomerType|Type of Customer
 
</source>
 
</source>
  
−
Where fieldname is the name of the custom field all in lowercase and with no spaces. Eg: IP Address would be:
+
Reference it as:
  
 
<source lang="php">
 
<source lang="php">
−
{$service_custom_field_ipaddress}
+
{$client_custom_field_typeofcustomer}
 
</source>
 
</source>
  
 
===Multi-line Text Areas===
 
===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:
+
 
 +
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:
  
 
<source lang="php">
 
<source lang="php">
 
{$client_custom_field_fieldnamehere|nl2br}
 
{$client_custom_field_fieldnamehere|nl2br}
 +
</source>
 
or
 
or
 +
<source lang="php">
 
{$service_custom_field_ipallocation|nl2br}
 
{$service_custom_field_ipallocation|nl2br}
 
</source>
 
</source>
  
−
==Searching Custom Field Values==
+
==Friendly Display Names==
−
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'''.
 
  
−
<div class="docs-alert-success">
+
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.
−
<span class="title">Tip: Searching Tick Boxes</span><br />
 
−
In order to search a 'Tick Box' type custom field, enter "on" in the Custom Field Value field. This will display results where the option has been ticked.
 
−
</div>
 
−
 
 
−
==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.
 
 
[[File:Custom_field_friendly.png|thumb|Custom Field Friendly Names]]
 
[[File:Custom_field_friendly.png|thumb|Custom Field Friendly Names]]
−
To achieve this use the format "required value|display value" - for example:
+
To achieve this, use the format "required value|display value". For example:
  
 
*Disk Space|Your Web Quota
 
*Disk Space|Your Web Quota
 
*10000MB|10 Gigabytes
 
*10000MB|10 Gigabytes
 
*rbx01ssd|French Server - Solid State Drive
 
*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.
 
−
 
−
<div class="docs-alert-warning">
 
−
Be aware, any forward slashes in your regular expression needs to be properly escaped using back slashes: \/
 
−
</div>
 

Latest revision as of 15:11, 19 December 2023

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.

Client Custom Fields

Custom fields for clients display in the client's profile for admins, clients, or both and can optionally display on the order form. 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.

To add a custom field to your clients' profiles:

  1. Go to Configuration () > System Settings > Custom Fields or, prior to WHMCS 8.0, Setup > Custom Client Fields.
  2. Locate the desired custom field to edit or create a new custom field under Add New Custom Field.
  3. Enter the requested field information and choose a field type.
  4. Check the appropriate checkboxes to show or hide the field or require a response.
  5. Click Save Changes.

Searching

  • You can search for the values from custom client fields at Clients > View/Search Clients in the Search/Filter tab.
  • To search a Checkbox custom field, enter "on" in the Custom Field Value field. This will display results that include the checked option.

Product Custom Fields

Custom fields for products display as part of the configuration process when clients purchase a product, or you can choose to only display them in the Admin Area for purchased products. This allows you to collect further information that's specific to an individual product.

Some modules require specific fields, which you can find in the documentation for that module.

You can configure custom product fields in the Custom Fields tab at Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services.

Searching

  • You can search for the values from custom product fields at Clients > Products/Services in the Search/Filter tab for the desired product group.
  • To search a Checkbox custom field, enter "on" in the Custom Field Value field. This will display results that include the checked option.

Support Department Custom Fields

Custom fields for support departments display during ticket submission, or you can optionally choose to only display them in the Admin Area. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords.

You can configure custom support department fields in the Custom Fields tab at Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments.

Field Types

When you create a custom field, you can choose from the following field types:

  • Text Box — For a text entry.
  • Link/URL — A URL. The prefix http:// will automatically be prefixed to any value entered.
  • Password — A value to be encrypted, will appear as a password field type in the client area.
  • Drop Down — A drop-down combo box for a selection of preset options.
  • Checkbox — For a yes-or-no answer.
  • Text Area — For a long text entry of multiple lines.

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}$/

Numbers only (0-9, any length): 

/^[0-9]+$/

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: \/

Other Settings

Depending on the type of custom field you are creating, you can enable the following options:

Admin Only

Check Admin Only if you want to hide this in the Client Area.

Required Field

Check Required Field if you want to require a response.

Show on Order Form

Check Show on Order Form if you want to display this field on the order form in the Client Area when a client is registering.

Show on Invoice

Check Show on Invoice if you want this field to display on the client's invoices.

You might want to display custom fields on invoices if, for example, you have a client custom field for a Tax ID or VAT Number.

  • 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 in the Invoices tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. 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}

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
Retrieved from "http://3.17.75.209/index.php?title=Custom_Fields&oldid=34342"