PHP Jet - Formuláře

Úvod

Vítám vás u dalšího článku :-) V dnešním příspěvku si ukážeme jak je v PHP Jet řešena práce s formuláři.

Když tvoříme aplikace jako jsou různé administrace, informační systémy, ale i REST (či jiné) API (ano, Jet Form se používá i v REST API – ukážeme si) tak formuláře jsou vlastně středobodem aplikace.

Formuláře v PHP Jet jsou věc, která prošla velkou evolucí. Zkusil jsem několik cest jak problematiku řešit, až jsem dospěl k současnému řešení, se kterým jsem opravdu spokojený a které by mohlo posloužiti vám.

Problematiku si rozdělíme na následující okruhy:

• Obecná definice formulářů
• Zobrazování formulářů
• Zachytávání a validace dat
• Formuláře definované třídou a „naklikané“ v Jet Studiu
• Použití formulářů v REST API
• Napojení formulářů na překladač a lokalizovatelnost
• Na konci článku si vytvoříme z nuly jednoduchý kontaktní formulář (video)
• A na úplný závěr pár stručných informací co je kolem PHP Jet obecně nového

Definice formulářů

Účelem subsystému formulářů v PHP Jet je formulář zpracovávat ve smyslu zachycení a validace dat, ale rovněž formuláře i zobrazovat. Ale to jsou dvě rozdílné (i když propojené) věci. Ovšem vždy je nutné formulář nějak definovat a na základě této definice následně probíhá jak zachytávání a validace dat a práce s chybami, tak zobrazení formuláře.

Definici formuláře představuje instance třídy Form a definice jednotlivých formulářových polí jsou pak instance tříd Form_Field_*, které reprezentují jednotlivé typy formulářových polí a vstupních dat.

Definice zahrnuje vše co je nutné o formuláři a jeho polích vědět. To znamená vše od názvů polí, výchozí hodnoty, popisky a nápovědu, přes definice chybových hlášek pro různé chybové stavy až po vlastní validátory a zachytávače hodnot. 

Zde je příklad definice formuláře s jedním polem. Pole je povinné, má definované vlastní doplňkový validátor, chybové hlášení a definice je připravená dále pracovat se zachycenou validní hodnotou:

use Jet\Form;
use Jet\Form_Field_Input;

$name_field = new Form_Field_Input(
    name: 'name',
    label: 'Vaše jméno:'
);

$name_field->setIsRequired( true );

$name_field->setErrorMessages([
    Form_Field_Input::ERROR_CODE_EMPTY => 'Prosím zadejte vaše jméno',
    'too_short' => 'Minimální délka jména jsou 3 znaky. Zadané jméno má %curr_len%'
]);

$name_field->setDefaultValue( 'Jára Cimrman' );

$name_field->setValidator(
function( Form_Field_Input $field ) : bool  {
    if(strlen($field->getValue())<3) {
        $field->setError('too_short', [
            'curr_len' => strlen($field->getValue())
        ]);
        return false;
    }

    return true;
});

$name_field->setFieldValueCatcher( function( string $value ) : void
{
    //TODO: Něco udělat se zachycenou a validní hodnotou
    echo $value;
});

$form = new Form( name: 'example_form', fields: [
    $name_field
] );

A pozor! Toto není jediný způsob jak formulář definovat a v praxi je to také ten méně častý. Jak si ukážeme hlavně ve videu, definice formuláře může být vázána na třídu a může být „naklikána“ v Jet Studiu. Ale to zatím nechme být. Pro objasnění principu je nutné začít touto ruční definicí, která je v uvedeném příklad. Ostatně i tento způsob je možné používat a někdy je to i vhodnější cesta.

Zobrazení formulářů

Když už máme formulář definovaný, pak je dobré jej také zobrazit. To se dělá velice jednoduše takto:

<?=$form->start()?>
    <?=$form->field('name')?>
<?=$form->end()?>

Je důležité zdůraznit, že podoba formuláře (v ukázkové aplikaci využívající Bootstrap) není vůbec pevně dána a do PHP Jet není jakkoliv zabudována. Jet nabízí pouze abstraktní model rendererů který je pomyslným mostem mezi vaším view, které takto jednoduše zobrazí formulář a obecnými view, které definici formuláře a rendereru formuláře převedou vše již na konkrétní HTML.

Skutečná view, která formulářová pole převedou na jejich konkrétní vizuální podobu najdete v rámci ukázkové aplikace v těchto adresářích:

• ~/application/bases/admin/views/form
• ~/application/bases/web/views/form
• ~/_tools/studio/application/views/form
• ~/_installer/views/form

Právě tam najdete view skripty využívající Bootstrap. A ano, ve všech těchto adresářích jsou skripty prakticky totožné. Teoreticky by mohly být na jednom místě, ale po pečlivém zvážení jsme to raději udělal takto, aby bylo možné ihned začít vše upravovat a zároveň aby se nic nerozbilo. 

Protože například pro administraci budete chtít zachovat Bootstrap (příklad – nemusíte, udělejte to jak chcete), ale pro web, či e-shop si uděláte něco vlastního. A co takové Jet Studio? To určitě potřebuje, aby mu na formuláře nikdo nesahal. A to samé instalátor. Tedy to že najdete na několika místech totéž není chyba, ale záměr a má to svou logiku.

