WordPress Shortcode(短代碼)：徹底指南

WordPress短代碼的使用很是簡單。好比說咱們想顯示給定的最新文章，咱們可使用相似下面的代碼：

1	[ recent - posts ]

再進一步的，咱們能夠經過設定一個參數來控制現實的文章的數量：

1	[ recent - posts posts = "5" ]

更進一步的，咱們能夠爲文章列表增長一個標題：

1	[ recent - posts posts = "5" ] Posts Heading [ / recent - posts ]

 1. 簡單的短代碼

本教程的第一部分，咱們將建立下面這個短代碼的代碼：

1	[ recent - posts ]

建立的過程很是簡單，不須要很高級的PHP知識。建立過程以下：

1. 建立一個函數，當 WordPress 發現短代碼的時候會調用此函數；
2. 經過設置一個惟一的名稱來註冊短代碼；
3. 把註冊的函數綁定到Wordpress的action上。

本教程的全部代碼均可以直接放到 functions.php 中，也能夠放在一個將包含在 functions.php 的單獨的PHP文件中。

1.1 建立回調函數

當發現短代碼的時候，它會被一個稱做回調函數的一段代碼所代替。因此咱們先建立一個函數，從數據庫中獲取最新的文章。

1 2 3 4 5 6 7 8 9 10

function recent_posts_function ( ) {    query_posts ( array ( 'orderby' = > 'date' , 'order' = > 'DESC' , 'showposts' = > 1 ) ) ;    if ( have_posts ( ) ) :        while ( have_posts ( ) ) : the_post ( ) ;          $return_string = '<a href="' . get_permalink ( ) . '">' . get_the_title ( ) . '</a>' ;        endwhile ;    endif ;    wp_reset_query ( ) ;    return $return_string ; }

如上所示，咱們查詢數據庫，獲取最新的文章，並返回一個帶有連接的字符串。值得注意的是，回調函數並不打印任何內容，而是返回一個字符串。

1.2 註冊短代碼

如今，咱們告訴Wordpress這個函數是一個短代碼：

1 2 3

function register_shortcodes ( ) {    add_shortcode ( 'recent-posts' , 'recent_posts_function' ) ; }

當在文章的內容中發現短代碼 [recent-posts] 時，將會自動調用 recent_posts_function() 函數，咱們須要確保短代碼的名字是惟一的，以免重複。

1.3 Hook into WordPress

爲了可以執行 recent_posts_function() 函數，咱們須要把它綁定在 WordPress 的初始化鉤子中。

1	add_action ( 'init' , 'register_shortcodes' ) ;

 1.4 測試短代碼

簡單的短代碼已經準備好了，如今咱們須要測試它是否可以正常運行。咱們建立一個新的文章（或打開一個已存在的），把下面的代碼加入到文章內容中的某個位置：

1	[ recent - posts ]

發佈文章並在瀏覽器中打開，你將看到一個執行你最新文章的連接，以下圖所示：

2. 進階短代碼

 2.1 短代碼參數

短代碼很是靈活，由於它容許咱們添加參數以使它們具備更多的功能。假定咱們須要顯示必定數量的最新文章。爲了實現這個，咱們須要給短代碼增長額外的選擇來指定顯示最新的多少篇文章。

咱們須要使用兩個函數，第一個是Wordpress內置的 shortcode_atts() 函數，它把用戶的短代碼屬性與本地屬性結合在一塊兒，並填充到所須要的位置。第二個是PHP的 extract() 函數，顧名思義，它提取短代碼的各個屬性。

擴展咱們的回調函數，咱們添加一個參數，它是一個數組，從中咱們能夠提取到咱們須要獲取的文章的數量。咱們查詢數據庫，獲取指定數量的文章，並返回一個列表：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

