Discuz!7.1新核心插件开发手册【官方提供】(一)
原文链接:http://www.17cha8.cn/bencandy.php?fid-89-id-4006-page-6.htm插件设计 |
您在开始论坛插件的设计之前,有必要了解一下我们所推荐的插件设计方式,更好的规范性和兼容性,将使得您设计的插件受到更多使用者的欢迎,对于程序员而言,也有助于形成良好的编码习惯,实现自身能力的提升。如果您有意编写 Discuz! 论坛插件,请按照先后顺序仔细阅读本文档。 |
准备工作 |
插件实现流程
文件命名规范
common.inc.php 模块功能白皮书
|
如果您使用自行编写的插件后台管理模块进行插件参数配置,请尽量将配置项目按照 pluginid 的对应关系,将参数存储于 pluginvars 表中,这样系统就可以自动将您增加的配置参数缓存起来,以供插件程序进行调用。
插件参数读取
了解了 Discuz! 插件存储的数据结构后,您可以在插件程序中根据需要选择合适的数据读取方式。由于数据库读取方式可以由数据结构推断而来,因此这里只介绍缓存读取的方式,这种方式是我们强烈推荐的插件数据读取方式。
在管理者配置好插件信息,或用户进行插件的参数设置之后,系统将根据插件设置的惟一标识符,自动生成一个插件数据的缓存文件,例如惟一标识符为 comsenz_virtual_bank,则缓存文件位于 ./forumdata/cache/plugin_comsenz_virtual_bank.php,您可以打开此文件查看其中的数据内容和格式。缓存采用数组的方式进行存储,引用此文件即可将所需的插件参数一次性赋值。
其中,$_DPLUGIN['comsenz_virtual_bank'] 这个数组下标,为插件的惟一标识符,所有插件缓存数据,一经被引用,就会赋值到 $_DPLUGIN 这个多维数组中。modules 描述了这个插件的模块信息;vars 描述了这个插件的配置变量,前面为变量名,后面为使用者赋予这个变量的值。
| ||
插件接口概述 | ||
使用管理员账号登录 Discuz! 系统设置,在左侧菜单将可以看到“插件设置”和“插件管理”两个选项,使用超级版主或版主账号登录,将只出现“插件设置”一个选项。“插件管理”是控制插件打开与否、设计插件模块、菜单、参数和使用权限的地方,插件开发者可以依照设计意图,在此进行插件的初步设置,这里同时也提供插件导入和插件开关的功能,用于导入他人设计的插件和对插件的可用状态进行变更。“插件设置”是对已经安装的插件进行设置的地方,供使用者对插件参数进行调整以实现不同的插件功能。即前者主要面向开发者,后者主要面向使用者。 开始编写一个新插件,请首先在插件管理中,输入新插件的名称和惟一标识符。名称用于表明此插件的用途,例如设置为“虚拟银行插件”。惟一标识符用于在后续的插件模块中调用本插件,不可与现有插件重复,命名规则限制与 PHP 变量命名相同,虽然初次设置后仍可改动,但强烈建议一次性将此配置设置好,否则可能涉及到很多代码方面的变更,增加编码的麻烦。请注意:惟一标识符请不要设置的过短,或使用有可能与其他插件重复的命名,例如制作此插件的公司叫做 Comsenz Inc.,插件名称是“虚拟银行插件”,惟一标识符可设置为“comsenz_virtual_bank”,后面将以“虚拟银行插件”和“comsenz_virtual_bank”为例进行说明。 在插件管理中添加插件后,仅仅是增加了一条插件记录,后面还需要很多相关的设计和设置。在列表中选择插件的“详情”进入插件的详细设置。插件设置分为三个部分:
| ||
参数读取与缓存控制 | ||
编写插件程序时,可能需要读取一些插件的信息,如果插件需要使用者进行配置,还需要读取使用者设置的参数值。Discuz! 允许插件程序使用数据库读取和缓存读取这两种方法获取插件信息和参数。Discuz! 的插件接口已经对插件信息进行了合理的缓存,使用缓存读取的方式,将比数据库读取速度更快,消耗的资源更是几乎可以忽略不计。缓存读取唯一的局限是需要插件使用插件接口提供的通用后台管理程序。如果使用自定义后台模块的方式,需要后台模块将参数存放到 pluginvars 数据表中,才能被系统正常缓存。我们强烈推荐您通过缓存读取插件信息和配置数据。 插件数据结构
pluginvars 表:
|
页面嵌入模块开发 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
<?phpclass plugin_sample {function _updatecache() {......return ...;}function viewthread_posttop() {......return ...;}......}?> |
插件的当前版本号位于 XML 文件的以下分支中,可自行更改。
| |||||||||||||||||||
特殊主题模块开发 | |||||||||||||||||||
| |||||||||||||||||||
插件安装、卸载、升级脚本的设计 | |||||||||||||||||||
|
<item id="plugin">......<item id="version"><![CDATA[当前版本]]></item>......</item> |
<item id="license"><![CDATA[授权协议文本]]></item><item id="intro"><![CDATA[插件介绍文本]]></item></item></root> |
- 模板、语言包
插件中的语言包可以写到导出的 XML 文件结尾,这样在插件安装的时候会自动把语言包生成文件名为 forumdata/plugins/identifier.lang.php 的文件。插件开发时,可直接在后台开启语言包选项后编辑此语言包文件。<item id="language"><item id="scriptlang"><item id="text"><![CDATA[脚本语言文字]]></item></item><item id="templatelang"><item id="text"><![CDATA[模版语言文字]]></item></item><item id="installlang"><item id="text"><![CDATA[安装语言文字]]></item></item></item></item></root> - scriptlang 为脚本文件的语言包,templatelang 为模版文件的语言包,installlang 为安装、升级、卸载脚本用的语言包。
插件的模板文件可以放置在 plugins 目录下,如 plugins/hooktest/templates 子目录下。页面嵌入模块的脚本中可用以下方式调用此目录下的模板。
通过 plugin.php 调用的插件可直接用以下函数。include template('index_top', 'hooktest', './plugins/hooktest/templates');
插件模版文件中的语言包中通过 {lang identifier: langvar} 方式调用,例如:include plugintemplate('index_top');
上例中对应的变量为语言包文件 forumdata/plugins/ identifier.lang.php 中 $templatelang['hooktest']['text'] 的值。脚本中引用语言包无需包含语言包文件,可直接使用变量。如插件脚本中可用变量 $scriptlang['hooktest']['text'],安装脚本中可用变量 $installlang['hooktest']['text']。<!--{block return}-->{lang hooktest:text}<!--{/block}-->
- 其他论坛数据导入
插件安装时可以直接导入一个或多个论坛数据,这些论坛数据包括数据调用(request)、论坛方案(project)、表情(smilies)、风格(styles)的数据。在导出的 XML 文件结尾加上需要导入数据的类型和数据文件名即可,多个文件名用逗号(",")分隔。<item id="importfile"><item id="request"><![CDATA[discuz_request_test.xml,discuz_request_test2.xml]]></item><item id="project"><![CDATA[discuz_project_test.xml]]></item><item id="smilies"><![CDATA[discuz_smilies_test.xml]]></item><item id="styles"><![CDATA[discuz_styles_test.xml]]></item></item></item></root> - 小提示
在新插件内核中,通过 plugin.php 方式访问的插件可直接通过 plugin.php?id=xxx:yyy 方式调用而无需再在后台定义为普通脚本模块,只要 plugins/xxx/yyy.inc.php 文件存在即可。如果 xxx 和 yyy 同名,可直接通过 plugin.php?id=xxx 方式访问。如果导出的 XML 文件名以 SC_GBK、SC_UTF8、TC_BIG5、TC_UTF8 结尾,显示的时候将直接显示为“简体”、“繁体”、“UTF8”等字样。
编写插件的原则与注意事项 | ||
请在您动手编写插件之前,还需要仔细的阅读以下原则,遵循这些原则,将有效的避免可能发生的问题:
| ||
插件钩子的设计 | ||
插件钩子的设计,需要您具有一定编程基础,比较了解 Discuz! 论坛程序的结构,并能够使用 PHP 语言撰写代码。对于普通用户,可以略过以下内容。 插件钩子(以下简称“钩子”)属于插件的一部分,因此在设计钩子之前应当首先进入后台——插件管理,新增插件或者编辑一个现有的插件,即可看到相关设置。 钩子的添加
钩子的删除
钩子的编辑与升级
钩子的放置与调用
例如:调用 插件demo 的钩子 testhook, 我们需要在程序中适当的地方加入下面的代码
|
设计范例
| |||
意见反馈 | |||
插件接口是 Discuz! 开发组为了方便插件设计、安装和使用而专门开发,虽然经过长期的优化和改进,可能仍然会有不够合理或不够完善的地方,欢迎各位插件程序员在使用此接口的过程中,为我们提出意见和建议,感谢您的支持。 |