Validators

From ISPWiki
Jump to: navigation, search

Introduction

Validators are special function of COREmanager that are used to validate data before thay are entered into the form (see Description of forms#Input fields).

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>

Where 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 the validator with a field, use the following attributes (see Description of forms#Input fields):

check
validator name without prefix
checkargs
arbitrary 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 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 comma separated):

case
do not convert symbols to lower-case
upper
convert all symbols to upper-case (if specified, it has higher priority than the case parameter)
digit
username size limit (the default value is 16)

E.g. (check that the string contains a valid user name 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 the maximum and the minimum value comma separated. One or both parameters can be omitted. For example (check the parameter value. It should be less than 100, the minimum value is not specified - or a negative number will be skipped):

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

You can specify one of the following data types as 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 are omitted in the range [-2,147,483,648 : +2,147,483,647]:

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

float

Similar to int, but for broken numbers.

The following data types can be specified as parameter:

  • float;
  • double.

alphanum

A value can contain the Latin alphabet letters, digits, symbols '-' and'_'. Cannot start and 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 specific class in parameter: v4 or v6. Example for IPv6 addresses:

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

net

Address of IP network in the format <address>/<mask>. 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 from the range 0 to 32, for IPv6 - 0 to 128.In the parameter you can specify a certain class: v4 or v6. An example of IPv4 network:

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

iprange

Range of IP addresses in one of the following formats:

<ip address>
a single address
<ip address> / <network mask>
network
<ip1 address> - <ip2 address>
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 specific 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
add a dot at the end of the name
allowlastdot
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.

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 from the range '0x20-0x7F'.

url

Uniform Resource Locator

<http>://<login>:<password>@<host>:<port>/<URL‐path>?<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 he field has the @checkpasswd attribute. It will set automatically, if other 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 set to yes.