如何快速创建一个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 </p>
- 本文档中为：Test + ServiceProvider.php = TestServiceProvider.php</p>
- 注意：命名空间的模块名称（首字母大写）；包名的名称格式为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',
