Creating own validators for Web Forms fields

In this topic

Validator class structure

Validator is the class or set of functions with the following structure:

Due to inconvenience of handling several functions, it is recommended to unite them into a class (namespace). Further description and provided example will be based on this recommendation. The validator in the example, "Number within range" is realised as the class CFormCustomValidatorNumberEx.

Validator description

Validator description method is used to an associative array of the following structure:

Example:

function GetDescription()
{
  return array(
    "NAME"            => "custom_number_ex",                                   // identifier
    "DESCRIPTION"     => "Number within range",                                 // name
    "TYPES"           => array("text", "textarea"),                            // types of fields
    "SETTINGS"        => array("CFormCustomValidatorNumberEx", "GetSettings"), // method, returning the array of settings 
    "CONVERT_TO_DB"   => array("CFormCustomValidatorNumberEx", "ToDB"),        // method, converting an array of settings into a string 
    "CONVERT_FROM_DB" => array("CFormCustomValidatorNumberEx", "FromDB"),      // method, converting settings string into an array 
    "HANDLER"         => array("CFormCustomValidatorNumberEx", "DoValidate")   // validator
  );
}

Validator parameters

Method, set by the element SETTINGS, must return an array of elements of type:

"parameter_name" => array(
	"TITLE"   => "parameter_title",
	"TYPE"    => "parameter_type",
	"DEFAULT" => "default_value",
	"VALUES"  => array(
		"value1" => "value_name1",
		"value2 " => "value_name2",
		"value3 " => "value_name3"
	)
)

Example:

function GetSettings()
{
  return array(
    "NUMBER_FROM" => array(
      "TITLE"   => "Number lower threshold",
      "TYPE"    => "TEXT",
      "DEFAULT" => "0",
    ),
    
    "NUMBER_TO" => array(
      "TITLE"   => "Number upper threshold",
      "TYPE"    => "TEXT",
      "DEFAULT" => "100",
    ),
    
    "NUMBER_FLOAT" => array(
      "TITLE"   => "Floating number",
      "TYPE"    => "CHECKBOX",
      "DEFAULT" => "Y",
    ),
  );
}

Parameter processing

Processing of validator parameters requires two methods, set in the description by the parameters CONVERT_TO_DB and CONVERT_FROM_DB. The first parameter receives an array of values on input and must return their string representation. The second parameter performs reverse conversion. Both methods can also perform random manipulations with parameter values.

Example:

function ToDB($arParams)
{
  // check of passed parameters 
  $arParams["NUMBER_FLOAT"] = $arParams["NUMBER_FLOAT"] == "Y" ? "Y" : "N";
  $arParams["NUMBER_FROM"]  = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_FROM"]) : intval($arParams["NUMBER_FROM"]);
  $arParams["NUMBER_TO"]    = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_TO"]) : intval($arParams["NUMBER_TO"]);
  
  // switch of threshold values, if required 
  if ($arParams["NUMBER_FROM"] > $arParams["NUMBER_TO"])
  {
    $tmp                     = $arParams["NUMBER_FROM"];
    $arParams["NUMBER_FROM"] = $arParams["NUMBER_TO"];
    $arParams["NUMBER_TO"]   = $tmp;
  }
  
  // return serialised string
  return serialize($arParams);
}

function FromDB($strParams)
{
  // no conversions required, just return unserialized array
  return unserialize($strParams);
}

Validator

Main method receives 4 parameters on input: validator parameters array, question parameters array, question answers array and answer values array. It must return true on successful value validation and false otherise. Error description is returned via CMain::ThrowException(). Error description can use the template #FIELD_NAME# to retrieve a field name, experiencing error.

Example:

function DoValidate($arParams, $arQuestion, $arAnswers, $arValues)
{
  global $APPLICATION;
  
  foreach ($arValues as $value)
  {
	// skip empty values 
    if (strlen($value) <= 0) continue;
    
    // Bring value to an integer
    $value = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($value) : intval($value);
    
    // check the integer lower threshold  
    if (strlen($arParams["NUMBER_FROM"]) > 0 && $value < intval($arParams["NUMBER_FROM"]))
    {
	  // return an error
      $APPLICATION->ThrowException("#FIELD_NAME#: value too small");
      return false;
    }
    
    // check the integer upper value 
    if (strlen($arParams["NUMBER_TO"]) > 0 && $value > intval($arParams["NUMBER_TO"]))
    {
	  // return an error  
      $APPLICATION->ThrowException("#FIELD_NAME#: value too large");
      return false;
    }
  }
  
  // all values are validated, return true
  return true;
}

