====== Z-BlogPHP插件开发 ======



===== 1.说明 =====

插件采用系统提供的各种接口，用来实现一些高级定制功能，让Z-BlogPHP变的更加强壮和有趣(Very Good,Very Strong.)。






===== 2.目录及命名要求 =====

  - 插件是放在系统的zb_users/plugin目录下的，插件必须有自己的目录名且不与其它插件同名。
  - 插件目录名即是插件的ID名称，系统也以此做为识别。
  - 插件必须设定正确的plugin.xml文件，系统依赖此文件对插件进行管理。
  - plugin.xml文件里的"<id>"节点一定要设定为插件的ID名称(即插件的目录名称)，这非常重要。
  - 由于linux系统对文件名大小写敏感，为了兼容性考虑，**所有使用的文件名请务必都用小写英文字符及其它半角字符**:!:

[[zblogphp:development:plugin:tips|更多的提示与技巧]]

===== 3.plugin.xml格式规范说明 =====

==== 3.1 样例文档 ====
<code xml|plugin.xml>
<?xml version="1.0" encoding="utf-8"?>
<plugin version="php">
<id>Totoro</id>
<name>Totoro</name>
<url>http://www.zsxsoft.com/</url>
<note>基于TotoroII的Z-Blog的评论及引用管理审核系统增强版。</note>
<description></description>
<path>main.php</path>
<include>include.php</include>
<level>1</level>
<author>
  <name>zsx</name>
  <email>zsx@zsxsoft.com</email>
  <url>http://www.zsxsoft.com</url>
</author>
<source>
  <name></name>
  <email></email>
  <url></url>
</source>
<adapted>130707</adapted>
<version>1.0</version>
<pubdate>2013-07-07</pubdate>
<modified>2013-09-02</modified>
<price>0</price>
<advanced>
  <dependency></dependency>
  <rewritefunctions></rewritefunctions>
  <conflict></conflict>
</advanced>
<sidebars>
  <sidebar1></sidebar1>
  <sidebar2></sidebar2>
  <sidebar3></sidebar3>
  <sidebar4></sidebar4>
  <sidebar5></sidebar5>
  <sidebar6></sidebar6>
  <sidebar7></sidebar7>
  <sidebar8></sidebar8>
  <sidebar9></sidebar9>
</sidebars>
</plugin>
</code>






