KT Forms

KT Forms nabízí snadné, rychlé a jednoduché vytváření HTML formulářů za pomocí předem definovaných vlastností a funkcí. Mají také navíc rozšířené možnosti propojení na WordPress, které vám umožní snadnou a rychlou manipulaci s daty, která jsou určena pro WordPress samotný. Probíhá také automaticky validace na straně HTML5 atributů, Javascriptu a nakonec i na straně serveru. Formuláře umožňují také snadný výpis dat, která jsou přiřazená nějaké lehké entitě.

Související komponenty

Logika práce s formuláři

KT_Form může mít definovaný jeden nebo více fieldsetů – KT_Form_Fieldset.
Formulář udržuje kolekci všech fieldsetů, která mu byla předána / definována.
Fieldset má následně definovanou sadu fieldů (KT_Field).

Obecně platí pravidlo, že se fieldsety definují ve vlastním configu modelu, kde je možné se na něj opakovaně dotazovat bez potřeby psát kód znovu.

Jak by vypadal jednoduchý formulář?

V první řadě si definujeme config našeho modelu, kam umístíme definici fieldsetu.


class KT_Car_Config {

	// Názevy (name) fieldů, které budeme posílat formulářem
 	// názvy by neměli obsahovat diakritiku, velká písmena, mezery a jiné speciální znaky
	// Jejich název bude použit pro uložení dat do DB
	const CAR_OPTIONS_FIELDSET = "kt-car-options-fieldset";
	const CAR_OPTIONS_PRICE = "kt-car-options-price";
	const CAR_OPTIONS_TYPE = "kt-car-options-type";
	const CAR_OPTIONS_MILEAGE = "kt-car-options-mileage";
	const CAR_OPTIONS_WITH_VAT = "kt-car-options-with-vat";
	
	public static function getCarOptionsFieldset(){
		$fieldset = new KT_Form_Fieldset(self::CAR_OPTIONS_FIELDSET);
		
		$fieldset->addText(self::CAR_OPTIONS_PRICE, __("Cena vozu", KT_DOMAIN))
			->setInputType(KT_Text_Field::INPUT_NUMBER)
			->addRule(KT_Field_Validator::INTEGER, __("Cena vozu musí být celé číslo", KT_DOMAIN))
			->addRule(KT_Field_Validator::REQUIRED, __("Musíte zadat cenu vozu", KT_DOMAIN))
			->addRule(KT_Field_Validator::MIN_NUMBER, __("Cena vozu musí být vyšší než 0",KT_DOMAIN ), 0);
		
		$carTypes = array(
			"suv" => "SUV",
			"family" => "Rodinné",
			"sport" => "Sportovní",
			"commercial" => "užitkový"
		);
		
		$fieldset->addSelect(self::CAR_OPTIONS_TYPE, __("Typ vozidla", KT_DOMAIN))
			->setOptionsData($carTypes);
		
		$fieldset->addText(self::CAR_OPTIONS_MILEAGE, __("Stav tachometru", KT_DOMAIN))
			->setInputType(KT_Text_Field::INPUT_NUMBER)
			->addRule(KT_Field_Validator::INTEGER, __("Stav musí být celé číslo", KT_DOMAIN))
			->addRule(KT_Field_Validator::MIN_NUMBER, __("Stav musí být vyšší než 0",KT_DOMAIN ), 0);
		
		$fieldset->addSwitch(self::CAR_OPTIONS_WITH_VAT, __("Odpis DPH", KT_DOMAIN))
			->setTooltip(__("Je u vozu možnost odpisu DPH?", KT_DOMAIN));
		
		return $fieldset;
		
	}
	
}

