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
  • 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

^[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

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 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.