Validators

Introduction

Validators are special functions of COREmanager that are used to validate the values of form fields at the input stage (see the Description of forms article). For input fields with @zoom property validators are executed for each substring separately.

Developers can add custom validators by creating descendants of the isp_api::CheckValue class or external handlers that will output a result in the following format:

  
<doc stylesheet="validator">
  <value>TEST</value>
 </doc>

Here the value node contains a field value, which may differ from the original one. For example, you can use lower-case symbols or convert a record into a certain format. Or an error, if the value check failed (see Errors).

A call to the validator may contain the following parameters:

value - value to check

args - value of the @checkargs attribute

name - parameter name (it is used for localizing error messages)

funcname - name of the form's function-handler, from which the validator was called (it is used for localizing error messages)

To associate a validator with a field, use the following attributes:

check - validator name without prefix

checkargs - any name that will be passed to the validator. The string format depends on a validator.

General recommendations

The name of the validator-function should start with the "check" prefix (it is set automatically for descendants of the isp_api::CheckValue class).
The validator should consider empty values valid. To forbid empty values, use the @required attribute.
Insignificant spaces can be cut (both before and after the value). If the value will get empty after you have cut it, it should be considered valid.
The validator should not check the length of a value using the @maxlength parameter. However, if you are going to use the validator for fields with @zoom, @maxlength will limit the size of the whole value, while the validator processes every string separately.

List of COREmanager validators

The following is a list of COREmanager validators, their parameters, and a short description.

username

Username check. By default, only the Latin-alphabet letters, digits, and printable characters up to 0x7e are allowed, except for " ,\t:+&#%$^(){}[]!@~*?<>=|\\/\"'`". All the letters will be lower-cased. The name cannot start or end with a dot and the '-' or '_' symbols. Possible values (several parameters can be specified separated with a comma):

case - do not convert symbols to lower-case;

upper - convert all symbols to upper-case (if specified, it has a higher priority than the case parameter);

digit - username size limit (the default value is 16).

Example to check that the string contains a valid username up to 8 characters long, the value will be converted to upper-case:

<input type="text" name="name" check="username" checkargs="upper,8"/>

int

An integer. You can specify a maximum and a minimum value separated with a comma. One or both parameters can be omitted. For example, "check the parameter value, which should be less than 100, the minimum value is not specified, any negative number will be skipped":

<input type="text" name="sum" check="int" checkargs=",100"/>

You can specify one of the following data types as a parameter (data types in C/C++ are given in brackets):

int (int);
uint (unsigned int);
long (long long);
ulong (unsigned long long).

In the following example the values in the range [-2,147,483,648 : +2,147,483,647] are omitted:

<input type="text" name="sum" check="int" checkargs="int"/>

float

Similar to int, but for fraction numbers.

The following data types can be specified as a parameter:

float;
double.

alphanum

A value can contain Latin alphabet letters, digits, symbols '-' and '_'. Cannot start or end with a digit and the '-' sign.

ip

IP address. The value will be converted to a canonical way. By default, both IPv4 and IPv6 addresses are accepted. You can specify a certain class in the parameter: v4 or v6. An example for IPv6 addresses:

<input type="text" name="address" check="ip" checkargs="v6"/>

net

Address of IP network in the <address>/<mask> format. The value will be converted to a canonical form. By default both IPv4 and IPv6 networks are accepted. For IPv4 network, the mask should be in the range of 0 to 32, for IPv6 - of 0 to 128. You can specify a certain class in the parameter: v4 or v6. An example of IPv4 network:

<input type="text" name="network" check="net" checkargs="v4"/>

netmask

Subnet Mask. By default both IPv4 and IPv6 subnet masks are accepted. For IPv4 networks, the mask must be in the range of 0 to 32, or be represented by a mask in the form of “255.255.255.255.0”. For IPv6 networks, the mask must be in the range of 0 to 128. You can specify a certain class in the parameter: v4 or v6. For example, for IPv4 networks:

<input type="text" name="mask" check="netmask" checkargs="v4"/>

iprange

A range of IP addresses in one of the following formats:

a single address / <network mask> network - range of address ip1 to ip2 included.

The string will be converted to a conical form. By default, both IPv4 and IPv6 addresses can be used. You can specify a certain class in the parameter: v4 or v6.

domain

Fully qualified domain name. A second-level domain and higher. All the characters will be converted to lower-case. Possible values:

addlastdot - adds a dot at the end of the nameallowlastdot, allow a dot after the name allowaster, allow using '*.' as a name in the first part of the name (for example: *.example.com)

By default, dots after the domain name will be deleted, the '*' symbol in the name cannot be used.

subdomain

Domain name.

domainrecordname

Domain name or reverse zone name.

path

File or directory name. If the fullname parameter is specified, only file names without directory will be accepted.

A single resource index in the format <schema>://<login>:<password>@<host>:<port>/?<parameters>#<anchor>

email

Email address mailbox_name@domain_name

xml

Xml-document.

date

Date in the format 'Y-m-d'.

datetime

Date and time in the format 'Y-m-d H:M:S'.

ascii

ASCII printable characters in the range of '0x20-0x7F'.

url

Uniform Resource Locator in the format <scheme>://<login>:<password>@<host>:<port>/?<parameters>#<anchor>

Password validator

Password strength. By default, the control panel accepts any password. Specify the PWStrength parameter in the configuration file to set the minimum number of characters (a rational number 0 to 3). You can pass an absolute or relative (put '+' or '-' before the value) in the parameter. Do not specify the validator if the field has the @checkpasswd attribute. It will be set automatically in case another validator is not specified.

This validator is implemented both on server and client sides (through javascript). When editing fields with passwords, other calls to the control panel are not made.

Password strength check can be disabled when working through API. To disable, pass the disablepasswordcheck parameter with its value set to yes.

Developer Guide