Languages: English • Customization API 日本語 Русский • (Add your language)
Для более детальной информации об API настройки тем пожалуйста посетите официальную документацию: https://developer.wordpress.org/themes/customize-api/.
API настройки тем, добавленные в Wordpress 3.4, позволяет разработчикам настраивать и добавлять настройки в раздел «Внешний вид → Customize» в панели администратора. Экран настройки позволяет администраторам корректировать настройки темы, цвет схемы или виджета, а так же видеть предварительный просмотр в реальном времени. Эта страница документирует API Настройки тем и его использование в ваших разработанных схемах.
Эта статья подразумевает, что вы уже прочитали Theme Development и Writing a Plugin, которые дают примерное представление о разработке сторонних тем и плагинов для Wordpress. Эта статья так же требует понимания принципов объектно-ориентированного программирования. Знакомство с Wordpress Settings API так же будет весьма хорошим дополнением.
Внимание: Эта информация верна для WordPress Version 3.4 и выше.
Независимо от того, являетесь ли вы разработчиком темы или плагина, вы можете использовать это API, чтобы добавить более мощные и интерактивные настройки в свою тему или плагин.
Чтобы добавить свои собственные параметры в Customizer, вам нужно использовать как минимум 2 хука:
Примечание: При желании, хук customize_preview_init также может использоваться для постановки в очередь пользовательского JavaScript на экране Customizer. JavaScript можно использовать для того, чтобы сделать настройщик более отзывчивым и мощным, но этот шаг не обязателен.
Важно: Не загружайте ваш код Customizer с проверкой is_admin(). Если вы добавляете свой customize_register только для is_admin(), то любые панели, секции или элементы управления будут недоступны при загрузке предварительного просмотра Customizer. Начиная с WordPress 4.1, существуют контекстные панели, разделы и элементы управления, так что они могут отображаться только при предварительном просмотре определенных URL-адресов. Если вы регистрируете свои панели, секции и элементы управления только для is_admin(), вы фактически будете говорить что они не контекстуальны для любого URL на вашем сайте. Для получения дополнительной информации см. #30387 и #29758.
Добавление новых settings, sections, или controls для Theme Customizer должны быть определены внутри действия customize_register. Это действие автоматически загружает объект $wp_customize, который является экземпляром класса WP_Customize_Manager.
Сначала определите действие следующим образом:
function mytheme_customize_register( $wp_customize ) {
//Все наши секции, настройки и элементы управления будут добавлены здесь
}
add_action( 'customize_register', 'mytheme_customize_register' );
Обратите внимание, что объект $wp_customize автоматически передается функции, и все настройки, которые вы вносите на страницу Theme Customizer, выполняются с помощью методов объекта $wp_customize.
Затем вам нужно определить ваши настройки, затем ваши секции, затем ваши элементы управления (элементам управления нужны секция и настройки для работы).
Настройки автоматически используют функцию WordPress-а theme_mod для получения/установки настроек для вашей темы.
Чтобы добавить новый параметр в Theme Customizer, необходимо вызвать метод $wp_customize->add_setting(). Определяя ваши настройки таким образом, вам не нужно делать никакой дополнительной работы для создания, сохранения или извлечения настроек для вашей темы.
Добавление настройки темы (в рамках действия 'customize_register') может выглядеть следующим образом:
$wp_customize->add_setting( 'header_textcolor' , array(
'default' => '#000000',
'transport' => 'refresh',
) );
Примечание: Примечание. Аргумент 'transport' является необязательным и по умолчанию равняется 'refresh'. Если оставить значение по умолчанию, окно предварительного просмотра настройщика темы будет обновляться, полностью перезагружаясь при изменении этого параметра. Если вы предпочитаете избегать обновлений и улучшать отзывчивость, вы можете вместо этого установить для этого параметра значение 'postMessage', а затем обрабатывать любые обновления стилей вручную с помощью небольшого количества JavaScript (см. Раздел Настройка предварительного просмотра ниже).
Секции - это группы опций. Когда вы определяете новые элементы управления, они должны быть добавлены в раздел. Хотя вы можете добавлять элементы управления в существующие разделы, мы кратко рассмотрим добавление новой секции.
Чтобы добавить новую секцию в Theme Customizer, вам необходимо вызвать метод $wp_customize->add_section()
Добавление раздела темы (в рамках действия 'customize_register') может выглядеть следующим образом:
$wp_customize->add_section( 'mytheme_new_section_name' , array(
'title' => __( 'Visible Section Name', 'mytheme' ),
'priority' => 30,
) );
WordPress включает в себя несколько встроенных разделов. Если вы хотите использовать какие-либо из существующих, встроенных, вам не нужно объявлять их с помощью add_section(). Вместо этого обращайтесь к ним по имени. Следующие разделы являются встроенными:
Элемент управления - это элемент формы HTML, который отображается на странице Theme Customizer и позволяет администраторам изменять настройки и просматривать эти изменения в режиме реального времени. Элементы управления связаны с одной настройкой и одной секцией
Чтобы добавить новый элемент управления в Theme Customizer, вам необходимо вызвать метод $wp_customize->add_control().
Добавление элемента управления в раздел темы (в рамках действия 'customize_register') может выглядеть следующим образом:
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array( 'label' => __( 'Header Color', 'mytheme' ), 'section' => 'your_section_id', 'settings' => 'your_setting_id', ) ) );
Контроллеры имеют довольно много опций, некоторые из которых требуют передачи ему другого класса (например, класс WP_Customize_Color_Control(), показанный в примере выше). Дополнительные примеры см. в документации по add_control().
Наконец, вам просто нужно убедиться, что вы извлекаете настройки и выводите все необходимые CSS в свой header. Если вы определили свои настройки с помощью действия 'customize_register', как описано выше, то получить значения настроек можно путем вывода css через 'wp_head', извлекая значения с помощью get_theme_mod()
Например, допустим, у вас есть параметр с именем 'header_color', и он выглядит так:
$wp_customize->add_setting( 'header_color' , array(
'default' => '#000000',
'transport' => 'refresh',
) );
Ваш код для вывода CSS в header может выглядеть примерно так:
function mytheme_customize_css()
{
?>
<style type="text/css">
h1 { color:<?php echo get_theme_mod('header_color', '#000000'); ?>; }
</style>
<?php
}
add_action( 'wp_head', 'mytheme_customize_css');
Когда вы посмотрите на исходный код страницы, вы увидите следующее в header:
<style type="text/css">
h1 {color:#000000;}
</style>
Для цвета по умолчанию задано значение #000000. Как только это значение будет изменено через настройщик, будет показано новое значение. Например, предположим, что вы хотите изменить цвет на белый. В настройщике вы вставляете шестнадцатеричное значение для белого, #ffffff, нажимаете Опубликовать.
Теперь на странице источника вы увидите:
<style type="text/css">
.h1 {color:#ffffff;}
</style>
На этом этапе ваши параметры настройки живой темы должны быть полностью функциональными (если параметры, которые вы определили в Части 1, используют 'transport'=>'postMessage').
Подсказка: В конце этого руководства приведен пример класса настройки темы. Этот класс содержит полезную функцию (которая НЕ является частью WordPress) под названием generate_css(), которая может помочь вам быстро и легко сгенерировать валидный CSS для этого шага.
Этот шаг не является обязательным, но может значительно улучшить пользовательский опыт. Этот метод использует небольшой пользовательский JavaScript в сочетании с вашими настройками для более быстрой и более интерактивной настройки тем. Если его не использовать, то обновления отображаются путем перезагрузки всего окна предварительного просмотра.
Чтобы создать этот пользовательский обработчик JavaScript, вам нужно сделать следующее:
Мы подробно рассмотрим все 3 шага ...
Во-первых, убедитесь, что для всех созданных вами пользовательских настроек установлено значение 'transport'=>'postMessage' (см. "Добавление новой настройки" выше). Это приведет к отключению режима автоматического обновления при изменении этого параметра, что позволит вам определить любую пользовательскую обработку JavaScript, которая вам нравится.
Обратите внимание, что все настройки WordPress Theme Customizer по умолчанию используют 'transport'=>'refresh'. Если вы хотите отключить режим автоматического обновления для встроенных по-умолчанию опций Theme Customizer, вы можете легко обновить их метод(ы) транспорта с помощью хука 'customize_register':
function mytheme_customize_register( $wp_customize ) {
$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';
$wp_customize->get_setting( 'background_color' )->transport = 'postMessage';
}
add_action( 'customize_register', 'mytheme_customize_register' );
Затем вам нужно создать новый файл JavaScript для всей вашей пользовательской обработки. Как правило, вы называете его theme-customizer.js и помещаете его в папку 'js/ вашей темы, но вы можете называть ее как хотите или помещать в нужное место.
Содержимое вашего файла theme-customizer.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( $ ) {
// Обновить название сайта в режиме реального времени ...
wp.customize( 'blogname', function( value ) {
value.bind( function( newval ) {
$( '#site-title a' ).html( newval );
} );
} );
//Обновить краткое описание сайта в режиме реального времени ...
wp.customize( 'blogdescription', function( value ) {
value.bind( function( newval ) {
$( '.site-description' ).html( newval );
} );
} );
//Обновить цвет заголовка сайта в режиме реального времени ...
wp.customize( 'header_textcolor', function( value ) {
value.bind( function( newval ) {
$('#site-title a').css('color', newval );
} );
} );
//Обновить фон сайта в режиме реального времени ...
wp.customize( 'background_color', function( value ) {
value.bind( function( newval ) {
$('body').css('background-color', newval );
} );
} );
//Обновить цвет ссылок в режиме реального времени ...
wp.customize( 'link_textcolor', function( value ) {
value.bind( function( newval ) {
$('a').css('color', newval );
} );
} );
} )( jQuery );
Как видно из приведенного выше примера, один базовый обработчик выглядит следующим образом:
wp.customize( 'YOUR_SETTING_ID', function( value ) {
value.bind( function( newval ) {
//Do stuff (newval variable contains your "new" setting data)
} );
} );
Наконец, вам просто нужно убедиться, что ваш JavaScript подключен.
Чтобы файл загружался только на экране администратора Theme Customizer (а не на вашем реальном веб-сайте), вы должны использовать хук customize_preview_init
Например...
/**
* Used by hook: 'customize_preview_init'
*
* @see add_action('customize_preview_init',$func)
*/
public static function mytheme_customizer_live_preview()
{
wp_enqueue_script(
'mytheme-themecustomizer', //Give the script an ID
get_template_directory_uri().'/assets/js/theme-customizer.js',//Point to file
array( 'jquery','customize-preview' ), //Define dependencies
'', //Define a version (optional)
true //Put script in footer?
);
}
add_action( 'customize_preview_init', 'mytheme_customizer_live_preview' );
В этом примере показана одна потенциальная реализация базового класса настройки темы, который можно легко включить в любую существующую тему. В этом примере класса даже используется транспортный метод postMessage для предварительного просмотра на основе JavaScript в Theme Customizer.
Обратите внимание, что этот класс следует использовать вместе с образцом файла theme-customize.js, который был рассмотрен ранее в этом руководстве.
<?php
/**
* Contains methods for customizing the theme customization screen.
*
* @link http://codex.wordpress.org/Theme_Customization_API
* @since MyTheme 1.0
*/
class MyTheme_Customize {
/**
* This hooks into 'customize_register' (available as of WP 3.4) and allows
* you to add new sections and controls to the Theme Customize screen.
*
* Note: To enable instant preview, we have to actually write a bit of custom
* javascript. See live_preview() for more.
*
* @see add_action('customize_register',$func)
* @param \WP_Customize_Manager $wp_customize
* @link http://ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own-themes/
* @since MyTheme 1.0
*/
public static function register ( $wp_customize ) {
//1. Define a new section (if desired) to the Theme Customizer
$wp_customize->add_section( 'mytheme_options',
array(
'title' => __( 'MyTheme Options', 'mytheme' ), //Visible title of section
'priority' => 35, //Determines what order this appears in
'capability' => 'edit_theme_options', //Capability needed to tweak
'description' => __('Allows you to customize some example settings for MyTheme.', 'mytheme'), //Descriptive tooltip
)
);
//2. Register new settings to the WP database...
$wp_customize->add_setting( 'link_textcolor', //No need to use a SERIALIZED name, as `theme_mod` settings already live under one db record
array(
'default' => '#2BA6CB', //Default setting/value to save
'type' => 'theme_mod', //Is this an 'option' or a 'theme_mod'?
'capability' => 'edit_theme_options', //Optional. Special permissions for accessing this setting.
'transport' => 'postMessage', //What triggers a refresh of the setting? 'refresh' or 'postMessage' (instant)?
)
);
//3. Finally, we define the control itself (which links a setting to a section and renders the HTML controls)...
$wp_customize->add_control( new WP_Customize_Color_Control( //Instantiate the color control class
$wp_customize, //Pass the $wp_customize object (required)
'mytheme_link_textcolor', //Set a unique ID for the control
array(
'label' => __( 'Link Color', 'mytheme' ), //Admin-visible name of the control
'section' => 'colors', //ID of the section this control should render in (can be one of yours, or a WordPress default section)
'settings' => 'link_textcolor', //Which setting to load and manipulate (serialized is okay)
'priority' => 10, //Determines the order this control appears in for the specified section
)
) );
//4. We can also change built-in settings by modifying properties. For instance, let's make some stuff use live preview JS...
$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';
$wp_customize->get_setting( 'background_color' )->transport = 'postMessage';
}
/**
* This will output the custom WordPress settings to the live theme's WP head.
*
* Used by hook: 'wp_head'
*
* @see add_action('wp_head',$func)
* @since MyTheme 1.0
*/
public static function header_output() {
?>
<!--Customizer CSS-->
<style type="text/css">
<?php self::generate_css('#site-title a', 'color', 'header_textcolor', '#'); ?>
<?php self::generate_css('body', 'background-color', 'background_color', '#'); ?>
<?php self::generate_css('a', 'color', 'link_textcolor'); ?>
</style>
<!--/Customizer CSS-->
<?php
}
/**
* This outputs the javascript needed to automate the live settings preview.
* Also keep in mind that this function isn't necessary unless your settings
* are using 'transport'=>'postMessage' instead of the default 'transport'
* => 'refresh'
*
* Used by hook: 'customize_preview_init'
*
* @see add_action('customize_preview_init',$func)
* @since MyTheme 1.0
*/
public static function live_preview() {
wp_enqueue_script(
'mytheme-themecustomizer', // Give the script a unique ID
get_template_directory_uri() . '/assets/js/theme-customizer.js', // Define the path to the JS file
array( 'jquery', 'customize-preview' ), // Define dependencies
'', // Define a version (optional)
true // Specify whether to put in footer (leave this true)
);
}
/**
* This will generate a line of CSS for use in header output. If the setting
* ($mod_name) has no defined value, the CSS will not be output.
*
* @uses get_theme_mod()
* @param string $selector CSS selector
* @param string $style The name of the CSS *property* to modify
* @param string $mod_name The name of the 'theme_mod' option to fetch
* @param string $prefix Optional. Anything that needs to be output before the CSS property
* @param string $postfix Optional. Anything that needs to be output after the CSS property
* @param bool $echo Optional. Whether to print directly to the page (default: true).
* @return string Returns a single line of CSS with selectors and a property.
* @since MyTheme 1.0
*/
public static function generate_css( $selector, $style, $mod_name, $prefix='', $postfix='', $echo=true ) {
$return = '';
$mod = get_theme_mod($mod_name);
if ( ! empty( $mod ) ) {
$return = sprintf('%s { %s:%s; }',
$selector,
$style,
$prefix.$mod.$postfix
);
if ( $echo ) {
echo $return;
}
}
return $return;
}
}
// Setup the Theme Customizer settings and controls...
add_action( 'customize_register' , array( 'MyTheme_Customize' , 'register' ) );
// Output custom CSS to live site
add_action( 'wp_head' , array( 'MyTheme_Customize' , 'header_output' ) );
// Enqueue live preview javascript in Theme Customizer admin screen
add_action( 'customize_preview_init' , array( 'MyTheme_Customize' , 'live_preview' ) );