The standard Charcoal Admin Control Panel (Backend Dashboard).
The preferred (and only supported) way of installing charcoal-admin is with composer:
$ composer require locomotivemtl/charcoal-admin
Note that charcoal-admin is intended to be run along a
charcoal-app
based project. To start from a boilerplate:$ composer create-project locomotivemtl/charcoal-project-boilerplate
- locomotivemtl/charcoal-core
- The framework classes. (Cache, Model, Metadata, View, Property, source, etc.)
- It brings the following dependencies:
- locomotivemtl/charcoal-config
- The configuration container for all things Charcoal.
- locomotivemtl/charcoal-property
- The building blocks of the Model's definition.
- locomotivemtl/charcoal-image
- Image manipulation.
- locomotivemtl/charcoal-view
- The view / templating engines. Mustache is the default engine.
- locomotivemtl/charcoal-config
- locomotivemtl/charcoal-object
- Object definition (Content and UserData), behaviors and tools.
- locomotivemtl/charcoal-user
- User defintion (as Charcoal Model), authentication and authorization (with Laminas ACL).
👉 Development dependencies are described in the Development section of this README file.
Which, in turn, require:
PHP 7.3+
ext-fileinfo
File / MIME identification.ext-mbstring
Multi-bytes string support.ext-pdo
PDO Database driver.
- MySQL
- Other databases (postgresql, sqlite) should work but are not supported.
- Apache with
mod_rewrite
- Other HTTP servers (IIS, _nginx) should work but are not supported.
pimple/pimple
for dependency injection container.slim/slim
for the routing engine and HTTP handling.mustache/mustache
for the template engine.phpmailer
to send emails.league/climate
for CLI utilities.monolog/monolog
for (PSR-3) logging.
The charcoal admin control panel is:
- Additional
admin
metadata on charcoal objects and models, which controls automatically how they can be customized in the backend. - A user / authentication system, which uses ACL for permissions.
- A customizable 2-level menu, which builds custom backend for every install.
- Dashboards and widgets. With some prebuilt functionalities for:
- Listing collection of objects (
admin/object/collection
), customizable from the object's admin metadata. - Creating and editing objects (
admin/object/edit
), customizable from the objects's admin metadata.
- Listing collection of objects (
- Set of scripts to manage objects and the backend from the CLI.
Like all Charcoal projects / modules, the main components are:
- Autoloader
- PSR-4, Provided by Composer.
- Config
- As JSON or PHP files in the config/ directory.
- Front Controller
- The admin front controller is handled in the
\Charcoal\Admin\Module
class.
- The admin front controller is handled in the
- Objects
- Typically into
\Charcoal\Object\Content
and\Charcoal\Object\UserData
- Extends
\Charcoal\Model\AbstractModel
, which implements the following interface:\Charcoal\Model\ModelInterface
\Charcoal\Core\IndexableInterface
\Charcoal\Metadata\DescribableInterface
\Charcoal\Source\StorableInterface
\Charcoal\Validator\ValidatableInterface
\Charcaol\View\ViewableInterface
- PHP Models in
src/Charcoal/Boilerplate/
- JSON metadata in
metadata/charcoal/boilerplate/
- Typically into
- Templates
- Templates are specialized Model which acts as View / Controller
- Split in
Templates
,Widgets
,PropertyDisplay
, andPropertyInput
- PHP Models in
src/Charcoal/Boilerplate/Template/
- Mustache views (templates) in
templates/boilerplate/
- Optionnally, templates metadata in
metdata/boilerplate/template/
- Actions
- Actions handle input and provide a response to a request
- They create the charcoal-admin REST API.
- The PHP classes in
src/Charcoal/Boilerplate/Action
- Assets
- Assets are files required to be on the webserver root
- Scripts, in
src/scripts/
and compiled inwww/assets/scripts/
- Styles , with SASS in
src/styles/
and compiled CSS inwww/assets/styles/
- Images, in
www/assets/images/
Authentication is done through the Charcoal\Admin\User
class. It reuses the authentication, authorization and user model provided by [charcoal-user](https://github.com/locomotivemtl/charcoal-user.
User-Interface Elements, in charcoal-admin (or any other Charcoal modules, in fact), are composed of:
- A PHP Controller, in src/Charcoal/Admin/{{type}}/{{ident}}
- A mustache templates, in templates/charcoal/admin/{{type}}/{{ident}}
- Optional additional metadata, in metadata/charcoal/admin/{{type}}/{{ident}}
There are 3 main types of UI Elements: Templates, Widgets and Property Inputs.
See the src/Charcoal/Admin/Templates 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/ directory.
In addition to being standard Template Models (controllers), all Template of the admin module also implements the \Charcoal\Admin\Template
class.
This class provides additional controls to all templates:
has_feedbacks
andfeedbacks
title
,subtitle
,show_title
andshow_subtitle
auth_required
- Protected, true by default. Set to false for templates that do not require an authenticated admin user.
The following base widgets are available to build the various admin templates:
Dashboard
Feedbacks
Form
FormGroup
FormProperty
Graph/Bar
Graph/Line
Graph/Pie
- Layout
- MapWidget
- Table
- TableProperty
Similar 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.
The following property inputs are available to build forms in the admin module:
Audio
- A special HTML5 widget to record an audio file from the microphone.
Checkbox
DateTimePicker
- A date-time picker widget.
- Requires the ``
File
- A default
<input type="file">
that can be used as a base for all File properties.
- A default
Image
- A specialized file input meant for uploading / previewing images.
MapWidget
- A specialized widget to edit a point on a map.
- Requires google-map.
Number
Radio
Readonly
Select
Switch
- A specialized Checkbox meant to be displayed as an on/off switch.
Text
- A default
<input type="text">
that can be used with most property types.
- A default
Textarea
- A default
<textarea>
editor that can be used with most textual property types.
- A default
Tinymce
- A specialized Textarea wysiwyg editor.
- Requires the
tinymce
javascript library.
Selectize
- A specialized hybrid between a Textbox and Select jQuery based.
- Highly customizable.
- Requires the
selectize
javascript library.
Name | Type | Description | Default | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
choice_obj_map | array | Custom 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.
|
{ "value" : "id", "label": "name:title:label:id" } |
||||||||
form_ident | string|array | Allow 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 "create" and "update" array keys | "quick" |
||||||||
selectize_templates | string|array | Allow custom rendering for selectize [item] and [option]. Overrule choice_obj_map[label]. Priotize using this for rendering custom labels instead of choice_obj_map. The 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.
|
{} |
||||||||
allow_create | bool | Display a 'create' button which triggers the selectize create functionality. | false |
||||||||
allow_update | bool | Display an 'update' button which triggers the selectize update functionality. Applies to currently selected element. | false |
||||||||
allow_clipboard_copy | bool | Display a 'copy' button which allows the user to easilly copy all selected elements at once. | false |
||||||||
deferred | bool | Allow the select to load the dropdown "options" with an ajax request instead of on load. This can speed up the page load when there is a lot of "options". | false |
||||||||
selectize_options | array | Defines the selectize js options. See the Selectize.js doc. Some usefull ones are :
|
{ persist: true, preload: "focus", openOnFocus: true, labelField: "label", searchField: [ "value", "label" ] } |
Usage example :
"categories": { "type": "object", "input_type": "charcoal/admin/property/input/selectize", "multiple": true, "deferred": true, "obj_type": "cms/object/news-category", "pattern": "title", "choice_obj_map": { "value": "ident", "label": "{{customLabelFunction}} - {{someAdditionalInfo }}" }, "selectize_templates": { "item": "project/selectize/custom-item-template", "option": "project/selectize/custom-option-template", "controller": "project/selectize/custom-template" }, "selectize_options": { "plugins": { "drag_drop": {}, "btn_remove": {}, "btn_update": {} } }, "form_ident": { "create": "quick.create", "update": "quick.update" } }
Selectize templates examples :
"selectize_templates": { "item": "{{customLabelFunction}} - {{someAdditionalInfo }}", "option": "{{customLabelFunction}} - {{someAdditionalInfo }}" }, --- "selectize_templates": "{{customLabelFunction}} - {{someAdditionalInfo }}", --- "selectize_templates": "project/selectize/custom-template", --- "selectize_templates": { "item": "project/selectize/custom-item-template", "option": "project/selectize/custom-option-template", "controller": "project/selectize/custom-template", "data": { "category": "{{selectedCategory}}" } },
See the src/Charcoal/Admin/Action/ directory for the list of availables Actions in this module.
In addition to being standard Action Models (controllers), all Action of the admin module also implements the \Charcoal\Admin\Action
class.
admin/login
admin/object/delete
admin/object/save
admin/object/update
admin/widget/load
admin/widget/table/inline
admin/widget/table/inlinue-multi
See the src/Charcoal/Admin/Action/Cli/ directory for the list of all available Cli Actions in this module.
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.
👉 The charcoal-cli tool, available from
charcoal-project-boilerplate
, is the perfect tool to call the CLI Actions. Make sure it stays outside the document root!
admin/objects
- List the object of a certain
obj-type
.
- List the object of a certain
admin/object/create
- Create a new object (and save it to storage) of a certain
obj-type
according to its metadata's properties.
- Create a new object (and save it to storage) of a certain
admin/object/table/alter
- Alter the existing database table of
obj-type
according to its metadata's properties.
- Alter the existing database table of
admin/object/table/create
- Create the database table for
obj-type
according to its metadata's properties.
- Create the database table for
admin/user/create
To install the development environment:
$ composer install --prefer-source
To run the tests:
$ composer test
- The auto-generated
phpDocumentor
API documentation is available at https://locomotivemtl.github.io/charcoal-admin/docs/master/ - The auto-generated
apigen
API documentation is available at https://codedoc.pub/locomotivemtl/charcoal-admin/master/
The Charcoal-Admin module follows the Charcoal coding-style:
- PSR-1, except for
- Method names MUST be declared in
snake_case
.
- Method names MUST be declared in
- PSR-2, except for the PSR-1 requirement.q
- PSR-4, autoloading is therefore provided by Composer
- phpDocumentor
- Add DocBlocks for all classes, methods, and functions;
- For type-hinting, use
boolean
(instead ofbool
),integer
(instead ofint
),float
(instead ofdouble
orreal
); - Omit the
@return
tag if the method does not return anything.
- Naming conventions
- Read the phpcs.xml file for all the details.
Coding style validation / enforcement can be performed with
composer phpcs
. An auto-fixer is also available withcomposer phpcbf
.
For Javascript, the following coding style is enforced:
- todo
Every classes, methods and functions should be covered by unit tests. PHP code can be tested with PHPUnit and Javascript code with QUnit.
- Mathieu Ducharme [email protected]
- Benjamin Roch [email protected]
- Dominic Lord [email protected]
- Chauncey McAskill [email protected]
- Antoine Boulanger [email protected]
- Joel Alphonso [email protected]
Charcoal is licensed under the MIT license. See LICENSE for details.