diff --git a/docs/00-intro.md b/docs/00-intro.md new file mode 100644 index 0000000..c7d198b --- /dev/null +++ b/docs/00-intro.md @@ -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. + diff --git a/docs/10-ui-checkbox.md b/docs/10-ui-checkbox.md new file mode 100644 index 0000000..11eb9a3 --- /dev/null +++ b/docs/10-ui-checkbox.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-color.md b/docs/10-ui-color.md new file mode 100644 index 0000000..ee647ea --- /dev/null +++ b/docs/10-ui-color.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-date.md b/docs/10-ui-date.md new file mode 100644 index 0000000..7855512 --- /dev/null +++ b/docs/10-ui-date.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-datetime.md b/docs/10-ui-datetime.md new file mode 100644 index 0000000..47bafd2 --- /dev/null +++ b/docs/10-ui-datetime.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-email.md b/docs/10-ui-email.md new file mode 100644 index 0000000..9779149 --- /dev/null +++ b/docs/10-ui-email.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-file.md b/docs/10-ui-file.md new file mode 100644 index 0000000..4b6d120 --- /dev/null +++ b/docs/10-ui-file.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-form.md b/docs/10-ui-form.md new file mode 100644 index 0000000..6bbacb7 --- /dev/null +++ b/docs/10-ui-form.md @@ -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 +
+ +
+``` \ No newline at end of file diff --git a/docs/10-ui-hidden.md b/docs/10-ui-hidden.md new file mode 100644 index 0000000..69de9cf --- /dev/null +++ b/docs/10-ui-hidden.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-image.md b/docs/10-ui-image.md new file mode 100644 index 0000000..1027a74 --- /dev/null +++ b/docs/10-ui-image.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-input.md b/docs/10-ui-input.md new file mode 100644 index 0000000..ee8790c --- /dev/null +++ b/docs/10-ui-input.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-numeric.md b/docs/10-ui-numeric.md new file mode 100644 index 0000000..b7c8571 --- /dev/null +++ b/docs/10-ui-numeric.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-password.md b/docs/10-ui-password.md new file mode 100644 index 0000000..0d9b359 --- /dev/null +++ b/docs/10-ui-password.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-radio.md b/docs/10-ui-radio.md new file mode 100644 index 0000000..46d8a6d --- /dev/null +++ b/docs/10-ui-radio.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-range.md b/docs/10-ui-range.md new file mode 100644 index 0000000..3f258f2 --- /dev/null +++ b/docs/10-ui-range.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-search.md b/docs/10-ui-search.md new file mode 100644 index 0000000..035a021 --- /dev/null +++ b/docs/10-ui-search.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-select.md b/docs/10-ui-select.md new file mode 100644 index 0000000..071de73 --- /dev/null +++ b/docs/10-ui-select.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-tel.md b/docs/10-ui-tel.md new file mode 100644 index 0000000..2a9a413 --- /dev/null +++ b/docs/10-ui-tel.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-text.md b/docs/10-ui-text.md new file mode 100644 index 0000000..04e08a0 --- /dev/null +++ b/docs/10-ui-text.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-textarea.md b/docs/10-ui-textarea.md new file mode 100644 index 0000000..148e475 --- /dev/null +++ b/docs/10-ui-textarea.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-time.md b/docs/10-ui-time.md new file mode 100644 index 0000000..fbdb592 --- /dev/null +++ b/docs/10-ui-time.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-url.md b/docs/10-ui-url.md new file mode 100644 index 0000000..3957336 --- /dev/null +++ b/docs/10-ui-url.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/10-ui-week.md b/docs/10-ui-week.md new file mode 100644 index 0000000..6e211ad --- /dev/null +++ b/docs/10-ui-week.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/20-method-form.md b/docs/20-method-form.md new file mode 100644 index 0000000..f2ccd10 --- /dev/null +++ b/docs/20-method-form.md @@ -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 +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; +} +``` \ No newline at end of file diff --git a/docs/30-component-popup.md b/docs/30-component-popup.md new file mode 100644 index 0000000..3284bfd --- /dev/null +++ b/docs/30-component-popup.md @@ -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} }' +``` \ No newline at end of file diff --git a/src/Common/UiElement.php b/src/Common/UiElement.php index 5f6faa2..b3f3aff 100644 --- a/src/Common/UiElement.php +++ b/src/Common/UiElement.php @@ -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; } diff --git a/src/Component/UiPopup.php b/src/Component/UiPopup.php index 618e34b..6fac143 100644 --- a/src/Component/UiPopup.php +++ b/src/Component/UiPopup.php @@ -22,9 +22,9 @@ class UiPopup extends UiElement implements Extension { return "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'); } } diff --git a/src/Form/UiTextarea.php b/src/Form/UiTextarea.php index 19e968b..59d865f 100644 --- a/src/Form/UiTextarea.php +++ b/src/Form/UiTextarea.php @@ -27,7 +27,6 @@ class UiTextarea extends UiInput { return "echoRaw($raw)->buildHtml($arguments) ?>"; } - protected function setValue($value) : void { $this->echoRaw ? $this->html($value) : $this->text($value); diff --git a/src/Method/Form.php b/src/Method/Form.php index e65378c..b850b2a 100644 --- a/src/Method/Form.php +++ b/src/Method/Form.php @@ -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 diff --git a/src/Method/FormContext.php b/src/Method/FormContext.php index 2d5cde4..bab16df 100644 --- a/src/Method/FormContext.php +++ b/src/Method/FormContext.php @@ -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); diff --git a/src/Method/FormInterface.php b/src/Method/FormInterface.php index cbfb766..493aa31 100644 --- a/src/Method/FormInterface.php +++ b/src/Method/FormInterface.php @@ -8,5 +8,5 @@ interface FormInterface public function validate(FormContextInterface $context) : bool; - public function execute(FormContextInterface $context) /* : mixed */; + public function execute(FormContextInterface $context); } \ No newline at end of file diff --git a/src/Method/Pagination.php b/src/Method/Pagination.php index e7bc69e..988ba7c 100644 --- a/src/Method/Pagination.php +++ b/src/Method/Pagination.php @@ -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 diff --git a/src/Method/PaginationHandler.php b/src/Method/PaginationHandler.php index 46dfe9c..f015ccc 100644 --- a/src/Method/PaginationHandler.php +++ b/src/Method/PaginationHandler.php @@ -41,7 +41,7 @@ class PaginationHandler { } public function __toString() { - return "hello world"; + return ""; } }