locomotivemtl/charcoal-ui

UI 工具（仪表盘、布局、表单和菜单）

维护者

详细信息

github.com/locomotivemtl/charcoal-ui

主页

源代码

问题

安装次数: 15,644

依赖项: 1

建议者: 0

安全: 0

星标: 2

关注者: 10

分支: 2

公开问题: 0

0.3.13.1 2021-12-22 22:28 UTC

Requires

Requires (Dev)

Suggests

  • pimple/pimple: DI Container to register the various Service Providers.

MIT 4216cc9c0ddd0e5cfd99b2bca4e8e87f719347c4

  • Mathieu Ducharme <mat.woop@locomotive.ca>
  • Locomotive

menuuiformcontrollayoutdashboardcharcoal

This package is auto-updated.

Last update: 2024-09-06 23:52:22 UTC

README

Charcoal\Ui 模块提供从简单的元数据/配置创建 UI 元素（仪表盘、布局、表单和菜单）的工具。

目录

如何安装

首选（也是唯一支持）的 charcoal-ui 安装方式是使用 composer

$ composer require locomotivemtl/charcoal-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'      => '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();

基本 UI 项目

所有 UI 类都实现了相同的基本类：\Charcoal\Ui\UiItemInterface。该接口定义了一组基本属性，这些属性在（几乎）所有 UI 项目类型之间共享。

基本 UI 项目配置

[1]表示本地化字符串（TranslationString）

视图集成

UiItemInterface 是一个 可查看的 项目；这意味着它还实现了 \Charcoal\View\ViewableInterface。通过使用 \Charcoal\View\ViewableTrait，AbstractUiItem 完全实现了此接口。

可查看的 对象可以设置一个 视图 对象，使用 setView($view)，并有一个 template_ident（可以使用 setTemplateIdent($id) 设置）。有关详细信息，请参阅 charcoal-view 模块。

使用视图的最简单方法是设置一个 ViewInterface 对象作为 DI 容器/服务提供者上的 view 服务。

仪表盘

仪表盘定义了 小部件 的 布局。

  • layout 是一个 LayoutInterface 对象，可以使用 LayoutBuilder 创建。
  • widgets 是任何 UiItemInterface 对象的集合。- 实际上任何 PHP 类都可以成为一个 "小部件"，但基本小部件已作为便利项提供。

仪表盘配置

仪表盘依赖项

  • logger
  • view
  • widget_factory

仪表盘 API

  • setLayout()
  • layout()
  • setWidgets(array $widgets)
  • widgets()
  • addWidget()
  • numWidgets()
  • hasWidget()

布局

布局定义了一个网格（基于列）结构。

布局配置

示例布局 JSON 配置

"layout": {
    "structure": [
        { "columns": [ 2, 1 ] },
        { "columns": [ 1 ] },
        { "columns": [ 1 ] }
    ]
}

布局 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()

布局感知对象

在 charcoal-ui 模块中，3 个基本对象使用布局：仪表盘、表单 和 表单组。

这些类通过实现\Charcoal\Ui\Layout\LayoutAwareInterface并使用相应的LayoutAwareTrait来实现布局要求。

表单

表单定义了表单组的布局、表单选项、数据和元数据。

  • 表单有组，组中有输入。
  • 组可以使用一个layout对象进行布局。
  • 表单可以预先填充表单数据。
  • 元数据 ca

表单配置

表单依赖项

  • view
  • group_factory

表单API

  • setAction($action)
  • action()
  • setMethod($method)
  • method()
  • setGroups(array $groups)
  • groups()
  • addGroup($groupIdent, $groupData)
  • numGroups()
  • hasGroups()
  • setFormData(array $formData)
  • formData()
  • addFormData()

表单组

表单组配置

表单组API

  • 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

菜单

菜单项

菜单项定义了菜单级别（标识、标签和URL）及其子项（菜单项数组）。

菜单项配置

  • ident
  • icon_ident
  • label
  • url
  • children

菜单项API

  • setIdent($ident)
  • ident()
  • setLabel($label)
  • label()
  • setUrl($url)
  • url()
  • setChildren($children)
  • children()
  • numChildren()
  • hasChildren()

创建性助手

大多数UI元素都非常动态。要创建的对象类型通常从配置对象中的字符串中读取。因此，工厂是实例化新UI项目的首选方式。

UI元素还有许多相互关联的依赖关系。因此，应该使用构建器进行对象创建/实例化。它们在内部使用工厂，并具有build($opts)方法，允许从动态源检索类名，进行初始化、依赖关系管理等等。构建器需要Pimple作为DI容器。

工厂

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

服务提供者

服务提供商在Charcoal\Ui\ServiceProvider命名空间中提供，以方便使用。它们是推荐使用charcoal-ui的方式，因为它们将所有创建性实用工具注册到一个容器中，并处理依赖关系。

  • \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
    • 注册所有其他服务提供商（仪表板、表单、布局和菜单）。

必需的服务

有一些外部服务的依赖关系，应在传递给服务提供商的相同DI容器中设置

  • logger，PSR-3日志实例。
    • 通常来自charcoal-app的monolog实例。
  • view，一个\Charcoal\View\ViewInterface实例。
    • 通常由\Charcoal\App\Provider\ViewServiceProvider提供。

开发

安装开发环境

$ composer install --prefer-source

API 文档

开发依赖项

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

持续集成

编码风格

Charcoal-Ui 模块遵循 Charcoal 编码风格

可以使用 composer phpcs 执行编码风格验证/执行。还可以使用 composer phpcbf 使用自动修复器。

作者

许可证

Charcoal 采用 MIT 许可证。有关详细信息，请参阅 LICENSE。