The UI package provides abstract tools for creating user interface elements.
composer require charcoal/ui
For Charcoal projects, the service provider can be registered from your configuration file:
{
"service_providers": {
"charcoal/ui/service-provider/ui": {}
}
}
use Charcoal\Config\GenericMetadata;
use Charcoal\Ui\Form\FormBuilder;
use Charcoal\Ui\Form\FormFactory;
$metadata = new GenericMetadata([
'properties' => [
'first_name' => [
'type' => 'string',
],
'last_name' => [
'type' => 'string',
],
'email' => [
'type' => 'email',
],
],
]);
$formData = [
'first_name' => 'Mathieu',
'last_name' => 'Ducharme',
'email' => '[email protected]',
];
$formConfig = [
'type' => 'charcoal/ui/form/generic'
'template_ident' => 'foo/bar/form',
'template_data' => [],
'label' => 'Example Form',
'groups' => [
'info' => [
'layout' => [
'structure' => [
'columns' => [
[ 1, 1 ],
[ 1 ],
],
],
],
'properties' => [
'first_name',
'last_name',
'email',
],
],
],
];
$formBuilder = new FormBuilder([
'form_factory' => new FormFactory(),
'view' => $container['view'],
]);
$form = $formBuilder->build($formConfig);
$form->setMetadata($metadata);
$form->setFormData($formData);
echo $form->render();
All UI classes implements the same basic class: \Charcoal\Ui\UiItemInterface
. This interface defines a basic set of properties that are shared across (almost) all ui item types.
Key | Type | Default | Description |
---|---|---|---|
type | string |
||
title | string [1] |
||
subtitle | string [1] |
||
description | string [1] |
||
notes | string [1] |
||
template_ident | string |
'' |
The default view template. |
Notes:
- [1] Indicates a multilingual string (
TranslationString
).
The UiItemInterface
is a Viewable item; that means it also implements the \Charcoal\View\ViewableInterface
. The AbstractUiItem
fully implements this interface by using \Charcoal\View\ViewableTrait
.
Viewable objects can set a View object with setView($view)
have a template_ident
(which can be set with setTemplateIdent($id)
). See the charcoal/view module for details.
The easiest way to use a View is by setting a ViewInterface
object as view
service on a DI container / Service Provider.
Dashboards define a layout of widgets.
layout
is aLayoutInterface
object that can be created with aLayoutBuilder
.widgets
is a collection of anyUiItemInterface
objects.- Any PHP class can actually be a "widget", but base widgets are provided as convenience.
Key | Type | Default | Description |
---|---|---|---|
type | string |
||
layout | LayoutConfig |
||
widgets | array |
logger
view
widget_factory
setLayout()
layout()
setWidgets(array $widgets)
widgets()
addWidget()
numWidgets()
hasWidget()
Layouts define a grid (column-based) structure.
Key | Type | Default | Description |
---|---|---|---|
structure | array |
||
structure.columns | array |
Example layout JSON config
"layout": {
"structure": [
{ "columns": [ 2, 1 ] },
{ "columns": [ 1 ] },
{ "columns": [ 1 ] }
]
}
setStructure(array $layouts)
structure()
numRows()
rowIndex($position = null)
rowData($position = null)
rowNumColumns($position = null)
rowNumCells($position = null)
rowFirstCellIndex($position = null)
cellRowIndex($position = null)
numCellsTotal()
cellSpan($position = null)
cellSpanBy12($position = null)
cellStartsRow($position = null)
cellEndsRow($position = null)
start()
end()
The UI package has three basic objects that use a layout: dashboards, forms and form groups.
Those classes implement the Layout requirement by implementing the \Charcoal\Ui\Layout\LayoutAwareInterface
with the use of its corresponding LayoutAwareTrait
.
Forms define a layout of form groups, form options, data and metadata.
- Forms have groups, which have inputs.
- Groups can be layouted with a
layout
object. - Form can be pre-populated with form data.
- Metadata ca
Key | Type | Default | Description |
---|---|---|---|
type | string |
||
action | string |
'' |
URL where the form will be submitted. |
method | string |
'post' |
HTTP method to submit ("post" or "get"). |
layout | LayoutConfig |
||
groups | FormGroupConfig[] |
||
form_data | array |
||
metadata | array |
view
group_factory
setAction($action)
action()
setMethod($method)
method()
setGroups(array $groups)
groups()
addGroup($groupIdent, $groupData)
numGroups()
hasGroups()
setFormData(array $formData)
formData()
addFormData()
Key | Type | Default | Description |
---|---|---|---|
form | |||
template_ident | string |
||
template_controller | string |
||
priority | int |
||
layout | LayoutConfig |
||
properties | array |
setForm($form)
setInputs(array $groups)
inputs()
addInput($inputIdent, $inputData)
numInputs()
hasInputs()
form
label
property_ident
template_ident
template_data
read_only
required
disabled
multiple
input_id
input_name
Menu items define a menu level (ident, label and url) and its children (array of Menu Item).
ident
icon_ident
label
url
children
setIdent($ident)
ident()
setLabel($label)
label()
setUrl($url)
url()
setChildren($children)
children()
numChildren()
hasChildren()
Most UI elements are very dynamic. The types of object to create is often read from a string in a configuration object. Therefore, factories are the preferred way of instanciating new UI items.
Ui items have also many inter-connected dependencies. Builders should therefore be used for object creation / instanciation. They use a factory internally, and have a build($opts)
methods that allow to retrieve class name from a dynamic source, do initialization, dpendencies management and more. Builders require Pimple
for a DI container.
\Charcoal\Ui\Dashboard\DashboardFactory
\Charcoal\Ui\Layout\LayoutFactory
\Charcoal\Ui\Form\FormFactory
\Charcoal\Ui\FormGroup\FormGroupFactory
\Charcoal\Ui\FormInput\FormInputFactory
\Charcoal\Ui\Menu\MenuFactory
\Charcoal\Ui\MenuItem\MenuItemFactory
\Charcoal\Ui\Dashboard\DashboardBuilder
\Charcoal\Ui\Layout\LayoutBuilder
\Charcoal\Ui\Form\FormBuilder
\Charcoal\Ui\FormGroup\FormGroupBuilder
\Charcoal\Ui\FormInput\FormInputBuilder
\Charcoal\Ui\Menu\MenuBuilder
\Charcoal\Ui\MenuItem\MenuItemBuilder
Service providers are provided in the Charcoal\Ui\ServiceProvider
namespace for for convenience. They are the recommended way of using the UI package, as they register all the creational utilities to a container, taking care of dependencies.
\Charcoal\Ui\ServiceProvider\DashboardServiceProvider
dashboard/factory
dashboard/builder
\Charcoal\Ui\ServiceProvider\FormServiceProvider
form/factory
form/builder
form/group/factory
form/input/factory
form/input/builder
\Charcoal\Ui\ServiceProvider\LayoutServiceProvider
layout/factory
layout/builder
\Charcoal\Ui\ServiceProvider\MenuServiceProvider
menu/factory
menu/builder
menu/item/factory
menu/item/builder
\Charcoal\Ui\ServiceProvider\UiServiceProvider
- Register all the other service providers (dashboard, form, layout and menu).