This commit is contained in:
yiqiu
408
plugins_dev.md
Normal file
408
plugins_dev.md
Normal file
@@ -0,0 +1,408 @@
|
||||
阅读须知：此文件是插件制作方法，和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 - 传入的参数
|
||||
Reference in New Issue
Block a user