function recent_posts_function ( $atts ) {    extract ( shortcode_atts ( array (        'posts' = > 1 ,    ) , $atts ) ) ;      $return_string = '<ul>' ;    query_posts ( array ( 'orderby' = > 'date' , 'order' = > 'DESC' , 'showposts' = > $posts ) ) ;    if ( have_posts ( ) ) :        while ( have_posts ( ) ) : the_post ( ) ;          $return_string . = '<li><a href="' . get_permalink ( ) . '">' . get_the_title ( ) . '</a></li>' ;        endwhile ;    endif ;    $return_string . = '</ul>' ;      wp_reset_query ( ) ;    return $return_string ; }

若是用戶不指定該選項，1將是默認值。咱們能夠添加更多的屬性，使短代碼接受更多的參數。用這個加強的函數，咱們能夠指定調用最新文章的數量：

1	[ recent - posts posts = "5" ]

在瀏覽器中顯示時，你將看到最新的五篇文章列表：

2.2 短代碼中添加內容

咱們能夠更進一步擴展咱們的短代碼，添加一些內容做爲參數來傳遞，這將是最新文章列表的標題。爲了實現此功能，咱們須要在回調函數中增長第二個參數 $content ，並把它顯示在列表前面的一個 <h3> 標籤中。新的函數以下：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

function recent_posts_function ( $atts , $content = null ) {    extract ( shortcode_atts ( array (        'posts' = > 1 ,    ) , $atts ) ) ;      $return_string = '<h3>' . $content . '</h3>' ;    $return_string . = '<ul>' ;    query_posts ( array ( 'orderby' = > 'date' , 'order' = > 'DESC' , 'showposts' = > $posts ) ) ;    if ( have_posts ( ) ) :        while ( have_posts ( ) ) : the_post ( ) ;          $return_string . = '<li><a href="' . get_permalink ( ) . '">' . get_the_title ( ) . '</a></li>' ;        endwhile ;    endif ;    $return_string . = '</ul>' ;      wp_reset_query ( ) ;    return $return_string ; }

這種短代碼相似於一個HTML標籤：

1	[ recent - posts posts = "5" ] This is the list heading [ / recent - posts ]

除了文章列表多了一個標題，其他的內容和上一個示例是同樣的：

3. 在任何地方顯示短代碼

3.1 在側邊欄小工具中使用短代碼

默認狀況下，側邊欄小工具是忽略短代碼的，實例以下：

1	[ recent - posts posts = "5" ]

若是你把這段代碼放在小工具裏的時候，你將看到相似下面的結果

咱們能夠經過一行代碼來啓用這個函數，爲了使側邊欄小工具支持短代碼，添加以下的代碼：

1	add_filter ( 'widget_text' , 'do_shortcode' ) ;

如今不須要修改其餘任何地方，刷新一下頁面看看，側邊欄將會正確的顯示：

一樣的，在評論中啓用短代碼：

1	add_filter ( 'comment_text' , 'do_shortcode' ) ;

在摘要中啓用短代碼：

1	add_filter ( 'the_excerpt' , 'do_shortcode' ) ;

4. TinyMCE編輯器增長短代碼按鈕

雖然短代碼能夠方便的爲文章添加動態內容，可是這對於普通用戶來講可能仍是有點複雜，尤爲是當參數比較多的時候。大多數用戶對於類HTML代碼並不熟悉，然而要使用短代碼，他們必須記住具體的語法與參數，由於即便是一個小小的語法錯誤，均可能致使意想不到的結果。

要解決這個，咱們能夠給 TinyMCE編輯器增長一個按鈕，使用戶能夠經過簡單的單擊來增長短代碼。建立這個按鈕僅需兩個步驟：

1. 爲這個按鈕建立一個JS文件
2. 註冊按鈕與JS文件

4.1 經過JS文件建立按鈕

JS文件是經過 TinyMCE API 來註冊 TinyMCE 插件的。咱們在主題的 js 文件夾下建立 recent-posts.js ，並貼進去下面的代碼（須要把圖片文件也放在這裏）：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

( function ( ) {    tinymce . create ( 'tinymce.plugins.recentposts' , {        init : function ( ed , url ) {          ed . addButton ( 'recentposts' , {              title : 'Recent posts' ,              image : url + '/recentpostsbutton.png' ,              onclick : function ( ) {                var posts = prompt ( "調用文章數量" , "1" ) ;                var text = prompt ( "列表標題" , "這裏是文章列表標題" ) ;                  if ( text != null && text != '' ) {                    if ( posts != null && posts != '' )                      ed . execCommand ( 'mceInsertContent' , false , '[recent-posts posts="' + posts + '"]' + text + '[/recent-posts]' ) ;                    else                      ed . execCommand ( 'mceInsertContent' , false , '[recent-posts]' + text + '[/recent-posts]' ) ;                }                else {                    if ( posts != null && posts != '' )                      ed . execCommand ( 'mceInsertContent' , false , '[recent-posts posts="' + posts + '"]' ) ;                    else                      ed . execCommand ( 'mceInsertContent' , false , '[recent-posts]' ) ;                }              }          } ) ;        } ,        createControl : function ( n , cm ) {          return null ;        } ,        getInfo : function ( ) {          return {              longname : "Recent Posts" ,              author : 'Specs' ,              authorurl : 'http://9iphp.com' ,              infourl : 'http://9iphp.com/opensystem/wordpress/1094.html' ,              version : "1.0"          } ;        }    } ) ;    tinymce . PluginManager . add ( 'recentposts' , tinymce . plugins . recentposts ) ; } ) ( ) ;

以下圖所示，咱們經過調用 tinymce.create() 建立了一個插件。代碼中最重要的是 init() 函數，咱們定義了一個名字，一個圖標文件及 onclick() 事件處理程序。

在 onclick() 函數的前兩行，彈出兩個對話框讓用戶輸入調用文章數量及列表標題兩個參數，而後根據用戶輸入，把生成的短代碼插入到編輯器中。

最後，TinyMCE插件經過 add() 函數添加到 PluginManager。如今咱們已經成功的整合了 [recent-posts] 短代碼到Wordpress中。

4.2 註冊按鈕及TinyMCE插件

建立完 JS 文件後，咱們如今須要註冊它和短代碼按鈕。因此咱們建立兩個函數並把它們綁定到合適的Wordpress過濾器中。

第一個叫作 register_button() 的函數把短代碼添加到按鈕數組中，在現有按鈕和新按鈕之間添加分割線。

1 2 3 4

function register_button ( $buttons ) {    array_push ( $buttons , "|" , "recentposts" ) ;    return $buttons ; }

第二個函數 add_plugin() 指出JS文件的路徑及文件名。

1 2 3 4

function add_plugin ( $plugin_array ) {    $plugin_array [ 'recentposts' ] = get_template_directory_uri ( ) . '/js/recent-posts.js' ;    return $plugin_array ; }

下一步是添加包含前面兩個函數的過濾器。register_button() 函數綁定到 mce_buttons 過濾器，這個會在編輯器加載插件的時候執行； add_plugin() 函數綁定到 mce_external_plugins 過濾器，當加載按鈕的時候執行。

1 2 3 4 5 6 7 8 9 10 11 12

function my_recent_posts_button ( ) {      if ( ! current_user_can ( 'edit_posts' ) && ! current_user_can ( 'edit_pages' ) ) {        return ;    }      if ( get_user_option ( 'rich_editing' ) == 'true' ) {        add_filter ( 'mce_external_plugins' , 'add_plugin' ) ;        add_filter ( 'mce_buttons' , 'register_button' ) ;    }   }

當用戶沒有對文章在可視化編輯器中編輯的權限時，前面的函數不會執行。

最後把函數勾到Wordpress初始化函數

1	add_action ( 'init' , 'my_recent_posts_button' ) ;

 4.3 按鈕用法

爲了檢測代碼是否正確，咱們打開一篇新的文章，這時一個咱們剛剛定義的按鈕是否是已經出如今第一行的末尾了？以下圖所示：

點擊按鈕的時候，會彈出對話框讓咱們輸入調用文章的數量：

輸入完點擊肯定後，會彈出第二個對話框，讓咱們輸入列表的標題：

參數留空的話，不會出如今最後的代碼中。最後，短代碼會添加到編輯器中：

 轉自：Specs' Blog