Главная > Блог > Web-разработка > CMS WoprdPress >

WordPress. Theme Customize API. Часть 1

03.04.2019

Теги: API • CMS • Web-разработка • WordPress • Настройка

Кастомайзер — это API для создания функционала предварительного просмотра любых изменений в WordPress во фронте в реальном времени без перезагрузки страницы. Это универсальный интерфейс для настройки разных опций темы: цвет, фон, виджеты, меню и так далее.

Объекты кастомайзера

Существует четыре типа объектов кастомайзера:

Панель (panel) — панель объединяет секции; но секция может существовать и вне панели.
Секция (section) — объединяет элементы управления (input, textarea).
Элемент управления (control) — это поле формы (input, textarea), расположены внутри секции.
Настройка (setting) — связывает элемент управления с настройкой из базы данных.

Используя методы объекта WP_Customize_Manager, можно добавлять, изменять и удалять объекты кастомайзера. Основная работа проводится на хуке customize_register, в функцию которого передаётся объект WP_Customize_Manager:

add_action(
    'customize_register',
    function($wp_customize) {
        /*
         * Здесь делаем что-либо с $wp_customize (объект класса WP_Customize_Manager)
         */

        // Действия с панелями
        $wp_customize->add_panel();     // добавить панель
        $wp_customize->get_panel();     // получить панель
        $wp_customize->remove_panel();  // удалить панель

        // Действия с секциями
        $wp_customize->add_section();    // добавить секцию
        $wp_customize->get_section();    // получить секцию
        $wp_customize->remove_section(); // удалить секцию

        // Действия с элементами управления
        $wp_customize->add_control();    // добавить элемент управления
        $wp_customize->get_control();    // получить элемент управления
        $wp_customize->remove_control(); // удалить элемент управления

        // Действия с настройками
        $wp_customize->add_setting();    // добавить настройку
        $wp_customize->get_setting();    // получить настройку
        $wp_customize->remove_setting(); // удалить настройку
    }
);

Панель (panel)

При добавлении новой панели доступны параметры:

$wp_customize->add_panel(
    'panel_example', // идентификатор панели
    [
        'title'          => '', // заголовок панели
        'capability'     => 'edit_theme_options', // права пользователя, который может видеть панель
        'theme_supports' => '', // идентификатор, чтобы потом включать панель с помощью add_theme_support()
        'priority'       => 10, // порядок сортировки, определяет порядок в списке панелей и секций
    ]
);

Секция (section)

При добавлении новой секции доступны параметры:

$wp_customize->add_section(
    'section_example', // идентфикатор секции
    [
        'title'          => '', // заголовок секции
        'description'    => '', // описание секции
        'panel'          => 'panel_example', // идентифкатор панели, в которой будет размещена секция
        'capability'     => 'edit_theme_options', // права пользователя, который может видеть секцию
        'theme_supports' => '', // идентификатор, чтобы потом включать секцию с помощью add_theme_support()
        'priority'       => 10, // порядок сортировки, определяет порядок в списке секций
    ]
);

Порядок сортировки секций:

Title	ID	Priority
Site Title & Tagline	title_tagline	20
Colors	colors	40
Header Image	header_image	60
Background Image	background_image	80
Menus (Panel)	nav_menus	100
Widgets (Panel)	widgets	110
Static Front Page	static_front_page	120
default		160
Additional CSS	custom_css	200

Настройка (setting)

При добавлении новой настройки доступны параметры:

$wp_customize->add_setting(
    'setting_example', // идентификатор настройки
    [
        // значение по умолчанию для настройки
        'default'              => '',
        // может быть option или theme_mod 
        'type'                 => 'theme_mod',
        // как обновлять окно предпросмотра (refresh или postMessage)
        'transport'            => 'refresh',
        // права доступа пользователя, чтобы видеть эту настройку            
        'capability'           => 'edit_theme_options',
        // идентификатор, чтобы потом включать настройку с помощью add_theme_support()
        'theme_supports'       => '',
        // фунция обратного вызова для проверки корректности данных
        'validate_callback'    => '',
        // фунция обратного вызова для очистки данных на стороне PHP
        'sanitize_callback'    => '',
        // фунция обратного вызова для очистки данных на стороне JS
        'sanitize_js_callback' => '',
    ]
);

Параметр type может принимать два значения:

option (опции) — хранятся в таблице wp_options и могут быть использованы независимо от активной темы. Например, «Название сайта» не завит от того, какая тема установлена.
theme_mod (модификации темы) — используются для темы и хранятся для каждой темы отдельно. Например, цвет заголовка или фон сайта.

Элемент управления (control)

При добавлении нового элемента управления доступны параметры:

$wp_customize->add_control(
    'control_example', // идентификатор элемента управления
    [
        'label'       => '',                // label элемента формы
        'description' => '',                // описание элемента формы
        'section'     => 'section_example', // идентификатор секции, в которой размещен этот элемент управления
        'settings'    => 'setting_example', // идентификатор настройки, с которой связан этот элемент управления
        'type'        => 'text',            // тип элемента формы
        'choices'     => array(),           // если type равен select или radio
        'priority'    => 10,                // порядок сортировки
    ]
);

Дополнительно

Поиск: API • CMS • Web-разработка • WordPress • Настройка • Элемент управления • Секция • Control • Section • Setting • Theme Customize