如何快速创建一个App模块(1.18.0及后续版本)
跳到导航
跳到搜索
如何快速创建一个App模块
|
第一章:开发者入门创建APP | 第二章:APP模块类型 | 第三章:后台控制器添加 |
第四章:商家控制器添加 | 第五章:API控制器开发 | 第六章:数据模型创建 |
第七章:语言包创建 | ||
1 第一篇:开发者入门
1.1 第一章:开发者入门创建APP
1.1.1 APP是什么?
- APP模块是区别于主程序,可独立于主应用运行的应用模块。
1.1.2 APP能做什么?
- APP模块可以实现各种功能,不受主程序约束。后台可轻易安装、卸载、删除应用。
1.1.3 APP放在那里?
- APP存放在系统根目录下的
content/apps
目录下,这里新建一个test
模块为例,新建一个test
文件夹
. ├── content │ ├── apps │ │ ├── adsense │ │ ├── affiliate │ │ ├── shopguide │ │ ├── sms │ │ ├── staff │ │ ├── stats │ │ ├── store │ │ ├── test //test应用模块
1.1.4 创建APP三要素
- 目录名:app模块目录
- configs:配置文件目录,必须包含
package.php
文件 - languages:语言包目录:默认读取
zh_CN
文件夹下的中文语言包,必须包含package.lang.php
文件(1.28.0以及后续版本为必须包含app模块名.lang.php
+app模块名.pot
,如果js用到语言包,则需要在config
目录下面添加jslang.php
文件)
├── test //app模块目录 │ ├── configs //配置文件目录 │ │ └── package.php //配置文件 │ ├── languages //语言包 │ │ ├── en_US │ │ │ └── package.lang.php │ │ └── zh_CN //默认读取中文语言包 │ │ └── package.lang.php
- package.php 配置文件代码:
<?php
defined('IN_ROYALCMS') or exit('No permission resources.');
/**
* test模块应用
*/
return array(
'identifier' => 'ecjia.test', /* 标示符 */
'directory' => 'test', /* 目录 */
'name' => 'test', /* 名字 */
'description' => 'test_desc', /* 描述 */
'author' => 'ECJIA TEAM', /* 作者 */
'website' => 'http://www.ecjia.com', /* 网址 */
'version' => '1.19.0', /* 版本号 */
'copyright' => 'ECJIA Copyright 2018.', /* 版权 */
'namespace' => 'Ecjia\App\Test', /* 命名空间 */
);
// end
- 在应用模块下新建
languages
文件夹,新建中文语言包文件夹zh_CN
,然后新建package.lang.php
文件,代码如下:
<?php
defined('IN_ECJIA') or exit('No permission resources.');
/**
* ECJIA 应用语言包
*/
return array(
'test' => '测试管理', //模块名字
'test_desc' => '测试管理简介' //模块描述
);
// end
1.1.5 创建APP的ServiceProvider类
- 在你的应用模块目录下新建
classes
文件夹 - 命名规范: app模块名(首字母大写) + ServiceProvider.php
- 本文档中为:Test + ServiceProvider.php = TestServiceProvider.php
- 注意:命名空间的模块名称(首字母大写);包名的名称格式为ecjia/app-模块名(全部小写)例如:ecjia/app-test
- 代码如下:
<?php
// 命名空间的模块名称(首字母大写)
namespace Ecjia\App\Test;
use Royalcms\Component\App\AppParentServiceProvider;
class TestServiceProvider extends AppParentServiceProvider
{
public function boot()
{
$this->package('ecjia/app-test');// 包名的名称格式为ecjia/app-模块名(全部小写)例如:ecjia/app-test
}
public function register()
{
}
}
1.1.6 加载APP
需要在3个配置文件中加载APP,分别是app.php、namespaces.php、provider.php
,位于content/configs
文件夹下
app.php
为系统APPS配置表,用于APP文件夹映射配置,- 命名规范:
'模块名称' => '模块文件夹名称'(全部小写),
/* 测试模块 */
'test' => 'test',
- namespaces.php 配置文件
- 命名规范:
'Ecjia\App\模块名(首字母大写)' => $contentDir . '/apps/模块名(首字母小写)/classes',
'Ecjia\App\Test' => $contentDir . '/apps/test/classes',
- provider.php 配置文件
- 命名规范:
'Ecjia\App\模块名(首字母大写)\app模块名(首字母大写) + ServiceProvider',
'Ecjia\App\Test\TestServiceProvider',
1.1.7 建立控制器文件测试
- 在 test 模块目录下新建
index.php
控制器文件,代码如下:
<?php
class index extends ecjia_admin {
public function init() {
echo "Hello ECJia!";
}
}
1.1.8 控制器被访问的URL地址规则生成及介绍
http://yourdomain.com/index.php?m=test&c=index&a=init
,这里是指test 应用模块目录的 - index控制器的 - init 方法
配置项 | 描述 |
---|---|
m | 应用目录名 |
c | 控制器文件名 |
a | 控制器类中的公开方法 |
1.1.9 通过地址访问查看效果
1.2 第二章:APP模块类型
1.2.1 控制器类型种类介绍
- 前台控制器:H5端
- 后台控制器:平台后台
- 商家控制器:商家后台
- 公众平台控制器:微信公众平台
- API控制器:API
1.2.2 控制器基类介绍以及命名规范
控制器类型 | 控制器名称 | 控制器命名规范 |
---|---|---|
前台控制器 | ecjia_front | xxxx.php |
后台控制器 | ecjia_admin | admin.php admin_xxxx.php(含有多个后台控制器时可以使用该前缀统一命名) |
商家控制器 | ecjia_merchant | merchant.php mh_xxxx.php(含有多个商家控制器时可以使用该前缀统一命名) |
公众平台控制器 | ecjia_platform | platform.php platform_xxxx.php(含有多个公众平台控制器时可以使用该前缀统一命名) |
API控制器 | ecjia_api -> api_front(前台API控制器) api_admin(后台API使用) | xxx_module.class.php |
1.3 第三章:后台控制器添加
1.3.1 创建后台菜单文件
- 在
test
应用目录下创建apis
文件夹; - 然后在apis文件夹下面创建该应用的菜单文件:test_admin_menu_api.class.php
- 命名规范:app模块名(首字母小写)_ + 接口名称 + _api.class.php
- 本文档中为:test_ + admin_menu + _api.class.php = test_admin_menu_api.class.php
. ├── admin.php ├── apis //后台菜单文件与权限文件存放位置 │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── index.php ├── languages │ └── zh_CN │ └── package.lang.php
- 代码如下
- test_admin_menu_api 继承 Component_Event_Api类,Component_Event_Api 继承 Component_Event_Event类
- make_admin_menu 方法作用为添加菜单,需要传入参数:action(菜单动作), name(菜单名称), link(菜单链接), sort(排序)
- link参数传入的链接:
RC_Uri::url
需要参数'路径',遵循上文提到的 m/c/a 规则,例如:RC_Uri::url('test(应用名称)/admin(控制器名称)/init(控制器中方法)'
- add_submenu 方法作用为添加二级菜单,需传入参数:menu。如果传入的是菜单对象,直接添加进子菜单数组;如果传入的是数组,直接合并进子菜单数组里;已经有子菜单了,立即更新状态
- add_purview 方法的作用为添加使用该菜单的权限,需要传入参数为权限的动作代号数组,例如:test_manage(在下文的【创建后台权限文件】中有讲到)
<?php
defined('IN_ECJIA') or exit('No permission resources.');
/**
* ECJIA后台test应用模块菜单
*/
class test_admin_menu_api extends Component_Event_Api {
public function call(&$options) {
//一级菜单:需要参数‘菜单动作’,‘菜单名称’,‘无需填写’,‘排序’;
$menus = ecjia_admin::make_admin_menu('01_test','测试管理', '', 0);
$submenus = array(
//二级菜单:需要参数‘菜单动作’,‘菜单名称’,‘菜单链接’,‘排序’;
ecjia_admin::make_admin_menu('01_test_list', '测试列表', RC_Uri::url('test/admin/init'), 1)
->add_purview(array('test_manage')),//是添加使用该菜单的权限;
);
//添加菜单或菜单数组进子菜单数组里
$menus->add_submenu($submenus);
return $menus;
}
}
1.3.2 创建后台权限文件
- 然后在apis文件夹下面创建该应用的菜单文件:test_admin_purview_api.class.php
- 创建好后可以在平台后台:控制面板-权限管理-角色管理-添加角色中查看
- 命名规范:app模块名(首字母小写)_ + 接口名称 + _api.class.php
- 本文档中为:test_ + admin_purview + _api.class.php = test_admin_purview_api.class.php
- 代码如下:
- 添加好的权限可以在平台后台:【控制面板】-【权限管理】-【角色管理】-【添加角色】中查看
- 数组中需要参数action_name(动作名称)、action_code(动作代号)、relevance(该权限相关联的权限)。
<?php
defined('IN_ECJIA') or exit('No permission resources.');
/**
* test后台权限
*/
class test_admin_purview_api extends Component_Event_Api {
public function call(&$options) {
$purviews = array(
//需要参数(‘动作名称’,‘动作代号’,‘关联权限’)
array('action_name' => '测试信息管理', 'action_code' => 'test_manage', 'relevance' => ''),
array('action_name' => '编辑测试资料', 'action_code' => 'test_update', 'relevance' => ''),
array('action_name' => '删除测试资料', 'action_code' => 'test_delete', 'relevance' => ''),
);
return $purviews;
}
}
1.3.3 创建模板文件
- 模板是将控制器处理过得信息很直观展示出来的页面
- 在test应用根目录下创建
templates
文件夹用来存放模板文件 - 然后再创建
admin
文件夹存放平台后台模板,因为也有其他平台的模板文件例如merchant
商家、front
前台、platform
公众平台,所以在此需要区分; - 命名规范:模板文件名 + .dwt.php
- 本文档中为:test + .dwt.php = test.dwt.php
. ├── admin.php ├── apis │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── languages │ └── zh_CN │ └── package.lang.php ├── statics └── templates //模板文件存放位置 ├── admin //平台后台模板文件存放位置 │ └── test.dwt.php └── merchant //商家后台模板文件存放位置 └── test.dwt.php
- 代码如下
<?php defined('IN_ECJIA') or exit('No permission resources.');?>//权限判断
<!--{extends file="ecjia.dwt.php"} -->//全局模板加载
<!-- {block name="footer"} -->
<script type="text/javascript">
ecjia.admin.test.init();//js调用
</script>
<!-- {/block} -->
<!-- {block name="main_content"} -->
<div>
<h1>{$test}</h1>
</div>
<!-- {/block} -->
1.3.4 应用内的JS、CSS、IMAGE存放
- 存放在应用模块下
statics
目录下,js文件放在js目录下,css文件放在css文件下,图片文件放在images目录下
├── test //app模块目录 │ ├── statics //静态资源存放文件夹 │ │ ├── css │ │ ├── js │ │ ├── images
1.3.5 后台控制器开发,继承父类
- 控制器是处理该模块有关逻辑的php文件;
- 一般我们都创建一个默认为
admin
的控制器为该应用的主控制器;当然你可以根据需要的情况以admin_
为前缀创建多个控制器。
. ├── admin.php //主控制器 ├── apis │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── index.php ├── languages │ └── zh_CN │ └── package.lang.php ├── statics │ ├── css │ │ └── test.css │ ├── images │ └── js └── templates //模板存放位置 ├── admin │ └── test.dwt.php
- 代码如下
- add_nav_here 方法的作用为添加导航菜单
- remove_last_nav_here 方法的作用为移除最后一个导航菜单
<?php
class admin extends ecjia_admin
{
public function __construct()
{//全局
parent::__construct();
//模块面包屑导航条设置
ecjia_screen::get_current_screen()->add_nav_here(new admin_nav_here('测试列表', RC_Uri::url('test/admin/init')));
}
/**
* 测试列表
*/
public function init()
{
ecjia_screen::get_current_screen()->remove_last_nav_here(); //导航条设置
ecjia_screen::get_current_screen()->add_nav_here(new admin_nav_here('测试列表'));
$this->assign('ur_here', '测试列表'); //页面标题设置
$this->assign('test', 'Hello ECJia!');//赋值给模板
$this->display('test.dwt');//模板加载(以上返回得到的信息以及请求该方法加载的页面就和该设置有关)
}
}
1.3.6 加载资源
- 所有资源需要在控制器中的全局方法进行加载,在 admin.php 中的
public function __construct()
加载资源,代码如下 - 第一个false代表是否底部加载,第二个false代表是否顶部加载
RC_Script::enqueue_script('test', RC_App::apps_url('statics/js/test.js', __FILE__), array(), false, false);
RC_Style::enqueue_style('test', RC_App::apps_url('statics/css/test.css', __FILE__));
1.3.7 设置面包屑导航
- 需要在控制器中的全局方法进行加载,在 admin.php 中的
public function __construct()
添加面包屑导航,代码如下 - TODO:面包屑导航使用举例
//模块面包屑导航条设置
ecjia_screen::get_current_screen()->add_nav_here(new admin_nav_here('测试列表', RC_Uri::url('test/admin/init')));
1.3.8 设置功能访问权限
- 在对应方法的开始处设置不同功能的访问权限,代码如下:
$this->admin_priv('test_manage');//模块权限
1.3.9 Smarty常用变量信息赋值
常用变量 | 作用 |
---|---|
ur_here | 页面标题 |
action_link | 点击跳转链接 |
1.3.10 模板加载
- 以上返回得到的信息以及请求该方法加载的页面就和该设置有关
. ├── admin.php //主控制器 ├── apis ├── classes ├── configs ├── index.php ├── languages ├── statics └── templates //模板存放位置 ├── admin │ └── test.dwt.php
- 代码如下
$this->display('test.dwt');
1.4 第四章:商家控制器添加
1.4.1 创建商家菜单文件
- 在
test
应用目录下创建apis
文件夹; - 然后在apis文件夹下面创建该应用的菜单文件:test_merchant_menu_api.class.php
- 命名规范:app模块名(首字母小写)_ + 接口名称 + _api.class.php
- 本文档中为:test_ + merchant_menu+ _api.class.php = test_merchant_menu_api.class.php
- 并在
/sites/merchant/content/configs/merchant.php
中加载菜单,举例如下:/* 商家后台测试菜单 */ 'test' => 'test',
. ├── admin.php ├── apis //后台菜单文件与权限文件存放位置 │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php │ ├── test_merchant_menu_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── index.php ├── languages │ └── zh_CN │ └── package.lang.php
- 代码同 创建后台菜单文件
1.4.2 创建商家权限文件
- 然后在apis文件夹下面创建该应用的菜单文件:test_merchant_purview_api.class.php
- 创建好后可以在平台后台:控制面板-权限管理-角色管理-添加角色中查看
- 命名规范:app模块名(首字母小写)_ + 接口名称 + _api.class.php
- 本文档中为:test_ + merchant_purview + _api.class.php = test_merchant_purview_api.class.php
- 代码同 创建后台菜单文件
1.4.3 创建商家模板文件
- 模板是将控制器处理过得信息很直观展示出来的页面
- 在test应用根目录下创建
templates
文件夹用来储存模板文件 - 然后再创建
merchant
文件夹存放平台后台模板,因为也有其他平台的模板文件例如admin
平台、front
前台、platform
公众平台,所以在此需要区分; - 命名规范:模板文件名 + .dwt.php
- 本文档中为:test + .dwt.php = test.dwt.php
. ├── admin.php ├── apis │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── languages │ └── zh_CN │ └── package.lang.php ├── statics └── templates //模板文件存放位置 ├── admin │ └── test.dwt.php └── merchant └── test.dwt.php
- 代码同 创建后台菜单文件
1.4.4 应用内的JS、CSS、IMAGE存放
- 存放在应用模块下
statics
目录下,js文件放在js目录下,css文件放在css文件下,图片文件放在images目录下
├── test //app模块目录 │ ├── statics //静态资源存放文件夹 │ │ ├── css │ │ ├── js │ │ ├── images
1.4.5 后台控制器开发,继承父类
- 控制器是处理该模块有关逻辑的php文件;
- 一般我们都创建一个默认为
admin
的控制器为该应用的主控制器;当然你可以根据需要的情况以admin_为前缀创建多个控制器。
. ├── merchant.php //商家主控制器 ├── apis │ ├── test_admin_menu_api.class.php │ ├── test_admin_purview_api.class.php ├── classes │ └── TestServiceProvider.php ├── configs │ └── package.php ├── index.php ├── languages │ └── zh_CN │ └── package.lang.php ├── statics │ ├── css │ │ └── test.css │ ├── images │ └── js └── templates //模板存放位置 ├── admin │ └── test.dwt.php
- 代码同 创建后台菜单文件
1.4.6 加载资源
- 所有资源需要在控制器中的全局方法进行加载,在 merchant.php 中的
public function __construct()
加载资源 - 代码同 创建后台菜单文件
1.4.7 设置面包屑导航
- 需要在控制器中的全局方法进行加载,在 merchant.php 中的
public function __construct()
添加面包屑导航 - 代码同 创建后台菜单文件
1.4.8 设置功能访问权限
- 在对应方法的开始处设置不同功能的访问权限
- 代码同 创建后台菜单文件
1.4.9 Smarty常用变量信息赋值
常用变量 | 作用 |
---|---|
ur_here | 页面标题 |
action_link | 点击跳转链接 |
1.4.10 模板加载
- 以上返回得到的信息以及请求该方法加载的页面就和该设置有关
. ├── admin.php //主控制器 ├── apis ├── classes ├── configs ├── index.php ├── languages ├── statics └── templates //模板文件存放位置 ├── admin //平台后台模板文件存放位置 │ └── test.dwt.php └── merchant //商家后台模板文件存放位置 └── test.dwt.php
- 代码同 创建后台菜单文件
1.5第五章:API控制器开发
1.5.1 接口路径举例说明
- 以
admin/merchant/goods/category/detail
接口为例说明各路径含义 - 在
api.php
配置文件中为:'admin/merchant/goods/category/detail' => 'goods::admin/goods/merchant/category/detail',
- 含义:
goods
应用模块下的 admin 文件夹中的 goods 文件夹下的 category文件夹下的 detail 接口 - 具体路径:
content/apps/goods/modules/admin/goods/category/detail_module.class.php
1.5.2 创建接口类
- 在
test
应用目录下创建modules
文件夹; - 然后在
modules
文件夹下面创建不同功能接口的文件夹,例如:address
,然后在该文件夹中创建接口类文件 - 命名规范: 接口类名称 + _module.class.php
- 本文档中为:list + _module.class.php = list_module.class.php
. ├── admin.php ├── apis ├── languages ├── modules │ └── test │ └── list_module.class.php
1.5.3 接口类说明
- 新建的接口类必须继承
api_front
类与实现api_interface
类的方法
1.5.4 加载接口进api配置文件
- 需要在
api.php
配置文件中把接口加载进api,api.php
位于content/configs
文件夹下 - 命名规范:modules下的文件夹名/接口类名称 => 应用模块目录名::modules下的文件夹名/接口类名称
'test/list' => 'test::test/list', //测试接口
- 代码如下:
<?php
defined('IN_ECJIA') or exit('No permission resources.');
//注意修改 list_module 为 接口类名称_module
class list_module extends api_front implements api_interface
{
public function handleRequest(\Royalcms\Component\HttpKernel\Request $request)
{
$info = array(
'test' => 'test',
);
return $info;
}
}
// end
1.5.5 测试接口
- 如果
api.php
没有配置正确的话,会返回以下信息
Api Error: test/list does not exist.
- 成功的话返回以下值:
{
"data": {
"test": "test"
},
"status": {
"succeed": 1
}
}
1.6 第六章:数据模型创建
1.6.1 数据模型创建及存放位置
- 在
test/classes
应用目录下创建Models
文件夹; - 然后在
Models
文件夹下面创建该应用的数据模型文件:AdModel.php - 命名规范: 数据库表名字(首字母大写) + Model.php
- 本文档中为:Ad + Model.php = AdModel.php
. └── adsense ├── apis ├── classes │ ├── Models //存放数据模型的文件夹 │ │ ├── AdModel.php
1.6.2 如何使用
- table:数据库表名
- primaryKey:数据表主键
- fillable:可以被批量赋值的属性
- timestamps:该模型是否被自动维护时间戳
<?php
// 命名空间的模块名称(首字母大写)
namespace Ecjia\App\Adsense\Models;
use Royalcms\Component\Database\Eloquent\Model;
defined('IN_ECJIA') or exit('No permission resources.');
class AdModel extends Model
{
//数据库表名
protected $table = 'ad';
//数据表主键
protected $primaryKey = 'ad_id';
/**
* 可以被批量赋值的属性。
*
* @var array
*/
protected $fillable = [
'position_id',
'media_type',
'ad_link',
'ad_name',
'ad_code',
'sort_order',
'show_client',
];
/**
* 该模型是否被自动维护时间戳
*
* @var bool
*/
public $timestamps = false;
}
// end
1.7 第七章:语言包创建
1.7.1 语言包的创建和存放位置
- 语言包存放在模块目录下的
languages
文件夹下,en_US
、zh_CN
两个文件夹分别对应英文、中文语言包
├── languages │ └── zh_CN │ └── package.lang.php │ └── en_US │ └── package.lang.php
1.7.2 语言包的调用
- 1.28.0以及后续版本语言包变动操作
1.7.2.1 语言包文件中定义更新
return array(
'log_id' => '编号',
'js_languages' => array(
'select_date_value' => '如果您要清除日志,请选择清除的日期',
),
);
1.7.2.2 控制器文件中语言包用法更新
//get('应用模块名称'::'语言包文件名称'.'键名')
'total_records' => RC_Lang::get('system::system.total_records'),
1.7.2.3 模板文件中语言包用法更新
- 第一种情况:
//{lang key='应用模块名称'::'语言包文件名称'.'键名'}
<!-- {foreach from=$test.msg item=msg} -->{lang key='system::check_file_priv.unread'}<!-- {/foreach} -->
- 第二种情况:
//先在控制器中添加如下:
$this->assign('cfg_range_lang', RC_Lang::get('system::shop_config.cfg_range'));
//然后在模板中赋值即可
<!-- {html_options options=$cfg_range_lang[$var.code] selected=$var.value} -->
1.7.2.4 system系统中语言包升级方法
- 在控制器使用:get_text('中文')
- 然后在模板中使用:{t}中文{/t}
- 最后使用poedit软件打开后缀为po的语言包文件,进行相应的中引文翻译保存即可。
1.7.3 语言包切换的配置说明
- 在
content/configs/system.php
中,把locale
的值为从zh_CN
修改为en_US
即可
//网站语言包
'locale' => 'en_US',