picea-ui/docs/00-intro.md

# Picea UI

Welcome to the `picea-ui` documentation.

This quick documentation will guide you through the use of the form system, every available
UI elements and how to add customs one and individual components.
 
Mostly everything you need to build and process form is available in this package.

The first part is most input callable as a widget :

```
{% ui:text "fullname", "John Doe" %}
```

Current input support is :
```php
- Input (string $source, array $attributes = [], array $options = []) 
- Checkbox (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Color (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Date (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Datetime (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Email (string $name, mixed $value = null, array $attributes = [], array $options = [])
- File (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Hidden (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Image (string $source, array $attributes = [], array $options = []) 
- Numeric (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Password (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Radio (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Range (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Search (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Select (string $name, array $list, mixed $value = null, array $attributes = [], bool $strictComparison = true)
- Tel (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Text (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Textarea (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Time (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Url (string $name, mixed $value = null, array $attributes = [], array $options = [])
- Week (string $name, mixed $value = null, array $attributes = [], array $options = [])
```

**[PICEA]** So, using this code:

```html
{% ui:form.post "user.save", current_url() %}
    <div class="field fullname">
        <label>Full name</label>
        {% ui:text "fullname", $user->fullname, [ 'required' => 'required' ] %}
    </div>
    
    <div class="field email">
        <label>Email address</label>
        {% ui:text "email", $user->email %}
    </div>

    <div class="field job">
        <label>Have a job</label>
        <label>{% ui:radio "job", 'yes', [], [ 'value' => $entity->job ] %} Yes</label>
        <label>{% ui:radio "job", 'no', [], [ 'value' => $entity->job ] %} No</label>
    </div>
    
    <div class="field role">
        <label>Role</label>
        {% ui:select "role", [ 'user' => "User", 'moderator' => "Moderator", 'admin' => "Admin" ], $user->role, [ 'required' => 'required' ] %}
    </div>

    <button type="submit">Save</button>
{% ui:endform %}
```

**[HTML]** Would render as such:

```html
<form class="ui-form" method="post" action="http://127.0.0.1/" enctype="multipart/form-data">
    <input class="ui-hidden" type="hidden" name="picea-ui-form[user.save]" value="617fb40f1999db63fbd0b4f680a77750">
    
    <div class="field fullname">
        <label>Full name</label>
        <input class="ui-text" type="text" value="" name="fullname" required="required">        
    </div>

    <div class="field email">
        <label>Email address</label>
        <input class="ui-text" type="text" value="" name="email">        
    </div>

    <div class="field job">
        <label>Have a job</label>
        <label><input class="ui-radio" type="radio" value="yes" name="job"> Yes</label>
        <label><input class="ui-radio" type="radio" value="no" name="job"> No</label>
    </div>

    <div class="field role">
        <label>Role</label>
        <select class="ui-select" name="role" required="required">
            <option value="user">User</option>
            <option value="moderator">Moderator</option>
            <option value="admin">Admin</option>
        </select>        
    </div>

    <button type="submit">Save</button>
</form>
```

## Use your forms in controller

Forms can be used to handle how your data is handled, from loading (get) to processing (post).

The process is as simple as defining a Form, implementing FormInterface :

```php
interface FormInterface
{
    public function initialize(FormContextInterface $context) : void;

    public function validate(FormContextInterface $context) : bool;
    
    public function execute(FormContextInterface $context);
}
```

`initialize` is called directly on `form()` method call. 

`validate` will be called if the request's method is either `post`, `put`, `patch` or `delete`, which implies **adding** / **editing** / **deleting**.

`execute` will finally launch only if `validate` returns `true`. This is usually where you want to **save** / **destroy** your entities.