Attention: when processing field values of listed types (dropdown, multiselect, radio, checkbox) the validator will receive array of selected answers IDs on input.

Validator integration

Validator class must be connected in any place, where it will be available from the Control Panel and in the public section (see details at page execution sequence, for example, in /bitrix/php_interface/init.php (please be advised, that CModule::IncludeModule("form"); will connect the webform module everywhere at all times.). Directly, the validator file can be located anywhere - for example in /bitrix/php_interface/include/form/validators/. Connecting validator is performed by installing the validator description function as the event handler onFormValidatorBuildList.

Example

Summarizing all of the above, create the validator. Validator class is located in the file /bitrix/php_interface/include/form/validators/val_num_ex.php

<?
// File listing /bitrix/php_interface/include/form/validators/val_num_ex.php

class CFormCustomValidatorNumberEx
{
  function GetDescription()
  {
    return array(
      "NAME"            => "custom_number_ex",                                   // identifier
      "DESCRIPTION"     => "Floating number ",                                 // name
      "TYPES"           => array("text", "textarea"),                            // field types
      "SETTINGS"        => array("CFormCustomValidatorNumberEx", "GetSettings"), // method returning a settings array
      "CONVERT_TO_DB"   => array("CFormCustomValidatorNumberEx", "ToDB"),        // method converting a settings array into string  
      "CONVERT_FROM_DB" => array("CFormCustomValidatorNumberEx", "FromDB"),      // method converting settings string into an array   
      "HANDLER"         => array("CFormCustomValidatorNumberEx", "DoValidate")   // validator
    );
  }

  function GetSettings()
  {
    return array(
      "NUMBER_FROM" => array(
        "TITLE"   => "Number lower threshold",
        "TYPE"    => "TEXT",
        "DEFAULT" => "0",
      ),

      "NUMBER_TO" => array(
        "TITLE"   => "Number upper threshold",
        "TYPE"    => "TEXT",
        "DEFAULT" => "100",
      ),
      
      "NUMBER_FLOAT" => array(
        "TITLE"   => "Floating number",
        "TYPE"    => "CHECKBOX",
        "DEFAULT" => "Y",
      ),
    );
  }

  function ToDB($arParams)
  {
    // check of passed parameters 
    $arParams["NUMBER_FLOAT"] = $arParams["NUMBER_FLOAT"] == "Y" ? "Y" : "N";
    $arParams["NUMBER_FROM"]  = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_FROM"]) : intval($arParams["NUMBER_FROM"]);
    $arParams["NUMBER_TO"]    = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_TO"]) : intval($arParams["NUMBER_TO"]);
    
    // switch of threshold values, if required 
    if ($arParams["NUMBER_FROM"] > $arParams["NUMBER_TO"])
    {
      $tmp                     = $arParams["NUMBER_FROM"];
      $arParams["NUMBER_FROM"] = $arParams["NUMBER_TO"];
      $arParams["NUMBER_TO"]   = $tmp;
    }
    
    // return serialized string 
    return serialize($arParams);
  }

  function FromDB($strParams)
  {
    // no conversions required, just return unserialized array 
    return unserialize($strParams);
  }
	
  function DoValidate($arParams, $arQuestion, $arAnswers, $arValues)
  {
    global $APPLICATION;
    
    foreach ($arValues as $value)
    {
      // skip empty values 
      if (strlen($value) <= 0) continue;
      
      // bring value to an integer 
      $value = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($value) : intval($value);
      
      // check number lower threshold 
      if (strlen($arParams["NUMBER_FROM"]) > 0 && $value < intval($arParams["NUMBER_FROM"]))
      {
        // return error
        $APPLICATION->ThrowException("#FIELD_NAME#: value too small");
        return false;
      }
      
      // check number upper threshold
      if (strlen($arParams["NUMBER_TO"]) > 0 && $value > intval($arParams["NUMBER_TO"]))
      {
        // return error
        $APPLICATION->ThrowException("#FIELD_NAME#: value too large");
        return false;
      }
    }
    
    // all values are validated, return true
    return true;
  }
}

// install method CFormCustomValidatorNumberEx as the event handler 
AddEventHandler("form", "onFormValidatorBuildList", array("CFormCustomValidatorNumberEx", "GetDescription"));
?>

After that, only insert into /bitrix/php_interface/init.php the string

include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/include/form/validators/val_num_ex.php");

See Also