locomotivemtl / charcoal-ui
UI tools (Dashboard, Layout, Form and Menu)
Installs: 15 681
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 10
Forks: 2
Open Issues: 0
Requires
- php: >7.1
- locomotivemtl/charcoal-config: ~0.10
- locomotivemtl/charcoal-factory: ~0.4
- locomotivemtl/charcoal-translator: ~0.3
- locomotivemtl/charcoal-user: ~0.6
- locomotivemtl/charcoal-view: ~0.4
- psr/log: ^1.0
Requires (Dev)
- mustache/mustache: ^2.11
- php-coveralls/php-coveralls: ^2.2
- phpunit/phpunit: ^7.5
- pimple/pimple: ^3.0
- squizlabs/php_codesniffer: ^3.3
- tedivm/stash: ~0.14
Suggests
- pimple/pimple: DI Container to register the various Service Providers.
- dev-master / 0.3.x-dev
- 0.3.13.1
- 0.3.13
- 0.3.12
- 0.3.11
- 0.3.10.1
- 0.3.10
- 0.3.9
- 0.3.8.2
- 0.3.8.1
- 0.3.8
- 0.3.7
- 0.3.6
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3
- 0.2.10
- 0.2.9
- 0.2.8
- 0.2.7
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2
- 0.1.5
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1
- dev-feature/camelizePropertiesAndUseArrayAccess
- dev-acl-manager-refactor
- dev-mcaskill-patch-view
- dev-mcaskill-form-view
- dev-mcaskill-labeller
This package is auto-updated.
Last update: 2024-11-07 00:07:42 UTC
README
The Charcoal\Ui
module provides tools to create UI elements (dashboards, layouts, forms and menus) from simple metadata / config.
Table of contents
- How to install
- Base UI Item
- Dashboard
- Layout
- Form
- Form Group
- Form Input
- Menu
- Menu Item
- Service Providers
- Development
How to install
The preferred (and only supported) way of installing charcoal-ui is with composer:
$ composer require locomotivemtl/charcoal-ui
Dependencies
- PHP 7.1+
psr/log
- A PSR-3 compliant logger should be provided to the various services / classes.
locomotivemtl/charcoal-config
0.6+- The UI objects are configurable with various configs.
locomotivemtl/charcoal-translation
- To provide l10n to the UI objects.
locomotivemtl/charcoal-view
0.1+- The base
UiItem
areViewable
, meaning they can be rendered with aView
.
- The base
Example Usage
Form
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' => 'mat@locomotive.ca', ]; $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();
Base UI Item
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.
Base UI Item config
[1] indicates a l10n string (TranslationString
)
View Integration
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.
Dashboard
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.
Dashboard config
Dashboard dependencies
logger
view
widget_factory
Dashboard API
setLayout()
layout()
setWidgets(array $widgets)
widgets()
addWidget()
numWidgets()
hasWidget()
Layout
Layouts define a grid (column-based) structure.
Layout config
Example layout JSON config
"layout": { "structure": [ { "columns": [ 2, 1 ] }, { "columns": [ 1 ] }, { "columns": [ 1 ] } ] }
Layout API
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()
Layout Aware objects
In the charcoal-ui
module, 3 base objects 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
.
Form
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
Form config
Form dependencies
view
group_factory
Form API
setAction($action)
action()
setMethod($method)
method()
setGroups(array $groups)
groups()
addGroup($groupIdent, $groupData)
numGroups()
hasGroups()
setFormData(array $formData)
formData()
addFormData()
Form Group
Form group config
Form group API
setForm($form)
setInputs(array $groups)
inputs()
addInput($inputIdent, $inputData)
numInputs()
hasInputs()
Form Input
form
label
property_ident
template_ident
template_data
read_only
required
disabled
multiple
input_id
input_name
Menu
Menu Item
Menu items define a menu level (ident, label and url) and its children (array of Menu Item).
Menu item config
ident
icon_ident
label
url
children
Menu item API
setIdent($ident)
ident()
setLabel($label)
label()
setUrl($url)
url()
setChildren($children)
children()
numChildren()
hasChildren()
Creational Helpers
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.
Factories
\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
Builders
\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
Service providers are provided in the Charcoal\Ui\ServiceProvider
namespace for for convenience. They are the recommended way of using charcoal-ui
, 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).
Required services
There are a few dependencies on external services, that should be set on the same DI container as the one passed to the service providers:
logger
, a PSR-3 logger instance.- Typically a
monolog
instance fromcharcoal-app
.
- Typically a
view
, a\Charcoal\View\ViewInterface
instance.- Typically provided with
\Charcoal\App\Provider\ViewServiceProvider
.
- Typically provided with
Development
To install the development environment:
$ composer install --prefer-source
API documentation
- The auto-generated
phpDocumentor
API documentation is available at https://locomotivemtl.github.io/charcoal-ui/docs/master/ - The auto-generated
apigen
API documentation is available at https://codedoc.pub/locomotivemtl/charcoal-ui/master/
Development dependencies
phpunit/phpunit
squizlabs/php_codesniffer
satooshi/php-coveralls
Continuous Integration
Coding Style
The Charcoal-Ui module follows the Charcoal coding-style:
- PSR-1
- PSR-2
- PSR-4, autoloading is therefore provided by Composer.
- phpDocumentor comments.
- Read the phpcs.xml file for all the details on code style.
Coding style validation / enforcement can be performed with
composer phpcs
. An auto-fixer is also available withcomposer phpcbf
.
Authors
- Mathieu Ducharme mat@locomotive.ca
License
Charcoal is licensed under the MIT license. See LICENSE for details.