Třída pro vytvářecí a editační formuláře pro YetORM

Zdravím,

předem se chci omluvit za možné překlepy a chybky, je 6 ráno a na této třídě jsem pracoval přes noc, tak snad mi neutrhnete hlavu :-)

Mám rád Nette\Database, proto používám YetORM. Také se mi líbí Nette\Forms. No a přemýšlel jsem, jak tyto dvě věci zkombinovat a usnadnit si nejčastější problém – tvorbu vytvářecích a editačních formulářů.

Určitě existují hotová řešení pro LeanMapper, Doctrine atd., ale nevím o ničem pro YetORM. Proto jsem se rozhodl napsat malou třídu, která za mě vyřeší rutiny spojené s přiřazováním hodnot z formuláře do YetORM entity a naopak. Tuto třídu poskytuji zdarma pro svobodné užití, s nadějí, že to někomu pomůže. Třída by teoreticky měla jít jednoduše přepsat pro spolupráci s entitami z jiných knihoven – kdyby to někdo chtěl zkoušet, mělo by stačit přepsat metody isEntityEmpty, getEntityValue a setEntityValue.

Popis třídy:
Třída EntityForm chce v konstruktoru YetORM entitu. Druhý parametr je volitelný a chce instanci Nette\Forms\Form nebo potomka, můžete tedy použít vlastní BaseForm.

