From d6c8af014b4c7fdedb3e18daa34df22735663e59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Vo=C5=99=C3=AD=C5=A1ek?= Date: Sun, 20 Aug 2023 20:45:42 +0200 Subject: [PATCH] Test docs build using CI (#2086) --- .github/workflows/test-unit.yml | 25 ++++++++ docs/app.md | 12 ++-- docs/autocomplete.md | 2 +- docs/baseline.txt | 103 ++++++++++++++++++++++++++++++++ docs/breadcrumb.md | 2 +- docs/callbacks.md | 4 +- docs/components.md | 2 +- docs/console.md | 4 +- docs/dataexecutor.md | 20 +++---- docs/fileupload.md | 6 +- docs/form-control.md | 30 ++++++---- docs/form.md | 32 +++++----- docs/grid.md | 16 ++--- docs/header.md | 3 + docs/icon.md | 6 +- docs/js.md | 35 +++++------ docs/loremipsum.md | 2 +- docs/misc.md | 3 + docs/multiline.md | 2 +- docs/overview.md | 4 +- docs/popup.md | 2 +- docs/requirements.txt | 2 +- docs/rightpanel.md | 2 +- docs/seed.md | 2 +- docs/table.md | 38 ++++++------ docs/tablecolumn.md | 24 ++++---- docs/template.md | 20 +++---- docs/tree-item-selector.md | 2 +- docs/type-presentation.md | 12 ++-- docs/view.md | 10 ++-- docs/virtualpage.md | 8 +-- 31 files changed, 285 insertions(+), 150 deletions(-) create mode 100644 docs/baseline.txt diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml index 289108fed5..0e9e3debee 100644 --- a/.github/workflows/test-unit.yml +++ b/.github/workflows/test-unit.yml @@ -455,3 +455,28 @@ jobs: token: ${{ secrets.CODECOV_TOKEN }} fail_ci_if_error: true files: coverage/merged.xml,coverage/js/clover.xml + + docs-test: + name: Docs + runs-on: ubuntu-latest + container: + image: ghcr.io/mvorisek/image-php:latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Install Python and dependencies + run: | + apk add python3 py3-pip + python --version + (cd docs && pip install -r requirements.txt) + + - name: Build + run: | + mv docs/baseline.txt docs/baseline.orig.txt + (cd docs && python -m sphinx -T -b html . out 2>&1 | tee baseline.txt) + sed -i -r 's~[^:]*/docs/([^:]*:)([0-9]+:)?~\1~;t;d' docs/baseline.txt + + - name: Diff build baseline + run: | + diff -u docs/baseline.orig.txt docs/baseline.txt diff --git a/docs/app.md b/docs/app.md index 5e186f29ba..b3d6606325 100644 --- a/docs/app.md +++ b/docs/app.md @@ -53,7 +53,7 @@ You may use App class hook to impact behavior of your application: - using hooks to globally impact object initialization - override methods to create different behavior, for example url() method may use advanced router logic to create beautiful URLs. -- you may re-define set-up of {php:class}`Persistence_i_Ui` and affect how data is loaded from UI. +- you may re-define set-up of {php:class}`Persistence\Ui` and affect how data is loaded from UI. - load templates from different files - use a different CDN settings for static files @@ -161,8 +161,8 @@ HelloWorld::addTo($app); $app->run(); ``` -If you do not want the application to automatically execute `run()` you can either set `$alwaysRun` to false -or use {php:meth}`terminate()` to the app with desired output. +If you do not want the application to automatically execute `run()` you can either set {php:attr}`App::$alwaysRun` to false +or use {php:meth}`App::terminate()` to the app with desired output. ## Exception handling @@ -210,7 +210,7 @@ Initializes all includes required by Agile UI. You may extend this class to add ::: Decodes current request without any arguments. If you are changing URL generation pattern, you -probably need to change this method to properly identify the current page. See {php:class}`App::url()` +probably need to change this method to properly identify the current page. See {php:meth}`App::url()` ## Loading Templates for Views @@ -286,7 +286,7 @@ No much magic in these methods. ## Database Connection -:::{php:property} db +:::{php:attr} db ::: If your `App` needs a DB connection, set this property to an instance of `Persistence`. @@ -434,7 +434,7 @@ Each layout, depending on it's content, may come with several views that you can ## Admin Layout -:::{php:class} Layout_i_Admin +:::{php:class} Layout\Admin ::: Agile Toolkit comes with a ready to use admin layout for your application. The layout is built diff --git a/docs/autocomplete.md b/docs/autocomplete.md index bf7fa3dc97..eb2d4fdf1b 100644 --- a/docs/autocomplete.md +++ b/docs/autocomplete.md @@ -5,7 +5,7 @@ # AutoComplete Form Control -:::{php:class} Form_i_Control_i_AutoComplete +:::{php:class} Form\Control\AutoComplete ::: Agile UI uses "Form\Control\Dropdown" by default on the form, but there is also implementation diff --git a/docs/baseline.txt b/docs/baseline.txt new file mode 100644 index 0000000000..46fb37c707 --- /dev/null +++ b/docs/baseline.txt @@ -0,0 +1,103 @@ +components.md: WARNING: toctree contains reference to nonexisting document 'field' +components.md: WARNING: toctree contains reference to nonexisting document 'loader' +components.md: WARNING: toctree contains reference to nonexisting document 'columns' +components.md: WARNING: toctree contains reference to nonexisting document 'dropdown' +core.md: WARNING: toctree contains reference to nonexisting document 'init' +core.md: WARNING: toctree contains reference to nonexisting document 'callback' +core.md: WARNING: toctree contains reference to nonexisting document 'stickyget' +tablecolumn.md: WARNING: duplicate object description of Atk4\Ui\Table\Column, other instance in /__w/ui/ui/docs/table.md +autocomplete.md: WARNING: document isn't included in any toctree +form-control.md: WARNING: document isn't included in any toctree +menu.md: WARNING: document isn't included in any toctree +multiline.md: WARNING: document isn't included in any toctree +session.md: WARNING: document isn't included in any toctree +tree-item-selector.md: WARNING: document isn't included in any toctree +app.md: [phpdomain] Target Atk4\Ui\Persistence\Ui not found +app.md: [phpdomain] Target Atk4\Ui\View::stickyGet not found +breadcrumb.md: [phpdomain] Target Atk4\Ui\View::url not found +components.md: [phpdomain] Target Atk4\Ui\Console::output not found +data.md: [phpdomain] Target Atk4\Ui\View::setSource not found +fileupload.md: [phpdomain] Target Atk4\Ui\Form\Control\Upload::onUpload not found +form.md: [phpdomain] Target Atk4\Ui\Form\Layout\Columns not found +form.md: [phpdomain] Target Atk4\Ui\ProxyModel not found +form.md: [phpdomain] Target Atk4\Ui\ProxyModel not found +form.md: [phpdomain] Target Atk4\Ui\Form\Control\Calendar::$type not found +form-control.md: [phpdomain] Target Atk4\Ui\Form::$typeToDecorator not found +form-control.md: [phpdomain] Target Atk4\Ui\Form\Control\Password not found +form-control.md: [phpdomain] Target Atk4\Ui\Form::renderRowFunction not found +form-control.md: [phpdomain] Target Atk4\Ui\Form::renderRowFunction not found +grid.md: [phpdomain] Target Atk4\Ui\Table\Column\Actions not found +grid.md: [phpdomain] Target Atk4\Ui\Table\Column\Actions::addAction not found +grid.md: [phpdomain] Target Atk4\Ui\Table\Column\Actions::addModal not found +icon.md: [phpdomain] Target Atk4\Ui\HtmlTemplate not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target #modals-and-reloading not found +js.md: [phpdomain] Target Atk4\Ui\App:requireJs not found +js.md: [phpdomain] Target Atk4\Ui\Js\JsChain::_jsonEncode not found +js.md: [phpdomain] Target Atk4\Ui\App::includeJS not found +js.md: [phpdomain] Target Atk4\Ui\App::includeCSS not found +message.md: [phpdomain] Target Atk4\Ui\Text::addParagraph not found +overview.md: [phpdomain] Target Atk4\Ui\HtmlTemplate not found +popup.md: [phpdomain] Target Atk4\Ui\Dropdown not found +table.md: [phpdomain] Target Atk4\Ui\View::setSource not found +table.md: [phpdomain] Target Atk4\Ui\Table::$useHtmlTags not found +table.md: [phpdomain] Target Atk4\Ui\Table::addTotals not found +table.md: [phpdomain] Target Atk4\Ui\Table::$tRow not found +table.md: [phpdomain] Target Atk4\Ui\Table::$tRow not found +table.md: [phpdomain] Target Atk4\Ui\Table::$tEmpty not found +table.md: [phpdomain] Target Atk4\Ui\addTotals not found +table.md: [phpdomain] Target Atk4\Ui\Table\Column\Money::getDataCellTemplate not found +table.md: [phpdomain] Target Atk4\Ui\Table\Column\Link::getDataCellTemplate not found +table.md: [phpdomain] Target Atk4\Ui\Lister::addJsPaginator not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Card not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Money not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Action not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\CheckBox not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Ordering not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Multiformat not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Table::addTotals not found +tablecolumn.md: [phpdomain] Target Atk4\Ui\Table:jsRow not found +template.md: [phpdomain] Target Atk4\Ui\HtmlTemplate::loadTemplate not found +template.md: [phpdomain] Target Atk4\Ui\HtmlTemplate::loadFromString not found +template.md: [phpdomain] Target Atk4\Ui\HtmlTemplate::set not found +template.md: [phpdomain] Target Atk4\Ui\HtmlTemplate::renderToHtml not found +template.md: [phpdomain] Target Atk4\Ui\PathFinder not found +template.md: [phpdomain] Target Atk4\Ui\PathFinder not found +template.md: [phpdomain] Target Atk4\Ui\defaultTemplate not found +template.md: [phpdomain] Target Atk4\Ui\App_Web::setTags not found +type-presentation.md: [phpdomain] Target Atk4\Ui\Persistence\Ui not found +type-presentation.md: [phpdomain] Target Atk4\Ui\Form\Control\Calendar not found +type-presentation.md: [phpdomain] Target Atk4\Ui\Table::decoratorFactory not found +type-presentation.md: [phpdomain] Target Atk4\Data\Field not found +type-presentation.md: [phpdomain] Target Atk4\Ui\Table::$useHtmlTags not found +type-presentation.md: [phpdomain] Target Atk4\Ui\Persistence\Ui not found +view.md: [phpdomain] Target Atk4\Ui\string|array not found +view.md: [phpdomain] Target Atk4\Ui\HtmlTemplate not found +view.md: [phpdomain] Target Atk4\Ui\HtmlTemplate not found +view.md: [phpdomain] Target Atk4\Ui\HtmlTemplate not found +wizard.md: [phpdomain] Target Atk4\Ui\View::url not found +app.md: WARNING: undefined label: system_pattern +app.md: WARNING: undefined label: page_manager +app.md: WARNING: undefined label: page_manager +form-control.md: WARNING: undefined label: field_visibility +js.md: WARNING: 'myst' reference target not found: #modals-and-reloading +lister.md: WARNING: undefined label: uipersistence +loremipsum.md: WARNING: undefined label: reloading +rightpanel.md: WARNING: undefined label: dynamic +seed.md: WARNING: undefined label: render tree +table.md: WARNING: undefined label: field_visibility +table.md: WARNING: undefined label: uipersistence +table.md: WARNING: undefined label: universal_data_access +table.md: WARNING: undefined label: uipersistence +tablecolumn.md: WARNING: undefined label: uipersistence +template.md: WARNING: undefined label: resource diff --git a/docs/breadcrumb.md b/docs/breadcrumb.md index 10de6c13c7..20640b44e4 100644 --- a/docs/breadcrumb.md +++ b/docs/breadcrumb.md @@ -53,7 +53,7 @@ Calling addCrumb adds more elements into the $path property. Each element there - link - where to go if clicked - divider - which divider to use after the crumb -By default `divider` is set to {php:attr}`Breadcrumb::dividerClass`. You may also manipulate $path array yourself. +By default `divider` is set to {php:attr}`Breadcrumb::$dividerClass`. You may also manipulate $path array yourself. For example the next code will use some logic: ``` diff --git a/docs/callbacks.md b/docs/callbacks.md index 16eb369131..1ef0d8a443 100644 --- a/docs/callbacks.md +++ b/docs/callbacks.md @@ -109,7 +109,7 @@ if ($cb->set(function () { return true; })) { ``` This example uses return of the {php:meth}`Callback::set()` to add class to a label, however a -much more preferred way is to use {php:attr}`$triggered`. +much more preferred way is to use {php:attr}`Callback::$triggered`. :::{php:attr} triggered ::: @@ -176,7 +176,7 @@ CallbackLater is used by several actions in Agile UI, such as JsReload(), and en you are reloading are fully rendered by the time callback is executed. Given our knowledge of Callbacks, lets take a closer look at how JsReload actually works. So what do we -know about {php:class}`Js_i_JsReload` already? +know about {php:class}`Js\JsReload` already? - JsReload is class implementing JsExpressionable - you must specify a view to JsReload diff --git a/docs/components.md b/docs/components.md index aacee71cee..714ca36798 100644 --- a/docs/components.md +++ b/docs/components.md @@ -41,7 +41,7 @@ label text loremipsum header -beadcrumb +breadcrumb icon image message diff --git a/docs/console.md b/docs/console.md index cc6dd8b0a9..400ccd8f49 100644 --- a/docs/console.md +++ b/docs/console.md @@ -89,7 +89,7 @@ $console->runMethod('StaticLib', 'myStaticMethod'); :::{php:method} exec($cmd, $args) ::: -:::{php:argument} lastExitCode +:::{php:attr} lastExitCode ::: To execute a command, use: @@ -122,7 +122,7 @@ Console::addTo($app)->set(function (Console $c) { ``` Method exec() will return `$this` if command was run inside callback and was successful. It will return `false` on error -and will return `null` if called outside of callback. You may also refer to {php:attr}`Console::lastExitCode` which +and will return `null` if called outside of callback. You may also refer to {php:attr}`Console::$lastExitCode` which contains exit code of the last command. Normally it's safe to chain `exec` which ensures that execution will stack. Should any command fail, the subsequent diff --git a/docs/dataexecutor.md b/docs/dataexecutor.md index 1903f4e80c..37a688e3ef 100644 --- a/docs/dataexecutor.md +++ b/docs/dataexecutor.md @@ -19,15 +19,15 @@ Demo: https://ui.atk4.org/demos/data-action/actions.php All executors must implement the ExecutorInterface or JsExecutorInterface interface. -:::{php:interface} UserAction_i_ExecutorInterface +:::{php:interface} UserAction\ExecutorInterface ::: -:::{php:interface} UserAction_i_JsExecutorInterface +:::{php:interface} UserAction\JsExecutorInterface ::: ## Basic Executor -:::{php:class} UserAction_i_BasicExecutor +:::{php:class} UserAction\BasicExecutor ::: This is the base view for most of the other action executors. This executor generally @@ -40,7 +40,7 @@ BasicExecutor will display: ## Preview Executor -:::{php:class} UserAction_i_PreviewExecutor +:::{php:class} UserAction\PreviewExecutor ::: This executor is specifically set in order to display the $preview property of the current model UserAction. @@ -48,7 +48,7 @@ You can select to display the preview using regular console type container, regu ## Form Executor -:::{php:class} UserAction_i_FormExecutor +:::{php:class} UserAction\FormExecutor ::: This executor will display a form where user is required to fill in either all model fields or certain model fields @@ -56,7 +56,7 @@ depending on the model UserAction $field property. Form control will depend on m ## Argument Form Executor -:::{php:class} UserAction_i_ArgumentFormExecutor +:::{php:class} UserAction\ArgumentFormExecutor ::: This executor will display a form but instead of filling form control with model field, it will use model UserAction @@ -65,7 +65,7 @@ The type of form control type to be used in form will depend on how $args is set ## JS Callaback Executor -:::{php:class} UserAction_i_JsCallbackExecutor +:::{php:class} UserAction\JsCallbackExecutor ::: This type of executor will output proper javascript that you can assign to a view event using View::on() method. @@ -73,7 +73,7 @@ It is also possible to pass the UserAction argument via $_POST argument. ## Modal Executor -:::{php:class} UserAction_i_ModalExecutor +:::{php:class} UserAction\ModalExecutor ::: The ModalExecutor is base on Modal view. This is a one size fits all for model UserAction. When setting the UserAction via the @@ -93,7 +93,7 @@ Modal::$title property. ## Confirmation Executor -:::{php:class} UserAction_i_ConfirmationExecutor +:::{php:class} UserAction\ConfirmationExecutor ::: Like ModalExecutor, Confirmation executor is also based on a Modal view. It allow to display UserAction::confirmation property prior to @@ -129,7 +129,7 @@ other hand, if MODIFIER_UPDATE is set, then Table needs to be reloaded. ## The Executor Factory -:::{php:class} UserAction_i_ExecutorFactory +:::{php:class} UserAction\ExecutorFactory ::: :::{php:attr} executorSeed diff --git a/docs/fileupload.md b/docs/fileupload.md index 6d72a1ea75..14f5018b63 100644 --- a/docs/fileupload.md +++ b/docs/fileupload.md @@ -14,7 +14,7 @@ in steps: 1. User arrives at the page with a form 2. User selects file. 3. File begins uploading. -4. PHP upload callback {php:meth}`Form_i_Control_i_Upload::onUpload` is called, returns "file_id" +4. PHP upload callback {php:meth}`Form\Control\Upload::onUpload` is called, returns "file_id" 5. "file_id" is placed inside form. 6. User submits the form 7. {php:meth}`Form::onSubmit()` receives "file_id" @@ -24,7 +24,7 @@ it can be removed. Both Upload and UploadImage controls contain an upload button open a File Selection dialog. UploadImage also implements image preview icon. During upload, a progress bar will appear. -:::{php:class} Form_i_Control_i_Upload +:::{php:class} Form\Control\Upload ::: ## Attributes @@ -134,7 +134,7 @@ $img->onDelete(function (string $fileId) use ($img) { Similar to Upload, this is a control implementation for uploading images. Here are additional properties: -:::{php:class} Form_i_Control_i_UploadImage +:::{php:class} Form\Control\UploadImage ::: UploadImage form control inherits all of the Upload properties plus these ones: diff --git a/docs/form-control.md b/docs/form-control.md index 9baecaad26..d5461d0cd6 100644 --- a/docs/form-control.md +++ b/docs/form-control.md @@ -5,7 +5,7 @@ # Form Controls -:::{php:class} Form_i_Control +:::{php:class} Form\Control ::: Agile UI dedicates a separate namespace for the Form Controls. Those are @@ -50,6 +50,10 @@ When used stand-alone, Form\Controls will produce a basic HTML (I have omitted i ### Using in-form +:::{php:attr} form +Form Control objects can be associated with a Form object. +::: + Form Control can also be used inside a form like this: ``` @@ -70,7 +74,7 @@ page and the following HTML is now produced: ``` The markup that surronds the button which includes Label and formatting is produced by -{php:class}`Form_i_Layout`, which does draw some of the information from the Form Control +{php:class}`Form\Layout`, which does draw some of the information from the Form Control itself. ### Using in Form Layouts @@ -94,7 +98,7 @@ $form->onSubmit(function (Form $form) { }); ``` -This is further explained in documentation for {php:class}`Form_i_Layout` class, +This is further explained in documentation for {php:class}`Form\Layout` class, however if you do plan on adding your own form control types, it's important that you extend it properly: @@ -131,7 +135,7 @@ $form->addControl('name', ['hint' => new \Atk4\Ui\Text( or you can inject a view with a custom template: ``` -$form->addControl('name', ['hint' => ['template' => new \Atk4\Ui\Template( +$form->addControl('name', ['hint' => ['template' => new \Atk4\Ui\HtmlTemplate( 'Click here' )]]); ``` @@ -195,9 +199,9 @@ Form Control Decorator. The rules are rather straightforward but may change in future versions of Agile UI: -- if [enum](https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$enum) is defined, use {php:class}`Form_i_Control_i_Dropdown` +- if [enum](https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$enum) is defined, use {php:class}`Form\Control\Dropdown` - consult {php:attr}`Form::$typeToDecorator` property for type-to-seed association -- type=password will use {php:class}`Form_i_Control_i_Password` +- type=password will use {php:class}`Form\Control\Password` You always have an option to explicitly specify which field you would like to use: @@ -228,7 +232,7 @@ the value of the field would be read from `$decorator->entityField->get()`. ## Line Input Form control -:::{php:class} Form_i_Control_i_Input +:::{php:class} Form\Control\Input Implements View for presenting Input form controls. Based around https://fomantic-ui.com/elements/input.html. ::: @@ -305,7 +309,7 @@ To see various examples of form controls and their attributes see `demos/form-co ### Integration with Form -When you use {php:class}`Form::addControl()` it will create 'Form Control Decorator' +When you use {php:meth}`Form::addControl()` it will create 'Form Control Decorator' ### JavaScript on Input @@ -345,7 +349,7 @@ $c1->onChange(\Atk4\Ui\Js\JsExpression('console.log(\'c1 changed: \' + date + \' ## Dropdown -:::{php:class} Form_i_Control_i_Dropdown +:::{php:class} Form\Control\Dropdown ::: Dropdown uses Fomantic-UI Dropdown (https://fomantic-ui.com/modules/dropdown.html). A Dropdown can be used in two ways: @@ -354,10 +358,10 @@ Dropdown uses Fomantic-UI Dropdown (https://fomantic-ui.com/modules/dropdown.htm ### Usage with a Model -A Dropdown is not used as default Form Control decorator (`$model->hasOne()` uses {php:class}`Form_i_Control_i_Lookup`), but in your Model, you can define that +A Dropdown is not used as default Form Control decorator (`$model->hasOne()` uses {php:class}`Form\Control\Lookup`), but in your Model, you can define that UI should render a Field as Dropdown. For example, this makes sense when a `hasOne()` relationship only has a very limited amount (like 20) of records to display. Dropdown renders all records when the paged is rendered, while Lookup always sends an additional request to the server. -{php:class}`Form_i_Control_i_Lookup` on the other hand is the better choice if there is lots of records (like more than 50). +{php:class}`Form\Control\Lookup` on the other hand is the better choice if there is lots of records (like more than 50). To render a model field as Dropdown, use the ui property of the field: @@ -516,7 +520,7 @@ $this->addField('expressions', [ ## DropdownCascade -:::{php:class} Form_i_Control_i_DropdownCascade +:::{php:class} Form\Control\DropdownCascade ::: DropdownCascade input are extend from Dropdown input. They rely on `cascadeFrom` and `reference` property. @@ -548,7 +552,7 @@ $form->addControl('product_id', [DropdownCascade::class, 'cascadeFrom' => 'sub_c ## Lookup -:::{php:class} Form_i_Control_i_Lookup +:::{php:class} Form\Control\Lookup ::: Lookup input is also based on Fomantic-UI dropdown module but with ability to dynamically request server for data it's diff --git a/docs/form.md b/docs/form.md index 56a549831a..aabd210637 100644 --- a/docs/form.md +++ b/docs/form.md @@ -80,8 +80,8 @@ $form->model->set([ Form also relies on a `\Atk4\Ui\Form::Layout` class and displays form controls through decorators defined at `\Atk4\Ui\Form::Control`. See dedicated documentation for: -- {php:class}`Form::Layout` -- {php:class}`Form::Control` +- {php:class}`Form\Layout` +- {php:class}`Form\Control` To tweak the UI properties of an form control input use `setInputAttr()` (and not the surrounding `
` as `setAttr()` would do). Here is how to set the HTML "maxlength" attribute on the generated input field: @@ -110,7 +110,7 @@ The basic 2-line syntax will extract all the required logic from the Model inclu - Fields defined for this Model will be displayed - Display of default values in the form - Depending on the field type, a form control will be selected from Form\Control namespace -- Using {php:class}`Form_i_Layout_i_Columns` can make form more compact by splitting it into columns +- Using {php:class}`Form\Layout\Columns` can make form more compact by splitting it into columns - Form control captions, placeholders, hints and other elements defined in Field::ui are respected (https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$ui) - Fields that are not editable by default will not appear on the form (https://atk4-data.readthedocs.io/en/develop/fields.html#Field::isEditable) - Field typecasting will be invoked such as for converting dates @@ -186,7 +186,7 @@ $form->setModel(new User($db), ['email', 'gender', 'terms']); ``` Form control does not have to be added directly into the form. You can use a separate -{php:class}`Form_i_Layout` or even a regular view. Simply specify property {php:meth}`Form_i_Control::$form`: +{php:class}`Form\Layout` or even a regular view. Simply specify property {php:meth}`Form\Control::$form`: ``` $myview = View::addTo($form, ['defaultTemplate' => './mytemplate.html']); @@ -214,7 +214,7 @@ is documented here: https://atk4-data.readthedocs.io/en/develop/fields.html Form uses a small UI component to visualize HTML input fields associated with the respective Model Field. We call this object "Form Control". All form -controls extend from class {php:class}`Form::Control`. +controls extend from class {php:class}`Form\Control`. Agile UI comes with at least the following form controls: @@ -241,7 +241,7 @@ $form->addControl('time', $calendar); ``` For more information on default form controls as well as examples on how to create -your own see documentation on {php:class}`Form::Control`. +your own see documentation on {php:class}`Form\Control`. :::{php:method} controlFactory(\Atk4\Data\Field $field, $defaults = []) ::: @@ -388,7 +388,7 @@ class User extends \Atk4\Data\Model } ``` -The seed for the UI will be combined with the default overriding {php:attr}`Form_i_Control_i_Calendar::type` +The seed for the UI will be combined with the default overriding {php:attr}`Form\Control\Calendar::$type` to allow month/year entry by the Calendar extension, which will then be saved and stored as a regular date. Obviously you can also specify decorator class: @@ -553,11 +553,11 @@ Specify a PHP callback that will be executed on successful form submission. ::: :::{php:method} jsError($field, $message) -Create and return {php:class}`Js_i_JsChain` action that will indicate error on a form control. +Create and return {php:class}`Js\JsChain` action that will indicate error on a form control. ::: :::{php:method} jsSuccess($title, [$subTitle]) -Create and return {php:class}`Js_i_JsChain` action, that will replace form with a success message. +Create and return {php:class}`Js\JsChain` action, that will replace form with a success message. ::: :::{php:method} setApiConfig($config) @@ -593,7 +593,7 @@ $form->onSubmit(function (Form $form) { ``` Callback function can return one or multiple JavaScript actions. Methods such as -{php:meth}`jsError()` or {php:meth}`jsSuccess()` will help initialize those actions for your form. +{php:meth}`Form::jsError()` or {php:meth}`Form::jsSuccess()` will help initialize those actions for your form. Here is a code that can be used to output multiple errors at once. Errors were intentionally not grouped with a message about failure to accept of terms and conditions: @@ -641,8 +641,8 @@ will not be included in response for security reasons. ### Form Layout and Sub-layout -As stated above, when a Form object is created and form controls are added through either {php:meth}`addControl()` -or {php:meth}`setModel()`, the form controls will appear one under each-other. This arrangement of form controls as +As stated above, when a Form object is created and form controls are added through either {php:meth}`Form::addControl()` +or {php:meth}`Form::setModel()`, the form controls will appear one under each-other. This arrangement of form controls as well as display of labels and structure around the form controls themselves is not done by a form, but another object - "Form Layout". This object is responsible for the form control flow, presence of labels etc. @@ -661,7 +661,7 @@ Adds a form header with a text label. Returns View. ::: :::{php:method} addGroup($header) -Creates a sub-layout, returning new instance of a {php:class}`Form_i_Layout` object. You +Creates a sub-layout, returning new instance of a {php:class}`Form\Layout` object. You can also specify a header. ::: @@ -721,7 +721,7 @@ $group->addControl('last_name', ['width' => 'five']); There are four specific sub layout views that you can add to your existing form layout: Generic, Accordion, Tabs and Columns. Generic sub layout is simply another layout view added to your existing form layout view. You add fields -the same way as you would do for {php:class}`Form_i_Layout`. +the same way as you would do for {php:class}`Form\Layout`. Sub layout section like Accordion, Tabs or Columns will create layout specific section where you can organize fields in either accordion, tabs or columns. @@ -895,7 +895,7 @@ $form->setGroupDisplayRules([ MOVE THIS TO SEPARATE FILE ::: -:::{php:class} Form_i_Layout +:::{php:class} Form\Layout Renders HTML outline encasing form controls. ::: @@ -904,6 +904,6 @@ Form layout objects are always associated with a Form object. ::: :::{php:method} addControl() -Same as {php:class}`Form::addControl()` but will place a form control inside this specific layout +Same as {php:meth}`Form::addControl()` but will place a form control inside this specific layout or sub-layout. ::: diff --git a/docs/grid.md b/docs/grid.md index b1c1120415..64a5f52040 100644 --- a/docs/grid.md +++ b/docs/grid.md @@ -67,7 +67,7 @@ $grid = Grid::addTo($app, ['menu' => false]); :::{php:method} addQuickSearch($fields = [], $hasAutoQuery = false) ::: -After you have associated grid with a model using {php:class}`View::setModel()` you can +After you have associated grid with a model using {php:meth}`View::setModel()` you can include quick-search component: ``` @@ -132,7 +132,7 @@ fixed height of your table container. :::{php:method} addActionButton($button, $action, $confirm = false) ::: -{php:class}`Table` supports use of {php:class}`Table_i_Column_i_Actions`, which allows to display button for each row. +{php:class}`Table` supports use of {php:class}`Table\Column\Actions`, which allows to display button for each row. Calling addActionButton() provides a useful short-cut for creating column-based actions. $button can be either a string (for a button label) or something like `['icon' => 'book']`. @@ -141,7 +141,7 @@ If $confirm is set to true, then user will see a confirmation when he clicks on Calling this method multiple times will add button into same action column. -See {php:meth}`Table_i_Column_i_Actions::addAction` +See {php:meth}`Table\Column\Actions::addAction` :::{php:method} addModalAction($button, $title, $callback) ::: @@ -160,7 +160,7 @@ $grid->addModalAction('Details', 'Additional Details', function (View $p, $id) u Calling this method multiple times will add button into same action column. -See {php:meth}`Table_i_Column_i_Actions::addModal` +See {php:meth}`Table\Column\Actions::addModal` ## Column Menus @@ -170,13 +170,13 @@ See {php:meth}`Table_i_Column_i_Actions::addModal` :::{php:method} addPopup($columnName, $popup = null, $icon = 'caret square down') ::: -Methods addDropdown and addPopup provide a wrapper for {php:meth}`Table_i_Column::addDropdown` and -{php:meth}`Table_i_Column::addPopup` methods. +Methods addDropdown and addPopup provide a wrapper for {php:meth}`Table\Column::addDropdown` and +{php:meth}`Table\Column::addPopup` methods. ## Selection -Grid can have a checkbox column for you to select elements. It relies on {php:class}`Table_i_Column_i_Checkbox`, but will -additionally place this column before any other column inside a grid. You can use {php:meth}`Table_i_Column_i_Checkbox::jsChecked()` +Grid can have a checkbox column for you to select elements. It relies on {php:class}`Table\Column\Checkbox`, but will +additionally place this column before any other column inside a grid. You can use {php:meth}`Table\Column\Checkbox::jsChecked()` method to reference value of selected checkboxes inside any {ref}`js_action`: ``` diff --git a/docs/header.md b/docs/header.md index 76fa1c972a..1b57a4414e 100644 --- a/docs/header.md +++ b/docs/header.md @@ -3,6 +3,9 @@ # Header +:::{php:class} Header +::: + Can be used for page or section headers. Based around: https://fomantic-ui.com/elements/header.html. diff --git a/docs/icon.md b/docs/icon.md index 12fd15d84f..4a78056c8c 100644 --- a/docs/icon.md +++ b/docs/icon.md @@ -68,11 +68,11 @@ Label::addTo($app, ['Label', 'class.right ribbon red' => true, 'icon' => 'flippe ## Groups -Fomantic-UI support icon groups. The best way to implement is to supply {php:class}`Template` to an +Fomantic-UI support icon groups. The best way to implement is to supply {php:class}`HtmlTemplate` to an icon: ``` -Icon::addTo($app, ['template' => new \Atk4\Ui\Template(' +Icon::addTo($app, ['template' => new \Atk4\Ui\HtmlTemplate(' '), false]); @@ -161,7 +161,7 @@ class SocialAdd extends \Atk4\Ui\View if (!$this->template) { // TODO: Place template into file and set defaultTemplate instead - $this->template = new \Atk4\Ui\Template( + $this->template = new \Atk4\Ui\HtmlTemplate( '<{_element}button{/} class="ui ' . $this->social . ' button" {$attributes}> {$Icon} diff --git a/docs/js.md b/docs/js.md index 47cdb51800..6e7b1014f9 100644 --- a/docs/js.md +++ b/docs/js.md @@ -40,7 +40,7 @@ the code for hiding a view can be generated by calling: $action = $view->js()->hide(); ``` -There are other ways to generate an action, such as using {php:class}`Js_i_JsExpression`: +There are other ways to generate an action, such as using {php:class}`Js\JsExpression`: ``` $action = new JsExpression('alert([])', ['Hello world']); @@ -141,7 +141,7 @@ for details. ## Building actions with JsExpressionable -:::{php:interface} Js_i_JsExpressionable +:::{php:interface} Js\JsExpressionable Allow objects of the class implementing this interface to participate in building JavaScript expressions. ::: @@ -166,7 +166,7 @@ $('#button-id').appendTo('#frame-id'); ### JavaScript Chain Building -:::{php:class} Js_i_JsChain +:::{php:class} Js\JsChain Base class JsChain can be extended by other classes such as Jquery to provide transparent mappers for any JavaScript framework. ::: @@ -181,7 +181,7 @@ $chain = new Jquery('#the-box-id'); $chain->dropdown(); ``` -The calls to the chain are stored in the object and can be converted into JavaScript by calling {php:meth}`Js_i_JsChain::jsRender()` +The calls to the chain are stored in the object and can be converted into JavaScript by calling {php:meth}`Js\JsChain::jsRender()` :::{php:method} jsRender() Converts actions recorded in JsChain into string of JavaScript code. @@ -207,9 +207,9 @@ JavaScript binding and also decides which actions should be available while crea :::{php:method} _jsEncode JsChain will map all the other methods into JS counterparts while encoding all the arguments using `_jsEncode()`. Although similar to the standard JSON encode function, this method quotes strings using single quotes -and recognizes {php:interface}`Js_i_JsExpressionable` objects and will substitute them with the result of -{php:meth}`Js_i_JsExpressionable::jsRender`. The result will not be escaped and any object implementing -{php:interface}`Js_i_JsExpressionable` interface is responsible for safe JavaScript generation. +and recognizes {php:interface}`Js\JsExpressionable` objects and will substitute them with the result of +{php:meth}`Js\JsExpressionable::jsRender`. The result will not be escaped and any object implementing +{php:interface}`Js\JsExpressionable` interface is responsible for safe JavaScript generation. ::: The following code is safe: @@ -227,10 +227,7 @@ argument to `text()`. We are not building JavaScript code just for the exercise. Our whole point is ability to link that code between actual views. All views support JavaScript binding through two methods: {php:meth}`View::js()` and {php:meth}`View::on()`. -:::{php:class} View -::: - -:::{php:method} js([$event, [$otherChain]]) +:::{php:method} View::js([$event, [$otherChain]]) Return action chain that targets this view. As event you can specify `true` which will make chain automatically execute on document ready event. You can specify a specific JavaScript event such as `click` or `mousein`. You can also use your custom event that you would trigger manually. If `$event` is false or null, no event binding will be performed. @@ -249,7 +246,7 @@ $b2 = new Button('Two'); $b2->js('click', $b1->js()->hide()); ``` -:::{php:method} on(String $event, [String selector], $callback = null) +:::{php:method} View::on(String $event, [String selector], $callback = null) Returns chain that will be automatically executed if $event occurs. If $callback is specified, it will also be executed on event. ::: @@ -297,7 +294,7 @@ $buttons->on('click', '.button', $b3->js()->hide()); ## JsExpression -:::{php:class} Js_i_JsExpression +:::{php:class} Js\JsExpression ::: :::{php:method} __construct(template, args) @@ -313,8 +310,8 @@ $action = new JsExpression('alert([])', [ ]); ``` -Because {php:class}`Js_i_JsChain` will typically wrap all the arguments through -{php:meth}`Js_i_JsChain::_jsonEncode()`, it prevents you from accidentally injecting JavaScript code: +Because {php:class}`Js\JsChain` will typically wrap all the arguments through +{php:meth}`Js\JsChain::_jsonEncode()`, it prevents you from accidentally injecting JavaScript code: ``` $b = new Button(); @@ -429,7 +426,7 @@ There are two modal implementations in ATK: - View - Modal: This works with a pre-existing Div, shows it and can be populated with contents; - JsModal: This creates an entirely new modal Div and then populates it. -In contrast to {php:class}`Modal`, the HTML `
` element generated by {php:class}`Js_i_JsModal` +In contrast to {php:class}`Modal`, the HTML `
` element generated by {php:class}`Js\JsModal` is always destroyed when the modal is closed instead of only hiding it. ### Modal @@ -490,7 +487,7 @@ or `contentCss` or use the method `addContentCss()`. See the Fomantic-UI modal d ### JsModal -:::{php:class} Js_i_JsModal +:::{php:class} Js\JsModal ::: This alternative implementation to {php:class}`Modal` is convenient for situations @@ -515,7 +512,7 @@ See [Modals and reloading](#modals-and-reloading) concerning the intricacies bet ## Reloading -:::{php:class} Js_i_JsReload +:::{php:class} Js\JsReload ::: JsReload is a JavaScript action that performs reload of a certain object: @@ -548,7 +545,7 @@ In this example, filling out and submitting the form will result in table conten ### Modals and reloading -Care needs to be taken when attempting to combine the above with a {php:class}`Js_i_JsModal` which requires a {ref}`virtualpage` to +Care needs to be taken when attempting to combine the above with a {php:class}`Js\JsModal` which requires a {ref}`virtualpage` to store its contents. In that case, the order in which declarations are made matters because of the way the Render Tree is processed. diff --git a/docs/loremipsum.md b/docs/loremipsum.md index 4e37ee3f8d..ad63b69e17 100644 --- a/docs/loremipsum.md +++ b/docs/loremipsum.md @@ -1,7 +1,7 @@ :::{php:namespace} Atk4\Ui ::: -(text)= +(loremipsum)= # LoremIpsum diff --git a/docs/misc.md b/docs/misc.md index 03deebcacb..730240e5f3 100644 --- a/docs/misc.md +++ b/docs/misc.md @@ -3,6 +3,9 @@ # Columns +:::{php:class} Columns +::: + This class implements CSS Grid or ability to divide your elements into columns. If you are an expert designer with knowledge of HTML/CSS we recommend you to create your own layouts and templates, but if you are not sure how to do that, then using "Columns" class might be a good alternative for some diff --git a/docs/multiline.md b/docs/multiline.md index af7a9c4789..1528f0ed41 100644 --- a/docs/multiline.md +++ b/docs/multiline.md @@ -1,7 +1,7 @@ :::{php:namespace} Atk4\Ui ::: -:::{php:class} Form_i_Control_i_Multiline +:::{php:class} Form\Control\Multiline ::: # Multiline Form Control diff --git a/docs/overview.md b/docs/overview.md index 19df3251c1..b436956eaa 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -259,7 +259,7 @@ https://atk4-core.readthedocs.io/en/develop/factory.html ### Templates -Components rely on {php:class}`Template` class for parsing and rendering their +Components rely on {php:class}`HtmlTemplate` class for parsing and rendering their HTML. The default template is written for Fomantic-UI framework, which makes sure that elements will look good and be consistent. @@ -277,7 +277,7 @@ Using App class will utilize a minimum of 2 templates: As you add more components, they will appear inside your layout. -You'll also find that a layout class such as {php:class}`Layout_i_Admin` will initialize +You'll also find that a layout class such as {php:class}`Layout\Admin` will initialize some components on its own - sidebar menu, top menu. :::{image} images/admin-layout.png diff --git a/docs/popup.md b/docs/popup.md index 4e3624f3d6..ef9915f5b9 100644 --- a/docs/popup.md +++ b/docs/popup.md @@ -30,7 +30,7 @@ Pop-up should be added into a viewport which will define boundaries of a pop-up, be positioned relative to the $button. Popup remains invisible until it's triggered by event of $button. If second argument in the {ref}`seed` is of class {php:class}`Button`, {php:class}`Menu`, -{php:class}`MenuItem` or {php:class}`Dropdown` (note - NOT {php:class}`Form_i_Control`!), pop-up will also bind itself +{php:class}`MenuItem` or {php:class}`Dropdown` (note - NOT {php:class}`Form\Control`!), pop-up will also bind itself to that element. The above example will automatically bind "click" event of a button to open a pop-up. When added into a menu, pop-up will appear on hover: diff --git a/docs/requirements.txt b/docs/requirements.txt index 8aa7f5d9f9..c91f57ce16 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ sphinx<5 sphinx-rtd-theme -sphinxcontrib-phpdomain +sphinxcontrib-phpdomain @ git+https://github.com/markstory/sphinxcontrib-phpdomain@f785b8b333 myst-parser linkify-it-py diff --git a/docs/rightpanel.md b/docs/rightpanel.md index b29fe7a7e0..ef917ed650 100644 --- a/docs/rightpanel.md +++ b/docs/rightpanel.md @@ -5,7 +5,7 @@ # Right Panel -:::{php:class} Panel_i_Right +:::{php:class} Panel\Right ::: Right panel are view attached to the app layout. They are display on demand via javascript event diff --git a/docs/seed.md b/docs/seed.md index b07436c8dc..381384021f 100644 --- a/docs/seed.md +++ b/docs/seed.md @@ -91,7 +91,7 @@ $seed = [new Button('hello', 'class.big red' => true), 'icon' => ['book', 'class ## Additional cases An individual object may add more ways to deal with seed. For example, when adding columns -to your Table you can specify seed for the decorator: {php:class}`Table_i_Column`: +to your Table you can specify seed for the decorator: {php:class}`Table\Column`: ``` $table->addColumn('salary', [\Atk4\Ui\Table\Column\Money::class]); diff --git a/docs/table.md b/docs/table.md index a7ee7f9143..a4ba7cbbcd 100644 --- a/docs/table.md +++ b/docs/table.md @@ -9,7 +9,7 @@ ::: :::{important} -For columns, see {php:class}`Table_i_Column`. For DIV-based lists, see {php:class}`Lister`. For an +For columns, see {php:class}`Table\Column`. For DIV-based lists, see {php:class}`Lister`. For an interactive features see {php:class}`Grid` and {php:class}`Crud`. ::: @@ -152,7 +152,7 @@ display values of specific model Field. :::{php:method} columnFactory(\Atk4\Data\Field $field) ::: -If the value of the field can be displayed by {php:class}`Table_i_Column` then {php:class}`Table` will +If the value of the field can be displayed by {php:class}`Table\Column` then {php:class}`Table` will respord with object of this class. Since the default column does not contain any customization, then to save memory Table will re-use the same objects for all generic fields. @@ -175,10 +175,10 @@ it will automatically delete the corresponding record. You have probably noticed, that I have omitted the name for this column. If name is not specified (null) then the Column object will not be associated with any model field in -{php:meth}`Table_i_Column::getHeaderCellHtml`, {php:meth}`Table_i_Column::getTotalsCellHtml` and -{php:meth}`Table_i_Column::getDataCellHtml`. +{php:meth}`Table\Column::getHeaderCellHtml`, {php:meth}`Table\Column::getTotalsCellHtml` and +{php:meth}`Table\Column::getDataCellHtml`. -Some columns require name, such as {php:class}`Table_i_Column` will +Some columns require name, such as {php:class}`Table\Column` will not be able to cope with this situations, but many other column types are perfectly fine with this. Some column classes will be able to take some information from a specified column, but will work @@ -274,7 +274,7 @@ For more information see https://github.com/kylefox/jquery-tablesort ### Injecting HTML -The tag will override model value. Here is example usage of {php:meth}`Table_i_Column::getHtmlTags`: +The tag will override model value. Here is example usage of {php:meth}`Table\Column::getHtmlTags`: ``` class ExpiredColumn extends \Atk4\Ui\Table\Column @@ -300,7 +300,7 @@ Your column now can be added to any table: $table->addColumn(new ExpiredColumn()); ``` -IMPORTANT: HTML injection will work unless {php:attr}`Table::useHtmlTags` property is disabled (for performance). +IMPORTANT: HTML injection will work unless {php:attr}`Table::$useHtmlTags` property is disabled (for performance). ## Table Data Handling @@ -339,7 +339,7 @@ data stored inside your own database. Either way, several principles apply to th ### Table Rendering Steps Once model is specified to the Table it will keep the object until render process will begin. Table -columns can be defined any time and will be stored in the {php:attr}`Table::columns` property. Columns +columns can be defined any time and will be stored in the {php:attr}`Table::$columns` property. Columns without defined name will have a numeric index. It's also possible to define multiple columns per key in which case we call them "decorators". @@ -350,14 +350,14 @@ During the render process (see {php:meth}`View::renderView`) Table will perform 3. Iterate through rows 1. Current row data is accessible through $table->model property. 2. Update Totals if {php:meth}`Table::addTotals` was used. - 3. Insert row values into {php:attr}`Table::tRow` + 3. Insert row values into {php:attr}`Table::$tRow` 1. Template relies on {ref}`uiPersistence` for formatting values 4. Collect HTML tags from 'getHtmlTags' hook. 5. Collect getHtmlTags() from columns objects - 6. Inject HTML into {php:attr}`Table::tRow` template + 6. Inject HTML into {php:attr}`Table::$tRow` template 7. Render and append row template to Table Body ({$Body}) 8. Clear HTML tag values from template. -4. If no rows were displayed, then "empty message" will be shown (see {php:attr}`Table::tEmpty`). +4. If no rows were displayed, then "empty message" will be shown (see {php:attr}`Table::$tEmpty`). 5. If {php:meth}`addTotals` was used, append totals row to table footer. ## Dealing with Multiple decorators @@ -393,7 +393,7 @@ is not set or type is like "integer", then a generic formatter is used. There are a few things to note: -1. Property {php:attr}`Table::columns` contains either a single or multiple decorators for each +1. Property {php:attr}`Table::$columns` contains either a single or multiple decorators for each column. Some tasks will be done by first decorator only, such as getting TH/header cell. Others will be done by all decorators, such as collecting classes / styles for the cell or wrapping formatted content (link, icon, template). @@ -401,8 +401,8 @@ There are a few things to note: 3. output of the \Atk4\Ui\Table\Column\Money decorator is used into Link decorator as if it would be value of cell, however decorators have access to original value also. Decorator implementation is usually aware of combinations. -{php:meth}`Table_i_Column_i_Money::getDataCellTemplate` is called, which returns ONLY the HTML value, -without the `` cell itself. Subsequently {php:meth}`Table_i_Column_i_Link::getDataCellTemplate` is called +{php:meth}`Table\Column\Money::getDataCellTemplate` is called, which returns ONLY the HTML value, +without the `` cell itself. Subsequently {php:meth}`Table\Column\Link::getDataCellTemplate` is called and the '{$salary}' tag from this link is replaced by output from Money column resulting in this template: @@ -515,7 +515,7 @@ See also {ref}`js`. ### Static Attributes and classes -:::{php:class} Table_i_Column +:::{php:class} Table\Column ::: :::{php:method} addClass($class, $scope = 'body') @@ -560,8 +560,8 @@ $table->addColumn('name', [\Atk4\Ui\Table\Column::class]) Setting a new value to the attribute will override previous value. -Please note that if you are redefining {php:meth}`Table_i_Column::getHeaderCellHtml`, -{php:meth}`Table_i_Column::getTotalsCellHtml` or {php:meth}`Table_i_Column::getDataCellHtml` +Please note that if you are redefining {php:meth}`Table\Column::getHeaderCellHtml`, +{php:meth}`Table\Column::getTotalsCellHtml` or {php:meth}`Table\Column::getDataCellHtml` and you wish to preserve functionality of setting custom attributes and classes, you should generate your TD/TH tag through getTag method. @@ -580,8 +580,8 @@ $cb = $table->addColumn('CheckBox'); ### Using dynamic values -Body attributes will be embedded into the template by the default {php:meth}`Table_i_Column::getDataCellHtml`, +Body attributes will be embedded into the template by the default {php:meth}`Table\Column::getDataCellHtml`, but if you specify attribute (or class) value as a tag, then it will be auto-filled with row value or injected HTML. -For further examples of and advanced usage, see implementation of {php:class}`Table_i_Column_i_Status`. +For further examples of and advanced usage, see implementation of {php:class}`Table\Column\Status`. diff --git a/docs/tablecolumn.md b/docs/tablecolumn.md index 6122224692..d6f5aa35c1 100644 --- a/docs/tablecolumn.md +++ b/docs/tablecolumn.md @@ -12,7 +12,7 @@ cell. This is in contrast to {php:class}`View` and {php:class}`Lister` which do not use Table/Cell and therefore Column decorator is not required. -All column decorators in Agile UI have a base class {php:class}`Table_i_Column`. Decorators will often +All column decorators in Agile UI have a base class {php:class}`Table\Column`. Decorators will often look at the content of the associated value, for example {php:class}`Money` will add cell class `negative` only if monetary value is less than zero. The value is taken from Model's Field object. @@ -27,14 +27,14 @@ but if record is already archived, use a template "Archived on {$archive_date}". ## Generic Column Decorator -:::{php:class} Table_i_Column +:::{php:class} Table\Column Generic description of a column for {php:class}`Table` ::: Table object relies on a separate class: `\Atk4\Ui\Table\Column` to present most of the values. The goals of the column object is to format anything around the actual values. The type = 'atk4_money' will result in a custom formatting of the value, but will also require column to be right-aligned. To simplify this, -type = 'atk4_money' will use a different column class - {php:class}`Table_i_Column_i_Money`. There are several others, +type = 'atk4_money' will use a different column class - {php:class}`Table\Column\Money`. There are several others, but first we need to look at the generic column and understand it's base capabilities: A class resposnible for cell formatting. This class defines 3 main methods that is used by the Table @@ -107,7 +107,7 @@ $grid->addDropdown('name', ['Sort A-Z', 'Sort by Relevance'], function (string $ }); ``` -Those wrappers will invoke methods {php:meth}`Table_i_Column::addDropdown` and {php:meth}`Table_i_Column::addPopup` for +Those wrappers will invoke methods {php:meth}`Table\Column::addDropdown` and {php:meth}`Table\Column::addPopup` for a specified column, which are documented below. ### Popups @@ -158,11 +158,11 @@ $someColumn->addDropdown(['Change', 'Reorder', 'Update'], function (string $item ## Decorators for data types -In addition to {php:class}`Table_i_Column`, Agile UI includes several column implementations. +In addition to {php:class}`Table\Column`, Agile UI includes several column implementations. ### Link -:::{php:class} Table_i_Column_i_Link +:::{php:class} Table\Column\Link ::: Put `addColumn('name', [\Atk4\Ui\Table\Column\Link::class, ['details', 'id' = ### Money -:::{php:class} Table_i_Column_i_Money +:::{php:class} Table\Column\Money ::: Helps decorating monetary values. Will align value to the right and if value is less than zero will also @@ -197,7 +197,7 @@ For the actual number formatting, see {ref}`uiPersistence` ### Status -:::{php:class} Table_i_Column_i_Status +:::{php:class} Table\Column\Status ::: Allow you to set highlight class and icon based on column value. This is most suitable for columns that @@ -225,7 +225,7 @@ Current list of states supported: ### Template -:::{php:class} Table_i_Column_i_Template +:::{php:class} Table\Column\Template ::: This column is suitable if you wish to have custom cell formatting but do not wish to go through @@ -244,7 +244,7 @@ will only work if you assign it to a primary column (by passing 1st argument to ### Image -:::{php:class} Table_i_Column_i_Image +:::{php:class} Table\Column\Image ::: This column is suitable if you wish to have image in your table cell: @@ -257,7 +257,7 @@ $table->addColumn('image_url', new \Atk4\Ui\Table\Column\Image); ### ActionButtons -:::{php:class} Table_i_Column_i_ActionButtons +:::{php:class} Table\Column\ActionButtons ::: Can be used to add "action buttons" column to your table: @@ -306,7 +306,7 @@ Note that in this case ID is automatically passed to your callback. ### Checkbox -:::{php:class} Table_i_Column_i_Checkbox +:::{php:class} Table\Column\Checkbox ::: :::{php:method} jsChecked() diff --git a/docs/template.md b/docs/template.md index 3817a99c4a..1088ec6c74 100644 --- a/docs/template.md +++ b/docs/template.md @@ -193,10 +193,10 @@ is called _top. Template engine in Agile Toolkit can be used independently, without views if you require so. A typical workflow would be: -1. Load template using {php:meth}`GiTemplate::loadTemplate` or - {php:meth}`GiTemplate::loadFromString`. -2. Set tag and region values with {php:meth}`GiTemplate::set`. -3. Render template with {php:meth}`GiTemplate::renderToHtml`. +1. Load template using {php:meth}`HtmlTemplate::loadTemplate` or + {php:meth}`HtmlTemplate::loadFromString`. +2. Set tag and region values with {php:meth}`HtmlTemplate::set`. +3. Render template with {php:meth}`HtmlTemplate::renderToHtml`. ## Template use together with Views @@ -219,7 +219,7 @@ When an input is added into a Form, it adopts a "FormLine" region. While the nested tags would be identical, the markup around them would be dependent on form layout. -This approach allows you affect the way how {php:class}`Form_i_Control` is rendered +This approach allows you affect the way how {php:class}`Form\Control` is rendered without having to provide it with custom template, but simply relying on template of a Form. @@ -269,7 +269,7 @@ Template can be loaded from either file or string by using one of following commands: ``` -$template = GiTemplate::addTo($this); +$template = HtmlTemplate::addTo($this); $template->loadFromString('Hello, {name}world{/}'); ``` @@ -286,7 +286,7 @@ And place the following inside `template/mytemplate.html`: Hello, {name}world{/} ``` -GiTemplate will use {php:class}`PathFinder` to locate template in one of the +HtmlTemplate will use {php:class}`PathFinder` to locate template in one of the directories of {ref}`resource` `template`. ## Changing template contents @@ -319,7 +319,7 @@ Attempts to append non-escaped value, but will do nothing if tag does not exist. Example: ``` -$template = GiTemplate::addTo($this); +$template = HtmlTemplate::addTo($this); $template->loadFromString('Hello, {name}world{/}'); @@ -387,7 +387,7 @@ Let's assume you have the following template in `template/envelope.html`: You can use the following code to manipulate the template above: ``` -$template = GiTemplate::addTo($this); +$template = HtmlTemplate::addTo($this); $template->loadFromFile('envelope'); // templates/envelope.html // Split into multiple objects for processing @@ -573,7 +573,7 @@ $receiver->template->trySet($receiverData); It is strongly advised not to use templates directly unless you have no other choice. Views implement consistent and flexible layer on top of -GiTemplate as well as integrate with many other components of Agile Toolkit. +HtmlTemplate as well as integrate with many other components of Agile Toolkit. The only cases when direct use of SMlite is suggested is if you are not working with HTML or the output will not be rendered in a regular way (such as RSS feed generation or TMail) diff --git a/docs/tree-item-selector.md b/docs/tree-item-selector.md index fcb72e0f08..9886925d2b 100644 --- a/docs/tree-item-selector.md +++ b/docs/tree-item-selector.md @@ -1,7 +1,7 @@ :::{php:namespace} Atk4\Ui ::: -:::{php:class} Form_i_Control_i_TreeItemSelector +:::{php:class} Form\Control\TreeItemSelector ::: # TreeItemSelector Form Control diff --git a/docs/type-presentation.md b/docs/type-presentation.md index 492d8a0021..9418f7c04d 100644 --- a/docs/type-presentation.md +++ b/docs/type-presentation.md @@ -23,10 +23,10 @@ custom HTML template specified into generic {php:class}`View`. When it comes to decoration, the method is very dependent on the context. A form may present Calendar (DatePicker) or enable control icon to indicate currency. -Presentation in Agile Toolkit is handled by {php:class}`Persistence_i_Ui`. +Presentation in Agile Toolkit is handled by {php:class}`Persistence\Ui`. -Decoration is performed by helper classes, such as {php:class}`Form_i_Control_i_Calendar` or -{php:class}`Table_i_Column_i_Money`. The decorator is in control of the final output, so it can decide if +Decoration is performed by helper classes, such as {php:class}`Form\Control\Calendar` or +{php:class}`Table\Column\Money`. The decorator is in control of the final output, so it can decide if it uses the value from presentation or do some decoration on its own. # Extending Data Types @@ -50,7 +50,7 @@ of your integration. 3. Create your new decorator. Such as use drop-down to select currency from a pre-defined list inside your specific class - while extending {php:class}`Form_i_Control_i_Input` class. Make sure it can interpret input correctly. + while extending {php:class}`Form\Control\Input` class. Make sure it can interpret input correctly. The process is explained further down in this chapter. 4. Associate the types with your decorator. @@ -127,7 +127,7 @@ $model->addDecorator('account_number', new \Atk4\Ui\Table\Column\Password()); ## Create a decorator for hiding credit card number If you happen to store card numbers and you only want to display the last digits in tables, -yet make it available when editing, you could create your own {php:class}`Table_i_Column` decorator: +yet make it available when editing, you could create your own {php:class}`Table\Column` decorator: ``` class Masker extends \Atk4\Ui\Table\Column @@ -154,7 +154,7 @@ it's because this technique is unreliable due to ability to exclude HTML tags wi If we always have to display card numbers with spaces, e.g. "1234 1234 1234 1234" but have the database store them without spaces, then this is a data formatting task best done by -extending {php:class}`Persistence_i_Ui`: +extending {php:class}`Persistence\Ui`: ``` class MyPersistence extends Persistence\Ui diff --git a/docs/view.md b/docs/view.md index 2ecb9c6020..42496f32f1 100644 --- a/docs/view.md +++ b/docs/view.md @@ -361,11 +361,11 @@ to do something before child render, override method {php:meth}`View::recursiveR :::{php:attr} template ::: -Template of a current view. This attribute contains an object of a class {php:class}`Template`. +Template of a current view. This attribute contains an object of a class {php:class}`HtmlTemplate`. You may secify this value explicitly: ``` -View::addTo($app, ['template' => new \Atk4\Ui\Template('hello')]); +View::addTo($app, ['template' => new \Atk4\Ui\HtmlTemplate('hello')]); ``` :::{php:attr} defaultTemplate @@ -388,7 +388,7 @@ View::addTo($app, ['defaultTemplate' => __DIR__ . '/../templates/mytpl.httml']); Agile UI does not currently provide advanced search path for templates, by default the template is loaded from folder `vendor/atk4/ui/template`. To change this -behaviour, see {php:class}`App::loadTemplate()`. +behaviour, see {php:meth}`App::loadTemplate()`. :::{php:attr} region ::: @@ -414,7 +414,7 @@ class MyView extends View } ``` -As soon as the view becomes part of a render-tree, the Template object will also be allocated. +As soon as the view becomes part of a render-tree, the {php:class}`HtmlTemplate` object will also be allocated. At this point it's also possible to override default template: ``` @@ -439,7 +439,7 @@ a Lister is added inside Tags region which will use the contents of a given tag template, which will be repeated according to the number of referenced 'Tags' for given users and re-inserted back into the 'Tags' region. -See also {php:class}`Template`. +See also {php:class}`HtmlTemplate`. ## Unique ID tag diff --git a/docs/virtualpage.md b/docs/virtualpage.md index cc200dcef6..3643c2b1d6 100644 --- a/docs/virtualpage.md +++ b/docs/virtualpage.md @@ -65,7 +65,7 @@ see only the 'LoremIpsum' text. :::{php:attr} urlTrigger ::: -See {php:attr}`Callback::urlTrigger`. +See {php:attr}`Callback::$urlTrigger`. ## Output Modes @@ -199,7 +199,7 @@ Returns JS action which will trigger loading. The action will be carried out in - Content will be placed inside Loader's DIV replacing shiv (or previously loaded content) - loading indicator will is hidden -:::{php:attr} loadEvent = null +:::{php:attr} loadEvent ::: If you have NOT invoked jsLoad in your code, Loader will automatically assign it do DOM Ready(). If the automatic @@ -227,7 +227,7 @@ This approach allow you to trigger loader from inside JavaScript easily. See als ## Reloading -If you execute {php:class}`Js_i_JsReload` action on the Loader, it will return to original state. +If you execute {php:class}`Js\JsReload` action on the Loader, it will return to original state. ## Inline Editing Example @@ -256,7 +256,7 @@ $loader->set(function (\Atk4\Ui\Loader $p) { ## Progress Bar -:::{php:attr} progressBar = null +:::{php:attr} progressBar ::: Loader can have a progress bar. Imagine that your Loader has to run slow process 4 times: