KT Field

Komponenta vám umožní snadnou a rychlou manipulaci s jednotlivými položky fieldů pro definovaný formulář. Díky jednotlivým typům fieldů a jejich nastavení se pro Vás stane vytváření formulářů snadnou a běžnou prací.

Logika práce s fieldy

Všechny fieldy mají stejného rodiče a je možné na ně používat stejné sady parametrů.
Některé fieldy je potřeba napřed naplnit daty (selecboxy, checkboxy a radiobutton).
Fieldy následně tvoří kolekci pro definovaný fieldset.

Jaké druhy fieldů jsou připraveny?

Text field – s možností dalších HTML 5 typů
Textarea
Hidden input
File
Selectbox
Checkbox
Radio
Slider – výběr čísla pomocí jQuery slideru
MultiSelect – multi výběr (na základě knihovny chosen)
SingleSelect – single výběr (na základě knihovny chosen)

Z těchto základních fieldů se následně skládají některé rozšiřující se fieldy.

Co vše je možné fieldu definovat?

Pro ukázku vlastností jsme zvolili Text field, tyto vlastnosti jsou však dostupné nad všemi fieldy.


$field->setId($id); // CSS ID Selektor

$field->setClasses($classes); // Array - nastaví CSS classy, které field bude mít

$field->addClass($class); // Do kolekcee CSS class přidá další položku

$field->setAttributes($attributes); // Array - nastaví kolekci všech atributů HTML elementu

$field->addAttribute($name, $value); // do kolekce HTML atributů přidá další položku

$field->setLabel($label); // Nastavení label (popisek) fieldu

$field->setName($name); // Nastaví název fieldu (jednoznační identifikátr v rámci kolekce

$field->setPlaceholder($placeholder); // Nastaví HTML5 attribut placeholder

$field->setToolTip($toolTip); // Nastaveí Tooltip attribute

$field->setUnit($unit); // Pro hromadný výpis dat nastaví jednotku fieldu (Kč, Kusy, Metry, Kw, atd.)

$field->setValue($value) // Nastavení hodnotu fieldu, který je vybrána nebo bude defaultně nastavena

$field->setId($id); // CSS ID Selektor

$field->setClasses($classes); // Array - nastaví CSS classy, které field bude mít

$field->addClass($class); // Do kolekcee CSS class přidá další položku

$field->setAttributes($attributes); // Array - nastaví kolekci všech atributů HTML elementu

$field->addAttribute($name, $value); // do kolekce HTML atributů přidá další položku

$field->setLabel($label); // Nastavení label (popisek) fieldu

$field->setName($name); // Nastaví název fieldu (jednoznační identifikátr v rámci kolekce

$field->setPlaceholder($placeholder); // Nastaví HTML5 attribut placeholder

$field->setToolTip($toolTip); // Nastaveí Tooltip attribute

$field->setUnit($unit); // Pro hromadný výpis dat nastaví jednotku fieldu (Kč, Kusy, Metry, Kw, atd.)

$field->setValue($value) // Nastavení hodnotu fieldu, který je vybrána nebo bude defaultně nastavena

Rozšířené vlastnosti fieldů

Některé z popsaných fieldů mají v rámci svého typu některé rozšiřené vlastnosti, které se vám mohou občas hodit. Pojďme se na ně nyní podívat.

KT_Text_Field

Jednou z významných vlastností Text fieldu je zadání jeho typu v rámci HTML5 vlastností. Ty nejzákladnější jsou připravené ve formě constant na samotném objektu.

KT_Text_Field::INPUT_DATE
KT_Text_Field::INPUT_NUMBER
KT_Text_Field::INPUT_PASSWORD
KT_Text_Field::INPUT_URL


$textField = new KT_Text_Field("nazev-fieldu", "popisek-fieldu");
$textField->setInputType(KT_Text_Field::INPUT_NUMBER;); // pro ukázku jsem zvolil type = number

$textField = new KT_Text_Field("nazev-fieldu", "popisek-fieldu");

$textField->setInputType(KT_Text_Field::INPUT_NUMBER;); // pro ukázku jsem zvolil type = number

KT_Textarea_Field

U Textarea není moc co vymýšlet, proto jsou zde dostupné jen dvě drobná rozšíření v podobě nastavení velikosti textareay.


$textarea = new KT_Textarea_Field( $fieldName, $label);
$textarea->setRows( 10 ); // nastaví attribute rows
$textarea->setCols( 10 ); // nastaví attribute cols

$textarea = new KT_Textarea_Field( $fieldName, $label);

$textarea->setRows( 10 ); // nastaví attribute rows

$textarea->setCols( 10 ); // nastaví attribute cols

KT_Slider_Field

V případě, že chceme po uživateli zadat číslo a chceme mu práci trochu usnadnit a mít vše efektivní, můžeme využít připravení Slider field, který pomocí tahu umožní uživateli vybrat číslo

