Jet\Form

Přehled konstant

HTTP metody odeslání formuláře

Konstanta Význam
Form::METHOD_POST Formulář bude odeslán metodou POST - výchozí metoda
Form::METHOD_GET Formulář bude odeslán metodou GET

Druhy kódování formuláře

Konstanta Význam
Form::ENCTYPE_URL_ENCODED application/x-www-form-urlencoded
Form::ENCTYPE_FORM_DATA multipart/form-data
Form::ENCTYPE_TEXT_PLAIN text/plain

Přehled metod

Obecné

Obecné metody souvisí především s definicí formulářů.

Metoda Význam
public __construct(
string $name,
Form_Field[] $fields,
string $method=Form::METHOD_POST
) : 		Parametry:
  • $name
    Název formuláře.
  • $fields
    Formulářová pole.
  • $method
    HTTP metoda kterou bude formulář odesílán.
public setName(
string $name
) : void		 Umožňuje dodatečně změnit název formuláře.
public getName(
) : string		 Vrací název formuláře.
public getId(
) : string		 Vrací ID formuláře určené pro JavaScript a CSS.
public setMethod(
string $method
) : void		 Umožňuje změnit HTTP metodu kterou bude formulář odesílán (hodnoty: Form::METHOD_POST, nebo Form::METHOD_GET)
public getMethod(
) : string		 Vrací HTTP metodu, kterou bude formulář odesílán.
public setEnctype(
string $enctype
) : void		 Nastavuje kódování formuláře. Důležité zejména pro formuláře s nahráváním souborů.
Pozor! V praxi vlastně není třeba metodu extra používat, protože pole Jet\Form_Field_File a Jet\Form_Field_FileImage nastaví kódování formuláře automaticky.
public getEnctype(
) : string		 Vrátí nastavené kódování formuláře.
public setIsReadonly(
) : void		 Přepne formulář do režimu "pouze pro čtení". Takto jsou pak vykreslena formulářová pole a ani není možné provést zachycení a zpracování formuláře.
public getIsReadonly(
) : bool		 Indikuje zda je formulář v režimu "pouze pro čtení".
public setAction(
string $action
) : void		 Nastavuje akci formuláře. Tedy URL na kterou bude formulář odeslán.
public getAction(
) : string		 Vrací nastavuje akci formuláře. Tedy URL na kterou bude formulář odeslán.
public setTarget(
string $target
) : void		 Nastavuje cíl formuláře (např. _blank a podobně)
public getTarget(
) : string		 Vrací nastavený cíl formuláře (např. _blank a podobně)
public setAcceptCharset(
string $accept_charset
) : void		 Nastavuje atribut accept-charset.
public getAcceptCharset(
) : string		 Vrací nastavenou hodnotu atributu accept-charset.
public setNovalidate(
bool $novalidate
) : void		 Potlačuje (nebo opět povoluje) validaci formuláře již na straně prohlížeče - atribut novalidate.
public getNovalidate(
) : bool|null		 Indikuje zda je / není potlačena validaci formuláře již na straně prohlížeče - atribut novalidate.
public setAutocomplete(
bool $autocomplete
) : void		 Potlačuje (nebo opět povoluje) automatické doplňování formuláře na straně prohlížeče - atribut autocomplete.
public getAutocomplete(
) : bool		 Indikuje zda je / není potlačeno automatické doplňování formuláře na straně prohlížeče - atribut autocomplete.
public setSentKey(
string $sent_key
) : void		 Umožňuje změnit název skrytého pole indikujícího odeslání právě daného formuláře jen pro konkrétní formulář - pro jednu jeho instanci.

Název tohoto pole pro všechny formuláře je možné změnit pomoci systémové konfigurace SysConf_Jet_Form.
public getSentKey(
) : string		 Vrací název skrytého pole indikujícího odeslání právě daného formuláře platný pro konkrétní formulář.
public enableCSRFProtection(
) : void		 Zapne CSRF ochranu formuláře - do formuláře automaticky vloží pole s tokenem.
public getCSRFTokenField(
) : Form_Field|null		 Vrátí pole CSRF tokenu - pokud formulář takové pole obsahuje.

Práce s políčky

Práce s políčky rovněž souvisí především s definicí formulářů.

Metoda Význam
public setFields(
Form_Field[] $fields
) : void		 Nastaví naráz všechna pole. To znamená že pokud formulář již nějaká pole před voláním této metody měl, tak jsou tato odstraněna a jsou přidána ta pole, jejichž seznam je parametrem této metody.
public getFields(
bool $as_multidimensional_array=false
) : Form_Field[]		 Vrátí seznam všech polí, které formulář má. Pokud je parametr $as_multidimensional_array false, pak je vrácen běžný seznam.

Ovšem v kapitole o definici formulářů jsme si řekli, že formulářové prvky mohou být uspořádány do vícerozměrného pole a pro toto uspořádání se používá název v podobě cesty.

Pokud je uvedený parametr true, pak je právě toto zohledněno a již není vrácen běžný seznam polí, ale pole uspořádána do N rozměrného pole.

