Wordpress插件API
目录
|
概述
这篇文章介绍了对WordPress插件开发者有用的API(应用编程接口)Hooks，以及如何使用它们。
这篇文章假设你已经读过写一个插件，提供一个概要(和许多细节)去如何开发一个插件。这篇文章明确地是关于API “Hook”，亦称“Filters”和“Actions”，那WordPress用途设置你插件在行动。这些Hook也许也用于题材，如所描述这里。
注： 这信息适用于WordPress版本1.2或更高。在版本1.2之前，修改称为“Hacks”，并且介入编辑WordPress自身的源代码。
Hooks、Actions和Filters
Hook是由WordPress提供的，允许你的插件“钩入”WordPress；即在特定时间调用在你插件中的函数和从而使你的插件运行。有二种类型的Hooks：
-
- Actions：Actions是正在运行的WordPress核心程序在特殊点（或当特殊事件发生时）加载的Hook。使用Action
API，你的插件可能在这些点运行一个或多个PHP函数。 - Filters：Filter（过滤器）是WordPress加载的修改被存入数据库前和浏览器屏幕上前的多种类型的文本的Hook。使用Filter API，你的插件可以在这些时候使用一个或者多个PHP函数来对文本进行多种处理。
- Actions：Actions是正在运行的WordPress核心程序在特殊点（或当特殊事件发生时）加载的Hook。使用Action
有时你能使用Action或Filter实现同样的目的。例如，如果你想使用插件改变一篇博客的文本，你可以增加一个Action函数到publish_post(因此博客在它被保存入数据库时被修改)，或者加一个Filter函数到the_content(因此博客在它显示在浏览器上时被修改)。
请在Adam Brown’s WP Hooks Database查看一个关于所有Wordpress Action和Filter hooks的详尽列表。
函数参考
|
|
| 激活和禁用函数 |
|
|---|---|
Actions
Actions在WordPress进行某些特殊事件处理时被触发，例如发布日志，修改主题，或者在管理员面板显示页面。你的插件可以通过执行PHP函数来发挥作用，他们可以用来做如下事情：
- 修改数据库数据
- 送一个电子邮件
- 修浏览器屏幕显示内容(管理员或终端用户)
对做此的基本步骤发生(如下较详细地描述)是：
- 在你的插件中创建当事件发生时执行的PHP函数。
- 通过调用add_action()函数，Hook（钩入）Action到WordPress。
- 将你的PHP函数放入插件文件中，并且激活它。
创建一个Action函数
在插件中创建Action的第一步是在插件中编写一个实现Action功能的PHP函数并且将其放入你的插件文件中（插件文件必须放置
在wp-content/plugins目录）。比如，如果你希望当发表一篇博客后，发送Email通知给你的朋友，那么你可以定义如下函数：
<a>function email_friends($post_ID) {
$friends = 'bob@example.org,susie@example.org';
mail($friends, "sally's blog updated",
'I just put something on my blog: http://blog.example.com');
return $post_ID;
}</a>
为多数Action，你的函数应该接受一个唯一参量(通常岗位或评论ID，根据Action)。一些Action采取超过一个参量 –检查文献行动(若有)或WordPress原始代码对于更多信息。
除这一个参量以外，你能也访问WordPress的全局变量，并且叫其他WordPress在你的插件文件的函数(或函数)。
由函数的所有文本产品(即与印刷品)将出现于页来源于行动被
祈求的地点。
注意：切记其他插件或者WordPress核心可能已经使用了你想使用的函数名。更多信息参见避免功能名冲突。
Hook到WordPress
在你的函数被定义之后，下一步就是将它hook（钩入）或注册到WordPress中，你可以调用通过全局执行空间中的add_action()函数来实现它：
add_action (‘hook_name’， ‘your_function_name’， [priority]， [accepted_args]);
在这里：
- hook_name
- 是由WordPress提供的Action Hook名称，这决定了你的函数应当和哪个事件结合。
- your_function_name
- 你想执行由hook_name参数指定的事件的函数名称。该函数可以是标准的PHP函数，在WordPress核心中定义的函数，或者你在插件文件中定义的函数（如上面的’email_friends’函数）。
- priority（优先级）
- 一个可选的整型参数，它用来指明在结合特定事件的多个函数中，当前函数被执行的顺序（缺省为10）。更小的数字会被更早的执行，priority参数相同的函数会依照他们被加入Action的顺序来执行。
- accepted_args
- 一个可选的整型参数，它定义了你的函数中多少个参数可以被接收（默认为1）。该参数是非常有用的，因为某些Hook可以向你的函数中传入多个参数。该参数在1.5.1版本中被新加入。
在上面的例子中，我们在插件文件中加入以下行：
add_action (‘publish_post’， ‘email_friends’);
同样，你也能从Action hook中移除Action 。 细节参见Remove Actions and Filtes。
安装并且激活
你的ActionHook开始工作的最后一步是安装插件文件和激活插件。你编写的PHP函数和add_action函数调用放置在同一个PHP文件中，该PHP文件必须被安装在wp-content/plugins目录，当该文件安装完毕，你需要浏览WordPress的管理面板去激活你的插件，你可以参考Managing Plugins文章来获得更多信息。
当前的Actions Hooks
请浏览插件API/Action参考来获得一份当前版本的WordPress中可用的ActionHooks列表，它也链接到老版本的版本的WordPress。
Filter
Filters是WordPress在执行中的特定点传递数据的函数，它发生在对数据进行操作（如将其加数据到数据库或发送到浏览器）之前。Filter建立在数据库到浏览器之间的处理（当WordPress生成页面时），同时也建立在浏览器到数据库之间的处理（当WordPress新增日志或者评论到数据库时）；多数WordPress中的输入输出都通过了至少一个filter。WordPress默认已经实现了一些过滤操作，你的插件也可以加入你自己的过滤操作。
将你的filter加入WordPress中的基本步骤（在下面被详细描述）是：
- 创建用于过滤数据的PHP函数。
- 通过调用add_filter()函数将filter Hook（钩入）到WordPress。
- 将你的PHP函数放入插件文件，并且激活它。
创建Filter函数
Filter函数获得未经修改的数据，并返回修改后的数据（或者在某些情况下，返回空值来标识数据应当被删除或忽略）。如果你的filter不修改数据，那么应当返回原始数据，这样，如果必要，其余的插件可以继续修改数据。
因此，在你的插件中创建filter的第一步是编写一个PHP函数来进行过滤处理，并且将其放在你的插件文件（插件文件必须放置在wp-content/plugins目录）当中。例如，如果你希望确保你的帖子和评论中不包含脏话，你可以定义一个存放禁止词汇的全局变量，然后编写如下的 PHP函数：
function filter_profanity($content) {
global $profanities;
$content=str_ireplace($profanities,'{censored}',$content);
return $content;
}
为什么不在这工作中使用循环？$profanities应该是数组，并且str_replace通过你的数组循环。
注意：记住其它插件或WordPress核心程序也许已经使用你想用的函数名。对于更多信息请看插件开发建议。
你的Filter hook
在你的函数被定义之后，下一个步骤“Hook”或注册它到WordPress。 你可以调用通过全局执行空间中的add_filter()函数来实现它：
add_filter (‘hook_name’， ‘your_filter’， [priority]， [accepted_args]);
在这里：
- hook_name
- 由WordPress提供的Filter hook的名字，它定义了你的Filter什么时候被执行。
- your_filter
- 你想要为过滤使用函数的名字。这可以是一个标准PHP函数，当前WordPress核心的函数，或者在你的插件文件被定义的函数。
- priority（优先级 ）
- 一个可选的整型参数，它用来指明在结合特定事件的多个函数中，当前函数被执行的顺序（缺省为10）。更小的数字会被更早的执行，priority参数相同的函数会依照他们被加入Filter的顺序来执行。
- accepted_args
- 一个可选的整型参数，它定义了你的函数中多少个参数可以被接收（默认为1）。该参数是非常有用的，因为某些Hook可以向你的函数中传入多个参数。
在上面的例子中，我们加以下代码到插件文件的主要执行部分，告诉WordPress过滤亵渎的评论：
add_filter (‘comment_text’， ‘filter_profanity’);
你也能使用remove_filter()函数从Filter Hook中去除Filter 。 参见Removing Actions andFilters。
安装并且激活
让你的Filter Hook开始工作的最后一步是安装插件文件和激活插件。你编写的PHP函数和 add_filter()函数调用放置在同一个PHP文件中，该PHP文件必须被安装在wp-content/plugins目录，当该文件安装完毕，你需要浏览WordPress的管理面板去激活你的插件，你可以参考Managing Plugins文章来获得更多信息。
当前的Filter Hook
请浏览插件API/Filter参考来获得一份当前WordPress中的FilterHook列表，它也链接到老版本的版本的WordPress。
例子
由Ozh所描述的在wp-hackers上的电子邮件名单的例子，为了插件修改(或重写)缺省bloginfo()函数。 这将要求修改核心函数行为。
add_filter('bloginfo', 'mybloginfo', 1, 2);
add_filter('bloginfo_url', 'mybloginfo', 1, 2);
function mybloginfo($result='', $show='') {
switch ($show) {
case 'wpurl':
$result = SITE_URL;
break;
case 'template_directory':
$result = TEMPL_DIR;
break;
default:
}
return $result;
}
移除Actions和Filters
有时，你希望你的插件屏蔽WordPress内建或者其他插件加入的Action或Filter。你可以通过执行remove_filter(’filter_hook’, ‘filter_function’)或者remove_action(’action_hook’,'action_function’)函数来实现。
例如，remove_action(’publish_post’, ‘generic_ping’)；会使得你在发表新日志时不发送日志引用（ping）。
注意如果某个hook在注册时使用了除默认值10以外的priority参数，则你必须修改调用remove_action()函数时的priority参数。同时也请注意，通常来讲除非你知道这样做的原因和后果，你不应当移除任何东西—请检查WordPress或者其他插件的源代码来保证这一点。
可插入的函数
除上面描述的hooks(Action和Filter)以外，插件可用另一个方式修改WordPress的行为去重载WordPress函数。实际上，有一个WordPress想要为插件重新定义的小的函数集，他们调用了Pluggable Functions，并且在wp-includes/pluggable.php中被定义，只有在所有插件被装载后当他们仍然未被定义的，WordPress才装载这些函数。 欲了解更详细的信息查看wp-settings.php文件。
激活或者禁用插件
如果你的插件在激活或禁用期间需要完成任务，它可以使用register_activation_hook和register_deactivation_hook。因为插件只修改当前行为，许多插件不需要使用这些。然而，如果你的插件在激活时需要改变的缺省选项，或者如果它需要从一个老版本做的变动升级，它可能使用这些函数。
用插件创建表有一个例子使用register_activation_hook函数使数据库与最新版本的插件兼容。
Popularity: 15%
我花了不少时间来翻译它！
测试嵌套引用！