- Added documentation, fixed some bugs and optimized some parts of the source code while doing the doc.
This commit is contained in:
parent
9190987b53
commit
3986437800
|
@ -0,0 +1,7 @@
|
|||
# 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.
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.checkbox` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.radio` component, which itself extends `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-checkbox"`
|
||||
- `'type' => "checkbox"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-checkbox" type="checkbox" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.color` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-color"`
|
||||
- `'type' => "color"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-color" type="color" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.date` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-date"`
|
||||
- `'type' => "date"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-date" type="date" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.datetime` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-datetime"`
|
||||
- `'type' => "datetime-local"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-datetime" type="datetime-local" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.email` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-email"`
|
||||
- `'type' => "email"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-email" type="email" value="" name="">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.file` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-file"`
|
||||
- `'type' => "file"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-file" type="file" value="" name="">
|
||||
```
|
|
@ -0,0 +1,18 @@
|
|||
# `ui.form` / `ui.form.get` / `ui.form.post` (string $method = "get", string $name = "", string $action = "", array $attributes = [])
|
||||
|
||||
A version exists also for unsupported methods (as of HTML5) on forms `ui.form.put` / `ui.form.patch` / `ui.form.delete`, which
|
||||
could find a use within a Javascript environment.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-form"`
|
||||
- `'enctype' => "multipart/form-data"`
|
||||
- `'method' => "get|post|put|patch|delete"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
|
||||
```html
|
||||
<form class="ui-form" enctype="multipart/form-data" action="$action" method="$method">
|
||||
<input class="ui-hidden" type="hidden" name="picea-ui-form[$name]" value="{ random md5 hash }">
|
||||
</form>
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.hidden` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-hidden"`
|
||||
- `'type' => "hidden"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-hidden" type="hidden" value="" name="">
|
||||
```
|
|
@ -0,0 +1,12 @@
|
|||
# `ui.image` (string $source, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-image"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<img class="ui-image" src="$source">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.input` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
This is small
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-input"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
|
||||
```html
|
||||
<input class="ui-input" type="input" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.numeric` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-numeric"`
|
||||
- `'type' => "numeric"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-numeric" type="numeric" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.password` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-password"`
|
||||
- `'type' => "password"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-password" type="password" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.radio` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-radio"`
|
||||
- `'type' => "radio"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-radio" type="radio" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.range` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-range"`
|
||||
- `'type' => "range"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-range" type="range" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.search` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-search"`
|
||||
- `'type' => "search"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-search" type="search" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.select` (string $name, array $list, $value = null, array $attributes = [], bool $strictComparison = true)
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-select"`
|
||||
- `'type' => "select"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-select" type="select" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.tel` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-tel"`
|
||||
- `'type' => "tel"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-tel" type="tel" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.text` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-text"`
|
||||
- `'type' => "text"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-text" type="text" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,12 @@
|
|||
# `ui.textarea` / `ui.textarea.raw` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`. This extension also comes with a raw modifier which skips the escaping.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-textarea"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<textarea class="ui-textarea" name="$name">$value</textarea>
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.time` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-time"`
|
||||
- `'type' => "time"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-time" type="time" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.url` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-url"`
|
||||
- `'type' => "url"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-url" type="url" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,13 @@
|
|||
# `ui.week` (string $name, mixed $value = null, array $attributes = [], array $options = [])
|
||||
|
||||
Built on top of `ui.input`.
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
- `'class' => "ui-week"`
|
||||
- `'type' => "week"`
|
||||
|
||||
and will typically be rendered such as :
|
||||
```html
|
||||
<input class="ui-week" type="week" value="$value" name="$name">
|
||||
```
|
|
@ -0,0 +1,107 @@
|
|||
# `form`(FormInterface $form, ? FormContext $formContext = null) : FormHandler
|
||||
|
||||
The `form()` method will process a form in three steps :
|
||||
|
||||
1. `initialize(FormContextInterface $context)` is first called on form processing.
|
||||
2. `validate(FormContextInterface $context) : bool` will execute on POST. If you define a name to the form, it will match the one found in the POST (`picea-ui-form[$context->name]`) ; if the form is not the target, it will be skipped. Also, if an error si found within the message list, the method will return `false`.
|
||||
3. `execute(FormContextInterface $context)` is the last method to run, which is usually where you save your entity and finilize your messages. The return value is accessible from the `formHandler` which `form()` returns.
|
||||
|
||||
**[PHP]** So, using this code:
|
||||
|
||||
in */app/controller/user.php*
|
||||
```php
|
||||
form(new \MyApp\Form\User\Create());
|
||||
```
|
||||
|
||||
*/app/form/create.php*
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace MyProject\Form;
|
||||
|
||||
use MyProject\{ Lib, Entity };
|
||||
use Picea\Ui\Method\{ FormContextInterface, Message\ErrorMessage };
|
||||
|
||||
use Psr\Http\Message\ServerRequestInterface;
|
||||
|
||||
use function MyProject\View\{ lang };
|
||||
|
||||
class Create implements \Picea\Ui\Method\FormInterface {
|
||||
|
||||
public function initialize(FormContextInterface $context) : void
|
||||
{
|
||||
$this->user = new Entity\User();
|
||||
|
||||
# $context->{varname} will be populated by $_POST data.
|
||||
$this->user = (string) $context->fullname;
|
||||
}
|
||||
|
||||
public function validate(FormContextInterface $context) : bool
|
||||
{
|
||||
if ( strlen($this->user) < 3 ) {
|
||||
# This won't allow `execute` to run because of the error message.
|
||||
$context->pushMessage(Lib\Message::generateError(
|
||||
lang("form.error.provide_fullName")
|
||||
));
|
||||
}
|
||||
|
||||
return $context->valid();
|
||||
}
|
||||
|
||||
public function execute(FormContextInterface $context) : void
|
||||
{
|
||||
# Saving a new user here
|
||||
Entity\User::repository()->save($this->user);
|
||||
|
||||
$context->pushMessage(Lib\Message::generateSuccess(
|
||||
lang("form.save")
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
which implements this interface :
|
||||
|
||||
```php
|
||||
interface FormInterface
|
||||
{
|
||||
public function initialize(FormContextInterface $context) : void;
|
||||
|
||||
public function validate(FormContextInterface $context) : bool;
|
||||
|
||||
public function execute(FormContextInterface $context);
|
||||
}
|
||||
```
|
||||
|
||||
Would yield the same result such as:
|
||||
```php
|
||||
true
|
||||
true
|
||||
```
|
||||
|
||||
Trying to access either variable before `execute` is called will return `null`.
|
||||
|
||||
## `FormContext` object
|
||||
|
||||
`__construct(ServerRequestInterface $request, ? string $formName = null)`
|
||||
|
||||
Creating a form context manually allows to define the formName, which is essential if you want to use the
|
||||
Cross-Scripting Request Forgery (CSRF).
|
||||
|
||||
It is populated with either $_POST or request's body which is json_decode. A property called `files` is also populated from PSR's `$request->getUploadedFiles()`.
|
||||
|
||||
It's `valid() : bool` method called into a form `validate()` function is first checking every message which were pushed into, using `pushMessage(FormMessage $message)`, and returns false if an error message is found in the list.
|
||||
|
||||
### Retrieve a form execution status / value
|
||||
|
||||
There is two ways to get the execution status (from the `execute` return value):
|
||||
|
||||
```php
|
||||
$formContext = new \Picea\Ui\Method\FormContext($request, 'form.user_create');
|
||||
$form = form(new \MyProject\Form\User\Create(), $formContext);
|
||||
|
||||
if ($formContext->formExecuted) {
|
||||
echo $form->executionStatus;
|
||||
echo $formContext->formExecutionStatus;
|
||||
}
|
||||
```
|
|
@ -0,0 +1,8 @@
|
|||
# `ui.popup` (string $name, array $variables = [], array $options = [])
|
||||
|
||||
The following attributes are assigned by this extension :
|
||||
|
||||
and will typically be rendered such as (directly inside an opening tag) :
|
||||
```html
|
||||
ui-popup='{ "name":$name,"vars":{$variables},"options":{$options} }'
|
||||
```
|
|
@ -242,7 +242,7 @@ class UiElement implements \ArrayAccess, \Iterator, \JsonSerializable {
|
|||
|
||||
public function text(?string $set = null) {
|
||||
if ($set !== null) {
|
||||
$this->content = htmlspecialchars( $set, ENT_NOQUOTES );
|
||||
$this->content = htmlspecialchars( $set, \ENT_NOQUOTES );
|
||||
|
||||
return $this;
|
||||
}
|
||||
|
|
|
@ -22,9 +22,9 @@ class UiPopup extends UiElement implements Extension {
|
|||
return "<?php echo 'ui-popup=\"' . ( new \\" . static::class . "() )->buildAttributes($arguments) . '\"' ?>";
|
||||
}
|
||||
|
||||
public function buildAttributes(string $name, array $variables = [], $options = []) : string
|
||||
public function buildAttributes(string $name, array $variables = [], array $options = []) : string
|
||||
{
|
||||
return htmlentities(json_encode([ "name" => $name, "vars" => $variables, "options" => $options ], JSON_HEX_APOS | JSON_HEX_QUOT), ENT_QUOTES, 'UTF-8');
|
||||
return htmlentities(json_encode([ "name" => $name, "vars" => $variables, "options" => $options ], JSON_HEX_APOS | JSON_HEX_QUOT), \ENT_QUOTES, 'UTF-8');
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
@ -27,7 +27,6 @@ class UiTextarea extends UiInput {
|
|||
return "<?php echo ( new \\" . static::class . "() )->echoRaw($raw)->buildHtml($arguments) ?>";
|
||||
}
|
||||
|
||||
|
||||
protected function setValue($value) : void
|
||||
{
|
||||
$this->echoRaw ? $this->html($value) : $this->text($value);
|
||||
|
|
|
@ -7,9 +7,10 @@ use Picea\Extension\Extension,
|
|||
|
||||
use Picea\Compiler\Context;
|
||||
|
||||
use Picea\Extension\FunctionExtension;
|
||||
use Psr\Http\Message\ServerRequestInterface;
|
||||
|
||||
class Form implements Extension {
|
||||
class Form implements Extension, FunctionExtension {
|
||||
use ExtensionTrait;
|
||||
|
||||
public array $tokens;
|
||||
|
@ -22,14 +23,15 @@ class Form implements Extension {
|
|||
|
||||
public function __construct(ServerRequestInterface $request, Context $context) {
|
||||
$this->request = $request;
|
||||
$this->register($context);
|
||||
}
|
||||
|
||||
public function parse(\Picea\Compiler\Context &$context, ?string $arguments, string $token) : string { }
|
||||
|
||||
public function register(Context $context) : void
|
||||
public function exportFunctions(): array
|
||||
{
|
||||
$context->pushFunction("form", [ $this, 'formClass' ]);
|
||||
return [
|
||||
"form" => [ $this, 'formClass' ],
|
||||
];
|
||||
}
|
||||
|
||||
public function formClass(FormInterface $form, ? FormContext $formContext = null) : FormHandler
|
||||
|
|
|
@ -13,7 +13,7 @@ class FormContext implements FormContextInterface
|
|||
|
||||
public bool $formExecuted = false;
|
||||
|
||||
public /*mixed*/ $formExecutionStatus = null;
|
||||
public mixed $formExecutionStatus = null;
|
||||
|
||||
public array $values = [];
|
||||
|
||||
|
@ -86,7 +86,7 @@ class FormContext implements FormContextInterface
|
|||
|
||||
return $this->formSent = $valid;
|
||||
}
|
||||
|
||||
|
||||
public function __set($key, $value)
|
||||
{
|
||||
return $this->set($key, $value);
|
||||
|
|
|
@ -8,5 +8,5 @@ interface FormInterface
|
|||
|
||||
public function validate(FormContextInterface $context) : bool;
|
||||
|
||||
public function execute(FormContextInterface $context) /* : mixed */;
|
||||
public function execute(FormContextInterface $context);
|
||||
}
|
|
@ -7,9 +7,10 @@ use Picea\Extension\Extension,
|
|||
|
||||
use Picea\Compiler\Context;
|
||||
|
||||
use Picea\Extension\FunctionExtension;
|
||||
use Psr\Http\Message\ServerRequestInterface;
|
||||
|
||||
class Pagination implements Extension {
|
||||
class Pagination implements Extension, FunctionExtension {
|
||||
use ExtensionTrait;
|
||||
|
||||
public array $tokens;
|
||||
|
@ -20,14 +21,16 @@ class Pagination implements Extension {
|
|||
|
||||
public function __construct(ServerRequestInterface $request, Context $context) {
|
||||
$this->request = $request;
|
||||
$this->register($context);
|
||||
}
|
||||
|
||||
public function parse(\Picea\Compiler\Context &$context, ?string $arguments, string $token) : string { }
|
||||
|
||||
public function register(Context $context) : void
|
||||
|
||||
public function exportFunctions(): array
|
||||
{
|
||||
$context->pushFunction("pagination", [ $this, 'paginationClass' ]);
|
||||
return [
|
||||
"pagination" => [ $this, 'paginationClass' ]
|
||||
];
|
||||
}
|
||||
|
||||
public function paginationClass(string $name, ?string $url = null, ?array $params = null) : PaginationHandler
|
||||
|
|
|
@ -41,7 +41,7 @@ class PaginationHandler {
|
|||
}
|
||||
|
||||
public function __toString() {
|
||||
return "hello world";
|
||||
return "";
|
||||
}
|
||||
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue