plugins_design.htm

论坛代码网增加免费空间业务

	pluginvarid	插件配置的惟一 ID，自动地增
	pluginid		本项配置所隶属的插件 ID
	displayorder	本项配置的显示顺序，数值低的排在前面
	title		插件配置的名称
	description	插件配置的简介
	variable		插件配置的变量名
	type		插件配置的类型
	value		插件配置的值
	extra		当本项配置为“选择（select）”时，可选的取值范围
</pre></td></tr></table>

<p>如果您使用自行编写的插件后台管理模块进行插件参数配置，请尽量将配置项目按照 pluginid 的对应关系，将参数存储于 pluginvars 表中，这样系统就可以自动将您增加的配置参数缓存起来，以供插件程序进行调用。

</ul><p class="subtitle">插件参数读取<ul>

<p>了解了 Discuz! 插件存储的数据结构后，您可以在插件程序中根据需要选择合适的数据读取方式。由于数据库读取方式可以由数据结构推断而来，因此这里只介绍缓存读取的方式，这种方式是我们强烈推荐的插件数据读取方式。

<p>在管理者配置好插件信息，或用户进行插件的参数设置之后，系统将根据插件设置的惟一标识符，自动生成一个插件数据的缓存文件，例如惟一标识符为 comsenz_virtual_bank，则缓存文件位于 ./forumdata/cache/plugin_comsenz_virtual_bank.php，您可以打开此文件查看其中的数据内容和格式。缓存采用数组的方式进行存储，引用此文件即可将所需的插件参数一次性赋值。

<p>其中，$_DPLUGIN['comsenz_virtual_bank'] 这个数组下标，为插件的惟一标识符，所有插件缓存数据，一经被引用，就会赋值到 $_DPLUGIN 这个多维数组中。modules 描述了这个插件的模块信息，其中 type 为 1~4 的整数值，从小到大依次为“直接链接(前台菜单)”、“前台调用(前台菜单)”、“后台调用(后台菜单)”、“包含运行(无菜单)”；vars 描述了这个插件的配置变量，前面为变量名，后面为使用者赋予这个变量的值。

</ul><br /></td></tr><tr><td class="title">编写插件的原则与注意事项</td></tr>
<tr><td><br />

<p>请在您动手编写插件之前，还需要仔细的阅读以下原则，遵循这些原则，将有效的避免可能发生的问题：

<p><ul>
<li>所有与插件的程序，包括<b>其全部的前后台程序</b>，请全部放入 ./plugins 目录中，同时在插件的安装说明中指出，插件的文件需要复制到哪些目录。为了避免与其他插件冲突，请尽量建立 ./plugins 下的子目录，并将插件程序放置于子目录下，这样您编写的插件将获得更好的兼容性。
<li>如果您的插件包含“前台调用（前台菜单）”模块，该模块将统一用 plugin.php?identifier=xxx&module=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 为插件的惟一标识符，yyy 为模块名称。前台插件外壳程序 plugin.php 已经加载了通用初始化模块（./include/common.inc.php），不需再次引用。
<li>如果您的插件包含“后台调用（后台菜单）”模块，该模块将统一用 admincp.php?action=plugins&identifier=xxx&mod=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 和 yyy 的定义与“前台调用（前台菜单）”模块中的相同。系统还允许用 admincp.php?action=plugins&edit=$edit&mod=$mod 的方式来生成链接和表单地址，$edit 和 $mod 变量已经被插件后台管理接口赋值，因此将这两个变量值带入 URL 中也是被支持的。由于后台模块是被 admincp.php 调用，因此已加载了通用初始化模块（./include/common.inc.php）并进行了后台管理人员权限验证，因此模块程序中可直接写功能代码，不需再进行验证。
<li>请勿绕过插件的前后台外壳（plugin.php 和 admincp.php）而以直接调用某程序的方式编写插件，因为这样既导致了用户使用不便，代码冗余和不规范，同时又产生了因验证程序考虑不周到而带来的安全隐患。您可以在任何地方，包括链接、表单等处方便的使用上述 URL 地址对插件模块进行调用。
<li>所有与插件有关的程序，包括全部的前后台程序，因全部使用外壳调用，请务必在第一行加入
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	if(!defined('IN_DISCUZ')) {
		exit('Access Denied');
	}
