README

标准的 Charcoal Admin 控制面板（后端仪表板）。

如何安装

安装 charcoal-admin 的首选（也是唯一支持的）方式是使用 composer

$ composer require locomotivemtl/charcoal-admin

注意 charcoal-admin 是为了与基于 charcoal-app 的项目一起运行。要从模板开始
$ composer create-project locomotivemtl/charcoal-project-boilerplate

依赖项

locomotivemtl/charcoal-core
- 框架类。包括（缓存、模型、元数据、视图、属性、源等）。
- 它带来了以下依赖项
  - locomotivemtl/charcoal-config
    - Charcoal 所有一切配置的容器。
  - locomotivemtl/charcoal-property
    - 模型定义的构建块。
    - locomotivemtl/charcoal-image
      - 图像处理。
  - locomotivemtl/charcoal-view
    - 视图/模板引擎。Mustache 是默认引擎。
locomotivemtl/charcoal-object
- 对象定义（内容和使用者数据）、行为和工具。
locomotivemtl/charcoal-user
- 用户定义（作为 Charcoal 模型）、身份验证和授权（使用 Laminas ACL）。

👉 开发依赖项在 README 文件的开发部分中描述。

这些，反过来，需要

PHP 7.3+
- ext-fileinfo 文件 / MIME 识别。
- ext-mbstring 多字节字符串支持。
- ext-pdo PDO 数据库驱动程序。
MySQL
- 其他数据库（postgresql，sqlite）应该可以工作，但不提供支持。
Apache 与 mod_rewrite
- 其他 HTTP 服务器（IIS，_nginx）应该可以工作，但不提供支持。
pimple/pimple 用于依赖注入容器。
slim/slim 用于路由引擎和 HTTP 处理。
mustache/mustache 用于模板引擎。
phpmailer 用于发送电子邮件。
league/climate 用于 CLI 工具。
monolog/monolog 用于（PSR-3）日志。

核心概念

charcoal 管理控制面板 是

Charcoal 对象和模型上的附加 admin 元数据，这些数据控制它们在后端中如何自动定制。
一个用户/身份验证系统，它使用 ACL 进行权限。
可定制的 2 级菜单，为每个安装构建自定义后端。
仪表板和小部件。具有一些预构建的功能
- 列出对象集合（admin/object/collection），可从对象的 admin 元数据 进行定制。
- 创建和编辑对象（admin/object/edit），可从对象的 admin 元数据 进行定制。
一组脚本，用于从 CLI 管理对象和后端。

这个模块里有什么？

像所有 Charcoal 项目/模块一样，主要组件包括

自动加载器
- PSR-4，由 Composer 提供。
配置
- 作为 JSON 或 PHP 文件位于 config/ 目录中。
前端控制器
- 管理员前端控制器由 \Charcoal\Admin\Module 类处理。
对象
- 通常在 \Charcoal\Object\Content 和 \Charcoal\Object\UserData 中。
- 扩展 \Charcoal\Model\AbstractModel，该模型实现以下接口
  - \Charcoal\Model\ModelInterface
  - \Charcoal\Core\IndexableInterface
  - \Charcoal\Metadata\DescribableInterface
  - \Charcoal\Source\StorableInterface
  - \Charcoal\Validator\ValidatableInterface
  - \Charcaol\View\ViewableInterface
- PHP 模型在 src/Charcoal/Boilerplate/ 中
- JSON 元数据在 metadata/charcoal/boilerplate/ 中
模板
- 模板是作为视图/控制器操作的专用模型
- 分为 Templates、Widgets、PropertyDisplay 和 PropertyInput
- PHP 模型位于 src/Charcoal/Boilerplate/Template/
- Mustache 视图（模板）位于 templates/boilerplate/
- 可选，模板元数据位于 metdata/boilerplate/template/
操作
- 操作处理输入并响应请求
- 它们创建 charcoal-admin REST API。
- 位于 src/Charcoal/Boilerplate/Action 的 PHP 类
资源
- 资源是需要放在 web 服务器根目录的文件
- 脚本，位于 src/scripts/ 并编译到 www/assets/scripts/
- 样式，使用 SASS 位于 src/styles/ 并编译成 CSS 位于 www/assets/styles/
- 图片，位于 www/assets/images/

对象

用户

