Wordpress/外掛:修訂版本之間的差異

出自福留子孫
跳轉到: 導覽搜尋
外掛鉤子
外掛鉤子
 
第 52 行: 第 52 行:
 
*[http://codex.wordpress.org/Plugin_API/Filter_Reference Filter列表]
 
*[http://codex.wordpress.org/Plugin_API/Filter_Reference Filter列表]
 
*#sanitize_user:清理、過濾帳號
 
*#sanitize_user:清理、過濾帳號
 +
====add_action()的進一步說明====
 +
描述:在一個action上掛載(掛鉤機制)一個函數。
 +
 +
函數原型:add_action ( '動作名', '響應函數名', [優先級], [參數數目] );
 +
 +
參數說明:
 +
 +
(一)動作名: WordPress所提供的動作名,用於標識在哪個動作發生時,執行響應函數。相應函數名:當動作 hook_name 發生時需要執行的響應函數的名字。可以是 PHP 標準的函數,或者是 WordPress 內的函數,或者是插件內自定義的函數。
 +
 +
動作 (Actions) 是由 WordPress 內部的某些事件所觸發的,比如說發表一篇文章、更換主題或者訪問後台的某個管理界面,這些都是一件事件的例子。而插件則可以指定某些 PHP 函數來響應這些事件所觸發的動作。例如:
 +
#修改數據庫數據
 +
#發送電子郵件
 +
#修改即將顯示出來的內容
 +
#使用動作來掛載插件的基本步驟如下:
 +
#在插件代碼中定義當某個事件發生時,需要執行的 PHP 函數
 +
 +
用add_action() 把這個函數註冊到動作執行掛勾上,把插件源碼放到 WordPress 指定的地方,然後啟用它
 +
 +
(二)定義動作響應函數:要在插件中執行動作,就要先在插件文件(必須放到wp-content/plugins下)中定義一個響應動作的 PHP 函數。比如下面的例子,實現的功能是在新文章發佈時,通過電子郵件通知好友。
 +
 +
<pre>$friends = 'bob@example.org,susie@example.org'; 
 +
    mail($friends, "sally's blog updated", 
 +
      'I just put something on my blog: http://blog.example.com'); 
 +
    return $post_ID;</pre>
 +
 +
可以把函數掛載到系統中:add_action ( 'publish_post', 'email_friends' );
 +
 +
(三)優先級:這是一個可選的參數,預設值為10。由於可以把多個函數註冊到同一個動作,所以這個參於是用於指定註冊到這個動作中的這個函數執行的優先級,數字越小優先 級越高,執行得也越早,反之亦然。如果若干個函數以相同的優先級註冊到同一個動作,那麼執行順序則是由它們註冊的先後順序所決定。
 +
 +
(四)參數數目:這是一個可選的參數,預設值是1。由於某些動作可能會把多個參數傳給響應函數,所以這個有時候需要指定響應函數能接受多少個參數。這個參數是在 1.5.1 版加進去的。這個函數類似於Qt中的信號槽機制。
  
 
===模版標籤===
 
===模版標籤===

2016年8月28日 (日) 21:29的最新修訂版本

概述

  • 位置在/wp-content/plugins/之下
  • 主要是php,不可兩插件同名
  • 附屬Javascript、CSS、圖照、語言檔等。
  • 如包含多個檔案,你還需要建立一個資料夾,並把外掛包含的所有檔案放到這個資料夾中,這樣你只要把整個資料夾放到wp-content/plugins/目錄下就可以了。資料夾夾的名稱通常和PHP的名稱相同,例如PHP的名稱叫做functionality.php的話,資料夾的名稱就可以叫做functionality。
  • 由於在WordPress中可以配置wp-content/plugins/目錄的位置,所以你必須使用plugin_dir_path()和plugins_url()兩個函數來獲取外掛的路徑。
  • 如果你想將你的插件發佈到http://wordpress.org/extend/plugins/
    1. 你必須在插件包中建立一個標準格式的readme.txt文件. 文件格式參見http://wordpress.org/extend/plugins/about/readme.txt.
    2. 你可以訪問http://wordpress.org/extend/plugins/about/readme.txt 查看如何去格式化自述文件,或者訪問http://generatewp.com/plugin-readme/ 來使用文檔自動生成器
    3. WordPress是通過自述文件來判斷這個插件是處於「必要」還是「測試」狀態的。

文件頭

至少要包括外掛名稱,這樣WordPress才能識別你的外掛。其他信息將顯示在控制面板外掛管理頁面中。標準外掛信息對各行順序沒有要求。
<?php
/*
Plugin Name: 外掛名稱
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: 外掛的簡單描述
Version: 外掛版本號, 例如: 1.0
Author: 外掛作者
Author URI: http://URI_Of_The_Plugin_Author作者地址
License:     GPL2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Domain Path: /languages
Text Domain: my-toolset
*/
?>

版權信息:略

外掛鉤子

WP action&filter.png

在WordPress運行期間,有許多特定的時間點,WordPress會在這些時間點檢測相應的外掛鉤子,如果檢測到有函數與當前的外掛鉤子相關聯的話,就會運行這些函數。正是這些函數改變了WordPress的預設功能。

外掛鉤子主要分成兩類,其作用方式如上圖:

  1. filter(過濾器類型的鉤子),WP核心期待有回傳值(return),讓WP核心利用你回傳的值來接著完成它該做的事。用 apply_filters('hook_name'[,參數1,參數2,參數3,…]) 產生 filter 鉤子。
  2. action(動作類型的鉤子),WP核心並不期待有回傳值。以 do_action ('hook_name'[,參數1,參數2,參數3,…]) 產生 action 鉤子。

例如,當WordPress在發表一篇文章之前,會首先檢測一個名為"the_title"的外掛鉤子(過濾器類型的鉤子),如果此時有任何外掛的函數與這個鉤子相關聯的話,那麼文章的標題就會首先被這些函數依次進行處理,最後再把函數處理的結果顯示到屏幕上。所以,如果你的外掛想要對文章的標題進行處理的話,就需要將對應的處理函數註冊到名為"the_title"的過濾器鉤子上。

再舉個例子,在WordPress即將生成</HTML>標籤之前,會檢測一個名為"wp_footer"的外掛鉤子(動作類型的鉤子),如果此時有外掛的函數與這個鉤子相關聯的話,那麼WordPress就會先依次執行這些函數,然後再繼續生成</HTML>標籤。

所以撰寫外掛其實就是:

  • add_action ( 'hook_name', 'your_function_name', [priority, [accepted_args]] );
  • add_filter ( 'hook_name', 'your_function_name', [priority, [accepted_args]] );

其各個參數的意義解釋如下:

  1. hook_name => 欲嫁接點的 action /filter hook 名稱
  2. your_function_name => 所需要執行的函數名稱
  3. priority => 優先權,預設值為 10,越小的數字越先執行
  4. accepted_args => 你所執行的函數有幾個輸入值(參數),預設為 1。某些 Action (Filter) 提供操過 2 個參數時即可以此設定。

add_action()的進一步說明

描述:在一個action上掛載(掛鉤機制)一個函數。

函數原型:add_action ( '動作名', '響應函數名', [優先級], [參數數目] );

參數說明:

(一)動作名: WordPress所提供的動作名,用於標識在哪個動作發生時,執行響應函數。相應函數名:當動作 hook_name 發生時需要執行的響應函數的名字。可以是 PHP 標準的函數,或者是 WordPress 內的函數,或者是插件內自定義的函數。

動作 (Actions) 是由 WordPress 內部的某些事件所觸發的,比如說發表一篇文章、更換主題或者訪問後台的某個管理界面,這些都是一件事件的例子。而插件則可以指定某些 PHP 函數來響應這些事件所觸發的動作。例如:

  1. 修改數據庫數據
  2. 發送電子郵件
  3. 修改即將顯示出來的內容
  4. 使用動作來掛載插件的基本步驟如下:
  5. 在插件代碼中定義當某個事件發生時,需要執行的 PHP 函數

用add_action() 把這個函數註冊到動作執行掛勾上,把插件源碼放到 WordPress 指定的地方,然後啟用它

(二)定義動作響應函數:要在插件中執行動作,就要先在插件文件(必須放到wp-content/plugins下)中定義一個響應動作的 PHP 函數。比如下面的例子,實現的功能是在新文章發佈時,通過電子郵件通知好友。

$friends = 'bob@example.org,susie@example.org';  
    mail($friends, "sally's blog updated",   
      'I just put something on my blog: http://blog.example.com');  
    return $post_ID;

可以把函數掛載到系統中:add_action ( 'publish_post', 'email_friends' );

(三)優先級:這是一個可選的參數,預設值為10。由於可以把多個函數註冊到同一個動作,所以這個參於是用於指定註冊到這個動作中的這個函數執行的優先級,數字越小優先 級越高,執行得也越早,反之亦然。如果若干個函數以相同的優先級註冊到同一個動作,那麼執行順序則是由它們註冊的先後順序所決定。

(四)參數數目:這是一個可選的參數,預設值是1。由於某些動作可能會把多個參數傳給響應函數,所以這個有時候需要指定響應函數能接受多少個參數。這個參數是在 1.5.1 版加進去的。這個函數類似於Qt中的信號槽機制。

模版標籤

另一個向WordPress中加入外掛的方式就是建立自定義的模板標籤Template Tags。這樣如果有人想要使用你的外掛,就可以把這些標籤添加到他們的主題、側邊欄、文章內容以及任何合適的地方。例如,可以為外掛定義一個名為geotag_list_states()的模板標籤函數,該函數可以為側邊欄的文章添加地理位置標籤,當點擊這個標籤時,還可以打開這個地理位置標籤下所有對應的文章。

要定義一個自定義模板標籤,你只需要寫一個PHP函數,然後把它通過文檔、外掛的主頁或是在PHP主文件中聲明的方式告訴外掛的使用者就可以了。當你為這個函數編寫文檔的時候,如果還能夠提供一個該函數的使用示例,來告訴用戶在主題中應當如何調用這個函數,就再好不過了。

保存外掛數據到資料庫

大多數WordPress外掛都需要獲取管理員或用戶輸入的一些信息,並保存在會話中,以便在過濾器函數(filter)、動作函數(action)和模板函數(template)中使用。若需要在下次會話中繼續使用這些信息,就必須將它們保存到WordPress資料庫中。以下是將外掛數據保存到資料庫的4種方法:

  1. 使用WordPress的"選項"機制(稍後會有介紹)。這種方式適合儲存少量靜態的、具有特定名稱的數據——這類數據通常是網站所有者在創建外掛時設置的一些初始化參數,並且以後很少會進行改動。
  2. 使用文章元數據(又名自定義域)。這種方式適合保存與個人文章、頁面或附件相關的數據。若需要瞭解更多,請參閱post_meta函數示例,以及與add_post_meta()相關的函數。
  3. 使用自定義分類。這種方式適合保存那些需要分門別類存放的數據,如用戶信息、評論內容以及用戶可編輯的數據等,特別適合於當你想要根據某個類型去查看相關的文章和數據的情況。若需要瞭解更多,請參閱Custom Taxonomies。
  4. 創建一個新的,自定義的資料表。這種方式適合保存那些與個人文章、頁面或附件無關的,會隨著時間逐漸增長的,並且沒有特定名稱的數據。關於如何使用,你可以閱讀Creating Tables with Plugins以獲取更多信息。

WordPress 選項機制

參閱Creating Options Pages,你將學會如何去創建一個自動保存選項數據的頁面。

WordPress有一個"選項"機制,用於保存、更新以及檢索那些獨立的,具有特定名稱的數據。選項的值可以是字串、陣列,甚至是PHP物件(當然,PHP物件在保存時必須能夠被序列化或轉換成字串,檢索的時候也必須能夠被反序列化)。選項的名稱必須是字串,且必須是唯一的,這樣才能夠確保它們不會和WoredPress或其它外掛產生衝突。

通常情況下,你最好能夠對外掛選項的數量進行一下精簡。例如,如果你有10個不同名稱的選項需要保存到資料庫中,那麼,你就可以考慮將這10個數據作為一個陣列,並保存到資料庫的同一個選項中。

以下是讓你的外掛使用選項機制的主要函數:

  1. add_option($name, $value, $deprecated, $autoload);創建一個新的選項並保存到資料庫中,若選項已存在,則不進行任何操作。
    • $name 必要參數(string)。要創建的選項的名稱。
    • $value 可選參數(string)。要創建的選項的值。預設值為空字串。
    • $deprecated 可選參數(string)。該選項是否已經過期。若需要讓後面的$autoload參數生效,則該參數必須傳入空字串或null。
    • $autoload 可選參數(enum: 'yes' or 'no')。是否自動加載該選項。若設置為 'yes',則該選項會被get_alloptions 函數自動檢索到。預設值為 'yes'。
  2. get_option($option);從資料庫中獲取指定選項的值。
    • $option 必要參數(string)。選項的名稱。你可以在Option Reference中找到與WordPress一同安裝的預設選項列表。
  3. update_option($option_name, $newvalue);更新資料庫中的選項值,若選項不存在,則創建該選項。(注意:如果你用不到$deprecated和$autoload參數的話,那麼大可不必使用add_option函數)。
    • $option_name 必要參數(string)。要更新/創建的選項名稱。
    • $newvalue 必要參數(string|array|object)。要更新/創建的選項的值。

管理面板

假定你的外掛有一些選項(option)存儲於WordPress的資料庫中(參看上一節),你可能會想要一個主控面板來允許你的外掛用戶查看和編輯選項值。實現這一目標的方法闡述於Adding Administration Menus。

外掛國際化

在你完成了你的外掛的編寫工作之後,另一個需要考慮的問題(假設你準備跟大家分享你的外掛的話)就是將其國際化。國際化就是將你的軟件設置成能夠本地化的過程;本地化是將軟件中顯示的語言翻譯成其他語言的過程。Wordpress正在被全球的人們使用,所以全球化和本地化是他內在的特性,這其中就包括了外掛的本地化。

我們十分希望你能夠將你的外掛國際化,這樣其他國家的用戶就可以在自己的本地使用它了。我們有一個關於國際化的綜合說明在 I18n for WordPress Developers,這其中就包括了一個描述外掛國際化的部分。

更新你的外掛

這個部分描述必要的步驟來更新你在http://wordpress.org/extend/plugins 上的外掛,還包括在wordpress.org中使用Subversion (SVN)的細節。

假設你已經提交了你的外掛到WordPress外掛存儲庫。隨著時間的推移,你可能會發現需要並希望將添加新的功能到您的外掛或修正錯誤。你常常想要完成這些改變並提交它們到你的外掛的主幹。變化將是公開可見的,但只有專業人員通過SVN才能查看你的外掛,其他用戶通過網站或他們的WordPress外掛管理下載的將不會改變。

當你準備發佈一個新版本的外掛時:

  1. 確保一切都被提交並且新版本可以正常工作。注意測試所有你的外掛所支持的Wordpress版本。也不只是測試新特性,確保你沒有不小心破壞一些老的功能外掛。
  2. 更新主PHP文件中頭註釋的版本號(在主文件夾)。
  3. 更新readme.txt文件中的'Stable tag'的版本號(在主文件夾)。
  4. 在readme.txt文件中添加一個新的部分——「更新日誌(changelog)」,簡要描述相比於最後一個版本的變化。它將被列在外掛頁中。
  5. 提交這些更改。
  6. 創建一個新的SVN標籤作為主幹的副本,參見這裡。

給系統幾分鐘去工作,然後檢查wordpress.org外掛頁面和Wordpress上安裝你的外掛的頁面,看看一切是否正確更新和是否在你安裝的Wordpress中顯示了外掛更新(更新檢查可能會被緩存,這可能需要一些時間,試著訪問「可用更新」的頁面在你安裝的WordPress中)。

故障排除:

  1. 在wordpress.org上的外掛頁面仍然列出了舊版本。你是否更新主文件夾中的'stable tag'?只是創建一個標籤,更新readme.txt在標籤文件夾中是不夠的!
  2. 外掛頁面提供了一個新版本的zip文件,但按鈕仍然列出了舊版本號並且在你的安裝WordPress中並沒有更新通知。你是否記得更新「版本(Version)」的註釋在主PHP文件中?
  3. 對於其他問題請參考Otto的關於常見問題的頁面:The Plugins directory and readme.txt files

外掛開發建議

  1. Wordpress外掛的代碼應該遵循 WordPress Coding Standards. 另外請同時參考Inline Documentation。
  2. 你的外掛中所有函數的名稱都應該與現存的Wordpress Core函數,其他外掛或主題的任何名稱不同。基於這個原因,我們建議你在你的外掛的所有函數的名稱之前加上一個你自己選擇的前綴,或者把你的外掛的函數都寫在一個類裡面(當然這個類的名字也必須是唯一的)。
  3. 請不要把Wordpress資料表格前綴(通常是「wp_」)直接寫在你的外掛裡,請使用$wpdb->prefix 。
  4. 雖然資料庫的讀取相對便宜,但它的寫入是相當昂貴的。資料庫十分擅長獲取信息並呈現給用戶,而且這些操作(通常)是非常迅速的。然而對資料庫進行改動就是一個非常複雜的過程了,而且需要使用更長的計算時間。因此,請盡量減少你對資料庫進行寫入的次數。在你編寫程序的時候就做好所有的準備,這樣就可以只在必須的時候再進行寫入了。
  5. 在資料庫裡只SELECT你需要的東西。儘管資料庫的讀取十分便捷,我們依然推薦你只查找真正需要的數據,來盡量減少資料庫的負載。例如,如果你只想獲得表格的行數,不要使用 SELECT * FROM, 因為這樣的話每一行中的所有數據都會被讀出,導致內存的浪費。同樣的,如果在外掛中你只想獲得post_id和post_author,請只 SELECT 這兩項來減少資料庫的負載。記住:在某一個操作的同時可能有其他上百個進程需要使用資料庫,而資料庫和服務器都必須同時滿足所有這些進程的需求。學習怎樣盡量減少你的外掛對資料庫的使用可以避免對這些資源的濫用。
  6. 不要讓你的PHP出錯。在你的wp_config.php文件中添加define('WP_DEBUG',true);,對你的所有函數進行測試來確定是否有任何的錯誤或者警告。有多少,就修復多少,直到再也不出現為止。

參考連結