locomotivemtl/charcoal-ui

UI tools (Dashboard, Layout, Form and Menu)

0.3.13.1 2021-12-22 22:28 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

The preferred (and only supported) way of installing charcoal-ui is with composer:

$ composer require locomotivemtl/charcoal-ui

Dependencies

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

Development dependencies

  • phpunit/phpunit
  • squizlabs/php_codesniffer
  • satooshi/php-coveralls

Continuous Integration

Coding Style

The Charcoal-Ui module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Authors

License

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