To znamená, že pole s názvem:
/content/cs_CZ/title
bude v navráceném seznamu polí zde:
$fields['content']['cs_CZ]['title'].
public getSubFormPrefixes(
): array		 Formulář se může být vygenerován tak, že bylo dohromady poskládáno několik formulářů z několika entit - z pravidla s hlavní entity a jejích subenentit. Typickým příkladem je například lokalizovaný obsah, kdy jednotlivé lokalizace tvoří instance subentity a klíče těchto subentit představují lokalizace.

Pro usnadnění zobrazení formulářů v takové situaci existuje tato metoda, která funguje následovně: <?= $form->field( 'date_time' ) ?>
        
<?php foreach( $form->getSubFormPrefixes('/localized') as $locale => $prefix ):
    $locale = new Locale($locale); ?>
    <legend><?= UI::flag( $locale ) ?> <?= $locale->getName() ?></legend>
    <?= $form->field( $prefix . 'title' ) ?>
    <?= $form->field( $prefix . 'annotation' ) ?>
    <?= $form->field( $prefix . 'text' ) ?>

<?php endforeach; ?>
public addField(
Form_Field $field
) : void		 Přidá do formuláře nové pole.
Pokud již pole se stejným názvem existovalo, tak je nahrazeno polem novým.
public getField(
string $name
) : Form_Field		 Vrací pole daného jména.
Pozor! Pokud takové pole neexistuje, tak je vyhozena výjimka.
public field(
string $name
) : Form_Field		 Alias metody getField pro kratší zápis často používaného volání.
public removeField(
string $field_name
) : void		 Odstraní pole daného jména z formuláře.
public fieldExists(
string $name
) : bool		 Indikuje zda formulář má pole daného jména.

Obecná zpráva formuláře

Velice často potřebujeme u formuláře zobrazit nějakou obecnou informační zprávu například po jeho odeslání. Může jít o informaci o úspěchu, nebo naopak nějaké obecné varování. Zpráva může být zobrazena společně s formulářem (viz dále), nebo využita jinak vaší aplikační logikou.

Metoda Význam
public setCommonMessage(
string $message
) : void		 Nastavuje obecnou zprávu formuláře určenou pro uživatele / klienta.
public getCommonMessage(
) : string		 Vrací obecnou zprávu formuláře určenou pro uživatele / klienta.

Zachycení a validace

Následuje přehled metod majících souvislost se zachycením a validací dat.

Metoda Význam
public catchInput(
array|Data_Array|null $input_data=null,
bool $force_catch=false
) : bool		 Zachytí vstupní data. Standardně z POST, nebo GET, ale není to podmínkou.

Parametry:
  • $input_data
    Vstupní data. Standardně automaticky POST, nebo GET (dle nastavené HTTP metody formuláře), ale je možné data předat jako parametr pocházející z libovolného zdroje. Pouze je nutné aby tato data měla podobu pole nebo instance Data_Array
  • $force_catch
    Vynutí zachycení formuláře i když na vstupu není pole / klíč indikující odeslání daného formuláře.
public validate(
) : bool		 Provede proces validace všech polí a vrátí výsledek (true pokud nebyla zaznamenána žádná chyba).
public setIsNotValid(
) : void		 Vnuceně přepne formulář do stavu "nevalidní".
public getIsValid(
) : bool		 Indikuje zda je formulář validní. Tedy zda byla zachycena data a ta úspěšně prošla validací.
public getValidationErrors(
) : Form_ValidationError[]		 Vrací seznam všech validačních chyb.

Práce se zachycenými daty

Tyto metody mají souvislost s prací se zachycenými daty a jejich předáním.

Metoda Význam
public getValues(
) : array|bool		 Pokud je formulář zachycen a je validní, tak vrátí hodnoty všech políček v podobě N rozměrného asociovaného pole.

Pokud formulář není validní, tak vrátí false.
public catchFieldValues(
) : bool		 Pokud je formulář zachycen a je validní, pak provede zachycení dat pomocí definovaných zachytávačů.

Pokud formulář není validní, tak vrátí false.
public catch(
) : bool		 Provede celou standardní sekvenci. Tedy: zachycení vstupu, validaci a volání zachytávačů.

Pokud kterýkoliv krok selže, pak vrátí false.

Překlad

Metody pro překladem formuláře nesmí chybět.

Metoda Význam
public _(
string $phrase,
array $data=[]
) : string		 Přeloží daný text dle nastavení formuláře. Metoda se primárně používá pro interní účely.
public setDoNotTranslateTexts(
bool $do_not_translate_texts
) : void		 Zapíná / vypíná příznak "nepřekládat". Tedy je možné překlad daného formuláře zcela vyřadit a žádné překlady neprovádět.
public getDoNotTranslateTexts(
) : bool		 Vrací stav příznaku "nepřekládat".
public setCustomTranslatorDictionary(
null|string $custom_translator_dictionary
) : void		 Nastavuje volitelný slovník překladače. Tedy jiný, než je ten aktuálně globálně platný.
public getCustomTranslatorDictionary(
) : null|string		 Vrací název volitelně nastaveného slovníku překladače.
public setCustomTranslatorLocale(
Locale|null $custom_translator_locale
) : void		 Nastavuje volitelnou lokalizaci překladače. Tedy jinou, než je ta aktuálně globálně platná.
public getCustomTranslatorLocale(
) : null|Locale		 Vrací volitelně nastavenou lokalizaci překladače.

Zobrazování

A na konec samozřejmě nesmí chybě zobrazování formulářů.

Metoda Význam
public renderer(
) : Form_Renderer_Form		 Přístup k rendereru začátku a konce formuláře pomocí něhož je parametry zobrazeného tagu formuláře dále nastavovat.
public start(
) : string		 Zabezpečí vygenerování HTML kódu začátku formuláře.

Prakticky se jedná o zkratku volání $form->renderer()->start();
public end(
) : string		 Zabezpečí vygenerování HTML kódu konce formuláře.

Prakticky se jedná o zkratku volání $form->renderer()->end();
public message(
) : Form_Renderer_Form_Message		 Přístup k rendereru obecné zprávy formuláře.

Prakticky se jedná o zkratku volání $form->renderer()->message();
Předchozí kapitola
Definice formulářů
Další kapitola
Jet\Form_Field
GitHub