{"id":19250290,"url":"https://github.com/charcoalphp/admin","last_synced_at":"2025-07-10T20:33:10.272Z","repository":{"id":37535857,"uuid":"505902913","full_name":"charcoalphp/admin","owner":"charcoalphp","description":"[READ-ONLY] The admin (Backend Dashboard) for Charcoal","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:50.000Z","size":164579,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-06T10:04:40.675Z","etag":null,"topics":["admin","backend","charcoal","cms","php","read-only-repository"],"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}},"created_at":"2022-06-21T15:35:04.000Z","updated_at":"2022-06-21T20:42:32.000Z","dependencies_parsed_at":"2024-01-13T04:50:03.201Z","dependency_job_id":"426d388f-34b1-4341-ab53-600b992205ea","html_url":"https://github.com/charcoalphp/admin","commit_stats":{"total_commits":2423,"total_committers":22,"mean_commits":"110.13636363636364","dds":0.6727197688815518,"last_synced_commit":"2cf0c06037875708119f2fd1e986412c263e3437"},"previous_names":[],"tags_count":351,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/admin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fadmin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fadmin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fadmin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fadmin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/admin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fadmin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264652738,"owners_count":23644322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["admin","backend","charcoal","cms","php","read-only-repository"],"created_at":"2024-11-09T18:16:43.403Z","updated_at":"2025-07-10T20:33:10.246Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","readme":"Charcoal Admin\n==============\n\nThe Admin package provides a customizable administration panel to manage data for Web applications and APIs.\n\n## Installation\n\n```shell\ncomposer require charcoal/admin\n```\n\n## Overview\n\n### Core concepts\n\nThe _charcoal admin control panel_ is:\n\n* Additional `admin` metadata on charcoal objects and models, which controls automatically how they can be customized in the backend.\n* A user / authentication system, which uses ACL for permissions.\n* A customizable 2-level menu, which builds custom backend for every install.\n* Dashboards and widgets. With some prebuilt functionalities for:\n  * Listing collection of objects (`admin/object/collection`), customizable from the object's _admin metadata_.\n  * Creating and editing objects (`admin/object/edit`), customizable from the objects's _admin metadata_.\n* Set of _scripts_ to manage objects and the backend from the CLI.\n\n### What's inside this module?\n\nLike all Charcoal projects / modules, the main components are:\n\n* **Autoloader**\n  * _PSR-4_, Provided by Composer.\n* **Config**\n  * As JSON or PHP files in the [config/](config/) directory.\n* **Front Controller**\n  * The admin front controller is handled in the `\\Charcoal\\Admin\\Module` class.\n* **Objects**\n  * Typically  into `\\Charcoal\\Object\\Content` and `\\Charcoal\\Object\\UserData`\n  * Extends `\\Charcoal\\Model\\AbstractModel`, which implements the following interface:\n    * `\\Charcoal\\Model\\ModelInterface`\n    * `\\Charcoal\\Core\\IndexableInterface`\n    * `\\Charcoal\\Metadata\\DescribableInterface`\n    * `\\Charcoal\\Source\\StorableInterface`\n    * `\\Charcoal\\Validator\\ValidatableInterface`\n    * `\\Charcaol\\View\\ViewableInterface`\n  * PHP Models in `src/Charcoal/Boilerplate/`\n  * JSON metadata in `metadata/charcoal/boilerplate/`\n* **Templates**\n  * Templates are specialized Model which acts as View / Controller\n  * Split in `Templates`, `Widgets`, `PropertyDisplay`, and `PropertyInput`\n  * PHP Models in `src/Charcoal/Boilerplate/Template/`\n  * Mustache views (templates) in `templates/boilerplate/`\n  * Optionnally, templates metadata in `metdata/boilerplate/template/`\n* **Actions**\n  * Actions handle input and provide a response to a request\n  * They create the Admin REST API.\n  * The PHP classes in `src/Charcoal/Boilerplate/Action`\n* **Assets**\n  * Assets are files required to be on the webserver root\n  * Scripts, in `src/scripts/` and compiled in `www/assets/scripts/`\n  * Styles , with SASS in `src/styles/` and compiled CSS in `www/assets/styles/`\n  * Images, in `www/assets/images/`\n\n### Users\n\nAuthentication is done through the `Charcoal\\Admin\\User` class. It reuses the authentication, authorization and user model provided by [charcoal/user].\n\n## UI Elements\n\nUser-Interface elements in the Admin package (or any other Charcoal modules, in fact), are composed of:\n\n* A PHP Controller, in _src/Charcoal/Admin/{{type}}/{{ident}}_\n* A mustache templates, in _templates/charcoal/admin/{{type}}/{{ident}}_\n* Optional additional metadata, in _metadata/charcoal/admin/{{type}}/{{ident}}_\n\nThere are 3 main types of UI Elements: _Templates_, _Widgets_ and _Property Inputs_.\n\n### Templates\n\nSee the [src/Charcoal/Admin/Templates](src/Charcoal/Admin/Template) directory for the list of available Templates in this module. Note that the template views themselves (the mustache templates) are located in [templates/charcoal/admin/template/](templates/charcoal/admin/template/) directory.\n\nIn addition to being standard Template Models (controllers), all _Template_ of the admin module also implements the `\\Charcoal\\Admin\\Template` class.\n\nThis class provides additional controls to all templates:\n\n* `has_feedbacks` and `feedbacks`\n* `title`, `subtitle`, `show_title` and `show_subtitle`\n* `auth_required`\n  * Protected, true by default. Set to false for templates that do not require an authenticated admin user.\n\n### Widgets\n\nThe following base widgets are available to build the various _admin_ templates:\n\n* `Dashboard`\n* `Feedbacks`\n* `Form`\n* `FormGroup`\n* `FormProperty`\n* `Graph/Bar`\n* `Graph/Line`\n* `Graph/Pie`\n* `Layout`\n* `MapWidget`\n* `Table`\n* `TableProperty`\n\n### Property Inputs\n\nSimilar to other UI elements, _Inputs_ are specialized widgets that are meant to display a \"form element\" for a `Property`. Properties models are defined in the [charcoal/property] package.\n\nThe following property inputs are available  to build forms in the _admin_ module:\n\n* `Audio`\n  * A special HTML5 widget to record an audio file from the microphone.\n* `Checkbox`\n* `DateTimePicker`\n  * A date-time picker widget.\n  * Requires the ``\n* `File`\n  * A default `\u003cinput type=\"file\"\u003e` that can be used as a base for all _File_ properties.\n* `Image`\n  * A specialized file input meant for uploading / previewing images.\n* `MapWidget`\n  * A specialized widget to edit a point on a map.\n  * Requires google-map.\n* `Number`\n* `Radio`\n* `Readonly`\n* `Select`\n* `Switch`\n  * A specialized _Checkbox_ meant to be displayed as an on/off switch.\n* `Text`\n  * A default `\u003cinput type=\"text\"\u003e` that can be used with most property types.\n* `Textarea`\n  * A default `\u003ctextarea\u003e` editor that can be used with most textual property types.\n* `Tinymce`\n  * A specialized _Textarea_ wysiwyg editor.\n  * Requires the `tinymce` javascript library.\n* `Selectize`\n  * A specialized hybrid between a _Textbox_ and _Select_ jQuery based.\n  * Highly customizable.\n  * Requires the `selectize` javascript library.\n\n#### Selectize inputs options\n\n\u003ctable width=\"100%\"\u003e\n\u003ctr\u003e\n  \u003cth width=\"120px\" align=\"left\"\u003eName\u003c/th\u003e\n  \u003cth width=\"30px\" align=\"left\"\u003eType\u003c/th\u003e\n  \u003cth align=\"left\"\u003eDescription\u003c/th\u003e\n  \u003cth width=\"60px\" align=\"left\"\u003eDefault\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003echoice_obj_map\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003earray\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eCustom mapping between an object properties or callable and the selectize. It is discouraged to use renderable data. choice_obj_map must be a mapping with existing object properties.\n  \u003ctable class=\"table table-bordered table-hover table-condensed\"\u003e\n          \u003cbr/\u003e\n          \u003cbr/\u003e\n          \u003ctbody\u003e\u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003evalue\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eObject property or object callable. Defines the actual value to be registered in the database\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003elabel\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eObject property or object callable. Defines the visible label of the input.\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003c/tbody\u003e\n      \u003c/table\u003e\n  \u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cpre\u003e{\n  \u0026quot;value\u0026quot; : \u0026quot;id\u0026quot;,\n  \u0026quot;label\u0026quot;: \u0026quot;name:title:label:id\u0026quot;\n}\u003c/pre\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eform_ident\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003estring|array\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eAllow to define a specific object form ident when creating or updating an object. You can specify different form idents for create and update by using the \u0026quot;create\u0026quot; and \u0026quot;update\u0026quot; array keys\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003e\u0026quot;quick\u0026quot;\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eselectize_templates\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003estring|array\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eAllow custom rendering for selectize [item] and [option]. Overrule choice_obj_map[label]. Priotize using this for rendering custom labels instead of choice_obj_map.\u003cbr\u003e\u003cbr\u003eThe value can either be a string with render tags, a path to a custom template or even an array mapping to handle \"item\", \"option\", \"controller\" and \"data\" individually.\n  \u003ctable class=\"table table-bordered table-hover table-condensed\"\u003e\n          \u003cbr/\u003e\n          \u003cbr/\u003e\n          \u003ctbody\u003e\u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003eitem\u003c/strong\u003e\u003cbr\u003e(Can be a renderable string or template path)\u003c/td\u003e\n          \u003ctd\u003eCustom renderable html or mustache template for the selectize item. [Item] is the term used to refer to a selected choice.\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003eoption\u003c/strong\u003e\u003cbr\u003e(Can be a renderable string or template path)\u003c/td\u003e\n          \u003ctd\u003eCustom renderable html or mustache template for the selectize option. [Option] is the term used to refer to an available choice.\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003econtroller\u003c/strong\u003e\u003c/td\u003e\n          \u003ctd\u003eDefines a rendering context (path to php controller). (optional) Default context is the object itself.\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003ctr\u003e\n          \u003ctd valign=\"top\"\u003e\u003cstrong\u003edata\u003c/strong\u003e(array)\u003c/td\u003e\n          \u003ctd\u003eProvides additional data to the controller\u003c/td\u003e\n          \u003c/tr\u003e\n          \u003c/tbody\u003e\n      \u003c/table\u003e\n  \u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003e{}\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eallow_create\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003ebool\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eDisplay a \u0026#39;create\u0026#39; button which triggers the selectize create functionality.\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003efalse\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eallow_update\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003ebool\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eDisplay an \u0026#39;update\u0026#39; button which triggers the selectize update functionality. Applies to currently selected element.\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003efalse\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eallow_clipboard_copy\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003ebool\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eDisplay a \u0026#39;copy\u0026#39; button which allows the user to easilly copy all selected elements at once.\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003efalse\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003edeferred\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003ebool\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eAllow the select to load the dropdown \u0026quot;options\u0026quot; with an ajax request instead of on load. This can speed up the page load when there is a lot of \u0026quot;options\u0026quot;. \u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003ccode\u003efalse\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd valign=\"top\"\u003e\u003cstrong\u003eselectize_options\u003c/strong\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cem\u003earray\u003c/em\u003e\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003eDefines the selectize js options. See the \u003ca href=\"https://github.com/selectize/selectize.js/blob/master/docs/usage.md\"\u003eSelectize.js doc\u003c/a\u003e. Some usefull ones are :\n  \u003cul\u003e\n  \u003cli\u003e\u0026quot;maxItems\u0026quot;\u003c/li\u003e\n  \u003cli\u003e\u0026quot;maxOptions\u0026quot;\u003c/li\u003e\n  \u003cli\u003e\u0026quot;create\u0026quot;\u003c/li\u003e\n  \u003cli\u003e\u0026quot;placeholder\u0026quot;\u003c/li\u003e\n  \u003cli\u003e\u0026quot;searchField\u0026quot;\u003c/li\u003e\n  \u003cli\u003e\u0026quot;plugins\u0026quot;\u003c/li\u003e\n  \u003c/ul\u003e\n  Also, two home made plugins are available : \u0026quot;btn_remove\u0026quot; and \u0026quot;btn_update\u0026quot; that are custom buttons for selected items that work well with charcoal objects and doesn\u0026#39;t break styling.\u003c/td\u003e\n  \u003ctd valign=\"top\"\u003e\u003cpre\u003e{\n   persist: true,\n   preload: \"focus\",\n   openOnFocus: true, \n   labelField: \"label\",\n   searchField: [\n     \"value\",\n     \"label\"\n   ]\n}\u003c/pre\u003e\n  \u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nUsage example:\n\n```json\n\"categories\": {\n    \"type\": \"object\",\n    \"input_type\": \"charcoal/admin/property/input/selectize\",\n    \"multiple\": true,\n    \"deferred\": true,\n    \"obj_type\": \"cms/object/news-category\",\n    \"pattern\": \"title\",\n    \"choice_obj_map\": {\n        \"value\": \"ident\",\n        \"label\": \"{{customLabelFunction}} - {{someAdditionalInfo }}\"\n    },\n    \"selectize_templates\": {\n        \"item\": \"project/selectize/custom-item-template\",\n        \"option\": \"project/selectize/custom-option-template\",\n        \"controller\": \"project/selectize/custom-template\"\n    },\n    \"selectize_options\": {\n        \"plugins\": {\n            \"drag_drop\": {},\n            \"btn_remove\": {},\n            \"btn_update\": {}\n        }\n    },\n    \"form_ident\": {\n        \"create\": \"quick.create\",\n        \"update\": \"quick.update\"\n    }\n}\n```\n\nSelectize templates examples:\n\n```json\n\"selectize_templates\": {\n    \"item\": \"{{customLabelFunction}} - {{someAdditionalInfo }}\",\n    \"option\": \"{{customLabelFunction}} - {{someAdditionalInfo }}\"\n},\n\n---\n\n\"selectize_templates\": \"{{customLabelFunction}} - {{someAdditionalInfo }}\",\n\n---\n\n\"selectize_templates\": \"project/selectize/custom-template\",\n\n---\n\n\"selectize_templates\": {\n   \"item\": \"project/selectize/custom-item-template\",\n   \"option\": \"project/selectize/custom-option-template\",\n   \"controller\": \"project/selectize/custom-template\",\n   \"data\": {\n        \"category\": \"{{selectedCategory}}\"\n   }\n},\n```\n\n### Actions\n\nSee the [src/Charcoal/Admin/Action/](src/Charcoal/Admin/Action/) directory for the list of availables Actions in this module.\n\nIn addition to being standard Action Models (controllers), all _Action_ of the admin module also implements the `\\Charcoal\\Admin\\Action` class.\n\n### Post Actions\n\n* `admin/login`\n* `admin/object/delete`\n* `admin/object/save`\n* `admin/object/update`\n* `admin/widget/load`\n* `admin/widget/table/inline`\n* `admin/widget/table/inlinue-multi`\n\n### CLI Actions\n\nSee the [src/Charcoal/Admin/Action/Cli/](src/Charcoal/Admin/Action/Cli/) directory for the list of all available Cli Actions in this module.\n\n_CLI Actions_ are specialized action meant to be run, interactively, from the Command Line Interface. With the Cli Actions in this module, it becomes quick and easy to manage a Charcoal project directly from a Terminal.\n\n* `admin/objects`\n  * List the object of a certain `obj-type`.\n* `admin/object/create`\n  * Create a new object (and save it to storage) of a certain `obj-type` according to its metadata's properties.\n* `admin/object/table/alter`\n  * Alter the existing database table of `obj-type` according to its metadata's properties.\n* `admin/object/table/create`\n  * Create the database table for `obj-type` according to its metadata's properties.\n* `admin/user/create`\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/property]: https://github.com/charcoalphp/property\n[charcoal/user]:     https://github.com/charcoalphp/user\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fadmin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fadmin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fadmin/lists"}