Write builder

Aneb metody pro vytváření a editaci záznamů v kolekcích.

V předchozích kapitolách jsme si ukázali, jak provést základní konfiguraci kolekce pomocí metod source, key, read a readAll. Nyní si ukážme metody create a update, již slouží k definici fieldů a jejich pravidel pro vytváření a editaci záznamů.

Výchozí konfigurace

Výchozí konfiguraci udává rodičovská třída CollectionRecipe a její konfigurace je totožná s tímto kódem:

app/Recipe/UserRecipe.php

class UserRecipe extends CollectionRecipe
{   
    // Definice fieldů pro zápis nových záznamů
    public function create(WriteBuilder $builder, CollectionRequest $request): WriteBuilder
    {
        return $builder->buildByDbSchema();
    }
    
    // Definice fieldů pro update stávajících záznamů
    public function update(WriteBuilder $builder, CollectionRequest $request): WriteBuilder
    {
        return $builder->buildByDbSchema();
    }
}

Parametry metod

Parametr	Popis
WriteBuilder	Objekt, díky kterému lze definovat fieldy a jejich pravidla pro zápis záznamů (podrobnosti v odstavci WriteBuilder).
CollectionRequest	Objekt, který obsahuje veškeré informace o aktuálním requestu prováděným nad kolekcí. Dostupné metody: $request->getHttpRequest() $request->isFormRendering() $request->getRequestData() $request->getSearchText() $request->getCustomData() $request->getRowId() $request->getRowValues()

WriteBuilder

Write builder obsahuje množství metod. V zásadě ale budete používat jen několik z nich:

Metoda	Popis metody	Parametr	Popis parametru
add(...)	Přidá či přepíše field.	IField $field	Konkrétní field k přidání.
		string $moveBeforeName	Přesune field před jiný.
		string $moveAfterName	Přesune field za jiný.
buildByDbSchema(...)	Vytvoří fieldy na základě databázového schématu.	bool $persist	Při prvním volání metody add(...) se odstraní veškeré automaticky vytvořené fieldy - tímto parametrem je možné toto chování potlačit.
		string[]: $exclude	Názvy fieldů, které nechcete vytvářet.
ignoreRules(...)	Vyignoruje validační pravidla konkrétních fieldů.	class-string[][] $rules	Asociativní pole, kde klíč je název fieldu a hodnota je pole rules (class-names), které chcete vynechat.

Podrobnější konfigurace

Prozatím není potřeba se zabývat konkrétní definicí jednotlivých fieldů - o těch si povíme v kapitole fields. Nyní jde hlavně o pochopení toho, že v metodách create a update můžete definovat fieldy (potažmo properties), které mají být dostupné v API a tedy i ve formulářích datagridu.

app/Recipe/UserRecipe.php

class UserRecipe extends CollectionRecipe
{   
    // V konstruktoru můžete využít DI kontejneru
    public function __construct(protected EntityManager $em)
    {
    }
    
    // Definice pravidel pro vytváření nových záznamů
    public function create(WriteBuilder $builder, CollectionRequest $request): WriteBuilder
    {
        return $builder
            ->add(new EmailField(
                name: 'email', 
                label: 'E-mail', 
                rules: [
                    new RequiredRule(),
                    new UniqueRule(
                        targetEntity: User::class, 
                        columnName: 'email', 
                        message: 'Tento e-mail je již použit.'
                    )
                ]
            ))
            ->add(new PasswordField(
                name: 'password', 
                label: 'Heslo', 
                rules: [
                    new RequiredRule(),
                    new MinRule(6),
                    new MaxRule(32)
                ]
            ))
            ->add(new PasswordField(
                name: 'password_check', 
                label: 'Heslo znovu', 
                rules: [
                    new RequiredRule(),
                    new EqualRule('password'),
                ], 
                mapToEntity: false
            ))
            ->add(new ToManySelectField(
                name: 'roles', 
                label: 'Role', 
                reverseEntity: Role::class
            ))
        ;
    }
    
    // Definice pravidel pro update stávajících záznamů
    public function update(WriteBuilder $builder, CollectionRequest $request): WriteBuilder
    {
        $pwf = new PasswordField(name: 'password', label: 'Heslo');
        
        // Zamezí zobrazení hesla při renderování formuláře
        if ($request->isFormRendering()) {
            $pwf->setValue(new EmptyValue());
        }
        
        return $builder
            ->add(new TextField(
                name: 'id', 
                label: 'ID', 
                attrs: ['fullWidth' => true], 
                disabled: true
            ))
            ->add(new EmailField(
                name: 'email', 
                label: 'E-mail'
            ))
            ->add($pwf)
            ->add(new ToManySelectField(
                name: 'roles',
                label: 'Role',
                reverseEntity: Role::class,
                attrs: ['fullWidth' => true]
            ));
    }
}