WordPress Theme Customizer 新增自訂欄位

記得 WordPress 佈景主題的外觀自訂功能出來以前,新增自訂欄位是靠著在佈景主題的 functions.php 裡面寫一個 Theme Option 頁面進行設定;後來試用別人開發的佈景主題時,發現 Theme Customizer 並非不能自行設置想要的欄位,對此相當有興趣、趁網誌改版自己試了一下。

WordPress Theme Customzier

如上圖黃色區塊所示,左邊是 Theme Customizer 的區塊、右邊則是即時預覽,而這個功能最少只需要動到三個檔案--佈景主題基本的 functions.php、自己另外設置的 theme-customize.js、以及想要顯示的頁面,例如 index.php。

佈景主題的 functions.php

首先,我們在 functions.php 裡面加入以下程式碼:

// theme customizer
function 佈景主題的名字_customize_register( $wp_customize ) {
    if ( class_exists( 'WP_Customize_Control' ) ) {
        class PTD_Textarea_Control extends WP_Customize_Control {
            public function render_content() {?>
                <label>
                <span class="customize-control-title"><?php echo esc_html( $this->label );?></span>
                <textarea class="large-text" cols="20" rows="5" <?php $this->link(); ?>>
                    <?php echo esc_textarea( $this->value() ); ?>
                </textarea>
                </label>
                <?php
            }
        }
    }
    $wp_customize->add_setting( 'textarea的代稱', array(
        'default'           => '',
        'transport'         => 'postMessage'
    ));
    $wp_customize->add_section( '佈景主題的名字_site_info', array(
        'title'             => '自訂欄位的標題', '佈景主題的名字',
        'description'       => '自訂欄位的解說', '佈景主題的名字',
        'priority'          => 20,
    ));
    $wp_customize->add_control( new PTD_Textarea_Control( $wp_customize, 'site_intro_control', array(
        'label'             => 'Section Under Menu', '佈景主題的名字',
        'section'           => '佈景主題的名字_site_info',
        'settings'          => 'textarea的代稱'
    )));

}
add_action( 'customize_register', '佈景主題的名字_customize_register' );

這段程式碼有四個必須自行修改取代的敘述:佈景主題的名字、自訂欄位的標題、自訂欄位的解說、與 textarea 的代稱。

「佈景主題的名字」顧名思義,如果你的佈景主題叫「MyTheme」就把它改成 MyTheme。「自訂欄位的標題」若如上圖所示,就是「Header Information」那個區塊標題,至於「自訂欄位的解說」則對應「Where you can add HTML under the menu.」這段文字。

「textarea 的代稱」是這邊簡化的講法 ,舉例來說命名為「whateveryousay」。這個比較重要,在之後要碰到的其他檔案也會用到。就把它看作欄位名稱,實際上是用來傳送 textarea 我們輸入的內容、對應上圖就是下面這段。

<a href="http://wanico.wamimo.net/" target="_blank"><img ...

關於這些設定的詳細解說,推薦有興趣的人閱讀「A Guide to the WordPress Theme Customizer: Sections, Settings, and Controls」這篇文章。

自行設置 theme-customize.js 即時預覽

為了實現自訂的即時預覽功能,我們可以將下列程式碼建立一個名為 theme-customize 的獨立 js 檔案。

/**
 * This file adds some LIVE to the Theme Customizer live preview. To leverage
 * this, set your custom settings to 'postMessage' and then add your handling
 * here. Your javascript should grab settings from customizer controls, and 
 * then make any necessary changes to the page using jQuery.
 */
( function( $ ) {
  // Update the custom text in real time...
  wp.customize( 'textarea的代稱', function( value ) {
    value.bind( function( to ) {
      $( '#對應欄位ID' ).html( to );
    } );
  } );
} )( jQuery );

「對應欄位ID」是連結到我們想要顯示結果的頁面之區塊,等下我們會碰到,例如我們將此 ID 命名為「showthecontent」。設立好 theme-customize.js 後、進行最後一個步驟之前,我們要回到 functions.php 加入以下程式碼呼叫剛才設立好的 js 檔。

function 佈景主題的名字_customizer_live_preview() {

    wp_enqueue_script(
        '佈景主題的名字-theme-customizer',
        get_template_directory_uri() . 'theme-customize.js', //注意檔案路徑
        array( 'jquery', 'customize-preview' ),
        '',
        true
    );

} // end customizer_live_preview
add_action( 'customize_preview_init', '佈景主題的名字_customizer_live_preview' );

想要顯示的頁面,以 index.php 為例

這是最後一個步驟,我們以 index.php 為例,在想要顯示的地方輸入下列程式碼、這段也可以放在任何你想顯示結果的頁面,如 category.php 或 archive.php。

<div id="對應欄位ID">
<?php echo get_theme_mod( 'textarea的代稱' ); ?>
</div>

「對應欄位ID」要確保和我們建立的 js 裡面的 ID 相同,就是上面舉例的「showthecontent」,「textarea的代稱」則是「whateveryousay」。到這裡就大功告成了!可以馬上開外觀自訂來看看是否成功。

小結

在嘗試修改 Theme Customizer 時,不知道是否自身搜尋能力不足,沒在繁體中文圈找到類似的教學、都是從英文圈下去看,除了 textarea 以外,可以加的東西還有很多,像是 radio input、text input、和 checkbox。這邊是做興趣的、能力有限,希望這篇文章能做為一個引路石、讓繁中圈開發 WordPress 佈景主題的強者們碰到這一塊,並讓更多 WordPress 愛用者們受惠。下列是參考文章。

分類:網站網誌

  • 很棒的分享文章,我陸續會寫一些關於customizer的內容,到時候在交流一下!
    謝謝!

    • Wanico

      謝謝,希望有更多關於 customizer 的文章!