$slider = new KT_Slider_Field( $fieldName, $label );
$slider->setMinValue(1) // Minimální hodnota slideru bude 1
     ->setMaxValue(100) // Maximální hodnota slideru bude 100
     ->setStep(5) // Každý krok slideru přidá 5
     ->setValue(1) // Výchozí hodnota bude 1

$slider = new KT_Slider_Field( $fieldName, $label );

$slider->setMinValue(1) // Minimální hodnota slideru bude 1

->setMaxValue(100) // Maximální hodnota slideru bude 100

->setStep(5) // Každý krok slideru přidá 5

->setValue(1) // Výchozí hodnota bude 1

Fieldy pro výběr z předem definovaných položek

KT_Select_Field, KT_Checkbox_Field, KT_Radio_Field

Všechny tyto fieldy umožňují výběr z předem definovaného pole hodnot, které jim nastavíte. Všechny tyto fieldy mají společného rodiče, v podobě KT_Options_Field_Base, která se stará právě o možnost přidat do fieldu data, která uživatel může následně zvolit nebo hromadně vybrat.

KT_Options_Field_Base



// Data musí být předána v této podobě
$data = array(
	"value-1" => "Výběr položky 1",
	"value-2" => "Výběr položky 2",
	"value-3" => "Výběr položky 3"
	// atd...
);
		
$select = new KT_Select_Field( $fieldName, $label);
$select->setOptionsData($data);
		
$checkbox = new KT_Checkbox_Field($fieldName, $label);
$checkbox->setOptionsData($data);
		
$radio = new KT_Radio_Field($fieldName, $label);
$radio->setOptionsData($data);

// Data musí být předána v této podobě

$data = array(

"value-1" => "Výběr položky 1",

"value-2" => "Výběr položky 2",

"value-3" => "Výběr položky 3"

// atd...

);

$select = new KT_Select_Field( $fieldName, $label);

$select->setOptionsData($data);

$checkbox = new KT_Checkbox_Field($fieldName, $label);

$checkbox->setOptionsData($data);

$radio = new KT_Radio_Field($fieldName, $label);

$radio->setOptionsData($data);

Protože mají všechny tři fieldy společného rodiče v podobě KT_Options_Field_Base, mají i stejné názvy funkcí, které jim data nastavují.

Data Managers

Protože ve WordPressu máme již připravenou určitou strukturu dat, FW myslí i na to, že budete potřebovat rychle a snadno tato data dávat na výběr uživatelům nebo správcům webových stránek. K tomu nám budou sloužit takzvané Data Managery.

Obecně platí, že do obecného data manageru lze přidat jakýkoliv obsah v podobě pole value => text. Pro představu a začátek má FW připravené data managery na nejpoužívanější obsah v rámci WordPressu.

Data Managery mají společného rodiče v podobě KT_Data_Manager_Base. Je tedy na vás, které Data Managery si založíte a rozšíříte pro vlastní potřebu.

Data Manager je součást KT_Options_Field_Base, je možné ho tedy nastavit i ostatním fieldům toho typu.

KT_Custom_Post_Type_Data_Manager

Data manager nám umožní přidat do Fieldu kolekci post_type – ať už Vámi definovaných, nebo co má již WordPress připravené.


$cptManager = new KT_Custom_Post_Data_Manager();
$cptManager->setQueryArgs(array(
	"post_type" => "car",
	"posts_per_page" => -1
	// parametry dle WP_Query
));
		
$select = new KT_Select_Field($fieldName, $label);
$select->setDataManager($cptManager);

// Nyní budou v selectu na výběr všechny post_type typu car

$cptManager = new KT_Custom_Post_Data_Manager();

$cptManager->setQueryArgs(array(

"post_type" => "car",

"posts_per_page" => -1

// parametry dle WP_Query

));

$select = new KT_Select_Field($fieldName, $label);

$select->setDataManager($cptManager);

// Nyní budou v selectu na výběr všechny post_type typu car

KT_Taxonomy_Data_Manager

Stejně jako výběr některého z post_type se velmi často využívá výběr některého z termu – ať už defaultní category, nebo Vámi definovaných Taxonomy.



$taxManager = new KT_Taxonomy_Data_Manager();
$taxManager->setTaxonomy("category");
		
$select = new KT_Select_Field($fieldName, $label);
$select->setDataManager($taxManager);

// Nyní budou v selectu všechny rubriky, které si uživatel založil

$taxManager = new KT_Taxonomy_Data_Manager();

$taxManager->setTaxonomy("category");

$select = new KT_Select_Field($fieldName, $label);

$select->setDataManager($taxManager);

// Nyní budou v selectu všechny rubriky, které si uživatel založil

KT_WP_User_Data_Manager

V případě, že je potřeba určit / vybrat uživatele, poslouží nám k tomu tento Data manager.



$userManager = new KT_WP_User_Data_Manager();
$userManager->setAllUserRoles(array("admin"));
		
