README

The Admin package provides a customizable administration panel to manage data for Web applications and APIs.

Installation

composer require charcoal/admin

Overview

Core concepts

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.
Set of scripts to manage objects and the backend from the CLI.

What's inside this module?

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.
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/
Templates
- Templates are specialized Model which acts as View / Controller
- Split in Templates, Widgets, PropertyDisplay, and PropertyInput
- 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 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 in www/assets/scripts/
- Styles , with SASS in src/styles/ and compiled CSS in www/assets/styles/
- Images, in www/assets/images/

Users

Authentication is done through the Charcoal\Admin\User class. It reuses the authentication, authorization and user model provided by charcoal/user.

UI Elements

User-Interface elements in the Admin package (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.

Templates

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 and feedbacks
title, subtitle, show_title and show_subtitle
auth_required
- Protected, true by default. Set to false for templates that do not require an authenticated admin user.

Widgets

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

Property Inputs

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.
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.
Textarea
- A default <textarea> editor that can be used with most textual property types.
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.

Selectize inputs options

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}}"
   }
},

Actions

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.

Post Actions

admin/login
admin/object/delete
admin/object/save
admin/object/update
admin/widget/load
admin/widget/table/inline
admin/widget/table/inlinue-multi

CLI Actions

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.

admin/objects
- List the object of a certain obj-type.
admin/object/create
- Create a new object (and save it to storage) of a certain obj-type according to its metadata's properties.
admin/object/table/alter
- Alter the existing database table of obj-type according to its metadata's properties.
admin/object/table/create
- Create the database table for obj-type according to its metadata's properties.
admin/user/create

Resources

Contributing
Report issues and send pull requests in the main Charcoal repository

charcoal / admin

Maintainers

Details