==== 3.2 节点说明 ====
  - plugin, 表示此文档存放插件信息，version="php"表示此插件为Z-BlogPHP版插件，而不是ASP版本的
  - id, 插件ID,英文及数字等组成，即存放该插件的目录名。注：不得与其他插件重名
  - name, 插件名称, 中英文均可.
  - url，插件发布页面网址
  - note, 插件简介.
  - description，插件详细描述
  - path, 插件管理页的文件路径，无管理页的插件可留空.
  - include, 接口挂接页面。默认为include.php,无须接口调用的插件可留空.
  - level, 插件管理最低权限等级，以数字表示，1为管理员,2为高级用户,3为中级用户,4为普通用户,5为游客.
  - author, 插件作者.
       - name, 作者名称.
       - url, 作者网址.
       - email, 作者电邮.
  - source，源作者信息，子节点参考author
  - adapted，插件最低要求博客版本号
  - version, 插件的版本号.
  - pubdate，插件发布日期
  - modified, 最后更新日期.
  - price，收费插件定价，可在[[http://app.rainbowsoft.org/|应用中心]]直接购买，为0表示免费。
  - advanced，插件高级选项
       - dependency，依赖插件列表，该插件如果需要其它插件配合使用，应在这里填写准确的依赖**插件ID**列表，以“|”符号分隔，如“demo1|demo2|demo3”。
       - rewritefunctions，系统函数重写列表，该插件如果要重写系统函数，应在这里填写准确的原**函数名**列表，以“|”符号分隔。
       - conflict，冲突插件列表，该插件如果跟其它插件存在冲突，应在这里填写准确的存在冲突**插件ID**列表，以“|”符号分隔。
  - sidebars，主题插件内置侧栏属性
       - sidebar1，侧栏1，该插件如果需要确定侧栏配置，应在这里填写准确的**模块ID**列表，以“|”符号分隔，如“searchpanel|comments|archives|link”。
       - sidebar2，侧栏2，配置方法同上
       - sidebar3，侧栏3，配置方法同上
       - sidebar4，侧栏4，配置方法同上
       - sidebar5，侧栏5，配置方法同上
       - sidebar6，侧栏6，配置方法同上
       - sidebar7，侧栏7，配置方法同上
       - sidebar8，侧栏8，配置方法同上
       - sidebar9，侧栏9，配置方法同上

===== 4.接口分类与调用 =====
Z-BlogPHP提供众多系统级API接口，具体请看[[zblogphp:development:plugin:interfaces]]。


  * 插件挂钩方式
<code php>
Add_Filter_Plugin('API名称','执行代码（函数）');
</code>






===== 5.插件的注册 =====

Z-BlogPHP系统的插件是采用主动插入方式来通知系统。所以必须在include.php文件中调用RegisterPlugin函数才能让插件进入系统的插件体系。

<code php>
//注册插件
RegisterPlugin("插件ID","ActivePlugin_插件ID");
</code>

如需挂载系统接口，还必须在"ActivePlugin_插件ID名称"函数中完成对接口的挂接工作，例如：
<code php>
//具体的接口挂接
function ActivePlugin_插件ID() {
  Add_Filter_Plugin('API名称','执行代码（函数）');
}
</code>



===== 6.插件的激活和禁用执行函数 =====

系统设定每个插件可以提供两个特殊的函数来执行激活和禁用过程中的一次性的任务。

如果你的插件有这种需求，请在include.php里使用这两个函数，系统会在启用和禁用这个插件时自动执行相应函数。

<code php>
function InstallPlugin_插件ID(){}
function UninstallPlugin_插件ID(){}
</code>






===== 7.判断插件状态 =====
判断某插件是否激活。可根据插件激活状态改动本插件功能配置。
<code php>if (!$zbp->CheckPlugin('插件ID')) {$zbp->ShowError(48);die();//插件未启用直接退出本页面（一般用于配置页面）}</code>

<note>:!: 注意，在函数中使用变量$zbp前应进行全局声明，即使用代码：<code php>	global $zbp;</code></note>
===== 8.保存插件数据到数据库 =====
插件如果需要将配置数据或其它扩展数据添加到数据库中，Z-BlogPHP提供了三种存储方式可供选择：

==== 8.1 使用Z-BlogPHP的选项机制 ====
Z-BlogPHP的选项机制，主要用于保存简单的插件选项数据。选项的值可以是字符串、数组或者PHP对象（PHP对象应能够被序列化或转换成字符串，在读取的时候应能够被反序列化）。
=== 1、设置并保存配置选项 ===
<code php>
$zbp->Config('插件ID')->选项参数=选项值;
$zbp->SaveConfig('插件ID');	
</code>
=== 2、读取配置选项 ===
<code php>
$s=$zbp->Config('插件ID')->选项参数;
</code>
=== 3、判断配置选项是否已创建 ===
<code php>
$zbp->HasConfig('插件ID'); //return bool
</code>
=== 4、判断配置选项某一键值是否存在 ===
<code php>
$zbp->Config('插件ID')->HasKey('选项参数'); //return bool
</code>
=== 5、删除配置 ===
删除配置一般选在卸载插件的时候执行。建议根据需要设定是否删除，通常我们建议保留配置以备下次重新启用。
<code php>
$zbp->DelConfig('插件ID');
</code>
==== 8.2 使用扩展元数据机制 ====
也就是Z-BlogPHP的[[zblogphp:自定义域]]机制，主要用于保存一些扩展数据，如文章评分、赞同或反对人数等等。操作自定义域很简单，我们只要定义选项及选项值（注意，选项的定义应是唯一的，不可与其它插件定义重复，值的要求与上述选项机制相同），在原数据保存时其自定义域操数据将同时被保存。下面以文章（$article为某一文章实例）为例：
=== 1、设置并保存自定义域选项 ===
<code php>
$article->Metas->选项参数=选项值;
$article->Save();
</code>
注：在设置后并不是必须要立即调用''Save''方法，在文章保存的同时，''Metas''数据自动一并被保存。
=== 2、读取自定义域选项 ===
<code php>
$s=$article->Metas->选项参数;
</code>
=== 3、删除自定义域 ===
删除配置一般选在卸载插件的时候执行
<code php>
$article->Metas->Del('选项参数');
</code>

==== 8.3 自定义数据表 ====
即创建一个全新的自定义的数据库表。这种方式适合保存那些与文章、分页或附件等等与原数据无关的独立数据，或者虽然是与原数据相关但本身数据量较大需要独立存储的情况也可以使用该方法。更多关于自定义数据库用法请参考[[zblogphp:development:plugin:自定义数据库表]]

===== 9.主题附带插件 =====
  - 主题可包含一个插件，这个插件的ID名称就等于主题的ID名称。
  - 主题里的插件文件必须直接放置在主题目录下。
  - 主题里的插件无plugin.xml，其信息全部记录在了主题的配置文件theme.xml文件节点里。
  - 主题里的插件的优先级最高且不可调整，只要启用这个主题，插件自动激活，直到切换其它主题为止。