如何客製WordPress後台的「說明」(Contextual Help)頁面與「顯示選項」(Screen Options)頁面?


作者: | 2011/02/27 18:06:54 | 2 則迴響


登入WP後台時,可以發現畫面的右上角有兩個標籤連結,分別是「顯示選項」及「說明」。按下這兩個連結,都會拉出一個小畫面,分別顯示與此頁面相關的控制選項及說明頁面。本篇文章先介紹其中的「說明」頁面該如何客製,而顯示選項(Screen Options)頁面的客製方式其實也差不多。

為什麼要客製「說明」和「顯示選項」頁面?

為什麼您可能需要去客製「說明」頁面呢?也許是因為您製作了新的外掛(Plugin),而您的外掛在後台提供了操作頁面,這時如果您希望使用者在進行設定時能獲得更詳細的說明時,您就需要去客製說明頁面。也有可能您不希望客戶看到預設的說明頁內容,您當然也可以把預設的內容「隱藏」起來。同樣的,如果有一些進階選項,您也可以放在顯示選項頁面裡。

客製「說明」頁面

要客製說明頁面,只要增加一個contextual_help的filter就可以了:



add_filter('contextual_help', 'custom_help', 10, 3);
function custom_help($contextual_help, $screen_id, $screen)
{
$contextual_help = '您好,歡迎使用WP!';
return $contextual_help;
}

先來個add_filter()的參數說明:

  1. add_filter的第一個參數是指我們要hook的function名稱,是wp提供給我們的。
  2. 第二個參數是我們自訂的hook function,名稱是自訂的,隨後我們就會把希望做的事寫進這個hook function中。
  3. 第三個參數值在此設為10,這是執行的優先順序(priority),預設是10,數值愈小表示愈早執行。
  4. 第四個參數值是3,這表示hook function的參數個數,共有三個,因為contextual_help function的規格就是需要三個參數,所以在此我們必須設定為3。

您可以把上述程式碼貼進您目前使用的佈景目錄下的functions.php (如果沒這個檔,自行新增就可以了),記得要放在<?php 和 ?> 之間。貼完後存檔,您可以發現,這時所有頁面的「說明」頁內容,全部變成「您好,歡迎使用WP!」了。 目前我們已經可以更改說明頁的內容,但還不夠好,因為我們想要針對某個頁面,去做內容的客製,所以我們需要利用 $screen_id 這個參數。

針對特定後台的頁面作客製

當我們自己新增自訂的後台頁面時,我們通常會利用一些名字看起來像add page的hook,例如:一般的頁面我們用add_menu_page,add_submenu_page來增加主選單及子選單頁面,如果是新增管理頁面,我們會用add_dashboard_page(控制台頁面),add_options_page(設定頁面)…等來增加選單頁面。 而當我們使用這些hook時,它其實就會回傳屬於此頁面的 hook id,而這個hook id就能拿來對應到 $screen_id 這個參數,以識別是否為此頁。

舉例說明,我們新增一個自訂的頁面放在「設定」裡,但我們要利用一個global變數存放它的hook id:


add_action('admin_menu', 'my_plugin_menu');
function my_plugin_menu()
{
global $my_plugin_hook;
$my_plugin_hook = add_options_page('MyPlugin Opts', 'MyPlugin', 'mag_opts', 'my-uniq-idr', 'my_plugin_opts');
}

接下來,我們回頭調整一下客製說明頁程式:

add_filter('contextual_help', 'custom_help', 10, 3);
function custom_help($contextual_help, $screen_id, $screen)
{
global $my_plugin_hook;
// 判斷若目前畫面的screen_id是我們的plugin hook id,就顯示對應的說明內容
if ($screen_id == $my_plugin_hook)
{
$contextual_help = '您好,歡迎使用My Plugin!';
}
return $contextual_help;
}

如此就能成功客製說明頁面囉! 至於內建的管理頁面,您可以透過輸出$screen_id來判斷該頁面的id為何,例如我們在不是自訂頁面的情況下,就在說明內容的最後一行輸出$screen_id的內容:

add_filter('contextual_help', 'custom_help', 10, 3);
function custom_help($contextual_help, $screen_id, $screen)
{
global $my_plugin_hook;
// 判斷若目前畫面的screen_id是我們的plugin hook id,就顯示對應的說明內容
if ($screen_id == $my_plugin_hook)
{
$contextual_help = '您好,歡迎使用My Plugin!';
}
else
{
$contextual_help .= '<h3>您好,目前頁面的screen_id為:'.$screen_id.'</h3>';
}
return $contextual_help;
}

如此就能針對內建頁面進行客製說明頁的內容了。

耶?我們好像還漏了一個參數沒有介紹,就是$screen。不過,我們先來看看客製「顯示選項」頁面的方式。

客製「顯示選項」頁面

我們只要利用screen_settings這個filter就能客製顯示選項頁面了:


add_filter('screen_settings', 'screen_options_demo', 10, 2);
function screen_options_demo($current, $screen)
{
$current .= '<b>此頁的screen id為:'.$screen->id.'</b>';

return $current;
}


您可以看到,這個filter的hook function也有一個$screen的參數,您可以用print_r($screen)來觀察$screen這個物件的內容,您會發現$screen_id和$screen->id的內容是一樣的,所以它跟說明頁面的客製方式其實非常相似。

使用print_r,我們還能看到$screen->action,$screen->parent_file…等其他設定值也會一併傳入,似乎是用來作POST資料之用,若有機會我們再深入介紹!

參考資料: http://codex.wordpress.org/Adding_Contextual_Help_to_Administration_Menus


標籤:,

分類:,

本文作者是Audi Lu

2 則留言

發佈回覆給「匿名訪客」的留言 取消回覆

發佈留言必須填寫的電子郵件地址不會公開。

*

*

*

這個網站採用 Akismet 服務減少垃圾留言。進一步瞭解 Akismet 如何處理網站訪客的留言資料