</pre></td></tr></table>
以免其被 URL 直接请求调用，产生安全问题。
<li>一般情况下，您发布插件请使用插件导出的功能，以方便使用者一次性导入插件的配置数据，极特殊的情况下，也可以分步骤告知使用者如何进行插件配置管理和安装此插件。
<li>如果功能独立，请尽量使用单独程序的方式编写插件（即外挂型插件），而尽量少的对论坛本身代码进行修改，这将为使用者今后的升级带来很大方便。
<li>您可以修改 Discuz! 本身的数据结构，但更推荐在不很影响效率的前提下将插件数据用另外的数据表存储，因为不能排除您增加的字段或索引和今后版本 Discuz! 核心数据字段重名的可能。<b>在任何情况下，请不要删除 Discuz! 标准版本数据结构中已有的字段或索引</b>。
<li>请在插件说明书中对插件做以详尽的描述，例如增加了哪些字段、哪些表，修改了或新增了哪些程序，版本兼容性，后续支持的提供方式（例如不提供支持，或以什么样的方式提供）。如果方便，请尽可能提供插件的卸载方法，例如去除哪些字段、删除哪些新增的程序、将哪些被插件修改的程序恢复原状等等，使用者会感激您为此付出的辛勤劳动，甚至愿意支付相应的费用支持您未来的发展。
<li>如果插件使用另外的数据表存储，请在插件管理中准确的设置插件所使用的数据表名称（不包含前缀），这样用户在备份数据的时候，能够把插件数据一同备份。
<li>Discuz! 自 4.0.0 版本起，内置了 8 种自定义积分，存储于 members 表中的 extcredits1 至 extcredits8 字段中，类型为有符号整数，您可以在引用 common.inc.php 后，在 $extcredits 或 $_DCACHE['settings']['extcredits'] 中读取 8 种积分的启用信息（详情请参考 ./forumdata/cache/cache_settings.php）。插件程序中如需更新用户积分，可直接 UPDATE 相应的积分字段，无需其他操作。

</ul><br /></td></tr>
<tr><td class="title">插件钩子的设计</td></tr>
<tr><td><br />
<p>插件钩子的设计，需要您具有一定编程基础，比较了解 Discuz! 论坛程序的结构，并能够使用 PHP 语言撰写代码。对于普通用户，可以略过以下内容。 插件钩子（以下简称“钩子”）属于插件的一部分，因此在设计钩子之前应当首先进入后台——插件管理，新增插件或者编辑一个现有的插件，即可看到相关设置。
<p class="subtitle">钩子的添加<ul>
<li>钩子名称：在一个插件内，钩子的名称是唯一的，不可重复。名称可以由英文字母、数字和“_”组成，不支持中文，最长255个字符。为了便于理解和记忆钩子的作用， 名称应当尽量简洁清晰，能够表述一定的含义。注意：钩子名称对字母大小敏感，例如：Index_start 和 index_start 将视为两个不同的钩子。
<li>钩子描述：对钩子的详细说明，如功能介绍、调用方法、使用方法等。
<li>PHP代码：这里是钩子的核心内容，也是一段PHP代码，需要您自行设计，完成钩子需要处理的数据或者需要执行的操作。
<li>可用：每个插件允许有多个钩子，您可以自由选择关闭或者开启某个钩子。
</ul><p class="subtitle">钩子的删除<ul>
<p>在钩子管理界面，您可以随时删除某一个钩子。 钩子删除以后，您应当及时修正放置钩子的程序文件，清除钩子标记，以免影响您论坛的正常使用。</ul>
<p class="subtitle">钩子的编辑与升级<ul>
<li>编辑：插件设计阶段，您可能需要随时编辑钩子，每次更改，系统会自动更新缓存文件，您可以立即看到更改的效果。如果是更改钩子名称，那么您可能需要调整钩子放置的程序，修改钩子调用的名称。
<li>升级：论坛程序进行升级之前，您应当使用插件的导出功能，导出插件备份。论坛升级并正常运行后，再导入插件备份，修改相关程序，重新安放钩子。
</ul><p class="subtitle">钩子的放置与调用<ul>
<p>钩子设计完成以后，您需要在相应的程序中安放钩子，不同钩子由于作用的不同，放置的位置也是不同的。 安放钩子，您仅仅需要将钩子的调用代码放入即可。调用代码格式如下：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td> <pre>

	 eval($hooks['插件唯一标识符(identifier)_钩子名称']);	  </pre>