Poté se s objektem třídy EntityForm pracuje stejně jako s normálním formulářem pomocí add* metod, jediná odlišnost je, že pokud se na začátku názvu uvede hash (#), pak se input namapuje na vlastnost entity se stejným názvem. Pokud jste třídě předali BaseForm, který obsahuje vlastní add* metody (např. addDateTime), pak je samozřejmě můžete také použít.

A nakonec, třída EntityForm disponuje vlastním onSuccess eventem, který kromě instance Form také vrací entitu naplněnou daty z formuláře.

Zpracovaný formulář pro zobrazení v šabloně získáte pomocí metody process().

Ukázka použití (namespace, výjimky, inject modelu atd nechám na vás)

Jednoduchá YetORM entita:

/**
 * @property-read int $id
 * @property string $email
 * @property string $name
 */
class User extends YetORM\Entity {
}

presenter:

/** @var Model\Entity\User */
protected $userEntity = NULL;

// Pro editační formulář entitu načteme z databáze
public function actionEditUser($id) {
    $this->userEntity = $this->userService->getById($id);
}

// Pro vytvářecí formulář vytvoříme novou prázdnou entitu
public function actionCreateUser() {
    $this->userEntity = new Model\Entity\User;
}

// EntityForm má vlastní onSuccess, který kromě Form vrací i naplněnou entitu
public function userFormSubmitted(Form $form, Model\Entity\User $user) {
    $this->userService->persist($user);
}

public function createComponentUserForm() {

    // Vytvoříme EntityForm, předáme mu entitu a form
    // Druhý parametr je nepovinný, pokud se neuvede, vytvoří se instance Nette\Forms\Form
    $entityForm = new Zax\Forms\EntityForm($this->userEntity, new Form);

    // Následně s ním pracujeme jako s klasickým formulářem, rozdíl je akorát v hashi v názvu
    $entityForm->addText('#name', 'Jméno:')
        ->setRequired();
    $entityForm->addText('#email', 'E-mail:')
        ->setRequired()
        ->addRule(Form::EMAIL);

    // Můžeme zjistit, zda je formulář vytvářecí, nebo editační
    $entityForm->addSubmit('userSubmit', ($entityForm->isCreateForm() ? 'Přidat' : 'Upravit') . ' uživatele');

    // onSuccess event
    $entityForm->onSuccess[] = array($this, 'userFormSubmitted');

    // Metoda process vrátí zpracovaný formulář
    return $entityForm->process();
}

Následně vytvoříme dvě šablony (editUser, createUser), do nich napíšeme {control userForm} a máme hotový jak vytvářecí, tak editační formulář!

No a samozřejmě zde je samotný kód třídy EntityForm:

<?php

/** @licence MIT */

namespace Zax\Forms;
use Nette,
    Nette\Forms\Form,
    Nette\ComponentModel\IComponent,
    Nette\Forms\IControl,
    YetORM\Entity;

class EntityForm extends Nette\Object {

    /** @var array */
    public $onSuccess;

    /** @var \YetORM\Entity */
    protected $entity;

    /** @var \Nette\Forms\Form */
    protected $form;

    /** @var array */
    protected $mappedProperties = array();

    public function __construct(Entity $entity, Form $form = NULL) {
        $this->entity = $entity;
        $this->form = ($form === NULL ? new Form : $form);
    }

    /** @return bool */
    protected function isEntityEmpty() {
        try {
            return !isset($this->entity->id);
        } catch (\Exception $e) {
            return true;
        }
    }

    /** @return mixed */
    protected function getEntityValue($name) {
        return $this->entity->$name;
    }

    /**
     * @param string
     * @param mixed
     * @return $this
     */
    protected function setEntityValue($name, $value) {
        $this->entity->$name = $value;
        return $this;
    }

    /** public alias
     *
     * @return bool
     */
    public function isCreateForm() {
        return $this->isEntityEmpty();
    }

    /**
     * @param string
     * @return bool
     */
    protected function shouldBeMapped($name) {
        return is_string($name) && (substr($name, 0, 1) === '#');
    }

    /**
     * @param string
     * @return string
     */
    protected function cleanName($name) {
        return str_replace('#', '', $name);
    }

    /** Fills form with values from entity, adds 'id' field if needed */
    protected function mapEntity() {
        if(!$this->isEntityEmpty()) {
            // set values in form
            foreach($this->mappedProperties as $name) {
                $this->form[$name]->setDefaultValue($this->getEntityValue($name));
            }

            // entity id
            $this->form->addHidden('id')
                ->setDefaultValue($this->getEntityValue('id'));
        }
    }

    /** Maps property and returns clean name
     *
     * @param string
     * @return string
     */
    protected function mapProperty($name) {
        return $this->mappedProperties[] = $this->cleanName($name);
    }

    /** Fills entity with form values and returns it
     *
     * @param array
     * @return \YetORM\Entity
     */
    public function fillEntity($values) {
        $entity = $this->entity;

        foreach($this->mappedProperties as $property) {
            if(isset($values[$property])) {
                $this->setEntityValue($property, $values[$property]);
            }
        }

        return $entity;
    }

    /** return \Nette\Forms\Form */
    public function getForm() {
        return $this->form;
    }

    /** return \Nette\Forms\Form */
    public function process() {
        $this->mapEntity();
        $entityForm = $this;
        foreach($this->onSuccess as $onSuccess) {
            $this->form->onSuccess[] = function(Form $form) use ($entityForm, $onSuccess) {
                call_user_func_array($onSuccess, array($form, $entityForm->fillEntity($form->getValues())));
            };
        }
        return $this->form;
    }

    /** If component is Forms\IControl, then it can be mapped
     *
     * @param \Nette\ComponentModel\IComponent
     * @param string
     * @param string|NULL
     * @return \Nette\Forms\Container
     */
    public function addComponent(IComponent $component, $name, $insertBefore = NULL) {
        if($this->shouldBeMapped($name) && is_a($component, 'Nette\Forms\IControl')) {
            $name = $this->mapProperty($name);
        }
        return $this->form->addComponent($component, $name, $insertBefore);
    }

    /** If add$name() is called, then it's probably a control that can be mapped, else just call form->$name()
     *
     * @param $name
     * @param $args
     * @return mixed
     */
    public function __call($name, $args) {
        if(substr($name, 0, 3) === 'add' && count($args) > 0) {
            $inputName = $args[0];
            if($this->shouldBeMapped($inputName)) {
                $args[0] = $this->mapProperty($inputName);
            }
        }

        return call_user_func_array(array($this->form, $name), $args);
    }

}

Budu rád za jakýkoliv feedback!

Editoval Zax (10. 4. 2014 0:03)