{"id":19250274,"url":"https://github.com/charcoalphp/ui","last_synced_at":"2026-04-21T16:36:55.699Z","repository":{"id":37490874,"uuid":"505906747","full_name":"charcoalphp/ui","owner":"charcoalphp","description":"[READ-ONLY] Ui tools (Dashboard, Layout, Form and Menu)","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:17.000Z","size":4057,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-25T23:55:31.531Z","etag":null,"topics":["charcoal","dashboard","form","layout","menu","php","read-only-repository","ui"],"latest_commit_sha":null,"homepage":"https://github.com/charcoalphp/charcoal","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charcoalphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-21T15:45:34.000Z","updated_at":"2022-06-21T16:25:14.000Z","dependencies_parsed_at":"2024-03-05T17:46:17.091Z","dependency_job_id":"07026c12-d83d-4b32-aacf-7b02f6f66d24","html_url":"https://github.com/charcoalphp/ui","commit_stats":{"total_commits":137,"total_committers":10,"mean_commits":13.7,"dds":0.6204379562043796,"last_synced_commit":"980d7f1693ddcffb886b6d83c34af071e41e7475"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32100582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T11:25:29.218Z","status":"ssl_error","status_checked_at":"2026-04-21T11:25:28.499Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charcoal","dashboard","form","layout","menu","php","read-only-repository","ui"],"created_at":"2024-11-09T18:16:41.112Z","updated_at":"2026-04-21T16:36:55.680Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal UI\n===========\n\nThe UI package provides abstract tools for creating user interface elements.\n\n## Installation\n\n```shell\ncomposer require charcoal/ui\n```\n\nFor Charcoal projects, the service provider can be registered from your configuration file:\n\n```json\n{\n    \"service_providers\": {\n        \"charcoal/ui/service-provider/ui\": {}\n    }\n}\n```\n\n## Example\n\n```php\nuse Charcoal\\Config\\GenericMetadata;\nuse Charcoal\\Ui\\Form\\FormBuilder;\nuse Charcoal\\Ui\\Form\\FormFactory;\n\n$metadata = new GenericMetadata([\n    'properties' =\u003e [\n        'first_name' =\u003e [\n            'type' =\u003e 'string',\n        ],\n        'last_name' =\u003e [\n            'type' =\u003e 'string',\n        ],\n        'email' =\u003e [\n            'type' =\u003e 'email',\n        ],\n    ],\n]);\n\n$formData = [\n    'first_name' =\u003e 'Mathieu',\n    'last_name'  =\u003e 'Ducharme',\n    'email'      =\u003e 'mat@locomotive.ca',\n];\n\n$formConfig = [\n    'type'           =\u003e 'charcoal/ui/form/generic'\n    'template_ident' =\u003e 'foo/bar/form',\n    'template_data'  =\u003e [],\n    'label'          =\u003e 'Example Form',\n    'groups'         =\u003e [\n        'info' =\u003e [\n            'layout' =\u003e [\n                'structure' =\u003e [\n                    'columns' =\u003e [\n                        [ 1, 1 ],\n                        [ 1 ],\n                    ],\n                ],\n            ],\n            'properties' =\u003e [\n                'first_name',\n                'last_name',\n                'email',\n            ],\n        ],\n    ],\n];\n\n$formBuilder = new FormBuilder([\n    'form_factory' =\u003e new FormFactory(),\n    'view'         =\u003e $container['view'],\n]);\n\n$form = $formBuilder-\u003ebuild($formConfig);\n$form-\u003esetMetadata($metadata);\n$form-\u003esetFormData($formData);\n\necho $form-\u003erender();\n```\n\n## API\n\n### Base UI Item\n\nAll 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.\n\n#### Base UI Item config\n\n| Key                | Type                   | Default | Description |\n| ------------------ | ---------------------- | ------- | ----------- |\n| **type**           | `string`               |         |\n| **title**          | `string`\u003csup\u003e[1]\u003c/sup\u003e |         |\n| **subtitle**       | `string`\u003csup\u003e[1]\u003c/sup\u003e |         |\n| **description**    | `string`\u003csup\u003e[1]\u003c/sup\u003e |         |\n| **notes**          | `string`\u003csup\u003e[1]\u003c/sup\u003e |         |\n| **template_ident** | `string`               | `''`    | The default view template. |\n\nNotes:\n\n* \u003csup\u003e[1]\u003c/sup\u003e Indicates a multilingual string (`TranslationString`).\n\n#### View Integration\n\nThe `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`.\n\n_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.\n\nThe easiest way to use a View is by setting a `ViewInterface` object as `view` service on a DI container / Service Provider.\n\n### Dashboard\n\nDashboards define a _layout_ of _widgets_.\n\n* `layout` is a `LayoutInterface` object that can be created with a `LayoutBuilder`.\n* `widgets` is a collection of any `UiItemInterface` objects.\n  * Any  PHP class can actually be a \"widget\", but base widgets are provided as convenience.\n\n#### Dashboard config\n\n| Key         | Type           | Default     | Description |\n| ----------- | -------------- | ----------- | ----------- |\n| **type**    | `string`       |\n| **layout**  | `LayoutConfig` |\n| **widgets** | `array`        |\n\n\n#### Dashboard dependencies\n\n* `logger`\n* `view`\n* `widget_factory`\n\n#### Dashboard API\n\n* `setLayout()`\n* `layout()`\n* `setWidgets(array $widgets)`\n* `widgets()`\n* `addWidget()`\n* `numWidgets()`\n* `hasWidget()`\n\n### Layout\n\nLayouts define a grid (column-based) structure.\n\n#### Layout config\n\n| Key                   | Type     | Default     | Description |\n| --------------------- | -------- | ----------- | ----------- |\n| **structure**         | `array`  |\n| **structure.columns** | `array`  |\n\n**Example layout JSON config**\n\n```json\n\"layout\": {\n    \"structure\": [\n        { \"columns\": [ 2, 1 ] },\n        { \"columns\": [ 1 ] },\n        { \"columns\": [ 1 ] }\n    ]\n}\n```\n\n#### Layout API\n\n* `setStructure(array $layouts)`\n* `structure()`\n* `numRows()`\n* `rowIndex($position = null)`\n* `rowData($position = null)`\n* `rowNumColumns($position = null)`\n* `rowNumCells($position = null)`\n* `rowFirstCellIndex($position = null)`\n* `cellRowIndex($position = null)`\n* `numCellsTotal()`\n* `cellSpan($position = null)`\n* `cellSpanBy12($position = null)`\n* `cellStartsRow($position = null)`\n* `cellEndsRow($position = null)`\n* `start()`\n* `end()`\n\n#### Layout Aware objects\n\nThe UI package has three basic objects that use a layout: _dashboards_, _forms_ and _form groups_.\n\nThose classes implement the Layout requirement by implementing the `\\Charcoal\\Ui\\Layout\\LayoutAwareInterface` with the use of its corresponding `LayoutAwareTrait`.\n\n### Form\n\nForms define a layout of form groups, form options, data and metadata.\n\n* Forms have [_groups_](#form-group), which have [_inputs_](#form-input).\n* Groups can be layouted with a `layout` object.\n* Form can be pre-populated with _form data_.\n* _Metadata_ ca\n\n#### Form config\n\n| Key           | Type            | Default     | Description |\n| ------------- | --------------- | ----------- | ----------- |\n| **type**      | `string`        |\n| **action**    | `string`        | `''`        | URL where the form will be submitted. |\n| **method**    | `string`        | `'post'`    | HTTP method to submit (\"post\" or \"get\"). |\n| **layout**    | `LayoutConfig`  |\n| **groups**    | `FormGroupConfig[]` |\n| **form_data** | `array`         |\n| **metadata**  | `array`         |\n\n\n#### Form dependencies\n\n* `view`\n* `group_factory`\n\n#### Form API\n\n* `setAction($action)`\n* `action()`\n* `setMethod($method)`\n* `method()`\n* `setGroups(array $groups)`\n* `groups()`\n* `addGroup($groupIdent, $groupData)`\n* `numGroups()`\n* `hasGroups()`\n* `setFormData(array $formData)`\n* `formData()`\n* `addFormData()`\n\n### Form Group\n\n#### Form group config\n\n| Key                     | Type           | Default     | Description |\n| ----------------------- | -------------- | ----------- | ----------- |\n| **form**                |\n| **template_ident**      | `string`       |\n| **template_controller** | `string`       |\n| **priority**            | `int`          |\n| **layout**              | `LayoutConfig` |\n| **properties**          | `array`        |\n\n#### Form group API\n\n* `setForm($form)`\n* `setInputs(array $groups)`\n* `inputs()`\n* `addInput($inputIdent, $inputData)`\n* `numInputs()`\n* `hasInputs()`\n\n### Form Input\n\n* `form`\n* `label`\n* `property_ident`\n* `template_ident`\n* `template_data`\n* `read_only`\n* `required`\n* `disabled`\n* `multiple`\n* `input_id`\n* `input_name`\n\n### Menu\n\n### Menu Item\n\nMenu items define a menu level (ident, label and url) and its children (array of Menu Item).\n\n#### Menu item config\n\n* `ident`\n* `icon_ident`\n* `label`\n* `url`\n* `children`\n\n#### Menu item API\n\n* `setIdent($ident)`\n* `ident()`\n* `setLabel($label)`\n* `label()`\n* `setUrl($url)`\n* `url()`\n* `setChildren($children)`\n* `children()`\n* `numChildren()`\n* `hasChildren()`\n\n### Creational Helpers\n\nMost 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.\n\nUi 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.\n\n#### Factories\n\n* `\\Charcoal\\Ui\\Dashboard\\DashboardFactory`\n* `\\Charcoal\\Ui\\Layout\\LayoutFactory`\n* `\\Charcoal\\Ui\\Form\\FormFactory`\n* `\\Charcoal\\Ui\\FormGroup\\FormGroupFactory`\n* `\\Charcoal\\Ui\\FormInput\\FormInputFactory`\n* `\\Charcoal\\Ui\\Menu\\MenuFactory`\n* `\\Charcoal\\Ui\\MenuItem\\MenuItemFactory`\n\n#### Builders\n\n* `\\Charcoal\\Ui\\Dashboard\\DashboardBuilder`\n* `\\Charcoal\\Ui\\Layout\\LayoutBuilder`\n* `\\Charcoal\\Ui\\Form\\FormBuilder`\n* `\\Charcoal\\Ui\\FormGroup\\FormGroupBuilder`\n* `\\Charcoal\\Ui\\FormInput\\FormInputBuilder`\n* `\\Charcoal\\Ui\\Menu\\MenuBuilder`\n* `\\Charcoal\\Ui\\MenuItem\\MenuItemBuilder`\n\n#### Service Providers\n\nService providers are provided in the `Charcoal\\Ui\\ServiceProvider` namespace for for convenience. They are the recommended way of using the UI package, as they register all the creational utilities to a container, taking care of dependencies.\n\n* `\\Charcoal\\Ui\\ServiceProvider\\DashboardServiceProvider`\n  * `dashboard/factory`\n  * `dashboard/builder`\n* `\\Charcoal\\Ui\\ServiceProvider\\FormServiceProvider`\n  * `form/factory`\n  * `form/builder`\n  * `form/group/factory`\n  * `form/input/factory`\n  * `form/input/builder`\n* `\\Charcoal\\Ui\\ServiceProvider\\LayoutServiceProvider`\n  * `layout/factory`\n  * `layout/builder`\n* `\\Charcoal\\Ui\\ServiceProvider\\MenuServiceProvider`\n  * `menu/factory`\n  * `menu/builder`\n  * `menu/item/factory`\n  * `menu/item/builder`\n* `\\Charcoal\\Ui\\ServiceProvider\\UiServiceProvider`\n  * Register all the other service providers (dashboard, form, layout and menu).\n\n## Resources\n\n* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)\n* [Report issues](https://github.com/charcoalphp/charcoal/issues) and\n  [send pull requests](https://github.com/charcoalphp/charcoal/pulls)\n  in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)\n\n[charcoal/view]: https://github.com/charcoalphp/view\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fui/lists"}