Charcoal UI

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
  • Dependencies
• Base UI Item
• Dashboard
• Layout
• Form
• Form Group
• Form Input
• Menu
• Menu Item
• Service Providers
• Development
  • Development dependencies
  • Coding Style
  • Authors
  • Changelog

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 are Viewable, meaning they can be rendered with a View.

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

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.

^[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 a LayoutInterface object that can be created with a LayoutBuilder.
• widgets is a collection of any UiItemInterface objects. - Any PHP class can actually be a "widget", but base widgets are provided as convenience.

Dashboard config

Key	Type	Default	Description
type	string
layout	LayoutConfig
widgets	array

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

Key	Type	Default	Description
structure	array
structure.columns	array

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

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

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

Key	Type	Default	Description
form
template_ident	string
template_controller	string
priority	int
layout	LayoutConfig
properties	array

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 from charcoal-app.
• view, a \Charcoal\View\ViewInterface instance.
  • Typically provided with \Charcoal\App\Provider\ViewServiceProvider.

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

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

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 with composer phpcbf.

Authors

• Mathieu Ducharme mat@locomotive.ca

License

Charcoal is licensed under the MIT license. See LICENSE for details.