Přeskočit na hlavní obsah

Fields

Fields jsou jednoduché PHP třídy, které řídí validace a ukládání dat do databáze - ať už je ukládáte přes API nebo přes formuláře v datagridu.

Příklad použití fieldů​

Přidání fieldu EmailField vám umožní pracovat s property email skrze API endpoint a zároveň i skrze formulářové pole v datagridu. Tento field má (by default) přiřazen EmailFieldRenderer.vue jenž zajištuje, že se ve formuláři zobrazí pole pro e-mail. K dispozici je celá řada fieldů a field rendererů.

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.'
                )
            ],
            serializers: [
                // Serializer pro uložení hodnoty do databáze
                new CallableSerializer(fn($value) => mb_strtolower($value))
            ],
            formatters: [
                // Formatter pro zobrazení hodnoty ve formuláři
                new CallableFormatter(fn($value) => mb_strtoupper($value))
            ]
        ))
        //->add(...)
        //->add(...)
   ;
}

Při ukládání záznamu se automaticky provedou validace podle pravidel v parametru rules. Následně se hodnota serializuje dle přiřazených serializers, namapuje na zdrojovou entitu a uloží do databáze.

Formátery, serializéry a pravidla​

Ačkoli jsou formátery určeny primárně pro columns, mohou být použity i ve fieldu. Hodí se to zejména pro naformátování výchozí hodnoty pro formulářové pole.

Nejlepší příklad je DateField - ten z databáze dostane hodnotu typu \DateTime, ovšem obsahuje DateFormatter, který ji převede na string ve formátu Y-m-d. Když pak hodnoty ukládáte přes formulář nebo přes API, tak se na fieldu aplikuje pravidlo DateRule - to provede validaci a zajistí, že hodnota bude ve správném formátu. Nakonec se aplikuje serializer DateSerializer, jenž hodnotu převede na formát vhodný pro uložení do databáze - tedy zpět na objekt typu \DateTime.

K dispozici je celá řada rules, serializers a formatters .

Přehled fieldů​

Field (název třídy)RulesSerializersFormattersExtra parametryRenderer
1PureFieldText
2ArrayFieldArray
3DateCzFieldDateCzDateTimeDateCzText
4DateFieldDateDateTimeDateText
5DateTimeCzFieldDateTimeCzDateTimeDateTimeCzText
6DateTimeFieldDateTimeDateTimeDateTimeText
7DateTimeIntervalFieldDateTimeIntervalDateTimeIntervalDateTimeIntervalText
8DateTimeZoneFieldDateTimeZoneDateTimeZoneDateTimeZoneDateTimeZone
9DecimalFieldDecimalDecimal
10EmailFieldEmailEmail
11HiddenFieldHidden
12HourMinuteCzFieldHourMinuteCzDateTimeHourMinuteCzText
13HourMinuteFieldHourMinuteDateTimeHourMinuteText
14IntegerFieldIntegerInteger
15JsonFieldJson?Schema $schemaJson
16NumericFieldNumericNumeric
17PasswordFieldStringPassword
18PhoneCzFieldPhoneCzText
19RichTextFieldStringRichText
20SelectFieldItem[] $itemsSelect
21SlugFieldSlug?string $slugFromSlug
22TextAreaFieldStringTextArea
23TextFieldStringText
24TimeCzFieldTimeCzDateTimeTimeCzText
25TimeFieldTimeDateTimeTimeText
26ToggleBtnFieldBooleanToggleBtn
27ToManySelectFieldXXclass-string $reverseEntity
string $primaryKey		Select
28ToOneSelectFieldXXclass-string $reverseEntity
string $primaryKey		Select
29UrlFieldUrlText
30VideoLinkFieldVideoLinkText

Společné parametry fieldů​

U všech fieldů vyjma ToManySelectField a ToOneSelectField lze nastavit tyto společné parametry:

ParametrTypVýchozí hodnotaPopis
namestringNázev fieldu.
labelstringPopisek fieldu ve formuláři.
rulesIRule[]dle fielduPole pravidel implementujících IRule.
serializersISerializer[]dle fielduPole serializérů implementujících ISerializer.
formattersIFormatter[]dle fielduPole formatterů implementujících IFormatter.
attrsmixed[]dle fielduPole vlastních atributů pro formulářové pole.
disabledboolfalseZakáže field ve formuláři a v API.
mapToEntitybooltruePovolí mapování fieldu na entitu.
valuemixednew UndefinedValue()Výchozí hodnota fieldu.
defaultValuemixednew UndefinedValue()Výchozí hodnota fieldu, pokud není vyplněná.

Nastavení 100% šířky fieldu​

Při renderování lze zapnout 100% šířku fieldu - stačí nastavit parametr attrs na hodnotu ['fullWidth' => true].

Přehled field rendererů​

