iT邦幫忙

2023 iThome 鐵人賽

DAY 26
1
WordPress

從 0 到 100:WordPress 開發者的實戰手冊系列 第 26

Day 26 - 外掛設計實戰 (2) 建立選單入口與設定頁面

  • 分享至 

  • xImage
  •  

一般來說,很少有不需要設定頁面的外掛,除非專門為了微調一些核心設定的外掛,例如只是利用過濾器去改變 WordPress 核心預設值的那種小外掛,使用者知道一啟用就會有作用。

然而,大部分的外掛還是需要提供設定頁面,讓使用者可以選擇他們想要啟用的功能,而外掛開發者也可以在設定頁面上,提供關於更多關於此外掛的資訊。

設定選單位置

後台控制台頁面
圖:後台控制台頁面

最上層選單

當我們一進去後台時,可以在側邊欄的導覽選單看到選單,可以稱為「最上層」選單。我們可以使用 add_menu_page 函式增加一個最上層選單,接著使用 add_submenu_page 函式在最上層選單下加入子選單。

這兩個函式是一般提供非常多客製化設定的外掛會使用的函式。

WP Shieldon 外掛設定選單
圖: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

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

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 範例程式碼
圖: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

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 範例程式碼
圖:add_options_page 範例程式碼 Gist

第 5 行:頁面的標題 (瀏覽器頁籤的 title)
第 6 行:位於選單上的文字
第 8 行:適用的權限。固定使用 manage_options
第 9 行:選單頁面的 slug。
第 10 行:渲染設定頁面的 HTML 用的回呼函式。
第 23 行:固定使用 admin_menu 鉤點來註冊此函式。

結果:

子選單位於設定下
動圖:子選單位於設定下

總結

今天主要介紹三個用來建立選單入口及設定頁面的 WordPress 核心函式,在函式列表中的其它函式用法也大同小異。我們可以視自己外掛特性,用專為不同上層選單設計子選單的函式,來作為設定頁面的入口。


課後思考:

在本篇文章的函式一覽中,有其它函式可以將設定頁面加入特定的最上層選單中,如果我們新增了一個新的文章類型「商品」(product),要如何將設定頁面選單加入該文章類型底下呢?

前篇解答參考:

在啟用外掛時,可以提示訊息引導使用者進行設定、或者邀請使用者上網給予評價,這兩種蠻常見的。另外在停用外掛時。也可以邀請使用者填寫問券,詢問使用者為什麼停用,以做為改進的參考。


上一篇
Day 25 - 外掛設計實戰 (1) 初始化並啟用外掛
下一篇
Day 27 - 外掛設計實戰 (3) 使用 Settings API 製作設定頁面
系列文
從 0 到 100:WordPress 開發者的實戰手冊30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言