Download the PHP package occ2/form-control without Composer

FormControl

1. Introduction

Form control is pretty nice and easy way to create, setup and use Forms in Nette applications. Form is encapsulated into Bootstrap4 card and use Bootstrap4 layout and Font Awesome 5 icons. It use annotation based settings of form and its controls.

Installation

composer require occ2/form-control

Form control has some important dependecies.

contributte/event-dispatcher - required contributte/recaptcha - required kdyby/translation - optional aleswita/formrenderer - required and whole Nette framework.

All text that are used are untranslated anchors. If you dont want to use translation you may use simple texts

2. Creating FORM

a. Create your form class - for example in MyForm.php

6. Set form values

There are two ways to fill form controls with values. First one by setDefaults method, second one by predefined callback

a. Use setDefaults()

Easiest way if use setDefaults($values). Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->onSuccess[] = function(NForm $form)use($t){
        $values = $form->getValues();
        $t->model->save($values);
        if($t->isAjax(){
            $t["myForm]->flashMessage("Saved !!");
            $t["myForm]->reload();
        }
        else{
            $t->redirect("this");
        }
    };
    $f->onError[] = function (NForm $form) use( $t){
        ...
    };
    ...
    return $f;
}
...

public function handleFillInForm($id){
    $data = (array) $this->model->get($id); // data must be array
    $this["myForm"]->setDefaults($data);
    $this["myForm"]->reload();
    return;
}

b. Use callback You can use callback that loads data and fill in form with then. Setup callback in factory and call in handler Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->setLoadValuesCallback(function($id) use($t){
        return (array) $t->model->get($id);
    });
    $f->onSuccess[] = function(NForm $form)use($t){
        $values = $form->getValues();
        $t->model->save($values);
        if($t->isAjax(){
            $t["myForm]->flashMessage("Saved !!");
            $t["myForm]->reload();
        }
        else{
            $t->redirect("this");
        }
    };
    return $f;
}

...

public function handleFillInForm($id){
    $this["myForm"]->laodValues($id));
    $this["myForm"]->reload();
    return;
}

!! IMPORTANT !! Be careful that loadValues() and setDefaults() must be call in handle or action method of presenter not in createComponent factory

7. Tips and tricks

a. How to access to form container?

You can find container in form property of FormControl Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $container =  $f->form;
    $container->addText(...);
    ...
    return $f;
}

b. How to access to form controls?

You can use form["controlName"] or simplier getItem("controlName") method Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $control =  $f->form["controlName"];
    // or
    $control = $f->getItem("controleName");
    return $f;
}

c. How to disable form annotation builder?

You can use disableBuilder() method in factory. Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->disableBuilder();
    $container =  $f->form;
    $container->addText(...);
    ...
    return $f;
}

d. How to override form text in handlers and actions

You can override form title, comment and footer in handlers and actions without changing annotations in form class Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->onSuccess[] = function(NForm $form)use($t){
        $values = $form->getValues();
        $t->model->save($values);
        if($t->isAjax(){
            $t["myForm]->flashMessage("Saved !!");
            $t["myForm]->reload();
        }
        else{
            $t->redirect("this");
        }
    };
    ...
    return $f;
}
...

public function handleChangeTexts(){
    $this["myForm"]->setTitle("newTitle"));
    $this["myForm"]->setComment("newComment"));
    $this["myForm"]->setFooter("newFooter"));
    $this["myForm"]->reload();
    return;
}

e. How to clear values in filled form?

You can use clearValues() method Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->setLoadValuesCallback(function($id) use($t){
        return (array) $t->model->get($id);
    });
    $f->onSuccess[] = function(NForm $form)use($t){
        $values = $form->getValues();
        $t->model->save($values);
        if($t->isAjax(){
            $t["myForm]->flashMessage("Saved !!");
            $t["myForm]->reload();
        }
        else{
            $t->redirect("this");
        }
    };
    return $f;
}

...

public function handleFillInForm($id){
    $this["myForm"]->laodValues($id));
    $this["myForm"]->reload();
    return;
}

public function handleResetForm(){
    $this["myForm"]->clearValues();
    $this["myForm"]->reload();
    return;
}

f. Do you want to use your own builder? No problem..

Your builder must implement IFormBuilder interface

Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->setBuilder(new MyOwnBuilder);
    ...
    return $f;
}

g. Is easy way to add error to control?

Yes. You can use error() method Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();

    $f->onSuccess[] = function(NForm $form)use($t){

        if(..something){
            $t["myForm]->error("someControl","Error message");
        }
        else{
            $t["myForm"]->flashMessage("Saved !!");
        }
        $t["myForm]->flashMessage("Saved !!");
        if($t->isAjax(){
            $t["myForm]->reload();
        }
        else{
            $t->redirect("this");
        }
    };
    return $f;
}

h. Can I use my own latte template instead of predefined bootstrap template?

Yes. You can use yout own template and override default settings by setTemplate() method Example:

...
public function createComponentMyForm(){
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->setTemplate("myTemplate.latte");
    ...
    return $f;
}

And file myTemplate.latte Example:

{snippet form}
    {snippetArea flashes}
        {include '../../templates/flashes.latte'}
    {/snippetArea}
    <form n:name=myForm class=form>
        <p><label n:name=user>Username: <input n:name=user size=20></label>
        <p><label n:name=password>Password: <input n:name=password></label>
        <p><input n:name=send class="btn btn-default">
    </form>   
{/snippet}

i. Can I use another iconset then Fon Awesome 5?

Yes you can override _iconPrefix static property Example:

...
public function createComponentMyForm(){
    MyForm::$_iconPrefix = "fa fa-";
    $t = $this;
    $f = $this->myFormFactory->create();
    $f->setTemplate("myTemplate.latte");
    ...
    return $f;
}