diff --git a/docs/00-intro.md b/docs/00-intro.md index c7d198b..047b0ec 100644 --- a/docs/00-intro.md +++ b/docs/00-intro.md @@ -5,3 +5,123 @@ 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() %} +
+ + {% ui.text "fullname", $user->fullname, [ 'required' => 'required' ] %} +
+ +
+ + {% ui.text "email", $user->email %} +
+ +
+ + + +
+ +
+ + {% ui.select "role", [ 'user' => "User", 'moderator' => "Moderator", 'admin' => "Admin" ], $user->role, [ 'required' => 'required' ] %} +
+ + +{% ui.endform %} +``` + +**[HTML]** Would render as such: + +```html +
+ + +
+ + +
+ +
+ + +
+ +
+ + + +
+ +
+ + +
+ + +
+``` + +## 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. + diff --git a/src/Form/UiInput.php b/src/Form/UiInput.php index cde816c..f185793 100644 --- a/src/Form/UiInput.php +++ b/src/Form/UiInput.php @@ -30,7 +30,7 @@ class UiInput extends UiElement implements Extension { return "buildHtml($arguments) ?>"; } - public function buildHtml(string $name, /*? mixed */ $value = null, array $attributes = [], array $options = []) : string + public function buildHtml(string $name, mixed $value = null, array $attributes = [], array $options = []) : string { $this->name = $name; diff --git a/src/Form/UiSelect.php b/src/Form/UiSelect.php index ae8ad6f..7ac20f1 100644 --- a/src/Form/UiSelect.php +++ b/src/Form/UiSelect.php @@ -22,7 +22,7 @@ class UiSelect extends UiElement implements Extension { return "buildHtml($arguments) ?>"; } - public function buildHtml(string $name, array $list, $value = null, array $attributes = [], bool $strictComparison = true) : string + public function buildHtml(string $name, array $list, mixed $value = null, array $attributes = [], bool $strictComparison = true) : string { if ($attributes['class'] ?? false) { $attributes['class'] = implode(" ", array_merge((array) $attributes['class'], (array) $this->attributes['class']));