as ``setAttr()`` would do). Here is how to set the HTML "maxlength" attribute on the generated input field:
+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:
```
$form = \Atk4\Ui\Form::addTo($this);
@@ -93,7 +97,7 @@ integration with front-end, integration with Model, error handling etc.
### Usage with Model
-A most common use of form is if you have a working Model (https://agile-data.readthedocs.io/en/develop/model.html):
+A most common use of form is if you have a working Model (https://atk4-data.readthedocs.io/en/develop/model.html):
```
// Form will automatically add a new user and save into the database
@@ -103,39 +107,39 @@ $form->setModel(new User($db));
The basic 2-line syntax will extract all the required logic from the Model including:
- - 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\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://agile-data.readthedocs.io/en/develop/fields.html#Field::$ui)
- - Fields that are not editable by default will not appear on the form (https://agile-data.readthedocs.io/en/develop/fields.html#Field::isEditable)
- - Field typecasting will be invoked such as for converting dates
- - Reference fields (https://agile-data.readthedocs.io/en/develop/references.html?highlight=hasOne#hasone-reference) displayed as Dropdown
- - Booleans are displayed as checkboxes but stored as defined by the model field
- - Not-nullable and Required fields will have form controls visually highlighted (https://agile-data.readthedocs.io/en/develop/fields.html?highlight=required#Field::$nullable)
- - Validation will be performed and errors will appear on the form (NEED LINK)
- - Unless you specify a submission handler, form will save the model ``User`` into ``$db`` on successful submission.
+- 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
+- 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
+- Reference fields (https://atk4-data.readthedocs.io/en/develop/references.html?highlight=hasOne#hasone-reference) displayed as Dropdown
+- Booleans are displayed as checkboxes but stored as defined by the model field
+- Not-nullable and Required fields will have form controls visually highlighted (https://atk4-data.readthedocs.io/en/develop/fields.html?highlight=required#Field::$nullable)
+- Validation will be performed and errors will appear on the form (NEED LINK)
+- Unless you specify a submission handler, form will save the model `User` into `$db` on successful submission.
All of the above works auto-magically, but you can tweak it even more:
- - Provide custom submission handler
- - Specify which form controls and in which order to display on the form
- - Override labels, form control classes
- - Group form controls or use custom layout template
- - Mix standard model fields with your own
- - Add JS Actions around fields
- - Split up form into multiple tabs
+- Provide custom submission handler
+- Specify which form controls and in which order to display on the form
+- Override labels, form control classes
+- Group form controls or use custom layout template
+- Mix standard model fields with your own
+- Add JS Actions around fields
+- Split up form into multiple tabs
-If your form is NOT associated with a model, then Form will automatically create a :php:class:`ProxyModel`
+If your form is NOT associated with a model, then Form will automatically create a {php:class}`ProxyModel`
and associate it with your Form. As you add form controls respective fields will also be added into ProxyModel.
### Extensions
Starting with Agile UI 1.3 Form has a stable API and we expect to introduce some extensions like:
- - Captcha form control
- - File Upload form control (see https://github.com/atk4/filestore)
- - Multi-record form
+- Captcha form control
+- File Upload form control (see https://github.com/atk4/filestore)
+- Multi-record form
If you develop such a feature please let me know so that I can include it in the documentation
and give you credit.
@@ -147,7 +151,7 @@ a View layout for it in order to create their HTML element. In other words, layo
is responsible of rendering HTML for fields.
When Form is first initialized, it will provide and set a default Generic layout within the form.
-Then using :php:meth:`Form::addControl()` will rely on that layout to add form control to it and render it properly.
+Then using {php:meth}`Form::addControl()` will rely on that layout to add form control to it and render it properly.
You may also supply your own layout when creating your form.
Form layout may contain sub layouts. Each sub layout being just another layout view, it is possible
@@ -160,7 +164,8 @@ More on Form layout and sub layout below.
## Adding Controls
-.. php:method:: addControl($name, $decorator = [], $field = [])
+:::{php:method} addControl($name, $decorator = [], $field = [])
+:::
Create a new control on a form:
@@ -181,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\\Layout` or even a regular view. Simply specify property :php:meth:`Form\\Control::$form`:
+{php:class}`Form_i_Layout` or even a regular view. Simply specify property {php:meth}`Form_i_Control::$form`:
```
$myview = View::addTo($form, ['defaultTemplate' => './mytemplate.html']);
@@ -197,19 +202,19 @@ If a field exists inside associated model, then model field definition will be u
a base, otherwise you can specify field definition through 3rd argument. I explain
that below in more detail.
-You can specify first argument ``null`` in which case control will be added without
+You can specify first argument `null` in which case control will be added without
association with field. This will not work with regular fields, but you can add
custom control such as CAPTCHA, which does not really need association with a
field.
### Form Control
-To avoid term miss-use, we use "Field" to refer to ``\Atk4\Data\Field``. This class
-is documented here: https://agile-data.readthedocs.io/en/develop/fields.html
+To avoid term miss-use, we use "Field" to refer to `\Atk4\Data\Field`. This class
+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:
@@ -221,9 +226,9 @@ Agile UI comes with at least the following form controls:
- Radio
- Money
-For some examples see: https://ui.agiletoolkit.org/demos/form3.php
+For some examples see: https://ui.atk4.org/demos/form3.php
-Field Decorator can be passed to ``addControl`` using 'string', :php:ref:`seed` or 'object':
+Field Decorator can be passed to `addControl` using 'string', {php:ref}`seed` or 'object':
```
$form->addControl('accept_terms', [\Atk4\Ui\Form\Control\Checkbox::class]);
@@ -236,16 +241,17 @@ $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 = [])
+:::{php:method} controlFactory(\Atk4\Data\Field $field, $defaults = [])
+:::
-If form control class is not specified (``null``) then it will be determined from
-the type of the Data control with ``controlFactory`` method.
+If form control class is not specified (`null`) then it will be determined from
+the type of the Data control with `controlFactory` method.
### Data Field
-Data field is the 3rd argument to ``Form::addControl()``.
+Data field is the 3rd argument to `Form::addControl()`.
There are 3 ways to define Data form control using 'string', 'json' or 'object':
@@ -261,13 +267,13 @@ class MyBoolean extends \Atk4\Data\Field
$form->addControl('test2', [], new MyBoolean());
```
-String will be converted into ``['caption' => $string]`` a short way to give
+String will be converted into `['caption' => $string]` a short way to give
field a custom label. Without a custom label, Form will clean up the name (1st
argument) by replacing '_' with spaces and uppercasing words (accept_terms
becomes "Accept Terms")
-Specifying array will use the same syntax as the 2nd argument for ``\Atk4\Data\Model::addField()``.
-(https://agile-data.readthedocs.io/en/develop/model.html#Model::addField)
+Specifying array will use the same syntax as the 2nd argument for `\Atk4\Data\Model::addField()`.
+(https://atk4-data.readthedocs.io/en/develop/model.html#Model::addField)
If field already exist inside model, then values of $field will be merged into
existing field properties. This example make email field mandatory for the form:
@@ -282,7 +288,7 @@ $form->addControl('email', [], ['required' => true]);
### addControl into Form with Existing Model
If your form is using a model and you add an additional control, then the underlying model field will be created but it will
-be set as "neverPersist" (https://agile-data.readthedocs.io/en/develop/fields.html#Field::$neverPersist).
+be set as "neverPersist" (https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$neverPersist).
This is to make sure that data from custom form controls wouldn't go directly into the database. Next
example displays a registration form for a User:
@@ -342,10 +348,10 @@ $form->onSubmit(function (Form $form) {
});
```
-Field ``date1`` is defined inside a :php:class:`ProxyModel` as a date field and will
+Field `date1` is defined inside a {php:class}`ProxyModel` as a date field and will
be automatically converted into DateTime object by Persistence typecasting.
-Field ``date2`` has no data type, do not confuse with ui type => date pass as second argument for Calendar field,
+Field `date2` has no data type, do not confuse with ui type => date pass as second argument for Calendar field,
and therefore Persistence typecasting will not modify it's value and it's stored inside model as a string.
The above code result in the following output:
@@ -357,13 +363,13 @@ date1 = DateTime Object ( [date] => 2017-09-03 00:00:00 .. ) and date2 = Septemb
### Seeding Form Control from Model
In large projects you most likely won't be setting individual form controls for each Form. Instead
-you can simply use ``setModel()`` to populate all form controls from fields defined inside a model. Form does
+you can simply use `setModel()` to populate all form controls from fields defined inside a model. Form does
have a pretty good guess about form control decorator based on the data field type, but what if you want to
use a custom decorator?
-This is where ``$field->ui`` comes in (https://agile-data.readthedocs.io/en/develop/fields.html#Field::$ui).
+This is where `$field->ui` comes in (https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$ui).
-You can specify ``'ui' => ['form' => $decoratorSeed]`` when defining your model field inside your Model:
+You can specify `'ui' => ['form' => $decoratorSeed]` when defining your model field inside your Model:
```
class User extends \Atk4\Data\Model
@@ -382,7 +388,7 @@ class User extends \Atk4\Data\Model
}
```
-The seed for the UI will be combined with the default overriding :php:attr:`Form\\Control\\Calendar::type`
+The seed for the UI will be combined with the default overriding {php:attr}`Form_i_Control_i_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:
@@ -397,9 +403,11 @@ Without the data 'type' property, now the calendar selection will be stored as t
Although there were many examples above for the use of setModel() this method
needs a bit more info:
-.. php:attr:: model
+:::{php:attr} model
+:::
-.. php:method:: setModel($model, [$fields])
+:::{php:method} setModel($model, [$fields])
+:::
Associate form controls with existing model object and import all editable fields
in the order in which they were defined inside model's init() method.
@@ -408,12 +416,12 @@ You can specify which form controls to import from model fields and their order
field names in an array as a second argument.
Specifying "false" or empty array as a second argument will import no model fields as form controls,
-so you can then use :php:meth:`Form::addControl` to import form controls from model fields individually.
+so you can then use {php:meth}`Form::addControl` to import form controls from model fields individually.
-Note that :php:meth:`Form::setModel` also delegates adding form control to the form layout
+Note that {php:meth}`Form::setModel` also delegates adding form control to the form layout
by using `Form->layout->setModel()` internally.
-See also: https://agile-data.readthedocs.io/en/develop/fields.html#Field::isEditable
+See also: https://atk4-data.readthedocs.io/en/develop/fields.html#Field::isEditable
### Using setModel() on a sub layout
@@ -427,7 +435,6 @@ $subLayout = $form->layout->addSubLayout();
$subLayout->setModel($model, ['first_name', 'last_name']);
```
-
When using setModel() on a sub layout to add controls per sub layout instead of entire layout,
make sure you pass false as second argument when setting the model on the Form itself, like above.
Otherwise all model fields will be automatically added in Forms main layout and you will not be
@@ -435,8 +442,8 @@ able to add them again in sub-layouts.
### Loading Values
-Although you can set form control values individually using ``$form->model->set('field', $value)``
-it's always nicer to load values for the database. Given a ``User`` model this is how
+Although you can set form control values individually using `$form->model->set('field', $value)`
+it's always nicer to load values for the database. Given a `User` model this is how
you can create a form to change profile of a currently logged user:
```
@@ -453,22 +460,22 @@ Submitting this form will automatically store values back to the database. Form
POST data to submit itself and will re-use the query string, so you can also safely
use any GET arguments for passing record $id. You may also perform model load after
record association. This gives the benefit of not loading any other fields, unless
-they're marked as System (https://agile-data.readthedocs.io/en/develop/fields.html#Field::$system),
-see https://agile-data.readthedocs.io/en/develop/model.html?highlight=onlyfields#Model::setOnlyFields:
+they're marked as System (https://atk4-data.readthedocs.io/en/develop/fields.html#Field::$system),
+see https://atk4-data.readthedocs.io/en/develop/model.html?highlight=onlyfields#Model::setOnlyFields:
```
$form = Form::addTo($app);
$form->setModel((new User($db))->load($currentUserId), ['email', 'name']);
```
-As before, field ``password`` will not be loaded from the database, but this time
+As before, field `password` will not be loaded from the database, but this time
using onlyFields restriction rather then `neverPersist`.
### Validating
The topic of validation in web apps is quite extensive. You should start by reading what Agile Data
has to say about validation:
-https://agile-data.readthedocs.io/en/develop/persistence.html#validation
+https://atk4-data.readthedocs.io/en/develop/persistence.html#validation
Sometimes validation is needed when storing field value inside a model (e.g. setting boolean
to "blah") and sometimes validation should be performed only when storing model data into
@@ -488,13 +495,13 @@ As far as form is concerned:
- Decorators must be able to parse entered values. For instance Dropdown will make sure that
value entered is one of the available values (by key)
-- Form will rely on Agile Data Typecasting (https://agile-data.readthedocs.io/en/develop/typecasting.html)
+- Form will rely on Agile Data Typecasting (https://atk4-data.readthedocs.io/en/develop/typecasting.html)
to load values from POST data and store them in model.
-- Form submit handler will rely on ``Model::save()`` (https://agile-data.readthedocs.io/en/develop/persistence.html#Model::save)
+- Form submit handler will rely on `Model::save()` (https://atk4-data.readthedocs.io/en/develop/persistence.html#Model::save)
not to throw validation exception.
-- Form submit handler will also interpret use of :php:meth:`Form::jsError` by displaying errors that
+- Form submit handler will also interpret use of {php:meth}`Form::jsError` by displaying errors that
do not originate inside Model save logic.
Example use of Model's validate() method:
@@ -526,7 +533,6 @@ class Person extends \Atk4\Data\Model
}
```
-
We can now populate form controls based around the data fields defined in the model:
```
@@ -542,21 +548,21 @@ $form->addControl('terms', ['type' => 'boolean', 'ui' => ['caption' => 'Accept T
### Form Submit Handling
-.. php:method:: onSubmit($callback)
-
- Specify a PHP callback that will be executed on successful form submission.
-
-.. php:method:: jsError($field, $message)
-
- Create and return :php:class:`JsChain` action that will indicate error on a form control.
-
-.. php:method:: jsSuccess($title, [$subTitle])
+:::{php:method} onSubmit($callback)
+Specify a PHP callback that will be executed on successful form submission.
+:::
- Create and return :php:class:`JsChain` action, that will replace form with a success message.
+:::{php:method} jsError($field, $message)
+Create and return {php:class}`Js_i_JsChain` action that will indicate error on a form control.
+:::
-.. php:method:: setApiConfig($config)
+:::{php:method} jsSuccess($title, [$subTitle])
+Create and return {php:class}`Js_i_JsChain` action, that will replace form with a success message.
+:::
- Add additional parameters to Fomantic-UI .api function which does the AJAX submission of the form.
+:::{php:method} setApiConfig($config)
+Add additional parameters to Fomantic-UI .api function which does the AJAX submission of the form.
+:::
For example, if you want the loading overlay at a different HTML element, you can define it with:
@@ -566,9 +572,9 @@ $form->setApiConfig(['stateContext' => 'my-JQuery-selector']);
All available parameters can be found here: https://fomantic-ui.com/behaviors/api.html#/settings
-.. php:attr:: successTemplate
-
- Name of the template which will be used to render success message.
+:::{php:attr} successTemplate
+Name of the template which will be used to render success message.
+:::
To continue with the example, a new Person record can be added into the database
but only if they have also accepted terms and conditions. An onSubmit handler
@@ -587,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}`jsError()` or {php:meth}`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:
@@ -620,7 +626,7 @@ $form->onSubmit(function (Form $form) {
So far Agile UI / Agile Data does not come with a validation library but
it supports usage of 3rd party validation libraries.
-Callback function may raise exception. If Exception is based on ``\Atk4\Core\Exception``,
+Callback function may raise exception. If Exception is based on `\Atk4\Core\Exception`,
then the parameter "field" can be used to associate error with specific field:
```
@@ -635,33 +641,33 @@ 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}`addControl()`
+or {php:meth}`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.
-.. php:method:: initLayout(Form\\Layout $layout)
-
- Sets a custom Form\Layout object for a form. If not specified then form will automatically
- use Form\Layout class.
-
-.. php:attr:: layout
-
- Current form layout object.
+:::{php:method} initLayout(Form\Layout $layout)
+Sets a custom Form\Layout object for a form. If not specified then form will automatically
+use Form\Layout class.
+:::
-.. php:method:: addHeader($header)
+:::{php:attr} layout
+Current form layout object.
+:::
- Adds a form header with a text label. Returns View.
+:::{php:method} addHeader($header)
+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\\Layout` object. You
- can also specify a header.
+:::{php:method} addGroup($header)
+Creates a sub-layout, returning new instance of a {php:class}`Form_i_Layout` object. You
+can also specify a header.
+:::
### Form Control Group Layout and Sub-layout
-Controls can be organized in groups, using method `Form::addGroup()` or as sub section using `Form\\Layout::addSubLayout()` method.
+Controls can be organized in groups, using method `Form::addGroup()` or as sub section using `Form\Layout::addSubLayout()` method.
### Using Group
@@ -715,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\\Layout`.
+the same way as you would do for {php:class}`Form_i_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.
@@ -763,15 +769,15 @@ form inside a segment (outline) and will make form controls appear smaller:
$form = new \Atk4\Ui\Form(['class.small segment' => true]));
```
-For further styling see documentation on :php:class:`View`.
+For further styling see documentation on {php:class}`View`.
## Not-Nullable and Required Fields
ATK Data has two field flags - "nullable" and "required". Because ATK Data works with PHP
values, the values are defined like this:
- - nullable = value of the field can be null.
- - required = value of the field must not be empty/false/zero, null is empty too.
+- nullable = value of the field can be null.
+- required = value of the field must not be empty/false/zero, null is empty too.
Form changes things slightly, because it does not allow user to enter NULL values. For
example - string (or unspecified type) fields will contain empty string if are not
@@ -785,7 +791,8 @@ numeric field, if zero must be a permitted entry, use "nullable=false" instead.
## Conditional Form
-.. php:method:: setControlsDisplayRules()
+:::{php:method} setControlsDisplayRules()
+:::
So far we had to present form with a set of form controls while initializing. Sometimes
you would want to hide/display controls while user enters the data.
@@ -884,17 +891,19 @@ $form->setGroupDisplayRules([
]);
```
-.. todo:: MOVE THIS TO SEPARATE FILE
-
-.. php:class:: Form\\Layout
-
- Renders HTML outline encasing form controls.
-
-.. php:attr:: form
+:::{todo}
+MOVE THIS TO SEPARATE FILE
+:::
- Form layout objects are always associated with a Form object.
+:::{php:class} Form_i_Layout
+Renders HTML outline encasing form controls.
+:::
-.. php:method:: addControl()
+:::{php:attr} form
+Form layout objects are always associated with a Form object.
+:::
- Same as :php:class:`Form::addControl()` but will place a form control inside this specific layout
- or sub-layout.
+:::{php:method} addControl()
+Same as {php:class}`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 0c8f8089a8..b1c1120415 100644
--- a/docs/grid.md
+++ b/docs/grid.md
@@ -1,11 +1,14 @@
-.. _grid:
+:::{php:namespace} Atk4\Ui
+:::
+
+(grid)=
# Grid
-.. php:namespace:: Atk4\Ui
-.. php:class:: Grid
+:::{php:class} Grid
+:::
-If you didn't read documentation on :ref:`table` you should start with that. While table implements the actual
+If you didn't read documentation on {ref}`table` you should start with that. While table implements the actual
data rendering, Grid component supplies various enhancements around it, such as paginator, quick-search, toolbar
and others by relying on other components.
@@ -29,12 +32,14 @@ $grid->menu->addItem('Reload Grid', new \Atk4\Ui\Js\JsReload($grid));
## Adding Menu Items
-.. php:attr:: menu
+:::{php:attr} menu
+:::
-.. php:method: addButton($label)
+:::{php:method} addButton($label)
+:::
Grid top-bar which contains QuickSearch is implemented using Fomantic-UI "ui menu". With that
-you can add additional items and use all features of a regular :php:class:`Menu`:
+you can add additional items and use all features of a regular {php:class}`Menu`:
```
$sub = $grid->menu->addMenu('Drop-down');
@@ -56,11 +61,13 @@ $grid = Grid::addTo($app, ['menu' => false]);
## Adding Quick Search
-.. php:attr:: quickSearch
+:::{php:attr} quickSearch
+:::
-.. php:method: addQuickSearch($fields = [], $hasAutoQuery = 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:class}`View::setModel()` you can
include quick-search component:
```
@@ -68,7 +75,7 @@ $grid->addQuickSearch(['name', 'surname']);
```
If you don't specify argument, then search will be done by a models title field.
-(https://agile-data.readthedocs.io/en/develop/model.html#title-field)
+(https://atk4-data.readthedocs.io/en/develop/model.html#title-field)
By default, quick search input field will query server when user press the Enter key. However, it is possible to make it
querying the server automatically, i.e. after the user has finished typing, by setting the auto query parameter:
@@ -79,9 +86,11 @@ $grid->addQuickSearch(['name', 'surname'], true);
## Paginator
-.. php:attr:: paginator
+:::{php:attr} paginator
+:::
-.. php:attr:: ipp
+:::{php:attr} ipp
+:::
Grid comes with a paginator already. You can disable it by setting $paginator property to false. Alternatively you
can provide seed for the paginator or even entire object:
@@ -98,7 +107,8 @@ $grid->ipp = 10;
### JsPaginator
-.. php:method:: addJsPaginator($ipp, $options = [], $container = null, $scrollRegion = 'Body')
+:::{php:method} addJsPaginator($ipp, $options = [], $container = null, $scrollRegion = 'Body')
+:::
JsPaginator will load table content dynamically when user scroll down the table window on screen.
@@ -106,20 +116,23 @@ JsPaginator will load table content dynamically when user scroll down the table
$table->addJsPaginator(30);
```
-See :php:meth:`Table::addJsPaginator`
+See {php:meth}`Table::addJsPaginator`
-.. php:method:: addJsPaginatorInContainer($ipp, $containerHeight, $options = [], $container = null, $scrollRegion = 'Body')
+:::{php:method} addJsPaginatorInContainer($ipp, $containerHeight, $options = [], $container = null, $scrollRegion = 'Body')
+:::
Use this method if you want fixed table header when scrolling down table. In this case you have to set
fixed height of your table container.
## Actions
-.. php:attr:: actions
+:::{php:attr} actions
+:::
-.. php:method:: addActionButton($button, $action, $confirm = false)
+:::{php:method} addActionButton($button, $action, $confirm = false)
+:::
-:php:class:`Table` supports use of :php:class:`Table\\Column\\\Actions`, which allows to display button for each row.
+{php:class}`Table` supports use of {php:class}`Table_i_Column_i_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']`.
@@ -128,9 +141,10 @@ 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\\Column\\\Actions::addAction`
+See {php:meth}`Table_i_Column_i_Actions::addAction`
-.. php:method:: addModalAction($button, $title, $callback)
+:::{php:method} addModalAction($button, $title, $callback)
+:::
Similar to addAction, but when clicking a button, will open a modal dialog and execute $callback
to populate a content:
@@ -146,22 +160,24 @@ $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:`Atk4\\Ui\\Table\\Column\\Actions::addModal`
+See {php:meth}`Table_i_Column_i_Actions::addModal`
## Column Menus
-.. php:method:: addDropdown($columnName, $items, $fx, $icon = 'caret square down', $menuId = null)
+:::{php:method} addDropdown($columnName, $items, $fx, $icon = 'caret square down', $menuId = null)
+:::
-.. php:method:: addPopup($columnName, $popup = null, $icon = 'caret square down')
+:::{php:method} addPopup($columnName, $popup = null, $icon = 'caret square down')
+:::
-Methods addDropdown and addPopup provide a wrapper for :php:meth:`Atk4\\Ui\\Table\\Column::addDropdown` and
-:php:meth:`Atk4\\Ui\\\Table\\Column::addPopup` methods.
+Methods addDropdown and addPopup provide a wrapper for {php:meth}`Table_i_Column::addDropdown` and
+{php:meth}`Table_i_Column::addPopup` methods.
## Selection
-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`:
+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()`
+method to reference value of selected checkboxes inside any {ref}`js_action`:
```
$sel = $grid->addSelection();
@@ -173,7 +189,8 @@ $grid->menu->addItem('show selection')
## Sorting
-.. php:attr:: sortable
+:::{php:attr} sortable
+:::
When grid is associated with a model that supports order, it will automatically make itself sortable. You can
override this behaviour by setting $sortable property to `true` or `false`.
@@ -181,10 +198,11 @@ override this behaviour by setting $sortable property to `true` or `false`.
You can also set $sortable property for each table column decorator. That way you can enable/disable sorting
of particular columns.
-See also :php:attr:`Table::$sortable`.
+See also {php:attr}`Table::$sortable`.
## Advanced Usage
-.. php:attr:: table
+:::{php:attr} table
+:::
-You can use a different component instead of default :php:class:`Table` by injecting $table property.
+You can use a different component instead of default {php:class}`Table` by injecting $table property.
diff --git a/docs/header.md b/docs/header.md
index 85287efe98..76fa1c972a 100644
--- a/docs/header.md
+++ b/docs/header.md
@@ -1,4 +1,5 @@
-.. php:namespace:: Atk4\Ui
+:::{php:namespace} Atk4\Ui
+:::
# Header
@@ -6,7 +7,7 @@ Can be used for page or section headers.
Based around: https://fomantic-ui.com/elements/header.html.
-Demo: https://ui.agiletoolkit.org/demos/header.php
+Demo: https://ui.atk4.org/demos/header.php
## Basic Usage
@@ -18,9 +19,11 @@ Header::addTo($this, ['Hello, Header']);
## Attributes
-.. php:attr:: size
+:::{php:attr} size
+:::
-.. php:attr:: subHeader
+:::{php:attr} subHeader
+:::
Specify size and sub-header content:
@@ -42,10 +45,11 @@ Header::addTo($seg, [
## Icon and Image
-.. php:attr:: icon
-
-.. php:attr:: image
+:::{php:attr} icon
+:::
+:::{php:attr} image
+:::
Header may specify icon or image:
@@ -68,4 +72,3 @@ Header::addTo($seg, [
'subHeader' => 'header with image',
]);
```
-
diff --git a/docs/helloworld.md b/docs/helloworld.md
index 05fb60bcae..0576d21982 100644
--- a/docs/helloworld.md
+++ b/docs/helloworld.md
@@ -1,10 +1,12 @@
-.. _helloworld:
+:::{php:namespace} Atk4\Ui
+:::
-# HelloWorld
+(helloworld)=
-.. php:namespace:: Atk4\Ui
+# HelloWorld
-.. php:class:: HelloWorld
+:::{php:class} HelloWorld
+:::
Presence of the "Hello World" component in the standard distribution is just us saying "The best way
to create a Hello World app is around a HelloWorld component".
diff --git a/docs/icon.md b/docs/icon.md
index 4780a7fbe9..12fd15d84f 100644
--- a/docs/icon.md
+++ b/docs/icon.md
@@ -1,10 +1,12 @@
-.. _icon:
+:::{php:namespace} Atk4\Ui
+:::
-# Icon
+(icon)=
-.. php:namespace:: Atk4\Ui
+# Icon
-.. php:class:: Icon
+:::{php:class} Icon
+:::
Implements basic icon:
@@ -18,8 +20,8 @@ Alternatively:
$icon = Icon::addTo($app, [], ['flag'])->addClass('outline');
```
-Most commonly icon class is used for embedded icons on a :php:class:`Button`
-or inside other components (see :ref:`icon_other_comp`):
+Most commonly icon class is used for embedded icons on a {php:class}`Button`
+or inside other components (see {ref}`icon_other_comp`):
```
$b1 = new \Atk4\Ui\Button(['Click Me', 'icon' => 'book']);
@@ -45,12 +47,12 @@ Button::addTo($app, ['Click Me', 'class.red' => true, 'icon' => 'flipped big que
Label::addTo($app, ['Battery Low', 'class.green' => true, 'icon' => 'battery low']);
```
-.. _icon_other_comp:
+(icon_other_comp)=
## Using on other Components
-You can use icon on the following components: :php:class:`Button`, :php:class:`Label`, :php:class:`Header`
-:php:class:`Message`, :php:class:`Menu` and possibly some others. Here are some examples:
+You can use icon on the following components: {php:class}`Button`, {php:class}`Label`, {php:class}`Header`
+{php:class}`Message`, {php:class}`Menu` and possibly some others. Here are some examples:
```
Header::addTo($app, ['Header', 'class.red' => true, 'icon' => 'flipped question']);
@@ -66,7 +68,7 @@ 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}`Template` to an
icon:
```
@@ -115,20 +117,18 @@ $app->add($noUsers);
## Icon in Your Component
Sometimes you want to build a component that will contain user-defined icon. Here you can find
-an implementation for ``SocialAdd`` component that implements a friendly social button with
+an implementation for `SocialAdd` component that implements a friendly social button with
the following features:
- - has a very compact usage ``new SocialAdd('facebook')``
- - allow to customize icon by specifying it as string, object or injecting properties
- - allow to customize label
+- has a very compact usage `new SocialAdd('facebook')`
+- allow to customize icon by specifying it as string, object or injecting properties
+- allow to customize label
Here is the code with comments:
```
/**
-```
- * Implements a social network add button. You can initialize the button by passing
-```
+ * Implements a social network add button. You can initialize the button by passing
* social network as a parameter: new SocialAdd('facebook')
* or alternatively you can specify $social, $icon and content individually:
* new SocialAdd(['Follow on Facebook', 'social' => 'facebook', 'icon' => 'facebook f']);
@@ -180,10 +180,8 @@ class SocialAdd extends \Atk4\Ui\View
$this->add($this->icon, 'Icon');
}
}
-```
- // Usage Examples. Start with the most basic usage
-```
+// Usage Examples. Start with the most basic usage
SocialAdd::addTo($app, ['instagram']);
// Next specify label and separately name of social network
diff --git a/docs/image.md b/docs/image.md
index 17d573bb95..3b4035ec03 100644
--- a/docs/image.md
+++ b/docs/image.md
@@ -1,10 +1,12 @@
-.. _image:
+:::{php:namespace} Atk4\Ui
+:::
-# Image
+(image)=
-.. php:namespace:: Atk4\Ui
+# Image
-.. php:class:: Image
+:::{php:class} Image
+:::
Implements Image around https://fomantic-ui.com/elements/image.html.
@@ -26,4 +28,3 @@ You can pass additional classes to an image:
$img = $app->cdn['atk'] . '/logo.png';
$icon = Image::addTo($app, [$img, 'class.disabled' => true]);
```
-
diff --git a/docs/index.md b/docs/index.md
index 52a53b51e1..5a2708107d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,37 +1,23 @@
-## Agile UI Documentation
+:::{php:namespace} Atk4\Ui
+:::
-Contents:
-
-.. toctree::
- :maxdepth: 4
-
- overview
- quickstart
- core
- filestructure
- components
- js
- advanced
+# Agile UI Documentation
+Contents:
-..
+:::{toctree}
+:maxdepth: 4
- base-components
- core
- layouts
- building-components
- menu
- lister
- table
- paginator
- grid
- form
- crud
- tree
- virtual-page
- console
+overview
+quickstart
+core
+filestructure
+components
+js
+advanced
+:::
-## Indices and tables
+# Indices and tables
-* :ref:`genindex`
-* :ref:`search`
+- {ref}`genindex`
+- {ref}`search`
diff --git a/docs/js.md b/docs/js.md
index 9ae560387a..47cdb51800 100644
--- a/docs/js.md
+++ b/docs/js.md
@@ -1,6 +1,7 @@
-.. php:namespace: Atk4\Ui
+:::{php:namespace} Atk4\Ui
+:::
-.. _js:
+(js)=
# JavaScript Mapping
@@ -21,16 +22,14 @@ as possible, then associate them with your UI through actions and events.
A great example would be `jQuery` library. It is designed to be usable with any HTML mark-up and
by specifying selector, you can perform certain actions:
-.. code-block:: js
-
-```
+```js
$('#my-long-id').hide();
```
Agile UI provides a built-in integration for jQuery. To use jQuery and any other JavaScript library
in Agile UI you need to understand how Actions and Events work.
-.. _js_action:
+(js_action)=
### Actions
@@ -41,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:meth:`JsExpression`:
+There are other ways to generate an action, such as using {php:class}`Js_i_JsExpression`:
```
$action = new JsExpression('alert([])', ['Hello world']);
@@ -68,10 +67,10 @@ $action = $view->js()->text(new JsExpression('[] + []', [
All of the above examples will produce a valid "Action" object that can be used further.
-.. important::
-
- We never encourage writing JavaScript logic in PHP. The purpose of JS layer is for binding
- events and actions with your generic JavaScript routines.
+:::{important}
+We never encourage writing JavaScript logic in PHP. The purpose of JS layer is for binding
+events and actions with your generic JavaScript routines.
+:::
### Events
@@ -79,7 +78,7 @@ Agile UI also offers a great way to associate actions with certain client-side e
events can be triggered by the user or by other JavaScript code. There are several ways to bind
`$action`.
-To execute actions instantly on page load, use `true` as first argument to :php:meth:`View::js()`:
+To execute actions instantly on page load, use `true` as first argument to {php:meth}`View::js()`:
```
$view->js(true, new JsExpression('alert([])', ['Hello world']));
@@ -116,42 +115,42 @@ All the above examples will map themselves into a simple and readable JavaScript
Agile UI builds upon the concepts of actions and events in the following ways:
- - Action can be any arbitrary JavaScript with parameters:
+- Action can be any arbitrary JavaScript with parameters:
- - parameters are always encoded/escaped,
- - action can contain nested actions,
- - you can build your own integration patterns.
+ - parameters are always encoded/escaped,
+ - action can contain nested actions,
+ - you can build your own integration patterns.
- - JsChain provides Action extension for JavaScript frameworks:
+- JsChain provides Action extension for JavaScript frameworks:
- - Jquery is implementation of jQuery binding through JsChain,
- - various 3rd party extensions can integrate other frameworks,
- - any jQuery plugin will work out-of-the-box.
+ - Jquery is implementation of jQuery binding through JsChain,
+ - various 3rd party extensions can integrate other frameworks,
+ - any jQuery plugin will work out-of-the-box.
- - PHP closure can be used to wrap action-generation code:
+- PHP closure can be used to wrap action-generation code:
- - Agile UI event will map AJAX call to the event,
- - closure can respond with additional actions,
- - various UI elements (such as Form) extend this concept further.
+ - Agile UI event will map AJAX call to the event,
+ - closure can respond with additional actions,
+ - various UI elements (such as Form) extend this concept further.
### Including JS/CSS
Sometimes you need to include an additional .js or .css file for your code
-to work. See :php:meth:`App:requireJs()` and :php:meth:`App::requireCss()`
+to work. See {php:meth}`App:requireJs()` and {php:meth}`App::requireCss()`
for details.
## Building actions with JsExpressionable
-.. php:interface:: JsExpressionable
-
- Allow objects of the class implementing this interface to participate in
- building JavaScript expressions.
+:::{php:interface} Js_i_JsExpressionable
+Allow objects of the class implementing this interface to participate in
+building JavaScript expressions.
+:::
-.. php:method:: jsRender
+:::{php:method} jsRender
+Express object as a string containing valid JavaScript statement or expression.
+:::
- Express object as a string containing valid JavaScript statement or expression.
-
-:php:class:`View` class is supported as JsExpression argument natively and will present
+{php:class}`View` class is supported as JsExpression argument natively and will present
itself as a valid selector. Example:
```
@@ -161,18 +160,16 @@ $button->js(true)->appendTo($frame);
The resulting Javascript will be:
-.. code-block:: js
-
-```
+```js
$('#button-id').appendTo('#frame-id');
```
### JavaScript Chain Building
-.. php:class:: JsChain
-
- Base class JsChain can be extended by other classes such as Jquery to provide transparent
- mappers for any JavaScript framework.
+:::{php:class} Js_i_JsChain
+Base class JsChain can be extended by other classes such as Jquery to provide transparent
+mappers for any JavaScript framework.
+:::
Chain is a PHP object that represents one or several actions that are to be executed on the
client side. The JsChain objects themselves are generic, so in these examples we'll be using Jquery which
@@ -184,11 +181,11 @@ $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:`JsChain::jsRender()`
+The calls to the chain are stored in the object and can be converted into JavaScript by calling {php:meth}`Js_i_JsChain::jsRender()`
-.. php:method:: jsRender()
-
- Converts actions recorded in JsChain into string of JavaScript code.
+:::{php:method} jsRender()
+Converts actions recorded in JsChain into string of JavaScript code.
+:::
Executing:
@@ -198,24 +195,22 @@ echo $chain->jsRender();
will output:
-.. code-block:: js
-
-```
+```js
$('#the-box-id').dropdown();
```
-.. important::
-
- It's considered very bad practice to use jsRender to output JavaScript manually. Agile UI takes care of
- JavaScript binding and also decides which actions should be available while creating actions for your chain.
+:::{important}
+It's considered very bad practice to use jsRender to output JavaScript manually. Agile UI takes care of
+JavaScript binding and also decides which actions should be available while creating actions for your chain.
+:::
-.. 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:`JsExpressionable` objects and will substitute them with the result of
- :php:meth:`JsExpressionable::jsRender`. The result will not be escaped and any object implementing
- :php:interface:`JsExpressionable` interface is responsible for safe JavaScript generation.
+:::{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.
+:::
The following code is safe:
@@ -230,17 +225,19 @@ argument to `text()`.
### View to JS integration
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()`.
+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:class} View
+:::
- 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.
+:::{php:method} 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.
- If `$otherChain` is specified together with event, it will also be bound to said event. `$otherChain` can also be
- a PHP closure.
+If `$otherChain` is specified together with event, it will also be bound to said event. `$otherChain` can also be
+a PHP closure.
+:::
Several usage cases for plain `js()` method. The most basic scenario is to perform action on the view when event happens:
@@ -252,10 +249,10 @@ $b2 = new Button('Two');
$b2->js('click', $b1->js()->hide());
```
-.. php:method:: 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.
+:::{php:method} 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.
+:::
The following code will show three buttons and clicking any one will hide it. Only a single action is created:
@@ -270,14 +267,14 @@ $buttons->on('click', '.button')->hide();
// Generates:
// $('#top-element-id').on('click', '.button', function (event) {
-// event.preventDefault();
-// event.stopPropagation();
-// $(this).hide();
+// event.preventDefault();
+// event.stopPropagation();
+// $(this).hide();
// });
```
-:php:meth:`View::on()` is handy when multiple elements exist inside a view which you want to trigger individually.
-The best example would be a :php:class:`Lister` with interactive elements.
+{php:meth}`View::on()` is handy when multiple elements exist inside a view which you want to trigger individually.
+The best example would be a {php:class}`Lister` with interactive elements.
You can use both actions together. The next example will allow only one button to be active:
@@ -300,10 +297,12 @@ $buttons->on('click', '.button', $b3->js()->hide());
## JsExpression
-.. php:class:: JsExpression
-.. php:method:: __construct(template, args)
+:::{php:class} Js_i_JsExpression
+:::
- Returns object that renders into template by substituting args into it.
+:::{php:method} __construct(template, args)
+Returns object that renders into template by substituting args into it.
+:::
Sometimes you want to execute action by calling a global JavaScript method. For this
and other cases you can use JsExpression:
@@ -314,8 +313,8 @@ $action = new JsExpression('alert([])', [
]);
```
-Because :php:class:`JsChain` will typically wrap all the arguments through
-:php:meth:`JsChain::_jsonEncode()`, it prevents you from accidentally injecting JavaScript code:
+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:
```
$b = new Button();
@@ -366,8 +365,8 @@ must operate with it in your browser by passing expressions into chain.
The template language for JsExpression is super-simple:
- - [] will be mapped to next argument in the argument array
- - [foo] will be mapped to named argument in argument array
+- `[]` will be mapped to next argument in the argument array
+- `[foo]` will be mapped to named argument in argument array
So the following lines are identical:
@@ -377,10 +376,10 @@ $sum = new JsExpression('[0] + [1]', [$h1, $h2]);
$sum = new JsExpression('[a] + [b]', ['a' => $h1, 'b' => $h2]);
```
-.. important::
-
- We have specifically selected a very simple tag format as a reminder not to write
- any code as part of JsExpression. You must not use JsExpression() for anything complex.
+:::{important}
+We have specifically selected a very simple tag format as a reminder not to write
+any code as part of JsExpression. You must not use JsExpression() for anything complex.
+:::
### Writing JavaScript code
@@ -390,16 +389,16 @@ but you should follow a proper pattern.
Create a file `test.js` containing:
-.. code-block:: js
-
- function mySum(arr) {
- return arr.reduce(function (a, b) {
- return a + b;
- }, 0);
- }
+```js
+function mySum(arr) {
+ return arr.reduce(function (a, b) {
+ return a + b;
+ }, 0);
+}
+```
-Then load this JavaScript dependency on your page (see :php:meth:`App::includeJS()` and
-:php:meth:`App::includeCSS()`). Finally use UI code as a "glue" between your routine
+Then load this JavaScript dependency on your page (see {php:meth}`App::includeJS()` and
+{php:meth}`App::includeCSS()`). Finally use UI code as a "glue" between your routine
and the actual View objects. For example, to match the size of `$rightContainer`
with the size of `$leftContainer`:
@@ -414,11 +413,11 @@ $rightContainer->js(true)->height(new JsExpression('mySum([])', [$heights]));
This will map into the following JavaScript code:
-.. code-block:: js
-
- $('#right_container_id').height(mySum([
- $('#left_box1').height(), $('#left_box2').height(), $('#left_box3').height(), // etc
- ]));
+```js
+$('#right_container_id').height(mySum([
+ $('#left_box1').height(), $('#left_box2').height(), $('#left_box3').height(), // etc
+]));
+```
You can further simplify JavaScript code yourself, but keep the JavaScript logic inside the `.js` files
and leave PHP only for binding.
@@ -427,25 +426,37 @@ and leave PHP only for binding.
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.
+- 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:`JsModal`
+In contrast to {php:class}`Modal`, the HTML `
` element generated by {php:class}`Js_i_JsModal`
is always destroyed when the modal is closed instead of only hiding it.
### Modal
-.. php:class:: Modal
+:::{php:class} Modal
+:::
+
+:::{php:method} set(callback)
+:::
+
+:::{php:method} jsShow()
+:::
+
+:::{php:method} jsHide()
+:::
-.. php:method:: set(callback)
-.. php:method:: jsShow()
-.. php:method:: jsHide()
-.. php:method:: addContentCss()
-.. php:method:: addScrolling()
-.. php:method:: setOption()
+:::{php:method} addContentCss()
+:::
+
+:::{php:method} addScrolling()
+:::
+
+:::{php:method} setOption()
+:::
This class allows you to open modal dialogs and close them easily. It's based around Fomantic-UI
-`.modal(), `_ but integrates PHP callback for dynamically
+[.modal()](https://fomantic-ui.com/modules/modal.html), but integrates PHP callback for dynamically
producing content of your dialog:
```
@@ -479,12 +490,13 @@ or `contentCss` or use the method `addContentCss()`. See the Fomantic-UI modal d
### JsModal
-.. php:class:: JsModal
+:::{php:class} Js_i_JsModal
+:::
-This alternative implementation to :php:class:`Modal` is convenient for situations
+This alternative implementation to {php:class}`Modal` is convenient for situations
when the need to open a dialog box is not known in advance. This class is not
a component, but rather an Action so you **must not** add it to the Render Tree.
-To accomplish that, use a :ref:`virtualpage`:
+To accomplish that, use a {ref}`virtualpage`:
```
$vp = \Atk4\Ui\VirtualPage::addTo($app);
@@ -494,16 +506,17 @@ $vp = \Atk4\Ui\VirtualPage::addTo($app);
->on('click', new \Atk4\Ui\Js\JsModal('My Popup Title', $vp->getUrl('cut')));
```
-Note that this element is always destroyed as opposed to :php:class:`Modal`,
+Note that this element is always destroyed as opposed to {php:class}`Modal`,
where it is only hidden.
-.. important::
-
- See `Modals and reloading`_ concerning the intricacies between jsMmodals and callbacks.
+:::{important}
+See [Modals and reloading](#modals-and-reloading) concerning the intricacies between jsMmodals and callbacks.
+:::
## Reloading
-.. php:class:: JsReload
+:::{php:class} Js_i_JsReload
+:::
JsReload is a JavaScript action that performs reload of a certain object:
@@ -535,7 +548,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 `JsModal`_ which requires a :ref:`virtualpage` to
+Care needs to be taken when attempting to combine the above with a {php:class}`Js_i_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.
@@ -543,10 +556,10 @@ For example, in order to open a modal dialog containing a form and reload a tabl
with the updated data on form submission (thus without having to reload the entire page), the following elements are
needed:
-* a virtual page containing a JsModal's contents (in this case a form),
-* a table showing data on the main page,
-* a button that opens the modal in order to add data, and
-* the form's callback on submit.
+- a virtual page containing a JsModal's contents (in this case a form),
+- a table showing data on the main page,
+- a button that opens the modal in order to add data, and
+- the form's callback on submit.
The following will **not** work:
@@ -654,16 +667,18 @@ $button->on('click', function () use ($button, $image) {
});
```
-However, it would be nice if the user was aware of the progress of your process, which is when `Server Sent Event (JsSse)`_
+However, it would be nice if the user was aware of the progress of your process, which is when {ref}`sse`
comes into play.
-.. _sse:
+(sse)=
### Server Sent Event (JsSse)
-.. php:class:: JsSse
+:::{php:class} JsSse
+:::
-.. php:method:: send(action)
+:::{php:method} send(action)
+:::
This class implements ability for your PHP code to send messages to the browser during process execution:
@@ -689,4 +704,4 @@ $button->on('click', $sse->set(function () use ($sse, $button, $image) {
}));
```
-The JsSse component plays a crucial role in some high-level components such as :php:class:`Console` and :php:class:`ProgressBar`.
+The JsSse component plays a crucial role in some high-level components such as {php:class}`Console` and {php:class}`ProgressBar`.
diff --git a/docs/label.md b/docs/label.md
index 9a6390ce57..8cc0ac67de 100644
--- a/docs/label.md
+++ b/docs/label.md
@@ -1,17 +1,19 @@
-.. _label:
+:::{php:namespace} Atk4\Ui
+:::
-# Label
+(label)=
-.. php:namespace:: Atk4\Ui
+# Label
-.. php:class:: Label
+:::{php:class} Label
+:::
Labels can be used in many different cases, either as a stand-alone objects, inside tables or inside
other components.
To see what possible classes you can use on the Label, see: https://fomantic-ui.com/elements/label.html.
-Demo: https://ui.agiletoolkit.org/demos/label.php
+Demo: https://ui.atk4.org/demos/label.php
## Basic Usage
@@ -27,33 +29,41 @@ $label = new \Atk4\Ui\Label('hello world');
$app->add($label);
```
-
Label has the following properties:
-.. php:attr:: icon
+:::{php:attr} icon
+:::
-.. php:attr:: iconRight
+:::{php:attr} iconRight
+:::
-.. php:attr:: image
+:::{php:attr} image
+:::
-.. php:attr:: imageRight
+:::{php:attr} imageRight
+:::
-.. php:attr:: detail
+:::{php:attr} detail
+:::
All the above can be string, array (passed to Icon, Image or View class) or an object.
## Icons
-There are two properties (icon, iconRight) but you can set only one at a time::
+There are two properties (icon, iconRight) but you can set only one at a time:
- Label::addTo($app, ['23', 'icon' => 'mail']);
- Label::addTo($app, ['new', 'iconRight' => 'delete']);
+```
+Label::addTo($app, ['23', 'icon' => 'mail']);
+Label::addTo($app, ['new', 'iconRight' => 'delete']);
+```
-You can also specify icon as an object::
+You can also specify icon as an object:
- Label::addTo($app, ['new', 'iconRight' => new \Atk4\Ui\Icon('delete')]);
+```
+Label::addTo($app, ['new', 'iconRight' => new \Atk4\Ui\Icon('delete')]);
+```
-For more information, see: :php:class:`Icon`
+For more information, see: {php:class}`Icon`
## Image
@@ -133,4 +143,3 @@ $table->onHook(\Atk4\Ui\Table\Column::HOOK_GET_HTML_TAGS, function (Table $table
Now while $table will be rendered, if it finds a record with id=1, it will replace $name value with a HTML tag.
You need to make sure that 'name' column appears first on the left.
-
diff --git a/docs/lister.md b/docs/lister.md
index 1d351bd861..4f9a48ed06 100644
--- a/docs/lister.md
+++ b/docs/lister.md
@@ -1,13 +1,15 @@
-.. _Lister:
+:::{php:namespace} Atk4\Ui
+:::
-# Lister
+(Lister)=
-.. php:namespace:: Atk4\Ui
+# Lister
-.. php:class:: Lister
+:::{php:class} Lister
+:::
Lister can be used to output unstructured data with your own HTML template. If you wish to output
-data in a table, see :php:class:`Table`. Lister is also the fastest way to render large amount of
+data in a table, see {php:class}`Table`. Lister is also the fastest way to render large amount of
output and will probably give you most flexibility.
## Basic Usage
@@ -61,10 +63,10 @@ Lister::addTo($view, [], ['Countries'])
While most other objects in Agile UI come with their own templates, lister will prefer
to use template inside your region. It will look for "row" and "rows" tag:
- 1. Create clone of {row} tag
- 2. Delete contents of {rows} tag
- 3. For each model row, populate values into {row}
- 4. Render {row} and append into {rows}
+1. Create clone of {row} tag
+2. Delete contents of {rows} tag
+3. For each model row, populate values into {row}
+4. Render {row} and append into {rows}
If you refresh your page now, you should see "Andorra" duplicated 20 times. This is because
the {row} did not contain any field tags. Lets set them up:
@@ -102,7 +104,7 @@ Finally, Lister permits you not to use {rows} and {row} tags if entire region ca
## Tweaking the output
-Output is formatted using the standard :ref:`uiPersistence` routine, but you can also fine-tune the content
+Output is formatted using the standard {ref}`uiPersistence` routine, but you can also fine-tune the content
of your tags like this:
```
@@ -126,9 +128,9 @@ $lister->setSource([
Your {row} template may contain few special tags:
- - {$_id} - will be set to ID of the record (regardless of how your id_field is called)
- - {$_title} - will be set to the title of your record (see $model->$titleField)
- - {$_href} - will point to current page but with ?id=123 extra GET argument.
+- {$_id} - will be set to ID of the record (regardless of how your id_field is called)
+- {$_title} - will be set to the title of your record (see $model->$titleField)
+- {$_href} - will point to current page but with ?id=123 extra GET argument.
## Load page content dynamically when scrolling
@@ -153,4 +155,3 @@ Lister::addTo($app, ['defaultTemplate' => 'lister.html']);
```
This should display a list nicely formatted by Fomantic-UI, with header, links, icons and description area.
-
diff --git a/docs/loremipsum.md b/docs/loremipsum.md
index 6df5330bef..4e37ee3f8d 100644
--- a/docs/loremipsum.md
+++ b/docs/loremipsum.md
@@ -1,13 +1,15 @@
-.. _text:
+:::{php:namespace} Atk4\Ui
+:::
-# LoremIpsum
+(text)=
-.. php:namespace:: Atk4\Ui
+# LoremIpsum
-.. php:class:: LoremIpsum
+:::{php:class} LoremIpsum
+:::
This class implements a standard filler-text which is so popular amongst web developers and designers.
-LoremIpsum will generate a dynamic filler text which should help you test :ref:`reloading` or layouts.
+LoremIpsum will generate a dynamic filler text which should help you test {ref}`reloading` or layouts.
## Basic Usage
@@ -25,7 +27,6 @@ $text = Text::addTo($app)
->addParagraph('Second Paragraph');
```
-
You may specify amount of text to be generated with lorem:
```
@@ -35,5 +36,3 @@ LoremIpsum::addTo($app, [1]); // just add a little one
LoremIpsum::addTo($app, [5]); // adds a lot of text
```
-
-
diff --git a/docs/menu.md b/docs/menu.md
index 883fc6575c..991d876355 100644
--- a/docs/menu.md
+++ b/docs/menu.md
@@ -1,15 +1,19 @@
-.. _menu:
+:::{php:namespace} Atk4\Ui
+:::
+
+(menu)=
# Menu
-.. php:namespace:: Atk4\Ui
-.. php:class:: Menu
+:::{php:class} Menu
+:::
Menu implements horizontal or vertical multi-level menu by using Fomantic-UI 'menu'.
## Using Menu
-.. php:method: addItem($label, $action)
+:::{php:method} addItem($label, $action)
+:::
Here is a simple usage:
@@ -27,7 +31,7 @@ $menu->addClass('vertical');
## Decorating Menu Items
-See :php:class:`MenuItem` for more options:
+See {php:class}`MenuItem` for more options:
```
$menu->addItem(['foo', 'icon' => 'book']);
@@ -44,15 +48,18 @@ $menu->addItem('bar', new JsModal('Test'));
## Creating sub-menus
-.. php:method: addMenu($label)
-.. php:method: addGroup($label)
-.. php:method: addRightMenu($label)
+:::{php:method} addMenu($label)
+:::
+
+:::{php:method} addGroup($label)
+:::
+
+:::{php:method} addRightMenu($label)
+:::
You can create sub-menu for either vertical or horizontal menu. For a vertical
menu you can also use groups. For horizontal menu, you can use addRightMenu.
-:
-
```
$menu = Menu::addTo($app);
$menu->addItem('foo');
@@ -63,7 +70,8 @@ $sub->addItem('bar 2');
## Headers
-.. php:method: addHeader($label)
+:::{php:method} addHeader($label)
+:::
## Advanced Use
@@ -71,10 +79,13 @@ You can add other elements inside menu. Refer to demos/menu.php.
## MenuItem
-.. php:class:: MenuItem
+:::{php:class} MenuItem
+:::
-.. php:attr:: label
+:::{php:attr} label
+:::
-.. php::attr:: $icon
+:::{php:attr} icon
+:::
-Additionally you can use :php:meth:`View::addClass()` to disable or style your menu items.
+Additionally you can use {php:meth}`View::addClass()` to disable or style your menu items.
diff --git a/docs/message.md b/docs/message.md
index ee4d2f370f..3288a4d9dd 100644
--- a/docs/message.md
+++ b/docs/message.md
@@ -1,14 +1,16 @@
-.. _message:
+:::{php:namespace} Atk4\Ui
+:::
-# Message
+(message)=
-.. php:namespace:: Atk4\Ui
+# Message
-.. php:class:: Message
+:::{php:class} Message
+:::
Outputs a rectangular segment with a distinctive color to convey message to the user, based around: https://fomantic-ui.com/collections/message.html
-Demo: https://ui.agiletoolkit.org/demos/message.php
+Demo: https://ui.atk4.org/demos/message.php
## Basic Usage
@@ -34,9 +36,10 @@ $message = Message::addTo($app, ['Warning Message Title', 'type' => 'warning']);
## Adding message text
-.. php:attr:: text
+:::{php:attr} text
+:::
-Property $text is automatically initialized to :php:class:`Text` so you can call :php:meth:`Text::addParagraph`
+Property $text is automatically initialized to {php:class}`Text` so you can call {php:meth}`Text::addParagraph`
to add more text inside your message:
```
@@ -48,7 +51,8 @@ $message->text->addParagraph('Second para');
## Message Icon
-.. php:attr:: icon
+:::{php:attr} icon
+:::
You can specify icon also:
@@ -59,5 +63,3 @@ $message = Message::addTo($app, [
'icon' => 'battery low',
])->text->addParagraph('Your battery is getting low. Re-charge your Web App');
```
-
-
diff --git a/docs/misc.md b/docs/misc.md
index bfe8ef7b54..03deebcacb 100644
--- a/docs/misc.md
+++ b/docs/misc.md
@@ -1,13 +1,15 @@
-.. php:namespace:: Atk4\Ui
+:::{php:namespace} Atk4\Ui
+:::
-## Columns
+# 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
basic content arrangements.
-.. php:method:: addColumn()
+:::{php:method} addColumn()
+:::
When you add new component to the page it will typically consume 100% width of its container. Columns
will break down width into chunks that can be used by other elements:
@@ -35,7 +37,7 @@ Box::addTo($c->addColumn(), ['red']);
Box::addTo($c->addColumn(['class.right floated' => true]), ['blue']);
```
-### Rows
+## Rows
When you add columns for a total width which is more than permitted, columns will stack below and form a second
row. To improve and control the flow of rows better, you can specify addRow():
@@ -57,10 +59,10 @@ Icon::addTo($r->addColumn(2), ['huge trash']);
This example also uses custom class for Columns ('internally celled') that adds dividers between columns and rows.
For more information on available classes, see https://fomantic-ui.com/collections/grid.html.
-### Responsiveness and Performance
+## Responsiveness and Performance
Although you can use responsiveness with the Column class to some degree, we recommend that you create your own
component template where you can have greater control over all classes.
-Similarly if you intend to output a lot of data, we recommend you to use :php:class:`Lister` instead with a custom
+Similarly if you intend to output a lot of data, we recommend you to use {php:class}`Lister` instead with a custom
template.
diff --git a/docs/multiline.md b/docs/multiline.md
index 579476e4a0..af7a9c4789 100644
--- a/docs/multiline.md
+++ b/docs/multiline.md
@@ -1,6 +1,8 @@
-.. php:namespace:: Atk4\Ui\Form\Control
+:::{php:namespace} Atk4\Ui
+:::
-.. php:class:: Multiline
+:::{php:class} Form_i_Control_i_Multiline
+:::
# Multiline Form Control
@@ -23,7 +25,7 @@ class User extends \Atk4\Data\Model
protected function init(): void
{
- parent:: init();
+ parent::init();
$this->addField('firstname', ['type' => 'string']);
$this->addField('lastname', ['type' => 'string']);
@@ -53,7 +55,8 @@ class Address extends \Atk4\Data\Model
This leads to a Multiline component automatically rendered for adding, editing and deleting Addresses of the current user record:
-.. image:: images/multiline_user_addresses.png
+:::{image} images/multiline_user_addresses.png
+:::
You can also check LINK_TO_DEMO/multiline.php for this example
@@ -91,7 +94,7 @@ class User extends \Atk4\Data\Model
protected function init(): void
{
- parent:: init();
+ parent::init();
$this->addField('firstname', ['type' => 'string']);
$this->addField('lastname', ['type' => 'string']);
@@ -103,7 +106,8 @@ class User extends \Atk4\Data\Model
Using a form with User model won't automatically add a Multiline to edit the related email addresses.
-.. php:method:: setReferenceModel(string $refModelName, Model $entity = null, array $fieldNames = []): Model
+:::{php:method} setReferenceModel(string $refModelName, Model $entity = null, array $fieldNames = []): Model
+:::
If you want to edit them along with the user, Multiline need to be set up accordingly using the setReferenceModel method:
@@ -125,7 +129,6 @@ $userForm->onSubmit(function (Form $form) use ($ml) {
});
```
-
Using the example above will create a form with control from the User model as well as a Multiline control for editing
the Email model's field.
@@ -140,9 +143,9 @@ normally call this method in your form onSubmit handler method.
## Multiline and Expressions
If a Model contains Expressions, there resulting values will automatically get updated when one of the form control value is changed.
-A loading icon on the ``+`` button will indicates that the expression values are being update.
+A loading icon on the `+` button will indicates that the expression values are being update.
-Lets use the example of demos/multiline.php:
+Lets use the example of `demos/multiline.php`:
```
class InventoryItem extends \Atk4\Data\Model
@@ -166,7 +169,7 @@ The 'total' expression will get updated on each field change automatically.
## OnLineChange Callback
If you want to define a callback which gets executed when a field value in a Multiline row is changed,
-you can do so using the ``onLineChange()`` method.
+you can do so using the `onLineChange()` method.
The first parameter is the callback function, the second one is an array containing field names that will trigger
the callback when values are changed.
You can return a single JsExpressionable or an array of JsExpressionables which then will be sent to the browser.
@@ -194,7 +197,8 @@ field type associated with Multiline control.
You will find a list of Vue component associated with each field type within the Multiline $fieldMapToComponent array.
-.. php:attr:: fieldMapToComponent
+:::{php:attr} fieldMapToComponent
+:::
Each control being a Vue component means that they accept 'Props' that may change their look or behaviour.
Props on each component may be applied globally, i.e. to all control within Multiline that use that control, or
@@ -204,7 +208,8 @@ per component.
Use the $componentProps property of Multiline in order to apply 'Props' to component globally.
-.. php:attr:: componentProps
+:::{php:attr} componentProps
+:::
Example of changing all Dropdown(SuiDropdown) within Multiline:
@@ -253,6 +258,5 @@ $ml = $form->addControl('ml', [Multiline::class, 'tableProps' => ['color' => 'bl
### Header
- The header uses the field's caption by default.
-- You can edit it by setting the ``$caption`` property.
-- If you want to hide the header, set the ``$caption`` property to an empty string ``''``.
-
+- You can edit it by setting the `$caption` property.
+- If you want to hide the header, set the `$caption` property to an empty string `''`.
diff --git a/docs/overview.md b/docs/overview.md
index 5d35590c0b..19df3251c1 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,4 +1,7 @@
-.. _overview:
+:::{php:namespace} Atk4\Ui
+:::
+
+(overview)=
# Overview of Agile UI
@@ -6,15 +9,16 @@ Agile UI is a PHP component framework for building User Interfaces entirely in P
Although the components of Agile UI will typically use HTML, JavaScript, jQuery and
CSS, the goal of Agile UI is to abstract them away behind easy-to-use component objects.
-As a framework it's closely coupled with Agile Data (https://agile-data.readthedocs.io)
+As a framework it's closely coupled with Agile Data (https://atk4-data.readthedocs.io/)
which abstracts database interaction operations. The default UI template set
uses Fomantic-UI (https://fomantic-ui.com) for presentation.
At a glance, Agile UI consists of the following:
-.. figure:: images/all-atk-classes.png
+:::{figure} images/all-atk-classes.png
+:::
-Agile UI is designed and built for the Agile Toolkit (https://agiletoolkit.org/) platform,
+Agile UI is designed and built for the Agile Toolkit (https://atk4.org/) platform,
with the goal of providing a user-friendly experience when creating data-heavy API / UI
backends.
@@ -66,7 +70,7 @@ Agile UI is designed and optimized for quick deployment into modern serverless
architecture providers such as: Heroku, Docker, or even AWS Lambdas.
Agile UI / PHP application has a minimum "start-up" time, has the best CPU usage,
-and gives you the highest efficiency and best scaling.
+and gives you the highest efficiency and best scaling.
### 5. High-level Solution
@@ -77,10 +81,9 @@ Simple scenario:
digging through heaps of HTML, CSS, or JS frameworks and need a solution
which will be quick and just works.
-.. _overview_example:
+(overview_example)=
-Overview Example
-^^^^^^^^^^^^^^^^
+#### Overview Example
Agile UI / Agile Data code for your app can fit into a single file. See below for
clarifications:
@@ -120,71 +123,66 @@ $db = new \Atk4\Data\Persistence\Sql($dsn);
Through the course of this example, We are performing several core actions:
- - `$app` is an object representing our Web Application and abstracting
- all the input, output, error-handling, and other technical implementation
- details of a standard web application.
-
- In most applications you would want to extend this class yourself. When
- integrating Agile UI with MVC framework, you would be using a different
- App class that properly integrates framework capabilities.
-
- For a :ref:`component` the App class provides level of abstraction and
- utility.
+- `$app` is an object representing our Web Application and abstracting
+ all the input, output, error-handling, and other technical implementation
+ details of a standard web application.
- For full documentation see :ref:`app`.
+ In most applications you would want to extend this class yourself. When
+ integrating Agile UI with MVC framework, you would be using a different
+ App class that properly integrates framework capabilities.
- - `$db` this is a database persistence object. It may be a Database which is
- either SQL or NoSQL but can also be RestAPI, a cache, or a pseudo-persistence.
+ For a {ref}`component` the App class provides level of abstraction and
+ utility.
- We used `Persistence\Sql` class, which takes advantage of a standard-compliant
- database server to speed up aggregation, multi-table, and multi-record operations.
+ For full documentation see {ref}`app`.
- For a :ref:`component` the Persistence class provides data storage abstraction
- through the use of a Model class.
+- `$db` this is a database persistence object. It may be a Database which is
+ either SQL or NoSQL but can also be RestAPI, a cache, or a pseudo-persistence.
- Agile Data has full documentation at https://agile-data.readthedocs.io.
+ We used `Persistence\Sql` class, which takes advantage of a standard-compliant
+ database server to speed up aggregation, multi-table, and multi-record operations.
- - `Offer` is a Model - a database-agnostic declaration of your business entity.
- Model object represents a data-set for specific persistence and conditions.
+ For a {ref}`component` the Persistence class provides data storage abstraction
+ through the use of a Model class.
- In our example, the object is created representing all our offer records that is then
- passed into the Crud :ref:`component`.
+ Agile Data has full documentation at https://atk4-data.readthedocs.io/.
- For a :ref:`component`, the Model represents information about the structure
- and offers a mechanism to retrieve, store, and delete date from `$db` persistence.
+- `Offer` is a Model - a database-agnostic declaration of your business entity.
+ Model object represents a data-set for specific persistence and conditions.
+ In our example, the object is created representing all our offer records that is then
+ passed into the Crud {ref}`component`.
- - `Crud` is a :ref:`component` class. Particularly Crud is bundled with Agile UI
- and implements out-of-the-box interface for displaying data in a table format
- with operations to add, delete, or edit the record.
+ For a {ref}`component`, the Model represents information about the structure
+ and offers a mechanism to retrieve, store, and delete date from `$db` persistence.
- Although it's not obvious from the code, Crud relies on multiple other components
- such as :php:class:`Grid`, :php:class:`Form`, :php:class:`Menu`, :php:class:`Paginator`,
- and :php:class:`Button`.
+- `Crud` is a {ref}`component` class. Particularly Crud is bundled with Agile UI
+ and implements out-of-the-box interface for displaying data in a table format
+ with operations to add, delete, or edit the record.
+ Although it's not obvious from the code, Crud relies on multiple other components
+ such as {php:class}`Grid`, {php:class}`Form`, {php:class}`Menu`, {php:class}`Paginator`,
+ and {php:class}`Button`.
To sum up Agile UI in more technical terms:
- - Fully utilizes abstraction of Web technologies through components.
- - Contains concise syntax to define UI layouts in PHP.
- - Has built-in security and safety.
- - Decouples from data storage/retrieval mechanism.
- - Designed to be integrated into full-stack frameworks.
- - Abstains from duplicating field names, types, or validation logic outside of Model
- class.
+- Fully utilizes abstraction of Web technologies through components.
+- Contains concise syntax to define UI layouts in PHP.
+- Has built-in security and safety.
+- Decouples from data storage/retrieval mechanism.
+- Designed to be integrated into full-stack frameworks.
+- Abstains from duplicating field names, types, or validation logic outside of Model
+ class.
### Best use of Agile UI
- - Creating admin backend UI for data entry and dashboards in shortest time and with
- minimum amount of code.
-
- - Building UI components which you are willing to use across multiple environments
- (Laravel, WordPress, Drupal, etc)
-
- - Creating MVP prototype for Web Apps.
+- Creating admin backend UI for data entry and dashboards in shortest time and with
+ minimum amount of code.
+- Building UI components which you are willing to use across multiple environments
+ (Laravel, WordPress, Drupal, etc)
+- Creating MVP prototype for Web Apps.
-
-.. _component:
+(component)=
## Component
@@ -202,21 +200,21 @@ $button = \Atk4\Ui\Button::addTo($form, [
])->link('dashboard.php');
```
-:php:class:`Button` and :php:class:`Icon` are some of the most basic components in
+{php:class}`Button` and {php:class}`Icon` are some of the most basic components in
Agile UI. You will find Crud / Form / Grid components much more useful:
-.. figure:: images/all-atk-classes.png
+:::{figure} images/all-atk-classes.png
+:::
### Using Components
-Look above at the :ref:`overview_example`, component `GRID` was made part
+Look above at the {ref}`overview_example`, component `GRID` was made part
of application layout with a line:
```
\Atk4\Ui\Crud::addTo($app);
```
-
To render a component individually and get the HTML and JavaScript use this format:
```
@@ -228,7 +226,6 @@ $form->setModel(new User($db));
$html = $form->render();
```
-
This would render an individual component and will return HTML:
```
@@ -240,7 +237,7 @@ This would render an individual component and will return HTML:
```
-For other use-cases please look into :php:meth:`View::render()`
+For other use-cases please look into {php:meth}`View::render()`
### Factory
@@ -254,35 +251,37 @@ in PHP language allows us to use an alternative shorter syntax:
```
By default, class names specified as the first array elements passed to the add() method are
-resolved to namespace `Atk4\\Ui`; however the application class can fine-tune the
+resolved to namespace `Atk4\Ui`; however the application class can fine-tune the
search.
Using a factory is optional. For more information see:
-https://agile-core.readthedocs.io/en/develop/factory.html
+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}`Template` 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.
### Layouts
-.. image:: images/layout-hierarchy.png
- :width: 40%
- :align: right
+:::{image} images/layout-hierarchy.png
+:align: right
+:width: 40%
+:::
Using App class will utilize a minimum of 2 templates:
- - html.html - boilerplate HTML code (,