$select = new KT_Select_Field($fieldName, $label);
$select->setDataManager($userManager);

// Nyní budou v selectu dostupní všichni uživateli s rolí admin

$userManager = new KT_WP_User_Data_Manager();

$userManager->setAllUserRoles(array("admin"));

$select = new KT_Select_Field($fieldName, $label);

$select->setDataManager($userManager);

// Nyní budou v selectu dostupní všichni uživateli s rolí admin

Sada fieldů na míru pro WordPress

Ze zkušeností programátorů je známo, že většina formulářů a fieldů se vytváří na straně adminstrace, aby mohl uživatel / správce webových stránek nějakým způsobem upravovat nebo editovat různé položky a nastavení. Proto má FW několik již připravených fieldů přesně pro tyto účely.

KT_Media_Field – výběr obrázku s knihovny médií (vrátí ID attachmentu)
KT_Page_Field – výběr z kolekce stránek
KT_Switch_Field – volba ANO / NE
KT_WP_User_Field – výběr uživatele
KT_WP_Nonce_Field – pro kontrolní mechanismus odesílané adresy

Práce s těmito fieldy je stejná jako se všemi ostatními. Mají již předem připravená data.

Validace

Za účelem validace formulářů – potažmo fieldů – je připraven objekt KT_Field_Validator, který provádí kontrolu základních informací. Validace probíhá na straně vyplněných HTML5 attributů, na straně prohlížeče v JS scriptu (jquery.form-validation.js) a nakonec na serveru.

Pro validaci formulářů na straně front-endu je potřeba přidat do stránky právě zmiňovaný script jquery.form-validation.js.

Nad každým fieldem je dostupná funkce addRule(), která nastavuje jeden z parametrů, který se má při odeslání formuláře kontrolovat.

addRule($validationType, $message, $param = null)

Validační prvek nám nabízí několik validačních typů, které jsou dostupné v podobě konstant na objektu KT_Field_Validator.

KT_Field_Validator::REQUIRED
KT_Field_Validator::EMAIL
KT_Field_Validator::FLOAT
KT_Field_Validator::INTEGER
KT_Field_Validator::LENGTH
KT_Field_Validator::MAX_LENGHT
KT_Field_Validator::MIN_LENGHT
KT_Field_Validator::MAX_NUMBER
KT_Field_Validator::MIN_NUMBER
KT_Field_Validator::RANGE
KT_Field_Validator::URL

Příklad validace

$field->addRule(KT_Field_Validator::REQUIRED, "Tento field musí být vyplněn");
$field->addRule(KT_Field_Validator::EMAIL, "Zadejte platnou emailovou adresu");
$field->addRule(KT_Field_Validator::FLOAT, "Musí být číslo včetně desetinné čárky");
$field->addRule(KT_Field_Validator::INTEGER, "Musí být celé číslo");
$field->addRule(KT_Field_Validator::LENGHT, "Musí mít přesně 5 znaků", 5);
$field->addRule(KT_Field_Validator::MAX_LENGHT, "Musí mít maximálně 5 znaků", 5);
$field->addRule(KT_Field_Validator::MIN_LENGHT, "Musí mít minimálně 5 znaků", 5);
$field->addRule(KT_Field_Validator::MAX_NUMBER, "Nesmí být vyšší než 5", 5);
$field->addRule(KT_Field_Validator::MIN_NUMBER, "Nesmí být nižší než 5", 5);
$field->addRule(KT_Field_Validator::RANGE, "Musí být v rozmezí 5 až 10", array( 5, 10 ));
$field->addRule(KT_Field_Validator::URL, "Musí být platné URL např.: http://www.domena.cz");

$field->addRule(KT_Field_Validator::REQUIRED, "Tento field musí být vyplněn");

$field->addRule(KT_Field_Validator::EMAIL, "Zadejte platnou emailovou adresu");

$field->addRule(KT_Field_Validator::FLOAT, "Musí být číslo včetně desetinné čárky");

$field->addRule(KT_Field_Validator::INTEGER, "Musí být celé číslo");

$field->addRule(KT_Field_Validator::LENGHT, "Musí mít přesně 5 znaků", 5);

$field->addRule(KT_Field_Validator::MAX_LENGHT, "Musí mít maximálně 5 znaků", 5);

$field->addRule(KT_Field_Validator::MIN_LENGHT, "Musí mít minimálně 5 znaků", 5);

$field->addRule(KT_Field_Validator::MAX_NUMBER, "Nesmí být vyšší než 5", 5);

$field->addRule(KT_Field_Validator::MIN_NUMBER, "Nesmí být nižší než 5", 5);

$field->addRule(KT_Field_Validator::RANGE, "Musí být v rozmezí 5 až 10", array( 5, 10 ));

$field->addRule(KT_Field_Validator::URL, "Musí být platné URL např.: http://www.domena.cz");