BlackFruit-UI/plugins_dev.md

阅读须知：此文件是插件制作方法，和BlackFruit-UI项目是互相辅助的关系，BlackFruit-UI需要配置的地方都会在插件中体现，也就是一个业务管理系统的主题和后台插件控制主题的关系。所以以下内容的路径不是指的BlackFruit-UI的位置，是业务管理系统的，和本项目无关。

一、位置

插件放在\public\plugins\addon\目录下

二、目录结构

\plugins\addon\idcsmart_ticket

|--- controller(控制器目录，后台控制器直接放此目录下)

|--- clientarea(前台控制器放此目录下)

|--- lang(语言目录)

|--- zh-cn.php(中文语言文件)

|--- template(模板)

|--- admin(后台模板目录)

|--- clientarea(前台模板目录)

|--- IdcsmartTicket.php(插件主文件)

|--- route.php(自定义路由文件)

|--- sidebar.php(后台插件导航文件)

三、开发流程

以工单插件为例：

1、创建工单插件目录\public\plugins\addon\idcsmart_ticket\；

①目录名以小写字母+下划线形式，必须以字母开头，如idcsmart_ticket；

2、创建入口文件:IdcsmartTicket.php：

①命名空间namespace addon\idcsmart_ticket(控制器下命名空间对应相应目录即可,其它同理);

②以目录名大驼峰+.php，创建在插件根目录下，如idcsmart_ticket\IdcsmartTicket.php；

③文件中需要定义info属性，示例：

插件基本信息

