Additional Domain Fields
Contents
What are additional domain fields?
Additional domain fields (or Extended Attributes) define the information that domain registries require for a given TLD.
When a domain registry requires information, a domain name will fail to register successfully unless you provide the values. For example, the information that domain registries request often includes things like the Registrant Legal Type and Registered Entity Name.
For general information about domains in WHMCS, see Domains Management.
When are the fields asked for?
Domain fields display in the shopping cart during the Domains Configuration step of the order process. If the system requires a field, customers must provide the requested information before moving to the next step.
The system saves the values in these fields and submits them to the domain's registrar.
How do I customise the displayed fields?
You can find the default field definitions that we ship with WHMCS in /resources/domains/dist.additionalfields.php.
Warning
- Do not edit this file.
- Prior to WHMCS 7.0, this file existed at /includes/additionaldomainfields.php.
To customise the fields, create a new additionalfields.php file within the /resources/domains/ directory.
Add a new field
To add a new field, create a new entry in your custom /resources/domains/additionalfields.php file. Use the field formatting in the /resources/domains/dist.additionalfields.php file as a reference:
$additionaldomainfields[".co.uk"][] = array(
"Name" => "Date of Birth",
"Type" => "text",
"Size" => "30",
);
Edit an existing field
To edit an existing field:
- Copy and paste the field definition from the /resources/domains/dist.additionalfields.php file into your custom /resources/domains/additionalfields.php file.
- Remove any key-and-value pairs for parameters you do not wish to customize.
- Customize the remaining options. To define a Display Name, add the pipe (|) symbol with the desired display name (for example, 1|Individual).
$additionaldomainfields[".co.uk"][] = array(
"Name" => "Legal Type",
"Options" => "1|Individual,2|UK Limited Company,3|UK Public Limited Company",
);
Remove a field
To remove an existing field, define the field within your custom /resources/domains/additionalfields.php file and set the Remove attribute to true.
$additionaldomainfields[".co.uk"][] = array(
"Name" => "Company ID Number",
"Remove" => true,
);
Translate a field name
To translate a field name:
- Define the field within your custom /resources/domains/additionalfields.php file and set the LangVar attribute to the desired language variable.
- Add the translation string with the corresponding attribute to your language override file.
$additionaldomainfields[".co.uk"][] = array(
"Name" => "Legal Type",
"Options" => "Individual,UK Limited Company,UK Public Limited Company",
"LangVar" => "uktldlegaltype",
);
Language override file entry:
$_LANG['uktldlegaltype'] = "Custom Field Label Text";
You can translate the field name via language override files. This allows you to change the label on the shopping cart next to the additional domain field based upon the language in which the visitor is viewing your site. For more information, see Easy Translation.
Prepopulated Data Variables
The following variables are available for use with dropdown field types.
| Tag | Description |
|---|---|
| {Countries} | Provides a comma-separated list of countries. The system will save a full country name and pass it to the registrar for the field (for example, United Kingdom). |
| {CountryCodeMap} | Provides an associative key-and-value pair list of country codes and country names. This will display the full country name for a user to choose, but it will only store and pass the ISO country code to the registrar (for example, GB). |
For example:
$additionaldomainfields[".co.uk"][] = array(
"Name" => "Registered Country",
"Type" => "dropdown",
"Options" => "{Countries}",
);
Conditional Requirements
You can set additional domain fields as never required, always required, or conditionally required. A conditional requirement allows you to denote a field as required only when another field contains a certain value. This allows you to define more complex validation rules.
How it Works
Consider the following example of defining a conditionally-required additional domain field:
$additionaldomainfields['.co.uk'][] = [
'Name' => 'Company ID Number',
'LangVar' => 'uktldcompanyid',
'Type' => 'text',
'Size' => '30',
'Required' => [
'Legal Type' => [
'UK Limited Company',
'UK Public Limited Company',
],
],
];
The example above only requires the Company ID Number field when the value of the Legal Type field is either "UK Limited Company" or "UK Public Limited Company".
To define a conditional requirement, set the value of the Requires key to an array containing a list of field names and values that trigger the requirement. The array syntax here supports defining multiple fields, and the system will require the field if any of the required fields have one of the defined values.
As with all customizations, if you wish to override the default requirements for a given field, use an override file.