一般來說,很少有不需要設定頁面的外掛,除非專門為了微調一些核心設定的外掛,例如只是利用過濾器去改變 WordPress 核心預設值的那種小外掛,使用者知道一啟用就會有作用。
然而,大部分的外掛還是需要提供設定頁面,讓使用者可以選擇他們想要啟用的功能,而外掛開發者也可以在設定頁面上,提供關於更多關於此外掛的資訊。
圖:後台控制台頁面
當我們一進去後台時,可以在側邊欄的導覽選單看到選單,可以稱為「最上層」選單。我們可以使用 add_menu_page 函式增加一個最上層選單,接著使用 add_submenu_page 函式在最上層選單下加入子選單。
這兩個函式是一般提供非常多客製化設定的外掛會使用的函式。
圖:WP Shieldon 外掛設定選單
例如筆者設計的 WP Shieldon 外掛和 Cache Master 外掛,都是採用這樣的方式。
另外比較常用的是 add_options_page 函式,它是在名為「設定」的最上層選單下加入子選單連結,有的外掛開發者會採用這個函式,只提供一個設定連結入口。
未來當設定的欄位變多時,可以在設定頁面上採用頁籤的方式來擴充提供設定的頁面。
除了剛剛提到的函式以外,在後台管理的側邊欄看的到的最上層選單都可以加入子選單。以下為函式的一覽表及它們的使用位置。
函式名稱 | 說明 | 使用位置 |
---|---|---|
add_menu_page | 新增一個最上層選單頁面 | 管理員側邊欄 |
add_submenu_page | 在最上層選單下新增子選單 | 最上層選單指定的位置 |
add_options_page | 在設定選單下新增子選單 | 設定選單 |
add_dashboard_page | 在儀表板下新增子選單 | 儀表板選單 |
add_posts_page | 在文章選單下新增子選單 | 文章選單 |
add_media_page | 在媒體選單下新增子選單 | 媒體選單 |
add_pages_page | 在頁面選單下新增子選單 | 頁面選單 |
add_comments_page | 在留言選單下新增子選單 | 留言選單 |
add_theme_page | 在外觀選單下新增子選單 | 外觀選單 |
add_plugins_page | 在外掛選單下新增子選單 | 外掛選單 |
add_users_page | 在使用者選單下新增子選單 | 使用者選單 |
add_management_page | 在工具選單下新增子選單 | 工具選單 |
通常我們只會考慮把設定頁面的入口做在最上層選單並搭配數個子選單,並以功能性質切分設定頁面,這會用到 add_menu_page 和 add_submenu_page 函式。
比較少的設定,則把設定頁面的入建立在「設定「選單」底下。這會用到 add_options_page 函式。
筆者就以上三個函式做示範說明。
add_menu_page($page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position);
參數說明:
$page_title
: (string) (必需) 瀏覽器標題欄中要顯示的文本。$menu_title
: (string) (必需) WordPress 選單中要顯示的文本。$capability
: (string) (必需) 決定誰能夠訪問此選單的權限。$menu_slug
: (string) (必需) 選單的 slug,用於識別這個選單頁面,並且必須是唯一值。$function
: (callable) (可選) 用於顯示頁面內容的回呼函式。$icon_url
: (string) (可選) 選單圖示的 URL 或者是用於或字型圖示的 dashicon class 字串。例如 dashicons-admin-tools
。$position
: (int) (可選) 選單項目在管理界面中的順序位置。add_submenu_page($parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function);
參數說明:
$parent_slug
: (string) (必需) 上級選單頁面的 slug,用於將此子選單和父級選單建立關聯。$page_title
: (string) (必需) 在瀏覽器標題列中將要顯示的文本。$menu_title
: (string) (必需) 在選單上將要顯示的文本。$capability
: (string) (必需) 決定誰能夠訪問此選單的權限。$menu_slug
: (string) (必需) 選單的 slug,用於識別這個選單頁面,並且必須是唯一值。$function
: (callable) (可選) 用於顯示頁面內容的回呼函式。綜合範例:
圖:add_menu_page、add_submanu_page 範例程式碼 Gist
第 6 行:頁面的標題 (瀏覽器頁籤的 title)
第 7 行:位於選單上的文字
第 8 行:適用的權限。固定使用 manage_options
。
第 9 行:選單頁面的 slug。
第 10 行:渲染設定頁面的 HTML 用的回呼函式。
第 14 行:最上層選單的 slug,用來建立關聯。
第 15 行:頁面的標題 (瀏覽器頁籤的 title)
第 16 行:位於選單上的文字
第 17 行:適用的權限。固定使用 manage_options
。
第 18 行:選單頁面的 slug。
第 19 行:渲染設定頁面的 HTML 用的回呼函式。
第 39 行:固定使用 admin_menu
鉤點來註冊此函式。
結果:
動圖:最上層選單位於設定下
add_options_page($page_title, $menu_title, $capability, $menu_slug, $function);
參數說明:
$page_title
: (string) (必需) 在瀏覽器標題列中將要顯示的文本。$menu_title
: (string) (必需) 在選單上將要顯示的文字。$capability
: (string) (必需) 用於控制誰能夠訪問此選單頁面的權限。$menu_slug
: (string) (必需) 選單的 slug,用於識別這個子選單頁面,並且必須是唯一值。$function
: (callable) (可選) 用於渲染選單頁面的回呼函式。範例:
圖:add_options_page 範例程式碼 Gist
第 5 行:頁面的標題 (瀏覽器頁籤的 title)
第 6 行:位於選單上的文字
第 8 行:適用的權限。固定使用 manage_options
。
第 9 行:選單頁面的 slug。
第 10 行:渲染設定頁面的 HTML 用的回呼函式。
第 23 行:固定使用 admin_menu
鉤點來註冊此函式。
結果:
動圖:子選單位於設定下
今天主要介紹三個用來建立選單入口及設定頁面的 WordPress 核心函式,在函式列表中的其它函式用法也大同小異。我們可以視自己外掛特性,用專為不同上層選單設計子選單的函式,來作為設定頁面的入口。
課後思考:
在本篇文章的函式一覽中,有其它函式可以將設定頁面加入特定的最上層選單中,如果我們新增了一個新的文章類型「商品」(product),要如何將設定頁面選單加入該文章類型底下呢?
前篇解答參考:
在啟用外掛時,可以提示訊息引導使用者進行設定、或者邀請使用者上網給予評價,這兩種蠻常見的。另外在停用外掛時。也可以邀請使用者填寫問券,詢問使用者為什麼停用,以做為改進的參考。