阅读本章内容之前请确定已了解微擎工作流程, 本章内容主要介绍如何编写及发布微擎功能模块. 模块功能描述编写功能模块前需要先确定模块的主要功能, 微擎使用 manifest.xml 来描述模块的主要功能和配置参数. 这个xml文件被定义为如下结构
manifest - xmlns *（新增）*
用来为此模块XML的命令空间，此处必须填写"http://www.we7.cc". manifest - versionCode
用来说明当前模块适用于哪个版本的微擎, 用来保证模块的兼容性. 多个支持的版本请使用逗号隔开. manifest - application 用来定义模块的基本设置属性
manifest - application - setting 用来说明此模块是否有针对模块的设置项, 设置项可以保存此模块需要的配置参数(此参数针对不同的公众号分别保存) manifest - application - name
模块的名称 manifest - application - identifie
模块标识符, 应对应模块文件夹的名称, 微擎系统按照此标识符查找模块定义 manifest - application - version
模块当前版本, 此版本用于模块的版本更新 manifest - application - type *（新增）*
模块的类型,方便在左侧菜单中归类与显示, 目前分为 business(主要业务),customer(客户关系),activity(营销及活动),services(常用服务及工具),other(其他) manifest - application - ability
模块功能描述, 使用简单的语言描述模块的作用, 来吸引用户 manifest - application - description
模块详细描述, 详细介绍模块的功能和使用方法 manifest - application - author
模块的作者, 留下你的大名吧 manifest - application - url
模块的发布页, 可以通过这个url来访问你的模块最新情况 manifest - platform
用来定义模块用以处理公众平台消息的设置项 manifest - platform - subscribes
消息订阅器定义(消息订阅器提供了一种处理公众平台消息的方式, 可以接受到指定类型的消息, 来进行分析和统计, 不能用以处理消息返回结果. 这种处理是并行的, 同一个消息会被每一个订阅它的模块接收到) manifest - platform - subscribes - message
定义需要被订阅器订阅的消息类型, 这里的消息被 WeModuleReceiver 处理 manifest - platform - handles
消息处理器定义(消息处理器用于接收公众平台的消息, 并返回相应的处理结果. 这种处理是互斥的, 同一个消息只能从一个模块返回处理结果) manifest - platform - handles - message
定义需要被处理器处理的消息类型, 这里的消息被 WeModuleProcessor 处理 manifest - platform - rule *（变更）*
定义此模块是否需要规则触发 manifest - platform - rule - embed
当前模块进行消息处理时需要定义规则, 是否使用规则路由. (使用规则路由必须要能处理text类型消息, handles节点中必须包含 ) manifest - bindings *（新增）*
定义此模块的封面,管理菜单,微站菜单及规则扩展菜单 manifest - bindings - cover
定义模块的封面入口,封面入口为单条图文信息即是模块需要对用户开放的入口地址. manifest - bindings - cover - call
定义模块动态扩展菜单项, 此值对应 WeModuleSite 类中的方法, 返回的值结构与entry相同, 将成为此节点的菜单项. manifest - bindings - cover - entry
模块绑定菜单的定义结构. 需要定义 title - 操作的名称, do - 模块操作入口, state - 附加的用户参数(定义于WeModuleSite) manifest - bindings - rule
定义规则的附加操作, 每个entry代表一个附加操作. manifest - bindings - menu
定义模块在左侧本模块菜单下拉列表中的附加菜单操作, 每一个entry代表一个菜单操作. manifest - bindings - home
定义模块在微站首页的扩展菜单项, 每一个entry代表一个微站首页菜单项. manifest - bindings - profile
定义模块在微站个人中心的扩展菜单项, 每一个entry代表一个微站个人中心菜单项. manifest - bindings - shortcut
定义模块在微站快捷菜单的扩展菜单项, 每一个entry代表一个微站快捷菜单项. manifest - install
安装执行脚本, 这里支持两种形式: php脚本和sql语句. 如果安装时只需要写入数据库相关内容, 可以在此直接定义sql语句. 也可以使用php文件, 例如: install.php 代表执行模块定义目录下的 install.php manifest - uninstall
卸载执行脚本, 参上 manifest - upgrade
升级执行脚本, 参上
模块文件结构模块定义后所有代码及资源文件应放置于同一文件夹内. 如定义无误, 将会被安装至 /source/modules/{identifie} 下. 其中 {identifie} 将与上一步描述文件中的 manifest.xml 中定义的标识符保持一致. 模块文件夹的结构如下: ├─template│ ├─mobile│ │ └───xxxx.html│ ├─settings.html│ └─xxxx.xxx├─module.php├─processor.php├─receiver.php├─site.php├─manifest.xml├─install.php├─preview.jpg├─icon.jpg├─...└─...
其中必须的文件包括 manifest.xml. 这个文件均位于模块文件夹根目录. 其他的文件及目录, 会根据你的 manifest.xml 来定义
推荐: 强烈建议使用系统内置的模块设计器来生成模块结构. - module.php 这个文件内容为微擎模块定义, 应为 WeModule 类的派生类. 请参阅(微擎处理流程-模块定义)
- processor.php 这个文件内容为微擎模块处理程序定义, 应为 WeModuleProcessor 类的派生类. 请参阅(微擎处理流程-模块定义)
- receiver.php 这个文件内容为微擎模块消息订阅器定义, 应为 WeModuleReceiver 类的派生类. 请参阅(微擎处理流程-模块定义)
- site.php 这个文件内容为微擎模块微站功能定义, 应为 WeModuleSite 类的派生类. 请参阅(微擎处理流程-模块定义)
- manifest.xml 描述文件
- preview.jpg 模块封面, 规格为600px*350px
- icon.jpg 模块图标, 规格为48px*48px
模块定义定义模块需要按照你的模块功能来继承并实现 WeModule, WeModuleProcessor, WeModuleReceiver 和 WeModuleSite 这几个类的特定函数成员来实现. WeModule 介绍WeModule 微擎系统将在用户管理界面使用 WeModule 的派生类来管理, 配置和显示此模块的在处理公众平台消息时的相关功能(如规则定义, 消息处理等).
WeModule 中可以定义程序嵌入点, 嵌入点方法可以直接从Web中访问. 定义格式为: 函数名 doXXX, 访问方式为 ./index.php?act=module&name={模块名称}&do={XXX} WeModule类的定义及派生时要实现的成员描述如下:
abstract class WeModule { // string: 预定义的数据, 当前模块的名称, 对应模块定义中的 application - identifie, 这个属性由系统初始化 public $modulename; /** * 可能需要实现的操作, 需要附加至规则表单的字段内容, 编辑规则时如果模块类型为当前模块, 则调用此方法将返回内容附加至规则表单之后 * @param int $rid 如果操作为更新规则, 则此参数传递为规则编号, 如果为新建此参数为 0 * @return string 要附加的内容(html格式) */ public function fieldsFormDisplay($rid = 0) { return ''; } /** * 可能需要实现的操作, 验证附加至规则表单的字段内容, 编辑规则时如果模块类型为当前模块, 则在保存规则之前调用此方法验证附加字段的有效性 * @param int $rid 如果操作为更新规则, 则此参数传递为规则编号, 如果为新建此参数为 0 * @return string 验证的结果, 如果为空字符串则表示验证成功, 否则返回验证失败的提示信息 */ public function fieldsFormValidate($rid = 0) { return ''; } /** * 可能需要实现的操作, 编辑规则时如果类型为当前模型, 则在提交成功后调用此方法 * @param int $rid 规则编号 * @return void */ public function fieldsFormSubmit($rid) { // } /** * 可能需要实现的操作, 在列表中删除规则如果类型为当前模型，则在删除成功后调用此方法，做一些删除清理工作。 * @param int $rid 规则id,必填值 * @return 如果操作成功则返回true,否则返回error信息 */ public function ruleDeleted($rid) { return true; } /** * 可能需要实现的操作, 如果模块需要配置参数, 请在此方法内部处理展示和保存配置项 * @param array $settings 已保存的配置项数据 * @return void */ public function settingsDisplay($settings) { //点击模块设置时将调用此方法呈现模块设置页面，$settings 为模块设置参数, 结构为数组。这个参数系统针对不同公众账号独立保存。 //在此呈现页面中自行处理post请求并保存设置参数（通过使用$this->saveSettings()来实现） if(checksubmit()) { //字段验证, 并获得正确的数据$dat $this->saveSettings($dat); } //这里来展示设置项表单 inlucde $this->template('settings'); } /** * 预定义的操作, 保存数据至模块参数项中, 保存的配置项可以在模块数组中的config元素中获取 * @param array $settings 需要保存的配置项数据 * @return bool 是否保存成功 */ protected function saveSettings($settings) {...} /** * 预定义的操作, 展示特定模板内容, 此方法不能直接展示模块内容, 需要使用 include $this->template(''); 的方式 * @param string $filename 模板名称, 如: settings 将会展示本模块定义下的 template/settings.html 模板文件, 请参阅 "模板机制" * @return void */ protected function template($filename, $flag = TEMPLATE_INCLUDEPATH) {...} /** * 可能需要实现的操作, 定义Web访问嵌入点 (Web访问此方法地址为: ./index.php?act=module&name={模块名称}&do={XXX}) * @param int $id 如果GET参数中包含 id 参数, 将被当作参数 $id 传递 * @param string $state 如果GET参数中包含 state 参数, 将被当作参数 $state 传递 * @return void */ public function doXXX($id = '', $state = '') { }}
WeModuleProcessor 介绍WeModuleProcessor 用户定义的模块处理程序, 当匹配此模块的消息到来时, 使用此对象处理对象并返回处理结果. WeModuleProcessor 执行流程描述如下:
- 系统根据上一步匹配到的模块创建对应的 Processor对象
- 系统上一步获得的模块附加数据初始化 $message, $inContext, $rule, $module 成员
- 系统调用 respond 方法, 获取响应内容并返回给微信接口
- 调用结束
WeModuleProcessor 的成员及作用描述如下:
abstract class WeModuleProcessor { // array: 预定义的数据, 本次请求消息, 此属性由系统初始化, 消息格式请参阅 "消息类型" public $message; // bool: 预定义的数据, 本次对话是否为上下文响应对话, 如果当前对话是由上下文锁定而路由到的. 此值为 true, 否则为 false public $inContext; // int: 预定义的数据, 本次请求所匹配的规则编号, 此属性由系统初始化, 如果为上下文对话, 那么此值为 -1 public $rule; // array: 预定义的数据, 本次请求所匹配的处理模块, 此属性由系统初始化, 在数组元素中 config 元素可以获取当前模块的配置参数 public $module; /** * 预定义的操作, 开始上下文对话, 附加的参数说明超时 * @param int $expire 当前上下文的超时 * @return bool 成功启动上下文返回true, 失败返回false(如果当前已经在上下文环境中也会返回false) */ protected function beginContext($expire = 1800); /** * 预定义的操作, 刷新上下文超时 * @param int $expire 新的上下文的超时 * @return bool 成功刷新上下文返回true, 失败返回false(如果当前不在上下文环境中也会返回false) */ protected function refreshContext($expire = 1800); /** * 预定义的操作, 结束上下文对话. **注意: 这个操作同样会销毁$_SESSION中的数据** * @return void */ protected function endContext(); /** * 需要实现的操作, 应答此条请求. 如果响应内容为空. 将会调用更低级优先的模块, 直到默认回复为止 * @return array|string 返回值为消息数据结构, 或者消息xml定义 */ abstract function respond(); /** * 预定义的操作, 构造返回文本消息结构 * @param string $content 回复的消息内容 * @return array 返回的消息数组结构 */ protected function respText($content); /** * 预定义的操作, 构造返回图像消息结构 * @param string $mid 回复的图像资源ID * @return array 返回的消息数组结构 */ protected function respImage($mid); /** * 预定义的操作, 构造返回声音消息结构 * @param string $mid 回复的音频资源ID * @return array 返回的消息数组结构 */ protected function respVoice($mid); /** * 预定义的操作, 构造返回视频消息结构 * @param array $video 回复的视频定义(包含两个元素 video - string: 视频资源ID, thumb - string: 视频缩略图资源ID) * @return array 返回的消息数组结构 */ protected function respVideo($video); /** * 预定义的操作, 构造返回音乐消息结构 * @param string $music 回复的音乐定义(包含元素 title - string: 音乐标题, description - string: 音乐描述, musicurl - string: 音乐地址, hqhqmusicurl - string: 高品质音乐地址, thumb - string: 音乐封面资源ID) * @return array 返回的消息数组结构 */ protected function respMusic($music); /** * 预定义的操作, 构造返回图文消息结构 * @param array $news 回复的图文定义(定义为元素集合, 每个元素结构定义为 title - string: 新闻标题, description - string: 新闻描述, picurl - string: 图片链接, url - string: 原文链接) * @return array 返回的消息数组结构 */ protected function respNews($news);}
WeModuleReceiver 介绍WeModuleReceiver 用户定义的模块订阅器处理程序. 当消息到达时, 系统会找到订阅过此类型消息的订阅器, 逐个调用. 使用此功能能实现数据统计分析的功能.
订阅器的操作发生在消息处理之后, 因此不能改变主处理流程, 只能进行数据统计分析 WeModuleReceiver 执行流程描述如下:
- 系统处理消息响应(Processor处理器) ...
- 系统判断当前到达的消息类型, 并找到所有订阅过此类型消息的模块
- 依次创建模块订阅器实例, 并初始化 $message, $params, $response, $keyword, $module
- 依次调用模块订阅器的 receive 方法
- 调用结束
WeModuleReceiver 的成员及作用描述如下:
abstract class WeModuleReceiver { // array: 预定义的数据, 本次请求消息, 此属性由系统初始化, 消息格式请参阅 "消息类型" public $message; // array: 预定义的数据, 本次请求的参数情况. 包括三个元素: module - string: 模块名称, rule - int: 规则编号, context - bool: 是否在上下文中 public $params; // array: 预定义的数据, 本次请求的响应情况 public $response; // array: 预定义的数据, 本次请求所匹配的关键字情况 public $keyword; // array: 预定义的数据, 本次请求所匹配的处理模块, 此属性由系统初始化, 在数组元素中 config 元素可以获取当前模块的配置参数 public $module; /** * 需要实现的操作. 处理此条请求订阅, 此方法内部的输出无效, 请不要调用 exit 或 die 来结束程序执行. * @return void */ abstract function receive();}
WeModuleSite 介绍WeModuleSite 用户定义的微站功能处理程序. 当用户访问微站时, 调用此处理程序来处理访问.
WeModuleSite 主要的功能是定义嵌入点, 包括两种类型的嵌入点:
doWebXXX - 是Web访问的嵌入点, 一般用作后台管理, 在微擎的管理中心进行访问(访问方式 - site.php?act=module&name={$module}&do=XXX) doMobileXXX - 是移动端的嵌入点, 一般用作访问展示, 在手机端或App内置浏览器中访问(访问方式 - mobile.php?act=module&name={$module}&do=XXX) WeModuleSite 执行方式要点描述如下:
- 要进行Web管理的, 比如编辑文章等操作, 请定义 doWebXXX 嵌入点
- 要进行移动端访问的, 比如展示页面等操作, 请定义 doMobileXXX 嵌入点
- 微擎系统定义了两个默认的移动端页面. 首页和个人中心来聚合所有模块的微站功能
- 首页和个人中心都包含功能嵌入方式 - 微站包含了会话访问机制, 通过图文消息进入微站的粉丝用户都会获得会话记录. 并将个人信息保存于 $_W['fans'] 中. (使用COOKIE机制保存)
- 个人中心内置了会话判断, 没有会话信息的访问将被拒绝
WeModuleSite 的成员及作用描述如下:
abstract class WeModuleSite { // array: 预定义的数据, 本次请求所匹配的处理模块, 此属性由系统初始化, 在数组元素中 config 元素可以获取当前模块的配置参数 public $module; // int: 预定义的数据, 本次请求的公众号编号 public $weid; // bool: 预定义的数据, 是否存在 public $inMobile; /** * 这个操作被定义用来呈现微站主页上的导航图标，返回值为数组集合结构, 每个元素将被呈现为一个链接. 元素结构为 array('title'=>'标题','url'=>'链接目标') * @return array 数组集合, 元素结构为 array('title'=>'标题','url'=>'链接目标') */ public function getHomeTiles() { return array(); } /** * 这个操作被定义用来呈现微站个人中心上的管理链接，返回值为数组结构, 每个元素将被呈现为一个链接. 元素结构为 array('title'=>'标题', url'=>'链接目标') * @return array 数组集合, 元素结构为 array('title'=>'标题','url'=>'链接目标') */ public function getProfileTiles() { return array(); } /** * 预定义的操作, 展示特定模板内容, 此方法不能直接展示模块内容, 需要使用 include $this->template(''); 的方式 * @param string $filename 模板名称, 如: settings 将会展示本模块定义下的 template/settings.html 模板文件, 请参阅 "模板机制" * @return void */ protected function template($filename, $flag = TEMPLATE_INCLUDEPATH) {...}}
模块发布模块编写完成后, 可以发布在论坛相应板块供其他用户使用(如果你对你的模块功能很满意并愿意商业化来赚点小钱, 微擎对此非常欢迎).
用户下载好模块包后解压并上传至微擎模块文件夹(/source/modules)内. 用管理员账号登陆, 在系统管理-模块管理中即可显示刚刚上传好的模块, 可以对其进行安装或者更新操作. - 安装时将调用 manifest.xml 中的 install 节点.如果定义为 sql 语句, 将直接运行并完成安装. 如果定义为 php 脚本, 将会包含并执行后完成安装.
- 如果此模块已经存在(根据identifie判别), 并且版本低于 manifest.xml 中定义的版本, 可以通过模块管理中的升级操作进行升级. 升级操作将会执行 upgrade 节点的定义, 执行方式类似于 install.
- 模块安装成功后, 需要针对用户授权模块.
- 按照模块说明使用吧.
- 当你不需要此模块的时候, 可以在模块管理中卸载此模块. 卸载操作将会执行 uninstall 节点的定义, 执行方式类似于 install. 同时会删除所有与此模块有关系的数据(包括规则, 模块权限, 模块配置项等)
|
