Difference between revisions of "Additional Domain Fields"

Revision as of 18:36, 26 November 2019

This page describes a feature available in version 7.0 and above

What are additional domain fields?

Additional domain fields (also commonly referred to as Extended Attributes) define the information required by domain registries for a given TLD.

When a domain registry requires the information, a domain name will fail to register successfully unless the values are provided.

Typical information requested by domain registries include things such as Registrant Legal Type, Registered Entity Name, etc...

When are the fields asked for?

Domain fields are displayed as part of the order process.

In the shopping cart they will appear during the Domains Configuration step.

If a field is required, customers will be required to provide the requested information before moving to the next step.

The values provided to these fields are then saved and submitted to the domain registrar when the domain is registered.

How do I customise the fields that are displayed?

The default field definitions that we ship with WHMCS can be found in /resources/domains/dist.additionalfields.php This file should not be edited.

Prior to WHMCS 7.0, this file was located at /includes/additionaldomainfields.php

To customise the fields, create a new file named additionalfields.php within the /resources/domains/ directory.

Adding a New Field

Add a new entry into your custom /resources/domains/additionalfields.php file
You can use the field formatting as found in the /resources/domains/dist.additionalfields.php file as a reference

$additionaldomainfields[".co.uk"][] = array(
    "Name" => "Date of Birth",
    "Type" => "text",
    "Size" => "30",
);

Editing an Existing Field

Begin by copying and pasting the field definition from the /resources/domains/dist.additionalfields.php file into your custom /resources/domains/additionalfields.php file
Remove any key/value pairs for parameters you do not wish to customise
Customise the remaining options as desired (in the example below the option values are being customised to just the 3 most commonly used options)
Options can have a Display Name defined by adding the "|" symbol followed by the desired display name - e.g., "1|Individual"

$additionaldomainfields[".co.uk"][] = array(
    "Name" => "Legal Type",
    "Options" => "1|Individual,2|UK Limited Company,3|UK Public Limited Company",
);

Removing 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,
);

Translating 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";

The field name can be translated via language override files. This allows you to change the label displayed on the shopping cart next to the additional domain field based upon the language in which the visitor is viewing your site.

Prepopulated Data Variables

The following variables are available for use with dropdown field types.

Tag	Description
{Countries}	Provides a comma separated list of countries. A full country name will be saved and passed to the registrar for the field (eg. United Kingdom).
{CountryCodeMap}	Provides an associative key value pair list of country codes and country names. This will display the full country name for a user to select from but only store and pass the ISO country code to the registrar (eg. GB).

Example Usage

$additionaldomainfields[".co.uk"][] = array(
    "Name" => "Registered Country",
    "Type" => "dropdown",
    "Options" => "{Countries}",
);

Conditional Requirements

This feature is available in WHMCS 7.9 and above.

Additional domain fields can be set as never required, always required, or conditionally required. A conditional requirement allows a field to be denoted as required only when another field contains a certain value. This allows for more complex validation rules to be defined.

How it Works

It is easiest to illustrate how to define a conditionally required additional domain field by looking at an example:

$additionaldomainfields['.co.uk'][] = [
    'Name' => 'Company ID Number',
    'LangVar' => 'uktldcompanyid',
    'Type' => 'text',
    'Size' => '30',
    'Required' => [
        'Legal Type' => [
            'UK Limited Company',
            'UK Public Limited Company',
        ],
    ],
];

In the example above, the field "Company ID Number" is only required when the value of the "Legal Type" field is one of either "UK Limited Company" or "UK Public Limited Company".

A conditional requirement is defined by setting 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 multiple fields to be defined, and the field will be required if any of the required fields have one of the defined values selected/specified.

As with all customisations, if you wish to override the default requirements for a given field, you should do so using an override file as described above.

Documentation