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

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

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

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

客製「說明」頁面

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

[code]
add_filter(‘contextual_help’, ‘custom_help’, 10, 3);
function custom_help($contextual_help, $screen_id, $screen)
{
$contextual_help = ‘您好，歡迎使用WP!’;
return $contextual_help;
}
[/code]

先來個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：

[code]
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’);
}
[/code]
接下來，我們回頭調整一下客製說明頁程式：
[code]
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;
}
[/code]
如此就能成功客製說明頁面囉! 至於內建的管理頁面，您可以透過輸出$screen_id來判斷該頁面的id為何，例如我們在不是自訂頁面的情況下，就在說明內容的最後一行輸出$screen_id的內容：
[code]
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;
}
[/code]
如此就能針對內建頁面進行客製說明頁的內容了。

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

客製「顯示選項」頁面

我們只要利用screen_settings這個filter就能客製顯示選項頁面了：
[code]
add_filter(‘screen_settings’, ‘screen_options_demo’, 10, 2);
function screen_options_demo($current, $screen)
{
$current .= ‘<b>此頁的screen id為：’.$screen->id.'</b>’;

return $current;
}
[/code]
您可以看到，這個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

標籤：WordPress, 網站設計

分類：WordPress, 網站設計

本文作者是Audi Lu