charcoal/ui

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

维护者

详细信息

github.com/charcoalphp/ui

主页

源代码

安装: 2

依赖者: 1

建议者: 0

安全: 0

星星: 0

关注者: 2

分支: 0

v5.0.0 2024-03-13 15:05 UTC

Requires

Requires (Dev)

Suggests

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

Replaces

MIT 883c6a7fba90595298a19e3d2d7906719e537b29

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

menuuiformcontrollayoutdashboardcharcoal

This package is auto-updated.

Last update: 2024-09-13 16:26:55 UTC

README

UI 包提供了创建用户界面元素的抽象工具。

安装

composer require charcoal/ui

对于 Charcoal 项目，服务提供者可以从您的配置文件中注册

{
    "service_providers": {
        "charcoal/ui/service-provider/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();

API

基本 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()

布局感知对象

UI 包有三个基本对象使用布局：仪表板、表单 和 表单组。

这些类通过使用相应的 LayoutAwareTrait 实现了 \Charcoal\Ui\Layout\LayoutAwareInterface 来满足布局需求。

表单

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

  • 表单有 组，它们有 输入。
  • 组可以使用一个 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()

表单输入

  • 表单
  • 标签
  • 属性标识
  • 模板标识
  • 模板数据
  • 只读
  • 必填
  • 禁用
  • 多选
  • 输入ID
  • 输入名称

菜单

菜单项

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

菜单项配置

  • 标识
  • 图标标识
  • 标签
  • URL
  • 子菜单

菜单项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命名空间中提供，以方便使用。它们是使用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
    • 注册所有其他服务提供商（仪表板、表单、布局和菜单）。

资源