public $info = array( 'name' => 'IdcsmartTicket', //插件英文名,作为插件唯一标识,改成你的插件英文就行了 'title' => '智简魔方工单插件', //插件名称 'description' => '智简魔方工单插件', //插件描述 'author' => 'idcsmart', //开发者 'version' => '1.0', // 版本号 );

④必须实现install()安装以及uninstall()卸载方法

⑤可实现钩子方法，如要实现订单创建后钩子after_order_create，则可在此文件中创建

public function afterOrderCreate($param)公共方法；

⑥系统会在订单创建后的位置放置⑤中的钩子，放置方式：

hook(‘after_order_create’,[‘id’=>$orderId]) ；

⑦如果定义变量noNav，表示不需要默认导航(具体参考7,插件后台导航)

public $noNav;

3、创建插件后台控制器 idcsmart_ticket\controller\TicketController.php

①命名空间addon\idcsmart_ticket\controller；

②继承后台基类控制器PluginAdminBaseController，增加了权限控制，允许使用一些通用方法；

③get_admin_id()可获取后台管理员登录ID；

④实现接口，如public function ticketList()，系统默认访问此接口的url为：

网站地址/admin/addon?_plugin=idcsmart_ticket&_controller=ticket&_action=ticket_list，说明：系统默认地址默认登录，若需要免登录访问，需要自定义路由(见后面自定义路由)；

⑤系统提供了生成④中默认访问地址的方法：

idcsmart_addon_url($url,$vars=[],$is_admin=false)

参数说明：

url: 格式：插件名://控制器名/方法，如 IdcsmartTicket://Ticket/ticketList

vars: 参数，默认为空数组

Is_admin: 是否后台，默认为false

4、创建插件前台控制器idcsmart_ticket\controller\clientarea\TicketController

.php

①命名空间addon\idcsmart_ticket\controller\clientarea；

②继承前台基类控制器PluginBaseController，允许使用一些通用方法；

③get_client_id()可获取前台客户登录ID；

④实现接口，如public function ticketList()，系统默认访问此接口的url为：

网站地址/console/addon?_plugin=idcsmart_ticket&_controller=ticket&_action=ticket_list或者：

网站地址/console/addon?_plugin=1&_controller=ticket&_action=ticket_list，1表示插件ID；

说明：系统默认地址默认登录，若需要免登录访问，需要自定义路由(见后面自定义路由)；

⑤系统提供了生成④中默认访问地址的方法：

idcsmart_addon_url($url,$vars=[],$is_admin=false)

参数说明：

url: 格式：插件名://控制器名/方法，如 IdcsmartTicket://Ticket/ticketList

vars: 参数，默认为空数组

Is_admin: 是否后台，默认为false

5、插件提供两种路由：

①、系统默认url带参数，参考4

②、自定义路由，插件根目录下定义route.php，示例：

前台路由：

Route::group('console/v1',function (){

Route::get('ticket',"\addon\idcsmart_ticket\controller\clientarea\TicketController@ticketList")->append(['_plugin'=>'idcsmart_ticket','_controller'=>'ticket','_action'=>'ticket_list']);# 带上默认参数,可以使用继承控制器app\admin\controller\PluginBaseController的一些通用方法,也可以不追加这些参数(_plugin插件名称C风格,_controller控制器名称C风格,_action方法名称C风格)

})->middleware(\app\http\middleware\ParamFilter::class)

->middleware(\app\http\middleware\CheckHome::class);#前台需要登录就使用此中间件

后台路由：

Route::group(DIR_ADMIN . '/v1',function (){

Route::get('ticket',"\addon\idcsmart_ticket\controller\TicketController@ticketList")->append(['_plugin'=>'idcsmart_ticket','_controller'=>'ticket','_action'=>'ticket_list']);})->middleware(\app\http\middleware\ParamFilter::class)->

middleware(\app\http\middleware\CheckAdmin::class);#后台需要登录就使用此中间件

6、插件多语言

①创建语言文件lang/zh-cn.php，返回如下格式的数组:

return [ 'success_message' => '请求成功', 'ticket_title_require' => '请输入工单标题',

'ticket_log_client_create_ticket' => '{client}新建工单:{ticket_id}', ]

②使用lang_plugins('语言标识',$param=[])实现多语言，$param为语言文件中参数，格式['{client}'=>'wyh'],如：

lang_plugins('ticket_log_client_create_ticket',['{client}'=>'wyh','{ticket_id}'=>1]);

③前端多语言文件

前台语言文件：在template/clientarea/lang/目录下index.js文件；

后台语言文件：在template/admin/lang目录下

(function () {

const module_lang = {

"zh-cn": {

  add: "添加",

},

"zh-hk": {

  add: "添加",

},

"en-us": {

  add: "Add",

},

};

const DEFAULT_LANG = localStorage.getItem("backLang") || "zh-cn";

window.module_lang = module_lang[DEFAULT_LANG];

})();

具体参考idcsmart_ticket工单插件

7、插件后台导航

①导航默认会创建在插件导航之下,默认链接：plugin/插件名/index.html，对应template/admin/index.php文件,同时需要在lang/下的语言文件创建如下格式的语言,nav_plugin_addon_插件名:

'nav_plugin_addon_idcsmart_ticket' => '工单',

②自定义导航，若是一级导航，会增加在插件导航之上，管理导航之下，在插件根目录下创建sidebar.php，示例：

/*

• 自定义后台导航菜单(仅支持一二级),注意系统会在插件导航下默认创建url为"plugin/插件名称/index.html"的导航,因此需要在template/admin/目录下创建index.php文件作为插件入口 */ return [ [ # 一级导航 'name' => 'nav_plugin_addon_ticket', # 导航名称,不要与系统冲突(参考idcsmart_nav表中name字段),同时需要在lang/目录下定义语言 'url' => '', # 为空表示一级导航,不需要链接 'icon' => 'tools', # 图标,获取图标:https://tdesign.tencent.com/vue/components/icon 'in' => '', # 一级导航,此值为空 'child' => [ # 二级导航 [ 'name' => 'nav_plugin_addon_ticket_list', # 导航名称 'url' => 'ticket', # 链接格式,会自动加上.html 'in' => 'nav_user_management', # 可定义导航在某个一级导航之下,默认会放置在此一级导航最后的位置(获取方式:idcsmart_nav表中的parent_id==0的name字段) 'icon' => '', # 图标,获取图标:https://tdesign.tencent.com/vue/components/icon ], [ 'name' => 'nav_plugin_addon_ticket_internal_list', # 导航名称 'url' => 'ticket_internal', # 链接格式,会自动加上.html 'in' => '', # 可定义导航在某个一级导航之下,默认会放置在此一级导航最后的位置 'icon' => '', # 图标,获取图标:https://tdesign.tencent.com/vue/components/icon ], ] ], ];

8、插件前台导航

①导航默认会创建在插件导航之下,默认链接：plugin/插件名/index.html；

②自定义导航，会增加在插件导航之上，管理导航之下，在插件根目录下创建sidebar_clientarea.php，示例：

/*

• 自定义前台导航菜单(仅支持一二级) */ return [ [ 'name' => 'nav_plugin_addon_ticket', # 链接名称,同时需要在lang/目录下定义语言 'url' => '', # 链接格式,会自动加上.html 'icon' => '', # 图标 'child' => [ # 二级菜单 [ 'name' => 'nav_plugin_addon_ticket_list', 'url' => 'ticket', 'icon' => '', # 图标 ], ] ], ];

9、插件后台权限管理

在插件根目录下创建auth.php，示例如下（注意定义语言）：

<?php /* * 定义权限,系统会默认插入名称为插件名的一级权限,以下仅需定义二级/三级权限;(首先，要使用二级权限，插件后台控制器需要继承app\event\controller\PluginAdminBaseController基类控制器) */ return [ [ 'title' => 'auth_plugin_addon_ticket_list', # y用户工单 'url' => 'ticket', 'child' => [ # 操作权限 [ 'title' => 'auth_plugin_addon_ticket_view', # 工单查看 'url' => '', 'auth_rule' => 'TicketController::ticketList', # 工单列表具体控制器方法 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_list' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_receive', 'url' => '', 'auth_rule' => 'TicketController::receive', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_receive' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_resolved', 'url' => '', 'auth_rule' => 'TicketController::resolved', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_resolved' # 具体权限名称 ], ] ], [ 'title' => 'auth_plugin_addon_ticket_detail', # 工单详情 'url' => 'ticket_detail', 'child' => [ [ 'title' => 'auth_plugin_addon_ticket_view', 'url' => '', 'auth_rule' => 'TicketController::index', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_index' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_reply', 'url' => '', 'auth_rule' => 'TicketController::reply', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_reply' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_download', 'url' => '', 'auth_rule' => 'TicketController::download', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_download' # 具体权限名称 ], ] ], [ 'title' => 'auth_plugin_addon_ticket_internal_list', # 内部工单 'url' => 'ticket_internal', 'child' => [ [ 'title' => 'auth_plugin_addon_ticket_view', 'url' => '', 'auth_rule' => 'TicketInternalController::ticketInternalList', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_list' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_view', 'url' => '', 'auth_rule' => 'TicketInternalController::index', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_index' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_add', 'url' => '', 'auth_rule' => 'TicketInternalController::create', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_create' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_receive', 'url' => '', 'auth_rule' => 'TicketInternalController::receive', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_receive' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_resolved', 'url' => '', 'auth_rule' => 'TicketInternalController::resolved', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_resolved' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_reply', 'url' => '', 'auth_rule' => 'TicketInternalController::reply', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_reply' # 具体权限名称 ], [ 'title' => 'auth_plugin_addon_ticket_forward', 'url' => '', 'auth_rule' => 'TicketInternalController::forward', 'auth_rule_title' => 'auth_rule_plugin_addon_ticket_internal_forward' # 具体权限名称 ], ] ], ]; 10、插件接口内部调用 使用plugin_api($addon,$controller,$action,$param=[])函数可内部调用插件API,需要开发者提供插件API开发文档，具体格式参考系统API文档 * @param string addon - 插件 require * @param string controller - 控制器前缀 require * @param string action - 方法 require * @param array param - 传入的参数