動作鉤子 ( actions )
- 動作鉤子讓你可以在 WordPress 加載過程中或者當某個事件發(fā)生的特定時刻觸發(fā)一個函數(shù)。例如：你可能希望當 WordPress 第一次加載一個頁面或者保存一篇文章時執(zhí)行一個函數(shù)。
do_action() 函數(shù)。
當鉤進 WordPress 中時，你的插件不會直接調(diào)用這個函數(shù)；但是你的插件幾乎都會間接的使用它。
<?php
do_action( $tag, $arg = '' );
?>
- $tag — 動作鉤子的名稱
- $arg — 傳遞給已注冊的動作的值。動作鉤子可以傳遞任何個數(shù)的參數(shù)，或者根本不傳參數(shù)。
下面是一個具有多參數(shù)的動作鉤子的例子
<?php
do_action( $tag, $arg_1, $arg_2, $arg_3 );
?>
例子：
<?php
do_action('wp_head');
?>
- wp_head 的鉤子現(xiàn)在前臺的 <head> 里面。 WordPress 和插件經(jīng)常用這個鉤子來添加 meta 信息，樣式表，和 js 腳本。
例子：
<?php
do_action( 'save_post', $post_ID, $post );
?>
- 這個 save_post 的鉤子傳遞兩個參數(shù)，一個 $post_ID，一個 $post。
add_action() 函數(shù)
<?php
add_action( $tag, $function, $priority, $accepted_args );
?>
- $tag – 你的函數(shù)執(zhí)行時代動作鉤子的名稱。
- $function – WordPress 要調(diào)用的函數(shù)名。
- $priority – 一個表示動作調(diào)用順序的整數(shù)，默認是10。數(shù)字越小，這個函數(shù)越早被調(diào)用。
- $accepted_args – 動作鉤子要傳遞給你的函數(shù)的參數(shù)個數(shù)。默認只有一個參數(shù)。
動作鉤子并不局限于單個動作。你的插件可以將多個函數(shù)添加到一個動作鉤子上。其他插件，甚至是 WordPress 核心，經(jīng)常將多個函數(shù)添加到同一個鉤子上。
- 常見的動作鉤子是 wp_footer 。它提供給前端用戶的 WordPress 模板使用。通常它剛好在</body>前調(diào)用。在下面的例子中，將要為 wp_footer 注冊一個動作并添加一條自定義信息到 footer。
<?php
add_action( 'wp_footer', 'boj_example_footer_message', 100 );
function boj_example_footer_message() {
echo "基于 <a >WordPress </a>架設(shè)。;
}
?>
第一個參數(shù)是鉤子的名字( wp_footer )。第二個參數(shù)是要回調(diào)的函數(shù) ( boj_example_footer_message )。第三個參數(shù)是優(yōu)先級 ( 100 )。這個函數(shù)比起其他鉤到 wp_footer 中的函數(shù)，會在比較靠后的次序執(zhí)行。如果設(shè)置成1，就較先執(zhí)行。
鉤子可能會因為許多原因在 WordPress 執(zhí)行過程中多次觸發(fā)。任何添加到這個鉤子中的動作每當鉤子觸發(fā)時都會執(zhí)行一次。
<?php
do_action_ref_arrray( $tag, $args );
?>
- $tag – 動作鉤子的名字。
- $args – 要傳遞給注冊到這個鉤子的函數(shù)的參數(shù)的數(shù)組。通常，這是一個動作可以改變的對象。
下面看一個 WordPress 如何調(diào)用 do_action_ref_array() 的實例。下面的代碼展示了 pre_get_posts 動作鉤子。WordPress 在從數(shù)據(jù)庫取得 posts 之前執(zhí)行這個鉤子，使得插件可以改變查詢 posts 的方式。
<?php
do_action_ref_array( 'pre_get_posts', array( & $this ) );
?>
- 第一個參數(shù) pre_get_posts 是鉤子的名字。第二個參數(shù)是從數(shù)據(jù)庫中查詢 posts 的參數(shù)的數(shù)組。這個鉤子使你可以執(zhí)行基于那個參數(shù)數(shù)組的代碼。
假如你想安裝隨機的順序來得到首頁的 blog，而不是默認的通過發(fā)布時間來得到。你就需要注冊一個動作到這個鉤子，并改變排序順序。
<?php
add_action( 'pre_get_posts', 'boj_randomly_order_blog_posts' );
function boj_randomly_order_blog_posts( $query ) {
if( $query -> is_home && empty( $query -> query_vars['suppress_filters']))
$query -> set( 'rderby', 'rand' );
}
?>
remove_action 函數(shù)
- remove_action() 可以刪除先前添加到一個鉤子的動作。如果動作被成功刪除，則函數(shù)返回 true，否則返回 false。
<?php
remove_action( $tag, $function_to_remove, $priority, $accepted_args );
?>
- 參數(shù)類似于 do_action()。要成功的從一個鉤子中刪除一個動作， $tag, $function_to_remove, 和 $priority 必須完全的復(fù)合 do_action() 中使用的參數(shù)。否則動作不會被溢出，同時 remove_action() 返回 flase。
remove_all_actions
- 在有些插件中，可能需要刪除所有特定 tag 或者 特定 tag + 特定優(yōu)先級的所有鉤子。使用 remove_all_actions() 可以一次刪除所有符合條件的動作。
<?php
remove_all_actions( $tag, $priority );
?>
- $priority 參數(shù)是可選的，默認是 false。如果你設(shè)置了這個參數(shù)，那么只有這個優(yōu)先級的動作會被刪除。下面的例子從 wp_head 動作鉤子中刪除不管任何優(yōu)先級的動作。
<?php
remove_all_actions( 'wp_head' );
?>
- 在使用這個函數(shù)的時候必須要小心。其他 plugin 或者 theme 可能添加了你不知道動作。這就可能破壞插件應(yīng)有的功能。通常應(yīng)該保持你的代碼盡可能的特殊。在大多數(shù)情況下，你應(yīng)該使用 remove_action() 函數(shù)來代替。
as_action
- 有的時候需要確定一個鉤子是否包含一些動作，或者一個特定的動作是否已經(jīng)添加到了鉤子里面。has_action() 提供了這些功能。
<?php
has_action( $tag, $function_to_check );
?>
- has_action() 函數(shù)的返回值是 Boolean 或者 一個整型值。如果 $function_to_check 參數(shù)為空，那么如果有動作已經(jīng)添加到了鉤子中就返回 true，反之，返回 false。而如果 $function_to_check 設(shè)置了，而且這個函數(shù)已經(jīng)添加到了鉤子里面，則返回該動作的優(yōu)先級，否則返回 false。
下面的例子中，根據(jù) wp_footer 動作鉤子中是否有注冊的動作來確定顯示的信息。
<?php
if( has_action( 'wp_footer' ) )
echo '<p> footer 中已經(jīng)注冊有動作了。</p>';
else
echo '<p> footer 中還沒有注冊動作。</p>';
?>
- 下面看一個 WordPress 核心添加到 wp_footer 中的動作。wp_print_footer_script() 默認注冊給這個鉤子。
<?php
add_action( 'wp_footer', 'wp_print_footer_scripts' );
?>
did_action
- did_action() 使你的插件可以檢查一個動作鉤子是否已經(jīng)被執(zhí)行，或者記錄執(zhí)行的次數(shù)。這也意味著這一次頁面的加載過程中有些動作被執(zhí)行了多次。
<?php
did_action( $tag );
?>
- 這個參數(shù)返回動作已經(jīng)執(zhí)行的次數(shù)，如果還未執(zhí)行，返回 false。這個函數(shù)的一般用途是判斷一個動作鉤子是否已經(jīng)被觸發(fā)，并執(zhí)行基于 did_action() 的返回值的代碼。
下面的例子中，如果 plugins_loaded 動作鉤子已經(jīng)被觸發(fā)，就定義一個 PHP 常量。
<?php
if ( did_action( 'plugins_loaded' ) )
define( 'BOJ_MYPLUGIN_READY' ,true );
?>
register_activation_hook 和 register_deactivation_hook
常用的動作鉤子
plugins_loaded
它在大多數(shù) WordPress 文件加載完成之后，并在pluggable 函數(shù)和 WordPress 開始執(zhí)行任何東西之前觸發(fā)。在大多數(shù)的插件中，在這個鉤子觸發(fā)之前，不應(yīng)該執(zhí)行其他的代碼。
plugins_loaded 在所有用戶啟用的插件都被 WordPress 加載之后執(zhí)行。
這也是在加載過程中插件開發(fā)這最早能用到的鉤子。WordPress 的插件應(yīng)該在這個鉤子中執(zhí)行安裝。其他動作也應(yīng)該添加到這個鉤子的回調(diào)函數(shù)中。
下面的例子中，使用boj_example_footer_message 動作。
要把它添加到鉤到 plugins_loaded 鉤子中的安裝動作中，而不是單獨調(diào)用它。
<?php
add_action( 'plugins_loaded', 'boj_footer_message_plugin_setup' );
function boj_footer_message_plugin_setup() {
/* 添加 footer 信息動作 */
add_action( 'wp_footer', 'boj_example_footer_message', 100 );
}
function boj_example_footer_message() {
echo "基于 <a >WordPress </a>架設(shè)。;
}
?>
- 創(chuàng)建一個安裝函數(shù)并把它鉤到 plugins_loaded 中。這樣做就可以確保不會由于特定的 WordPress 函數(shù)還沒有加載而觸發(fā)錯誤。
init
init 鉤子在大多數(shù)的 WordPress 都建立之后。WordPress 同樣添加許多內(nèi)部的功能到這個鉤子中，例如 post types 和 taxonomies 的廚廁以及默認 widgets 的初始化。
因為這時幾乎 WordPress 中的所有內(nèi)容都就緒了，當 WordPress 的所有信息都可用時，你的插件使用這個鉤子差不多可以做任何需要的事情了。
下面的例子中，為用戶添加了給 pages 寫摘要的功能。這應(yīng)該在 init 中執(zhí)行，因為 “page” post type 在這時使用 add_post_type_support() 函數(shù)來創(chuàng)建。
<?php
add_action( 'init', 'boj_add_excerpts_to_pages' );
function boj_add_excerpts_to_pages() {
add_post_type_support( 'page', array( 'excerpt' ) );
}
?>
admin_menu
admin_menu 鉤子在管理員頁面加載的時候調(diào)用。無論何時你的插件直接在管理頁面下工作，你都要用這個鉤子來執(zhí)行你的代碼。
下面的例子添加了一個內(nèi)容是 BOJ Settings 的 sub-menu 項到 WordPress 管理頁面的設(shè)置菜單。(詳見：Part-7，”插件設(shè)置”)
<?php
add_action( 'admin_menu', 'boj_admin_settings_page' );
function boj_admin_settings_page() {
add_options_page(
'BOJ Settings',
'BOJ Settings',
'manage_options',
'boj_admin_settings',
'boj_admin_settings_page'
);
}
?>
template_redirect
template_redirect 動作鉤子很有用，因為它是 WordPress 知道用戶正在瀏覽的頁面的關(guān)鍵。它在特定的頁面選擇 theme template 之前執(zhí)行。在只在網(wǎng)站的前端觸發(fā)，并不在管理員頁面觸發(fā)。
當你需要為特定的頁面加載代碼的時候，這個鉤子很有用。
下面的例子中，僅僅為 singular post 加載一個樣式表文件。
<?php
add_action( 'template_redirect', 'boj_singular_post_css' );
function boj_singular_post_css() {
if( is_singular( 'post' ) ) {
wp_enqueue_style (
'boj-singular-post',
'boj-example.css',
false,
0.1,
'screen'
);
}
}
?>
wp_head
- 在網(wǎng)站的前端，WordPress 的模板調(diào)用 wp_head() 函數(shù)，會觸發(fā) wp_head 鉤子。插件使用這個鉤子在 <head> 和 </head> 標簽之間添加 HTML。
下面的例子中在前端添加一個 meta description。
<?php
add_action( 'wp_head', 'boj_front_page_meta_description' );
function boj_front_page_meta_description() {
/* 得到站點描述 */
$description = esc_attr( get_bloginfo( 'description' ) );
/* 如果 description 設(shè)置了，顯示 meta 元素 */
if ( !empty( $description ) )
echo '<meta name="description" content="'. $description. '"/>';
}
?>
有些插件錯誤的使用了 wp_head 動作鉤子來添加 JavaScript 代碼，實際上應(yīng)該使用 wp_enqueue_script() 函數(shù)的。( 詳見：Part-12，”JavaScript 和 AJAX “)。唯一一種使用這個鉤子來添加 JavaScript 的情形是當 JavaScript 代碼不在一個單獨的文件中時。
