10. diel - FormControl - Predok pre formulárové kontrolky v PHP

V minulej lekcii, Tvorba formulárového frameworku v PHP - HtmlBuilder , sme si vytvorili HTML builder pre ľahké generovanie krátkych úsekov HTML. V dnešnom dieli vytvoríme abstraktné triedu FormControl, ktorá bude slúžiť ako predok pre konkrétny kontrolky formulára (napr. Pre TextBox).

FormControl

Ako už bolo povedané, trieda FormControl bude predkom pre všetky formulárové prvky. Bude obsahovať najmä mechanizmus validáciou a niekoľko spoločných vlastností a metód, aby sa s kontrolkami mohlo pracovať pomocou rovnakého rozhrania. Pripravme si teda prázdnu triedu:

abstract class FormControl
{

}

Spoločné vlastnosti

Začnime jednoducho. Každá kontrolka bude mať nejaký názov, popis a HTML atribúty. Do triedy tieto vlastnosti pridáme a napíšeme pre nich konštruktor:

public $label;
public $htmlParams = array();
public $name;

public function __construct($name, $label = '', $htmlParams = array())
{
    $this->name = $name;
    $this->label = $label;
    $this->htmlParams = $htmlParams;
    $this->htmlParams['name'] = $name;
    $this->htmlParams['id'] = $name;
}

Meno a id kontrolky rovno nastavíme do jej HTML parametrov. To sú HTML atribúty, ktoré sa k elementu pri renderovaní (prevode do HTML kódu) pridajú.

Keď sme pri tých jednoduchých vlastností, pridajme ešte setter na vlastnosť tooltip. To je text, ktorý sa zobrazí keď na kontrolku nabehnete myšou, stačí ho len nastaviť do HTML atribútu title. Typicky obsahuje nápovedu čo do poľa zadať:

public function setTooltip($toolTip)
{
    $this->htmlParams['title'] = $toolTip;
    return $this;
}

Getter a setter sa v PHP oproti napr. Jave príliš nepoužívajú. V tomto prípade však zohrávajú dôležitú úlohu. Setter vracia inštanciu FormControl, budú to tak robiť všetky setter. Keď budeme kontrolkám nastavovať nejaké vlastnosti, museli by sme to bez setter urobiť nasledujúcim štýlom:

$jmenoBox = $form->addTextBox('jmeno', 'Jméno', true);
$jmenoBox->toolTip = 'Zadejte své celé jméno';
$jmenoBox->text = 'Jan Novák';

Vďaka tomu, že Setter vracia inštanciu, na ktoré je metóda volaná, môžeme na ňu zas zavolať ďalšiu metódu a tak je krásne reťaziť. Kód vyššie môžeme teda zapísať takto:

$form->addTextBox('jmeno', 'Jméno', true)
     ->setToolTip('Zadejte své celé jméno')
     ->setText('Jan Novák');

Iste uznáte, že tento variant je oveľa čitateľnejšie a pretože definície formulárov budú obsiahlejšie, tak na kompaktnosti kódu veľmi záleží.

Pridajme kontrolke ešte metódu, ktorá k nej priradí nejakú CSS triedu. Musíme počítať aj s tým, že už nejakú má.

public function addClass($class)
{
    if (isset($this->htmlParams['class']))
        $this->htmlParams['class'] .= ' ' . $class;
    else
        $this->htmlParams['class'] = $class;
}

Validácia

Prejdime k validačný časti triedy, ktorá je bezpochyby tá najdôležitejšia.

Validačné pravidlá

Validácia formulárových polí budeme realizovať tak, že bude možné každému poli pridať niekoľko validačných pravidiel. Preto pridáme kolekciu $ rules:

private $rules = array();

Jednotlivé pravidlá budú napr. Pravidlo povinného poľa, pravidlo regulárneho výrazu, pravidlo pre heslo a podobne. Po odoslaní formulára sa každé kontrolke overia jej pravidlá a to ako na klientovi, tak na serveri.