Ostatně račte si to upravit jak libo. To kde má systém formulářů hledat své view je věc, kterou je tak jako tak nutné nastavit. A provádí se to například v inicializátorech bází:

namespace JetApplication;

//...
use Jet\SysConf_Jet_Form;
//...

class Application_Web
{
    //...

    public static function init( MVC_Router $router ): void
    {
        //...
        SysConf_Jet_Form::setDefaultViewsDir( $router->getBase()->getViewsPath() . 'form/' );
        //...
    }
    //...
}

A teď zpět k zobrazení. Pochopitelně by nestačilo pouze vypisovat něco již pevně daného, bez možnosti flexibility. Formulářové prvky je nutné dále modifikovat a donastavovat. A to také systém zobrazení formulářů umí. 

Zobrazení prvků je možné všemožně ovlivňovat, přidávat CSS třídy a styly, JavaScript, volitelné atributy HTML tagů a tak dále. Je to velice obsáhlé téma a je nutné „mrknout“ do dokumentace a pohrát si s ukázkovou aplikací. Ale opět stačí pochopit princip a pak už by to mělo být intuitivní. Jeden příklad si ukažme. 

Co takhle řádek s políčkem jméno udělat poloprůhledný? Není problém:

<?php
$form->field('name')->row()->addCustomCssStyle('opacity: 0.5');
?>
<?=$form->start()?>
    <?=$form->field('name')?>
<?=$form->end()?>

Zachytávání a validace dat

Na validaci a zachycení jednotlivého pole jsme již narazili hned v úvodním příklad. Ukažme si teď ještě názorně zachycení a validaci celého formuláře.

Zachycení samotného formuláře se provádí takto:

if(
    $form->catchInput() && //Formulář byl odeslán a je zachycen
    $form->getIsValid() //Formulář byl zvalidován a všechna pole jsou validní
) {

    /*
     * Vrátí všechny hodnoty formuláře v podobě asocciovaného pole
     *
     * V praxi velmi málo používané, ale možné
     */
    var_dump( $form->getValues() );


    /*
     * Získání zachycené hodnoty konkrétního pole
     */
    $form->field('name')->getValue();


    /*
     * Zavolá všechny definované zachytávače hodnot všech polí a postará se tak o předání hodnot na určená místa
     *
     * V praxi používané nejčastěji
     */
    $form->catchFieldValues();

}

Jak uvádím v příkladu, tak v praxi se nejčastěji používá systém zachytávačů hodnot, protože nejčastější je asociace definice formuláře na třídu. To je také nejpohodlnější způsob jak formuláře používat a prakticky si jej ukážeme ve videu.

Při tomto způsobu použití (když je formulář namapován na třídu – ukážeme si v zápětí) stačí při zachycení postupovat takto:

if( $form->catch() ) {
    /*
     * Formulář je odeslán, zachycen, zvalidován.
     * Jeho validní hodnoty jsou již předány na místo určení.
     */
}

Formuláře definované třídou a „naklikané“ v Jet Studiu

Jak jsme již zmínil, tak nejčastější způsob použití formuláře je jeho definice nějakou třídou a napojení na tuto třídu.

V praxi to znamená, že definované vlastnosti třídy tvoří zároveň formulářová pole a tato pole po validaci předají své hodnoty těmto vlastnostem v rámci instance této třídy.

Právě takto je tvořena většina ukázkové aplikace. Právě takto funguje i napojení formuláře na entity v rámci ORM (například ukázkové mikro CMS a administrace), ale i konfigurační entity (ty formuláře, co vyplňujete při instalaci) a tak dále. 

Jde o to, že právě díky tomuto konceptu je možné odstranit velké množství otravné rutinní práce a zároveň zachovat jednoduchost.

Definici formuláře a napojení na formulář může představovat jakákoliv třída. Stačí pouze, když implementuje potřebné rozhraní, použije určený trait a ty vlastnosti tříd předurčené k namapování na formulář mají potřebné definice. A pochopitelně nesmí chybět samotné vytvoření definice konkrétního formuláře, respektive formulářů – složitější entity mohou mít více různých formulářů. Zde je malý příklad, ale lépe si vše ukážeme ve videu, které opravdu vřele doporučuji. 

Teď zatím textový příklad:

namespace JetApplicationModule\ContactForm;

use Jet\Form;
use Jet\Form_Definition_Interface;
use Jet\Form_Definition_Trait;
use Jet\Form_Field;
use Jet\Form_Definition;

class ContactForm implements Form_Definition_Interface
{
    use Form_Definition_Trait;

    #[Form_Definition(
        type: Form_Field::TYPE_INPUT,
        label: 'Vaše jméno:',
        is_required: true,
        error_messages: [
            Form_Field::ERROR_CODE_EMPTY => 'Prosím zadejte Vaše jméno'
        ]
    )]
    protected string $from_name = '';

    //....

    protected ?Form $form = null;

    public function getForm() : Form
    {
        if( !$this->form ) {
            $this->form = $this->createForm( form_name: 'contact_form' );
        }

        return $this->form;
    }

    public function catchForm() : bool
    {
        return $this->getForm()->catch();
    }
}

