Difference between revisions of "Additional Domain Fields"

From WHMCS Documentation
Line 1: Line 1:
−
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> This page describes a feature available in version 7.0 and above</div>
+
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> This page describes a feature available in version 7.0 and above.</div>
  
 
==What are additional domain fields?==
 
==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.
+
Additional domain fields (or Extended Attributes) define the information that domain registries require for a given TLD.
  
−
When a domain registry requires the information, a domain name will fail to register successfully unless the values are provided.
+
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.
  
−
Typical information requested by domain registries include things such as Registrant Legal Type, Registered Entity Name, etc...
+
==When are the fields asked for?==
  
−
==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.
  
−
Domain fields are displayed as part of the order process.
+
==How do I customise the displayed fields?==
  
−
In the shopping cart they will appear during the ''Domains Configuration'' step.
+
You can find the default field definitions that we ship with WHMCS in <tt>/resources/domains/dist.additionalfields.php</tt>.
  
−
If a field is required, customers will be required to provide the requested information before moving to the next step.
+
<div class="docs-alert-danger">
 +
<span class="title">Warning</span><br />
 +
* Do '''not''' edit this file.
 +
* Prior to WHMCS 7.0, this file existed at <tt>/includes/additionaldomainfields.php</tt>.
 +
</div>
  
−
The values provided to these fields are then saved and submitted to the domain registrar when the domain is registered.
+
To customise the fields, create a new <tt>additionalfields.php</tt> file within the <tt>/resources/domains/</tt> directory.
  
−
==How do I customise the fields that are displayed?==
+
====Add a new field====
  
−
The default field definitions that we ship with WHMCS can be found in ''/resources/domains/dist.additionalfields.php''  This file should '''not''' be edited.
+
To add a new field, create a new entry in your custom <tt>/resources/domains/additionalfields.php</tt> file. Use the field formatting in the <tt>/resources/domains/dist.additionalfields.php</tt> file as a reference:
  
−
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> Prior to WHMCS 7.0, this file was located at ''/includes/additionaldomainfields.php''</div>
+
<div class="source-cli">
 +
$additionaldomainfields[".co.uk"][] = array(
 +
<br/>    "Name" => "Date of Birth",
 +
<br/>    "Type" => "text",
 +
<br/>   "Size" => "30",
 +
<br/>);
 +
</div>
  
−
To customise the fields, create a new file named ''additionalfields.php'' within the ''/resources/domains/'' directory.
+
====Edit an existing field====
  
−
'''Adding a New Field'''
+
To edit an existing field:
  
−
# Add a new entry into your custom ''/resources/domains/additionalfields.php'' file
+
# Copy and paste the field definition from the <tt>/resources/domains/dist.additionalfields.php</tt> file into your custom <tt>/resources/domains/additionalfields.php</tt> file.
−
# You can use the field formatting as found in the ''/resources/domains/dist.additionalfields.php'' file as a reference
+
# 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 (<tt>|</tt>) symbol with the desired display name (for example, <tt>1|Individual</tt>).
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields[".co.uk"][] = array(
 
$additionaldomainfields[".co.uk"][] = array(
−
    "Name" => "Date of Birth",
+
<br/>    "Name" => "Legal Type",
−
    "Type" => "text",
+
<br/>    "Options" => "1|Individual,2|UK Limited Company,3|UK Public Limited Company",
−
    "Size" => "30",
+
<br/>);
−
);
+
</div>
−
</source>
 
  
−
'''Editing an Existing Field'''
+
====Remove a 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
+
To remove an existing field, define the field within your custom <tt>/resources/domains/additionalfields.php</tt> file and set the '''Remove''' attribute to <tt>true</tt>.
−
# 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"
 
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields[".co.uk"][] = array(
 
$additionaldomainfields[".co.uk"][] = array(
−
    "Name" => "Legal Type",
+
<br/>    "Name" => "Company ID Number",
−
    "Options" => "1|Individual,2|UK Limited Company,3|UK Public Limited Company",
+
<br/>    "Remove" => true,
−
);
+
<br/>);
−
</source>
+
</div>
  
−
'''Removing an Existing Field'''
+
====Translate a field name====
  
−
# Define the field within your custom ''/resources/domains/additionalfields.php'' file and set the Remove attribute to '''TRUE'''
+
To translate a field name:
−
 
 
−
<source lang="php">
 
−
$additionaldomainfields[".co.uk"][] = array(
 
−
    "Name" => "Company ID Number",
 
−
    "Remove" => true,
 
−
);
 
