个人工具
名字空间
变换
操作

WordPress:Plugin API

来自站长百科
跳转到: 导航, 搜索

导航: 上一级 | WordPress | 首页 | WordPress中文论坛 | WordPress主机 | CMS程序 | 论坛程序 | ECShop | ShopNC | PowerEasy

目录

介绍

这个网页证明了API(应用程序接口)hooks,WordPress插件开发者可以使用,和怎样使用这些。

这篇文章假定你已经阅读了写一个插件,这个给出了怎样发表一个插件的梗概(和许多详细信息)。这篇文章是明确关于"Hooks"的API,也称为"过滤器" 和"Actions",WordPress用这个将你的插件设置为运转之中。

注:这个信息适用于WordPress1.2版本以及更高的版本。在1.2版本之前,修改被称为是"hacks"并且涉及到编辑WordPress自身的源代码。

Hooks, Actions 和过滤器

Hooks是由WordPress提供的,使你能够插入'hook into'WordPress的其余部分;这就是说,在特别时间里,访问你的插件里的函数,这样就将你的插件设置为运转的了。有两种类型的hooks:

  1. Actions:Actions是hooks,在执行的时候,或者当一个特别的事件发生的时候,WordPresshe核心发行在一个特殊的点上。你的WordPress可以指定它的一个或者更多的PHP函数在这些点的时候执行,使用Action API。
  1. 过滤器:过滤器是hooks,WordPress发行来更改不同类型的文本,在WordPress将文本添加到数据库或者将它发送到浏览器界面之前,添加。你的插件可以指定它的一个或者更多的PHP函数被执行用来在这些时候修改特别类型的文本,使用过滤器API。

有时候你可以使用一个action或者一个过滤器达到同样的目标。例如,如果你想要你的插件来更改一篇文章的文本,你可能添加一个action函数到publish_post(这样文章便被修改了,因为文章已经保存到了数据库),或者添加一个过滤器到 _内容(这样文章便被更改了,因为文章显示在浏览器界面)。

Actions

Actions是由发生在WordPress里的特殊事件触发的,例如发表一篇文章,更改主题,或者显示管理面板的一个页面。通过执行一个PHP函数,你的插件可以对事件做出回应,可能会执行以下一个或者更多的步骤:

  • 更改数据库数据
  • 发送一个电子邮件信息
  • 更改显示在浏览器屏面上的内容(管理或者最终用户)

使这个发生的基本步骤是(在下面有更加详细的描述):

  1. 创建PHP函数,这个函数在事件发生的时候,会在你的插件文件中执行。
  2. 通过访问add_action,hook到WordPress中的action
  3. 将你的PHP函数放入一个插件文件中,然后将它激活。

创建一个 Action 函数

在你的插件中创建一个action的第一个步骤就是用你的插件泛函性创建一个PHP函数,并且将这个函数放入你的插件文件(你的插件文件必须进入wp-content/插件目录)。例如,当你写了一篇新的文章的时候,你想让你的朋友得到一个电子邮件的关于你的文章的信息,你可能会定义以下的函数:

function email_friends($post_ID)  {
  $friends = 'bob@example.org,susie@example.org';
    mail($friends, "sally's blog updated", 
      '我只是在博客上写了一些东西: http://blog.example.com');
    return $post_ID;
}

对于大多数actions,你的函数应该接受一个单一的参数(通常是文章或者评论ID,这取决于action)。有的action不止需要一个参数—查看文件中的action(如果拥有的话)或者WordPress源代码得到更多的信息。除了一个参数以外,你可以访问WordPress的全局变数,和其它的WordPress函数(或者你的插件文件的函数)。

: ;牢记其它的插件或者WordPress核心可能已经在使用你想到的函数名。更多的信息,请看避免函数名重叠

Hook to 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是一个任意的整数论点,可以用来规定函数与一个特别的action 执行的顺序(默认值是:10)。更小的数字与更早的执行相符合,有着同样的优先权的函数,执行是按它们添加到action的顺序。
  • accepted_args是一个任意的整数引数规定了你的函数可以接受多少个引数(默认为1),这很有用,因为有的hooks可以通过几个引数到达你的函数。这个参数在1.5.1版本中是新的。

在上述的例子中,我们会将下面的行放到插件文件中:

add_action('publish_post', 'email_friends');

同样地,你也可以从action hooks中移除 Actions。详细信息请看那个部分。

安装和激活

使你的action hook运行的最后的一个步骤就是安装文件并且激活那个插件。你所写的和add_action访问必须一同地进入一个PHP文件,PHP文件必须安装在wp-content/plugins目录。 一旦PHP文件安装了,你就要访问WordPress的管理部分并且激活你的插件;更多详细信息请看管理插件

关于Actions的当前的Hooks

请查看WordPress:Plugin API/Action Reference得到WordPress里的action hooks的一个当前的列表以及链接到先前版本的WordPress的链接。

过滤器

过滤器是WordPress,在执行时的某一点上,就在用数据采取一些活动之前,通过数据的函数(例如将它添加到数据库或者将它发送到浏览器界面)。过滤器在数据库和浏览器之间(当WordPress产生网页的时候),在浏览器和数据库之间(当WordPress给数据库添加新的文章和评论的时候);WordPress中大多数输入和输出至少通过一个过滤器。默认情况下,WordPress处理一些过滤,而且你的插件可以添加它自己的过滤。

将你自己的过滤器添加到WordPress的基本步骤是(在下面详细描述了):

  1. 创建过滤了数据的PHP函数。
  2. 通过访问add_filter,hook到WordPress里的过滤器。
  3. 将PHP函数放到一个插件文件中,并且将它激活。