A ano, takové definice můžete naklikad v Jet Studiu v nástroji k tomu určeném. Opět opakuji – viz video. 

Ale připomínám, že můžete, ale nemusíte. Klidně můžete definici vytvořit ručně, nebo si ji „předklikat“ a ručně upravovat. Jet Studio je pouze pomocný nástroj a ne mandatorní věc – to platí obecně.

Více viz video níže ;-)

Použití formulářů v REST API

Formuláře nemusí být nutné vizuální. Mohou sloužit pouze k zachycení a validaci vstupních dat, která mohou pocházet z libovolného zdroje – ne nutně z POST či GET. 

Stejně tak je možné pracovat s validačními chybami formulářů. Ty lze například jednoduše převést na JSON a například poslat v odpovědi na chybný REST požadavek.

Koncepce má to jednu zásadní výhodu – formulář často stačí definovat jednou. Například entita Article má jednu společnou definici formuláře pro přidání a editaci článku. A tyto formuláře slouží jak v administraci, tak v ukázkovém REST API a mohou sloužit na dalším místě. Napadá mě další využití například v nějakém nástroji pro hromadný import dat. Fantazii se meze nekladou.

Ale teď si pojďme ukázat konkrétně právě REST API.

Koukněme se na modul Content.Articles.REST, což je jedene z ukázkových modulů REST API serveru.

Konkrétně tedy nahlédněme na třídu JetApplicationModule\Con­tent\Articles\REST a její metodu add_Action sloužící pro přidávání článku (pomocí REST API):

public function add_Action(): void
{
    $article = new Content_Article();

    $form = $article->getEditForm();

    $data = $this->getRequestData();

    $form->catchInput( $data, true );

    if( $form->validate() ) {
        $form->catchFieldValues();

        $article->save();

        Logger::success(
            event: 'article_created',
            event_message: 'Article created',
            context_object_id: $article->getId(),
            context_object_name: $article->getTitle(),
            context_object_data: $article
        );

        $this->responseData( $article );
    } else {
        $this->responseValidationError( $form->getValidationErrors() );
    }

}

Vytvoření této operace v rámci REST API je vlastně absolutně triviální. Má to jedno jediné specifikum. Data nejsou načtena přímo z POST, ale s JSON v rámci těla REST HTTP požadavku a je vynucené zachycení formuláře. To dělá tento kousek kódu:

$data = $this->getRequestData();

$form->catchInput( $data, true );

A pokud je něco špatně, tak se REST klient dozví co přesně, protože jsou mu předány chybové hlášky z vazbou na vstupní pole:

$this->responseValidationError( $form->getValidationErrors() );

To je vše – nic složitějšího v tom není.

Napojení formulářů na překladač a lokalizovatelnost

Protože je PHP Jet jet stavěn primárně pro prostředí EU, tak pochopitelně neschází zabudovaná podpora lokalizovatelnosti a překladů přímo do formulářů (ale nikdo vám neříká, že to musíte používat ;-) ).

O překladech se dozvíte více v dokumentaci a také to uvidíte „v akci“ ve videu na konci článku – teda vlastně hned teď záhy ;-)

Ukázka – kontaktní formulář

Účelem článku nebylo obsáhnout vše co Jet Form umí, ale nastínit filozofii a naznačit schopnosti celé té věci. Ovšem jsem toho názoru, že praxe je lepší než teorie a tak si to ukažme rovnou prakticky na jednoduchém příkladu:

(Mimochodem: Už dorazil fantomový napaječ pro mikrofon – zvuk je již o hodně lepší. Ještě jednou díky za rady!)

Co nového v PHP Jet

A již tradičně krátká zpráva o tom, co se od posledního článku událo s PHP Jet:

• Doplnil jsem podporu zabudovaného web serveru PHP.  Jet je tedy možné rychle vyzkoušet bez instalace na plnohodnotný web server.
• Na GitHub jsme zpnul diskuze. Po zvážení všech možnosti se mi to jeví jako nejlepší cesta jak zřídit fórum.
• Připravil jsem stránku pro rychlé seznámení s PHP Jet určenou pro nově příchozí uživatele.
• Pár drobných oprav a vylepšení.
• Začala se již chystat anglická mutace webu a dokumentace. Můj domov ČR bude vždy o něco napřed, ale na web přichází poměrně dost lidí z celého světa a PHP Jet by do budoucna neměl být pouze lokální žáležitostí.
• Začala práce na podpoře PostgreSQL, Oracle a MS SQL.
• EasyDeployer již má podporu SFTP/SCP a dotal pár vylepšení (např. první vývojářský účet je možné vytvořit již během instalace).
• PHP Jet i Easy Deployer jsou od teď i na sourceforge.net

A to je pro dnešek vše. Velice děkuji za Váš čas. Pokud chcete, vše si vyzkoušejte, ptejte se a tak dále.

Brzy se ozvu s dalšími články, které již teď chystám.