Руководство для разработчиков

Валидаторы

Введение

Валидаторы - специальные функции CORE, которые могут быть использованы для проверки значении полей форм на этапе ввода (см. Описание форм ). Для полей ввода со свойством @zoom валидатор выполняется для каждой подстроки отдельно.

Разработчик может добавлять собственные валидаторы создавая наследников класса isp_api::CheckValue или создавая внешние обработчики, которые должны отдавать результат в следующем формате:

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

Где узел value содержит значение поля, оно может отличаться от оригинального. Например, вы можете перевести все символы в нижний регистр или привести запись к некому каноническому виду. Или ошибку, если значение не прошло проверку см. Ошибки

Запрос к валидатору может содержать следующие параметры:

value значение, которое необходимо проверить

args значение атрибута @checkargs

name имя параметра (используется для локализации сообщения об ошибке)

funcname имя функции-обработчика формы, из которой был вызван валидатор (используется для локализации сообщения об ошибке)

Для привязки валидатора к полю ввода используются следующие атрибуты (подробнее см. Описание форм):

check указывает имя валидатора без префикса

checkargs произвольная строка, которая будет передана в валидатор. Формат строки зависит от конкретного валидатора

Общие рекомендации

  • Имя функции-валидатора должно начинаться с префикса "check." (для наследников класса isp_api::CheckValue подставляется автоматически)
  • Валидатор должен пропускать пустое значение, как валидное. Для запрета пустых значений служит специальный атрибут @required
  • Допускается обрезание незначащих пробелов, как перед, так и после значения. Если после обрезания пробелов значение стало пустым, оно должно быть признано валидным.
  • Валидатор не должен проверять длинну значения, для этого есть параметр @maxlength. Правда, если вы собираетесь использовать валидатор для полей с @zoom, @maxlength ограничивает размер всего значения, в то время, как валидатор обрабатывает каждую подстроку отдельно.

Перечень валидаторов COREmanager

Далее приведен список валидаторов COREmanager, перечислены их параметры и дано краткое описание логики работы

username

Проверка имени пользователя. По умолчанию, пропускает только латиницу и цифры и печатные символы с кодами до 0x7e, кроме следующих: " ,\t:+&#%$^(){}[]!@~*?<>=|\\/\"'`". Переводит все буквы в нижний регистр. Имя не может начинаться или заканчиваться точкой. Также не может начинаться с символов '-' и '_'. Возможные значения параметров (через запятую может быть перечислено несколько параметров):

case не переводить символы в нижний регистр

upper перевести все символы в верхний регистр (если указан, перекрывает параметр case)

число ограничивает длинну имени заданным количеством символов (по умолчанию 16)

Например, "Проверить, что введенная строка - допустимое имя пользователя, длиной до 8 символов включительно. Значение будет переведено в верхний регистр):

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

int

Целое число. В качестве параметра можно задать минимально и максимально допустимое значения, разделенные запятой. Один или оба параметра могут быть пропущены. Например, "Проверить значение параметра, оно должно быть меньше 100, нижняя граница не определена - любое отрицательное число будет пропущено):

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

Также в качестве параметра возможно указать один из следующих типов данных (в скобках указаны типы данных в представлении языка C/C++):

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

В следующем примере будут пропущены значения в диапазоне [-2,147,483,648 : +2,147,483,647]:

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

float

Аналогично int, но для дробных чисел.

В качестве параметра возможно указывать следующие типы данных:

  • float;
  • double.

alphanum

Значение может содержать латинские буквы, цифры, символы '' и '_'. Не может начинаться с цифры и знака ''.

ip

Ip адрес. Значение будет преобразовано к каноническому виду. По умолчанию принимает как IPv4, так и IPv6 адреса. В параметре можно указать конкретный класс: v4 или v6. Например для IPv6 адресов:

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

net

Адрес IP сети в формате <адрес>/<маска>. Строка будет преобразована к каноническому виду. По умолчанию принимает сети IPv4 и IPv6. Для IPv4 сетей маска должна лежать в диапазоне от 0 до 32, для IPv6 - от 0 до 128. В параметре можно указать конкретный класс: v4 или v6. Например для сетей IPv4:

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

netmask

Маска подсети. По умолчанию принимает маски подсетей IPv4 и IPv6. Для IPv4-сетей маска должна лежать в диапазоне от 0 до 32, либо быть представлена маской в виде "255.255.255.0". Для IPv6-сетей маска должна лежать в диапазоне от 0 до 128. В параметре можно указать конкретный класс: v4 или v6. Например для сетей IPv4:

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

iprange

Диапазон IP адресов в одном из следующих форматов:

одиночный адрес / <маска сети> сеть - диапазон адресов от ip1 до ip2 включительно.

Строка будет преобразована к каноническому виду. По умолчанию принимает диапазоны как IPv4, так и IPv6 адресов. В параметре можно указать конкретный класс: v4 или v6.

domain

Полностью определённое имя домена. Пропускает доменные имена второго уровня и ниже. Все символы будут приведены в нижний регистр. Может принимать следующие параметры:

addlastdot добавлять точку после имени allowlastdot разрешить точку после имени allowaster разрешить использование '*.' в качестве имени первой части имени (Например: *.example.com)

По умолчанию точки после доменного имени будут удалены, символ '*' в имени - запрещен.

subdomain

Имя домена.

domainrecordname

Имя домена или имя реверсной зоны.

path

Имя файла или каталога. Если задан параметр filename, пропускает только имена файлов без указания каталога.

url

Единый указатель ресурсов в формате <схема>://<логин>:<пароль>@<хост>:<порт>/?<параметры>#<якорь>

email

Email адрес вида имя_ящика@доменное_имя

xml

Xml-документ.

date

Дата в формате 'Y-m-d'.

datetime

Дата и время в формате 'Y-m-d H:M:S'.

ascii

Печатные символы ASCII в диапазоне '0x20-0x7F'.

Специальный валидатор password

Проверка качества пароля. По умолчанию, панель принимает все пароли. Используя параметр PWStrength файла конфигурации панели, Вы можете задать минимально допустимое качество (дробное значение от 0 до 3). В качестве параметра вы можете передать абсолютное или относительное (указав перед значением '+' или '-') качество. Валидатор не надо задавать явно, если у поля есть атрибут @checkpasswd. В этом случае он подставляется автоматически, если не указан другой валидатор.

Данный валидатор реализован и на стороне сервера, и на стороне клиента (через javascript). Поэтому при редактировании полей с паролем никаких дополнительных запросов в панель не происходит.

Проверка уровня сложности пароля может быть отключена при работе через API. Для этого в запросе необходимо передать служебный параметр disablepasswordcheck со значением yes.