创建一个过滤器函数

一个过滤器函数用来输入未修改的数据,并且返回修改的数据(或者在有些情况下,一个null值暗示数据应该被删除或者忽视)。如果数据没有被你的过滤器修改,那么原始的数据必须返回,这样如果需要的话,随后的数据会继续修改值。

因此,在你的插件上创建一个过滤器的第一步便是创建一个PHP函数来做过滤,并把这个函数放入你的插件文件(而且你的插进文件必须进入wp-content/插件目录)。例如,如果你想确定你的文章和评论没有包含任何亵渎的内容,你可能要用一列禁语定义一个全局变量,然后创建下面的PHP函数:

function filter_profanity($content) {
    global $profanities;
    foreach($profanities as $profanity) {
        $content=str_ireplace($profanity,'{censored}',$content);
    }
    return $content;
}

:牢记其它的插件或者WordPress核心可能已经正在使用你已经想到的函数名。更多的信息请看避免函数名重叠

你的过滤器的Hook

在你的函数得到定义之后,下一步就是将它"hook"或者注册到WordPress。要做到这一点,在你的插件文件的全局执行空间访问add_filter

add_filter('hook_name', 'your_filter', [priority], [accepted_args]);

这儿有:

  • hook_name是一个过滤器hook的名称,由WordPress提供,定义了什么时候应该使用你的过滤器。
  • 你的_过滤器是你想用来过滤的函数名。这可能是一个标准的PHP函数,一个显示在WordPress核心的函数,或者一个你定义在插件文件中的函数。
  • priority是一个随意的整型参数,可以用来规定函数一个特别的过滤器执行的顺序(默认:10)更低的数字符合更早的执行,拥有同样的优先权的函数执行的顺序,是它们添加到过滤器的顺序。
  • accepted_args是一个任意的整型参数,定义你的函数可以接受多少参数(默认1),有用,因为有的hooks可以通过不止一个参数到你的函数上。

在上述的例子中,我们会将以下的内容放到插件文件的主要执行区域,指示WordPress为防止亵渎,而过滤评论:

add_filter('comment_text','filter_profanity');

你也可以使用WordPress函数remove_filter()将过滤器从过滤器hooks中移除。请看看移除 Actions 和过滤器

安装和激活

使你的过滤器hook运行的最后一步便是安装文件并且激活插件。你写的PHP函数和add_filter调用必须一同地进入一个PHP文件,而且PHP文件必须安装在wp-content/plugins目录。一旦这个文件安装了,你就要访问WordPress的管理部分并且激活你的插件;更多的信息请看看管理你的插件

过滤器的当前的Hooks

请看WordPress:Plugin API/过滤器参考中WordPress当前过滤器hooks的列表,和链接到先前版本WordPress的链接。

例子

这是一个例子,如Ozh 在 wp-hackers电子邮件列表上所描述的

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 和过滤器

有的情况下,你可能发现你想要你的插件取消WordPress建的其中的一个actions或者过滤器,或者添加另一个插件。通过访问remove_filter('filter_hook','filter_function') 或者remove_action('action_hook','action_function'),你便可以做到这一点。

例如,remove_action('publish_post','generic_ping');会防止你的博客在产生一篇新的文章的时候,发送pings。

注意如果一个hook已经注册了,使用一个优先而不是默认的10,那么你也必须规定命令中的优先为remove_action()。同时注意,一般情况下,你不应该移除任何东西,除非你知道你移除的东西是执行什么的以及它为什么会执行—查看WordPress或者其它插件的源代码以得到确切答案。

默认使用的过滤器和Actions

找到WordPress默认使用的过滤器和actions的最可靠的方法便是在WordPress核心文件中搜索add_filteradd_action

WordPress 2.1

在WordPress2.1中,大多数的默认的过滤器和actions都是从文件wp-includes/default-filters.php上添加的。一些其它的是在以下的这些文件中:

  • wp-admin/admin-ajax.php
  • wp-admin/admin-functions.php
  • wp-admin/custom-header.php
  • wp-admin/edit.php
  • wp-admin/index.php
  • wp-admin/options-permalink.php
  • wp-admin/upload-functions.php
  • wp-admin/upload.php
  • wp-includes/bookmark.php
  • wp-includes/general-template.php
  • wp-includes/kses.php
  • wp-includes/plugin.php
  • wp-includes/rewrite.php
  • wp-includes/template-loader.php
  • wp-includes/theme.php

大多数默认的过滤器和actions都添加在WordPress1.5中的wp-includes/default-filters.php中。


你可以搞定的函数

除了以上所描述的hooks(actions和过滤器),一个插件修改WordPress的执行的另一种方法就是搞定WordPress函数。事实上,有一些函数WordPress打算让插件来重新定义。只有所有的插件都载入后,这些函数还都没有定义的情况下,WordPress才会载入这些,来利用这个。

这些函数定义在文件wp-includes/pluggable.php中。这里有一个列表(目前是2.1版本的);其中的一些文件可以在函数参考中找到:

  • set_current_user
  • wp_set_current_user
  • wp_get_current_user
  • get_currentuserinfo
  • get_userdata
  • update_user_cache
  • get_userdatabylogin
  • wp_mail
  • wp_login
  • is_user_logged_in
  • auth_redirect
  • check_admin_referer
  • wp_redirect
  • wp_get_cookie_login
  • wp_setcookie
  • wp_clearcookie
  • wp_notify_postauthor
  • wp_notify_moderator
  • wp_new_user_notification
  • wp_verify_nonce
  • wp_create_nonce
  • wp_salt
  • wp_hash

留言