</td></tr></table>
<p>例如：调用 插件demo 的钩子 testhook,  我们需要在程序中适当的地方加入下面的代码
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	eval($hooks['demo_testhook']); </pre>
</td></tr></table>
</ul><p class="subtitle">设计范例<ul>
<p>此处我们为您提供一个使用钩子技术的插件范例，完成功能十分简单，旨在使您直观的了解钩子的使用。此范例实现了当游客访问论坛首页时，强制用户登录的功能。
<ul>
<li>进入系统设置中的插件管理，添加一个名称和惟一标识符均为 <b>demo</b> 的插件。
<li>编辑插件 <b>demo</b> 详情，找到“插件钩子设置”，添加一个名为 <b>index_force_loggedin</b> 的钩子，然后提交。
<li>编辑钩子 <b>index_force_loggedin</b>，按如下内容填写设置：
<ul>
<li>钩子描述：当游客访问论坛首页的时候，程序会弹出提示框，并自动跳转到登陆页面。
<li>PHP代码：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	if(!$discuz_uid) {
		showmessage('请您登陆后访问本站，现在将转入登录页面。', 'logging.php?action=login');
	}
</pre></td></tr></table>
</ul>
<li>提交后，回到此插件的设置页面。将钩子 <b>index_force_loggedin</b> 设置为可用。
<li>点击左侧导航，进入插件管理，将插件 <b>demo</b> 设置为可用。
<li>编辑论坛程序 <b>index.php</b> 安放钩子，方法如下：
<ul>
<li>查找代码：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	$discuz_action = 1;
</pre></td></tr></table><br />
<li>在上述代码下放添加代码：
<table width="80%" cellpadding="0" cellspacing="0" border="0" class="code">
<tr><td><pre>

	eval($hooks['demo_index_alter']);
</pre></td></tr></table>
</ul>
<li>保存文件后将文件上传到服务器。
<li>至此，一个简单的使用钩子实现的插件已经彻底完成。您可以退出登陆并访问论坛首页，测试一下插件的效果。</ul>

</ul><p>Discuz! 插件的钩子技术，为广大的插件开发者提供了一个更加灵活的插件设计机制。当 Discuz! 升级后，用户只需重新将钩子调用代码安放到程序中原来的位置，就几乎可以继续使用原来已安装的插件，降低了对于程序修改的幅度和插件安装的难度，更加有利于插件程序的规范、管理、维护、相互交流。因此我们强烈建议插件开发者能够深入研究个应用这一机制，创作出越来越多的优秀插件。

</ul><br /></td></tr><tr><td class="title">意见反馈</td></tr>
<tr><td><br />
<p>插件接口是 Discuz! 开发组为了方便插件设计、安装和使用而专门开发，虽然经过长期的优化和改进，可能仍然会有不够合理或不够完善的地方，欢迎各位插件程序员在使用此接口的过程中，为我们提出意见和建议，感谢您的支持。

</td></tr></table>

<script language="JavaScript" src="footer.js"></script>
</body>
</html>