Difference between revisions of "Additional Domain Fields"

From WHMCS Documentation

(→‎How do I customise the fields that are displayed?)
(→‎What are additional domain fields?)
 
(8 intermediate revisions by 5 users not shown)
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...
+
For general information about domains in WHMCS, see [[Domains Management]].
  
 
==When are the fields asked for?==
 
==When are the fields asked for?==
  
−
Domain fields are displayed as part of the order process.
+
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.
  
−
In the shopping cart they will appear during the ''Domains Configuration'' step.
+
The system saves the values in these fields and submits them to the domain's registrar.
  
−
If a field is required, customers will be required to provide the requested information before moving to the next step.
+
==How do I customise the displayed fields?==
  
−
The values provided to these fields are then saved and submitted to the domain registrar when the domain is registered.
+
You can find the default field definitions that we ship with WHMCS in <tt>/resources/domains/dist.additionalfields.php</tt>.
  
−
==How do I customise the fields that are displayed?==
+
<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 default field definitions that we ship with WHMCS can be found in ''/resources/domains/dist.additionalfields.php''  This file should '''not''' be edited.
+
To customise the fields, create a new <tt>additionalfields.php</tt> file within the <tt>/resources/domains/</tt> directory.
  
−
<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>
+
====Add a new field====
  
−
To customise the fields, create a new file named ''additionalfields.php'' within the ''/resources/domains/'' directory.
+
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:
  
−
'''Adding a New Field'''
+
<div class="source-cli">
 +
$additionaldomainfields[".co.uk"][] = array(
 +
<br/>    "Name" => "Date of Birth",
 +
<br/>    "Type" => "text",
 +
<br/>    "Size" => "30",
 +
<br/>);
 +
</div>
 +
 
 +
====Edit an existing 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)
 
  
−
<source lang="php">
+
<div class="source-cli">
 
$additionaldomainfields[".co.uk"][] = array(
 
$additionaldomainfields[".co.uk"][] = array(
−
    "Name" => "Legal Type",
+
<br/>    "Name" => "Company ID Number",
−
    "Options" => "Individual,UK Limited Company,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">
+
# Define the field within your custom <tt>/resources/domains/additionalfields.php</tt> file and set the '''LangVar''' attribute to the desired language variable.
−
$additionaldomainfields[".co.uk"][] = array(
+
# Add the translation string with the corresponding attribute to your language override file.
−
    "Name" => "Company ID Number",
 
−
    "Remove" => true,
 
−
);
 
−
</source>
 
  
−
'''Translating a Field Name'''<br/>
+
<div class="source-cli">
−
# 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
 
−
 
 
−
<source lang="php">
 
 
$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 [[Language_Overrides|language override files]]. This allow 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. For more information, see [[Easy_Translation#Localising_a_Field|Easy Translation]].
  
 
==Prepopulated Data Variables==
 
==Prepopulated Data Variables==
Line 88: Line 92:
 
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><tt>{Countries}</tt></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><tt>{CountryCodeMap}</tt></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==
 +
 
 +
<div class="docs-alert-info"><i class="fa fa-info-circle"></i>This feature is available in WHMCS 7.9 and above.</div>
 +
 
 +
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:
 +
 
 +
<div class="source-cli">
 +
$additionaldomainfields['.co.uk'][] = [
 +
<br/>   'Name' => 'Company ID Number',
 +
<br/>    'LangVar' => 'uktldcompanyid',
 +
<br/>    'Type' => 'text',
 +
<br/>    'Size' => '30',
 +
<br/>    'Required' => [
 +
<br/>        'Legal Type' => [
 +
<br/>            'UK Limited Company',
 +
<br/>            'UK Public Limited Company',
 +
<br/>        ],
 +
<br/>    ],
 +
<br/>];
 +
</div>
 +
 
 +
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 <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 customizations, if you wish to override the default requirements for a given field, use an override file.

Latest revision as of 16:07, 18 April 2022

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.

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:

  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. For more information, see Easy Translation.

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=32088"