class KT_Car_Config {

// Názevy (name) fieldů, které budeme posílat formulářem

// názvy by neměli obsahovat diakritiku, velká písmena, mezery a jiné speciální znaky

// Jejich název bude použit pro uložení dat do DB

const CAR_OPTIONS_FIELDSET = "kt-car-options-fieldset";

const CAR_OPTIONS_PRICE = "kt-car-options-price";

const CAR_OPTIONS_TYPE = "kt-car-options-type";

const CAR_OPTIONS_MILEAGE = "kt-car-options-mileage";

const CAR_OPTIONS_WITH_VAT = "kt-car-options-with-vat";

public static function getCarOptionsFieldset(){

$fieldset = new KT_Form_Fieldset(self::CAR_OPTIONS_FIELDSET);

$fieldset->addText(self::CAR_OPTIONS_PRICE, __("Cena vozu", KT_DOMAIN))

->setInputType(KT_Text_Field::INPUT_NUMBER)

->addRule(KT_Field_Validator::INTEGER, __("Cena vozu musí být celé číslo", KT_DOMAIN))

->addRule(KT_Field_Validator::REQUIRED, __("Musíte zadat cenu vozu", KT_DOMAIN))

->addRule(KT_Field_Validator::MIN_NUMBER, __("Cena vozu musí být vyšší než 0",KT_DOMAIN ), 0);

$carTypes = array(

"suv" => "SUV",

"family" => "Rodinné",

"sport" => "Sportovní",

"commercial" => "užitkový"

);

$fieldset->addSelect(self::CAR_OPTIONS_TYPE, __("Typ vozidla", KT_DOMAIN))

->setOptionsData($carTypes);

$fieldset->addText(self::CAR_OPTIONS_MILEAGE, __("Stav tachometru", KT_DOMAIN))

->setInputType(KT_Text_Field::INPUT_NUMBER)

->addRule(KT_Field_Validator::INTEGER, __("Stav musí být celé číslo", KT_DOMAIN))

->addRule(KT_Field_Validator::MIN_NUMBER, __("Stav musí být vyšší než 0",KT_DOMAIN ), 0);

$fieldset->addSwitch(self::CAR_OPTIONS_WITH_VAT, __("Odpis DPH", KT_DOMAIN))

->setTooltip(__("Je u vozu možnost odpisu DPH?", KT_DOMAIN));

return $fieldset;

}

Nyní můžeme založit formulář


$form = new KT_Form(); // založíme nový objekt formuláře
$form->addFieldSetByObject(KT_Car_Config::getCarOptionsFieldset()); // Do formulář přidáme náš definovaný fieldset z configu
		
$form->validate(); // provedeme validaci formuláře

if( ! $form->hasError() ){
	// validace je v pořádku, můžeme data zpracovat
			
	return;
}
		
// ve formuláři jsou chyby, pokračujeme na výjimku

$form = new KT_Form(); // založíme nový objekt formuláře

$form->addFieldSetByObject(KT_Car_Config::getCarOptionsFieldset()); // Do formulář přidáme náš definovaný fieldset z configu

$form->validate(); // provedeme validaci formuláře

if( ! $form->hasError() ){

// validace je v pořádku, můžeme data zpracovat

return;

}

// ve formuláři jsou chyby, pokračujeme na výjimku

Nyní, když máme připravené zpracování formuláře, potřebujeme ho už jenom zpracovat, pro případnou editaci do něj načíst data a zároveň ho uživateli vykreslit.


$form = new KT_Form(); // založíme nový objekt formuláře
$form->addFieldSetByObject(KT_Car_Config::getCarOptionsFieldset()); // Do formulář přidáme náš definovaný fieldset z configu
		
$form->validate(); // provedeme validaci formuláře
		
if( ! $form->hasError()){
	$form->saveFieldsetToPostMeta($postId); // uložíme všechny data do wp_postemta na ID příspěvku
	$form->loadDataFromPostMeta($postId); // načteme do formuláře všechny data z wp_postmeta na ID příspěvku

	echo $form->getFormToHtml(); // vykreslíme formuláře do v prostém HTML

	return;
} 

// ve formuláři jsou chyby, pokračujeme na výjimku
return;

$form = new KT_Form(); // založíme nový objekt formuláře

$form->addFieldSetByObject(KT_Car_Config::getCarOptionsFieldset()); // Do formulář přidáme náš definovaný fieldset z configu

$form->validate(); // provedeme validaci formuláře

if( ! $form->hasError()){

$form->saveFieldsetToPostMeta($postId); // uložíme všechny data do wp_postemta na ID příspěvku

$form->loadDataFromPostMeta($postId); // načteme do formuláře všechny data z wp_postmeta na ID příspěvku

echo $form->getFormToHtml(); // vykreslíme formuláře do v prostém HTML

return;

}

// ve formuláři jsou chyby, pokračujeme na výjimku

return;

Nyní máme připravený základní formulář, který obsahuje několik inputů, dle naší definice. Nezapomeňte, že fieldsety se definují do souborů s configy. Nemělo by se Vám nikdy stát, že byste měli jeden zapsaný vícekrát než jednou na jednom místě. Struktura je navržena tak, abyste se na potřebné fieldy nebo samotné fieldsety dostali vždy z každé pozice kódu a části Vašeho projektu.

Formulář může udržovat jeden nebo celou kolekci fieldsetů. Validace, ukládání a načítání se provádí vždy nad celou kolekcí. Pokud potřebujete fieldsety a jejich zpracování rozdělit, je potřeba založit více formulářů.

Ukládání a načítání dat do formuláře

Stejně jako je možné uložit automaticky data poslané formulářem do příslušné části WordPressu, tak můžete využit i některé další funkce:

$form->saveFieldsetToOptionTable() – uloží data do WP_Options
$form->saveFieldsetToPostMeta( $postId ) – uloží data do WP_PostMetas
$form->saveFieldsetToUserMeta( $userId ) – uloží data do WP_UserMetas
$form->saveFieldsetToCommentMetaTable( $userId ) – uloží data do WP_CommentMetas
$form->saveFieldsetToTermMetaTable( $userId ) – uloží data do KT_TermMetas

Stejně, jako je potřeba data ukládat, je možné data na stejném principu načítat, k tomu nám slouží následující funkce:

$form->loadDataFromPostMeta( $postId )
$form->loadDataFromUserMeta( $userId )
$form->loadDataFromWpOption()
$form->loadDataFromCommentMeta()
$form->loadDataFromTermMeta()

Načítání i ukládání dat z formuláře probíhá na vazbě Input name => input value.

Ruční načtení dat

Občas bude nutné do formuláře dostat data ručně – mimo naše tabulky. Například z důvodu, že budeme chtít data kombinovat z více míst. Nezapomeňte, že celý formulář pracuje vždy s fieldsety. Je tedy nutné načítání dat do něj provádět přes tyto fieldsety.



// v tomto tvaru je nutné mít připravené data pro formulář
$formData = array(
	"nas-fieldset" => array(
		"nazev-inputu" => "Hodnota inputu",
		"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",
		"nejaky-selectbox" => 3
		// atd...
	),
	"nas-dalsi-fieldset" => array(
		"nazev-inputu" => "Hodnota inputu",
		"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",
		"nejaky-selectbox" => 3
		// atd...
	)
);
			
$form = new KT_Form();
$form->addFieldSetByObject(KT_Car_Config::getNasFieldset()); // přidáme fieldset do formuláře
$form->addFieldSetByObject(KT_Car_Config::getNasDalsiFieldset()); // přidáme druhý fieldset do formuláře
	
$form->setFormData($formData); // vložíme data do formuláře
$form->getFormToHtml(); // vykreslíme formulář

// v tomto tvaru je nutné mít připravené data pro formulář

$formData = array(

"nas-fieldset" => array(

"nazev-inputu" => "Hodnota inputu",

"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",

"nejaky-selectbox" => 3

// atd...

"nas-dalsi-fieldset" => array(

"nazev-inputu" => "Hodnota inputu",

"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",

"nejaky-selectbox" => 3

// atd...

)

);

$form = new KT_Form();

$form->addFieldSetByObject(KT_Car_Config::getNasFieldset()); // přidáme fieldset do formuláře

$form->addFieldSetByObject(KT_Car_Config::getNasDalsiFieldset()); // přidáme druhý fieldset do formuláře

$form->setFormData($formData); // vložíme data do formuláře

$form->getFormToHtml(); // vykreslíme formulář

Ruční načtení dat v postupném sledu

Někdy může být také potřeba, že budete do formuláře potřebovat přidávat fieldset postupně včetně jejich dat.



$form = new KT_Form();
			
$form->addFieldSetByObject(KT_Car_Config::getNasFieldset())
	->setFieldsData(array(
		"nazev-inputu" => "Hodnota inputu",
		"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",
		"nejaky-selectbox" => 3
		// atd...
	));
			
			
			
$form->addFieldSetByObject(KT_Car_Config::getNasDalsiFieldset())
	->setFieldsData(array(
		"nazev-inputu" => "Hodnota inputu",
		"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",
		"nejaky-selectbox" => 3
		// atd...
	));
			
// možná budete potřebovat data přepsat jinými.
			
$form->getFieldSetByName("nas-dalsi-fieldset")
	->setFieldsData(array( ... ));
			
$form->getFormToHtml();

$form = new KT_Form();

$form->addFieldSetByObject(KT_Car_Config::getNasFieldset())

->setFieldsData(array(

"nazev-inputu" => "Hodnota inputu",

"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",

"nejaky-selectbox" => 3

// atd...

));

$form->addFieldSetByObject(KT_Car_Config::getNasDalsiFieldset())

->setFieldsData(array(

"nazev-inputu" => "Hodnota inputu",

"nazev-dalsiho-inputu" => "Hodnota dalšího inputu",

"nejaky-selectbox" => 3

// atd...

));

// možná budete potřebovat data přepsat jinými.

$form->getFieldSetByName("nas-dalsi-fieldset")

->setFieldsData(array( ... ));

$form->getFormToHtml();

Pomocí prvku KT_WP_Nonce_Field je možné v rámci KT_Formu integrovat WP kontrolu odesílané adresy, tj. aby např. nešlo odesílat formuláře z externích serverů apod. Stačí si do formuláře, resp. fieldsetu přidat nonce prvek (metoda addWpNonce na KT_Fieldsetu) a pak je ještě třeba před nebo při zpracování formuláře volat metodu nonceValidate(), která zajistí samotnou kontrolu.

Obecné nastavení parametrů formuláře

Objekt formuláře udržuje také řadu parametrů, které je občas potřeba nastavit.



$form->setAction($action) // kam se mají data poslat - defaultně #
$form->setMethod($method) //GET nebo POST - defaulntě POST
$form->setFormClasses($formClasses) // nastaví CSS classu pro formulář
$form->setFormId($id) // nastaví CSS ID pro formulář
$form->setSuccessMessage($message) // Nastaví zprávu, která se vypíše, pokud data projdou validací
$form->setError($error) // Nastaví zprávu, která se vypíše, pokud validce nebyla splněna
$form->setButtonValue($value) // Nastaví text tlačítka pro odeslání
$form->setEnctype($enctype) // Nastaví enctype formuláře

$form->setAction($action) // kam se mají data poslat - defaultně #

$form->setMethod($method) //GET nebo POST - defaulntě POST

$form->setFormClasses($formClasses) // nastaví CSS classu pro formulář

$form->setFormId($id) // nastaví CSS ID pro formulář

$form->setSuccessMessage($message) // Nastaví zprávu, která se vypíše, pokud data projdou validací

$form->setError($error) // Nastaví zprávu, která se vypíše, pokud validce nebyla splněna

$form->setButtonValue($value) // Nastaví text tlačítka pro odeslání

$form->setEnctype($enctype) // Nastaví enctype formuláře

Nezapomeňte, že formulář má nastavené defaultní výchozí hodnoty. Nemusíte proto vždy nastavovat každý parametr, který formulář využívá.

Ruční vykreslení formuláře

Někdy je také nutné mít nad formulářem kontrolu a je potřeba vypisovat / poskládat si data ručně dle Vaší potřeby.


echo $form->getFormHeader(); // hlavička formuláře
			
echo $form->getFormNotice(); // vykreslení notifikace
			
echo $form->getFieldSetByName("nas-fieldset")
	->getInputsToTable();
			
// nejaké Vaš data nebo HTML
			
echo $form->getFieldSetByName("nas-dalsi-fieldset") 
	->getInputsToTable();
			
// vykreslení pouze jednoho fieldu z celéhé fieldsetu
echo $form->getFieldSetByName("nas-fieldset")
	->getFieldByName("nazev-naseho-fieldu")
	->getField();
			
echo $form->getSubmitButton();
echo $form->getEndForm();

echo $form->getFormHeader(); // hlavička formuláře

echo $form->getFormNotice(); // vykreslení notifikace

echo $form->getFieldSetByName("nas-fieldset")

->getInputsToTable();

// nejaké Vaš data nebo HTML

echo $form->getFieldSetByName("nas-dalsi-fieldset")

->getInputsToTable();

// vykreslení pouze jednoho fieldu z celéhé fieldsetu

echo $form->getFieldSetByName("nas-fieldset")

->getFieldByName("nazev-naseho-fieldu")

->getField();

echo $form->getSubmitButton();

echo $form->getEndForm();

arrayAccess

Formulář má zaveden arrayAcces pro snadnější přístup k instancím daných fieldů.

echo $form["nazev-naseho-fieldu"]->getField();

1	echo $form["nazev-naseho-fieldu"]->getField();

V případě, že chcete využívat arrayAcces je nutné nemít stejné názvy fieldů v kolekcích fieldsetů. ArrayAccess prochází jednotlivé kolekce fieldů na fieldsetech a v případě schody s názvem fieldů ho ihned vrací.