身份验证通过 Charcoal\Admin\User 类完成。它重用了 [charcoal-user](https://github.com/locomotivemtl/charcoal-user) 提供的认证、授权和用户模型。

UI 元素

用户界面元素在 charcoal-admin（或任何其他 Charcoal 模块，实际上）由以下组成

一个 PHP 控制器，位于 src/Charcoal/Admin/{{type}}/{{ident}}
一个 Mustache 模板，位于 templates/charcoal/admin/{{type}}/{{ident}}
可选的额外元数据，位于 metadata/charcoal/admin/{{type}}/{{ident}}

有 3 种主要的 UI 元素类型：模板、小部件 和 属性输入。

模板

查看该模块中可用的模板列表，请参阅 src/Charcoal/Admin/Templates 目录。注意，模板视图本身（mustache 模板）位于 templates/charcoal/admin/template/ 目录。

除了是标准的模板模型（控制器）之外，该管理模块的所有模板也实现了 \Charcoal\Admin\Template 类。

这个类为所有模板提供了额外的控制

has_feedbacks 和 feedbacks
title、subtitle、show_title 和 show_subtitle
auth_required
- 受保护，默认为 true。对于不需要认证管理用户的模板，设置为 false。

小部件

以下基本小部件可用于构建各种 admin 模板

仪表板
反馈
表单
表单组
表单属性
图表/柱状图
图表/折线图
图表/饼图
布局
地图小部件
表格
表格属性

属性输入

类似于其他 UI 元素，输入是专门的 widget，旨在显示 Property 的 "表单元素"。属性模型在 charcoal-property 包中定义。

以下属性输入可用于在 admin 模块中构建表单

音频
- 一个特殊的 HTML5 小部件，可以从麦克风录制音频文件。
复选框
日期时间选择器
- 一个日期时间选择器小部件。
- 需要 ``
文件
- 一个默认的 <input type="file">，可以作为所有文件属性的基。
图片
- 一个专门用于上传/预览图片的文件输入。
地图小部件
- 一个专门用于编辑地图上点的 widget。
- 需要 google-map。
数字
单选按钮
只读
选择
开关
- 一个专门用于显示为开/关开关的 复选框。
文本
- 一个默认的 <input type="text">，可以与大多数属性类型一起使用。
多行文本框
- 一个默认的 <textarea> 编辑器，可以与大多数文本属性类型一起使用。
Tinymce
- 一个专门用于 wysiwyg 的 多行文本框 编辑器。
- 需要 tinymce JavaScript 库。
Selectize
- 一个介于 文本框 和选择之间的特殊混合体，基于 jQuery。
- 高度可定制。
- 需要 selectize JavaScript 库。

Selectize 输入选项

使用示例

"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 模板示例

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

操作

查看该模块中所有可用动作的列表，请参阅 src/Charcoal/Admin/Action/ 目录。

除了是标准的动作模型（控制器）之外，管理模块中的所有动作也实现了 \Charcoal\Admin\Action 类。

后置动作

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

CLI 动作

查看该模块中所有可用 CLI 动作的列表，请参阅 src/Charcoal/Admin/Action/Cli/ 目录。

CLI 动作 是专门的动作，旨在从命令行界面交互式运行。使用此模块中的 CLI 动作，可以快速轻松地从终端直接管理 Charcoal 项目。

👉 可从 charcoal-project-boilerplate 获取的 charcoal-cli 工具是调用 CLI 动作的完美工具。确保它位于文档根目录之外！

admin/objects
- 列出特定 obj-type 的对象。
admin/object/create
- 根据其元数据的属性创建新的对象（并将其保存到存储中）。
admin/object/table/alter
- 根据其元数据的属性修改 obj-type 的现有数据库表。
admin/object/table/create
- 根据其元数据的属性创建 obj-type 的数据库表。
admin/user/create

开发

安装开发环境

$ composer install --prefer-source

运行测试

$ composer test

API 文档

自动生成的 phpDocumentor API 文档可在 https://locomotivemtl.github.io/charcoal-admin/docs/master/ 找到。
自动生成的 apigen API 文档可在 https://codedoc.pub/locomotivemtl/charcoal-admin/master/ 找到。

编码风格

Charcoal-Admin 模块遵循 Charcoal 编码风格

PSR-1，除了
- 方法名称必须声明为 snake_case。
PSR-2，除了 PSR-1 的要求。
PSR-4，因此自动加载由 Composer 提供
phpDocumentor
- 为所有类、方法和函数添加 DocBlocks；
- 对于类型提示，使用 boolean（而不是 bool），integer（而不是 int），float（而不是 double 或 real）；
- 如果方法不返回任何内容，则省略 @return 标签。
命名约定
- 请参阅 phpcs.xml 文件以获取所有详细信息。

可以使用 composer phpcs 执行编码风格验证/强制执行。还可以使用 composer phpcbf 获取自动修复器。

对于 JavaScript，强制执行的编码风格如下

待办事项

每个类、方法和函数都应该由单元测试覆盖。可以使用 PHPUnit 测试 PHP 代码，以及使用 QUnit 测试 JavaScript 代码。

作者

Mathieu Ducharme mat@locomotive.ca
Benjamin Roch benjamin@locomotive.ca
Dominic Lord dom@locomotive.ca
Chauncey McAskill chauncey@locomotive.ca
Antoine Boulanger antoine@locomotive.ca
Joel Alphonso joel@locomotive.ca

许可证

Charcoal 使用 MIT 许可证。详情请参阅 LICENSE。

locomotivemtl / charcoal-admin

维护者

详细信息