Vue field rendererSouborVue renderujePoznámka
1ArrayArrayFieldRenderer.vue<v-text-field>
2DateTimeZoneDateTimeZoneFieldRenderer.vue<v-text-field> a <autocomplete>
3DecimalDecimalFieldRenderer.vue<v-text-field>
4EmailEmailFieldRenderer.vue<v-text-field>
5HiddenHiddenFieldRenderer.vue<input type="hidden">
6IntegerIntegerFieldRenderer.vue<v-text-field>
7JsonJsonFieldRenderer.vue<v-textarea>
8NumericNumericFieldRenderer.vue<v-text-field>
9PasswordPasswordFieldRenderer.vue<v-text-field type="password">
10RichTextRichTextFieldRenderer.vue<div contenteditable="true">Quill editor
11SelectSelectFieldRenderer.vue<v-select>Může být multiple
12SlugSlugFieldRenderer.vue<v-text-field>
13TextAreaTextAreaFieldRenderer.vue<v-textarea>
14TextTextFieldRenderer.vue<v-text-field>
15ToggleBtnToggleBtnFieldRenderer.vue<v-switch>

Vlastní field​

Pokud potřebujete ovlivnit validaci, serializaci, formátování, či vykreslení fieldu jiným způsobem, než umožňují dostupné fieldy, můžete si vytvořit vlastní field.

Vytvoření fieldu​

Stačí přidat novou třídu, která podědí BaseField a implementuje metodu renderer().

app/Collection/Field/MyCustomField.php
class MyCustomField extends BaseField
{
    /** 
     * Definuje název Vue field-rendereru.     
     * Pokud Vue komponenta není zaregistrována, 
     * provede se fallback na TextFieldRenderer.vue.      
     */
    public function renderer(): string
    {
        return 'my-custom-field-renderer';
    }
    
    /**
     * Pomocí konstruktoru lze přidat jakékoli vlastní parametry.
     *
     * @param \Megio\Collection\WriteBuilder\Rule\Base\IRule[] $rules
     * @param \Megio\Collection\WriteBuilder\Serializer\Base\ISerializer[] $serializers
     * @param \Megio\Collection\Formatter\Base\IFormatter[] $formatters
     * @param array<string, string|int|float|bool|null> $attrs
     */
    public function __construct(
        protected string $name,
        protected string $label,
        protected string $myParam,
        protected array  $rules = [],
        protected array  $serializers = [new DateTimeZoneSerializer()],
        protected array  $formatters = [new DateTimeZoneFormatter()],
        protected array  $attrs = [],
        protected bool   $disabled = false,
        protected bool   $mapToEntity = true,
        protected mixed  $value = new UndefinedValue(),
        protected mixed  $defaultValue = new UndefinedValue()
    )
    {
        $this->rules[] = new DateTimeZoneRule();
        parent::__construct(
            $this->name,
            $this->label,
            $this->rules,
            $this->serializers,
            $this->formatters,
            $this->attrs,
            $this->disabled,
            $this->mapToEntity,
            $this->value,
            $this->defaultValue
        );
    }
    
    /** 
     * Také je možné přidat metodu toArray(), díky které 
     * můžete přidat vlastní data pro field.
     *
     * @return array<string, mixed> 
     */
    public function toArray(): array
    {
        $data = parent::toArray();
        $data['params'] = [
            'items' => \DateTimeZone::listIdentifiers()
            'myParam' => $this->myParam,
        ];
        return $data;
    }
}

Povinné parametry konstruktoru​

Konstruktor musí obsahovat veškeré parametry, které obsahuje i konstruktor rodičovské třídy BaseField.

/**
 * @param \Megio\Collection\WriteBuilder\Rule\Base\IRule[] $rules
 * @param \Megio\Collection\WriteBuilder\Serializer\Base\ISerializer[] $serializers
 * @param \Megio\Collection\Formatter\Base\IFormatter[] $formatters
 * @param array<string, string|int|float|bool|null> $attrs
 */
public function __construct(

    // Název fieldu
    protected string $name,
    
    // Popisek fieldu ve formuláři.
    protected string $label,
    
    // Navíc - Váš rozšiřující parametr
    protected string $myParam,

    // Navíc - Další rozšiřující parametr
    protected string $myParamX,
    
    // Pole pravidel implementujících IRule.
    protected array  $rules = [],
    
    // Pole serializérů implementujících ISerializer.
    protected array  $serializers = [],
    
    // Pole formatterů implementujících IFormatter.
    protected array  $formatters = [],
    
    // Pole vlastních atributů pro formulářové pole.
    protected array  $attrs = [],
    
    // Zakáže field ve formuláři a v API.
    protected bool   $disabled = false,
    
    // Povolí mapování fieldu na entitu.
    protected bool   $mapToEntity = true,
    
    // Výchozí hodnota fieldu.
    protected mixed  $value = new UndefinedValue(),
    
    // Výchozí hodnota fieldu, pokud není vyplněná.
    protected mixed  $defaultValue = new UndefinedValue(),
)
{
    // ...
}

Vlastní field renderer​

Pokud potřebujete vytvořit vlastní Vue komponentu pro vykreslení fieldu, lze to provést ideálně ve složce assets/datagrid/fields. Vytvoříme zde tedy nový soubor MyCustomFieldRenderer.vue a dále budeme postupovat podle následující kapitoly: megio panel - field