Jednotlivé pravidlá alebo validator, ak chcete, som sa rozhodol realizovať priamo vo vnútri triedy FormControl a to pomocou jednoduchých metód. Ďalším prístupom by bolo oddeliť každé pravidlo do samostatnej triedy, ale triedy by boli tak jednoduché a podobné, že mi to prišlo ako príliš vysoká granularita. Druhý prístup viac tried som naopak zvolil ďalej u konkrétnych kontroliek formulára.

Konštanty

Jednotlivé pravidlá budeme rozlišovať pomocou konštánt, pridajme si ich:

const RULE_REQUIRED = 0;
const RULE_MAX_LENGTH = 1;
const RULE_PASSWORD = 2;
const RULE_DATETIME = 3;
const RULE_PATTERN = 4;
const RULE_REQUIRED_FILE = 5;

Podľa názvu iste spoznáte, čo ktoré pravidlo overuje. Ďalšie pravidlá možno zostaviť rôznymi kombináciami.

Pridávanie pravidiel

Každé pravidlo bude reprezentované ako asociatívne pole. K ich pridanie do kolekcie $ rules si vytvoríme privátne metódu:

private function addRule($rule, $validateClient, $validateServer)
{
    $rule['validate_client'] = $validateClient;
    $rule['validate_server'] = $validateServer;
    $this->rules[] = $rule;
    return $this;
}

Metóda berie pole, ktoré obsahuje dáta pravidlá. Ďalšie dva parametre označujú, či sa má pravidlo kontrolovať na klientovi a na serveri. Pravidlu pridáme tieto vlastnosti podľa parametrov a uložíme ho do kolekcie. Za účelom dodržania prístupu setter vrátime inštanciu.

Pravidlo povinného poľa

Pridajme metódu, ktorá kontrolke pridá pravidlo povinného poľa:

public function addRequiredRule($validateClient = true, $validateServer = true)
{
    return $this->addRule(array(
        'type' => self::RULE_REQUIRED,
        'message' => 'Povinné pole',
    ), $validateClient, $validateServer);
}

Metóda vyrobí pole s pravidlom. Každé pravidlo bude vždy obsahovať kľúč "type" s typom pravidlá a potom kľúč "message" s chybovým hlásením. Tá sa zobrazí v prípade, že pravidlo nebude splnené, tu teda keď je miesto prázdne alebo úplne chýba. Pravidlo (pole) pridáme pomocou privátnej metódy do kolekcie $ rules.

Rovnakým spôsobom vytvoríme ďalšie metódy na pridanie pravidiel ďalších typov.

Pravidlo maximálnej dĺžky

Pravidlo maximálnej dĺžky sa neskôr na klientovi preloží na atribút Maxlength. Bude vyzerať nasledovne:

public function addMaxLengthRule($maxLength, $validateClient = true, $validateServer = true)
{
    return $this->addRule(array(
        'type' => self::RULE_MAX_LENGTH,
        'max_length' => $maxLength,
        'message' => 'Maximální délka hodnoty je ' . $maxLength,
    ), $validateClient, $validateServer);
}

Pravidlo pre regulárny výraz

Úplne kľúčové pravidlo pre nás bude pravidlo potvrdzujúce hodnotu poľa regulárnym výrazom.

public function addPatternRule($pattern, $validateClient = true, $validateServer = true)
{
    return $this->addRule(array(
        'type' => self::RULE_PATTERN,
        'pattern' => $pattern,
        'message' => 'Hodnota má nesprávný formát',
    ), $validateClient, $validateServer);
}

Pravidlo budeme hojne používať v ďalších pravidlách. Do triedy si pridáme niekoľko konštánt pre najpoužívanejšie regulárne výrazy:

const PATTERN_URL = '(http|https)://.*';
const PATTERN_INTEGER = '[0-9]+';
const PATTERN_EMAIL = '[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,4}$';

Pravidlá budeme písať bez striešky na začiatku a dolára na konci (^ a $), pridajú sa tam neskôr automaticky. V budúcej lekcii, Dokončenie triedy FormControl v PHP , triedu dokončíme pridaním najmä metód pre zvyšná pravidlá a tiež metódy na ich zhodnotenie.