−
</source>
 
  
−
'''Translating a Field Name'''<br/>
+
# Define the field within your custom <tt>/resources/domains/additionalfields.php</tt> file and set the '''LangVar''' attribute to the desired language variable.
−
# 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.
−
# Add the translation string with the corresponding attribute to your language override file
 
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields[".co.uk"][] = array(
 
$additionaldomainfields[".co.uk"][] = array(
−
    "Name" => "Legal Type",
+
<br/>    "Name" => "Legal Type",
−
    "Options" => "Individual,UK Limited Company,UK Public Limited Company",
+
<br/>    "Options" => "Individual,UK Limited Company,UK Public Limited Company",
−
    "LangVar" => "uktldlegaltype",
+
<br/>    "LangVar" => "uktldlegaltype",
−
);
+
<br/>);
−
</source>
+
</div>
  
 
Language override file entry:
 
Language override file entry:
  
−
<source lang="php">
+
<div class="source-cli">
 
$_LANG['uktldlegaltype'] = "Custom Field Label Text";
 
$_LANG['uktldlegaltype'] = "Custom Field Label Text";
−
</source>
+
</div>
  
−
The field name can be translated via [https://developers.whmcs.com/languages/overrides/ 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.
+
You can translate the field name via [https://developers.whmcs.com/languages/overrides/ 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.
  
 
==Prepopulated Data Variables==
 
==Prepopulated Data Variables==
Line 89: Line 90:
 
The following variables are available for use with dropdown field types.
 
The following variables are available for use with dropdown field types.
  
−
<table class="table table-striped">
+
<table class="table table-striped table-condensed">
−
<tr><td>'''Tag'''</td><td>'''Description'''</td></tr>
+
<tr><th>Tag</th><th>Description</th></tr>
−
<tr><td>{Countries}</td><td>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).</td></tr>
+
<tr><td>{Countries}</td><td>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).</td></tr>
−
<tr><td>{CountryCodeMap}</td><td>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).</td></tr>
+
<tr><td>{CountryCodeMap}</td><td>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).</td></tr>
 
</table>
 
</table>
  
−
'''Example Usage'''
+
For example:
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields[".co.uk"][] = array(
 
$additionaldomainfields[".co.uk"][] = array(
−
    "Name" => "Registered Country",
+
<br/>    "Name" => "Registered Country",
−
    "Type" => "dropdown",
+
<br/>    "Type" => "dropdown",
−
    "Options" => "{Countries}",
+
<br/>    "Options" => "{Countries}",
−
);
+
<br/>);
−
</source>
+
</div>
  
 
==Conditional Requirements==
 
==Conditional Requirements==
  
−
<div class="docs-alert-info"><i class="fa fa-info-circle"></i> This feature is available in WHMCS 7.9 and above.</div>
+
<div class="docs-alert-info"><i class="fa fa-info-circle"></i>This feature is available in WHMCS 7.9 and above.</div>
  
−
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.
+
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===
 
===How it Works===
  
−
It is easiest to illustrate how to define a conditionally required additional domain field by looking at an example:
+
Consider the following example of defining a conditionally-required additional domain field:
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields['.co.uk'][] = [
 
$additionaldomainfields['.co.uk'][] = [
−
    'Name' => 'Company ID Number',
+
<br/>    'Name' => 'Company ID Number',
−
    'LangVar' => 'uktldcompanyid',
+
<br/>    'LangVar' => 'uktldcompanyid',
−
    'Type' => 'text',
+
<br/>    'Type' => 'text',
−
    'Size' => '30',
+
<br/>    'Size' => '30',
−
    'Required' => [
+
<br/>    'Required' => [
−
        'Legal Type' => [
+
<br/>        'Legal Type' => [
−
            'UK Limited Company',
+
<br/>            'UK Limited Company',
−
            'UK Public Limited Company',
+
<br/>            'UK Public Limited Company',
−
        ],
+
<br/>        ],
−
    ],
+
<br/>    ],
−
];
+
<br/>];
−
</source>
+
</div>
  
−
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".
+
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".
  
−
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.
+
To define a conditional requirement, set the value of the <tt>Requires</tt> 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 customisations, if you wish to override the default requirements for a given field, you should do so using an override file as described above.
+
As with all customizations, if you wish to override the default requirements for a given field, use an override file.

Revision as of 17:37, 18 May 2020

This page describes a feature available in version 7.0 and above.

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.

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:

  1. Copy and paste the field definition from the /resources/domains/dist.additionalfields.php file into your custom /resources/domains/additionalfields.php file.
  2. Remove any key-and-value pairs for parameters you do not wish to customize.
  3. 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:

  1. Define the field within your custom /resources/domains/additionalfields.php file and set the LangVar attribute to the desired language variable.
  2. 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.

Prepopulated Data Variables

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

TagDescription
{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

This feature is available in WHMCS 7.9 and above.

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.

Retrieved from "http://3.17.75.209/index.php?title=Additional_Domain_Fields&oldid=28474"