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 :

- 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:

{% 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:

<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 :

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.