Расширяем Theme Customizer. Создание страницы настроек темы для Wordpress

777617

Если вы занимаетесь профессиональной разработкой тем для WordPress, то наверняка сталкивались с вопросом создания страницы настроек. Начиная с версии 3.4 в WordPress появился Theme Customizer. Кодекс рекомендует разработчикам встраивать настройки темы с его помощью, а не создавать свою страницу отдельно.

Позволяя пользователям менять настройки темы и просматривать введённые изменения “на лету”, вы сделаете тему более простой в использовании и легкой для понимания. Ранее разработчики создавали отдельную страницу, которая была менее удобной для пользователя, так как, чтобы изменения вступили в силу, администратору требовалось обновить страницу.

Элементы управления по умолчанию

Коротко пробежимся по основным моментам. Theme Customization API позволяет создавать элементы управления в разделе Внешний вид->Настроить в меню панели управления WordPress. Каждая тема, особенно последних лет, снабжена некоторыми настройками по умолчанию: заголовок сайта, слоган, цвет фона, меню, фоновое изображение, виджеты, а также статическая и главная страница. Нет необходимости добавлять какой-либо код для поддержки этих базовых параметров.

Однако, в Theme Customization API заложен большой потенциал, который было бы неправильно не использовать.

Общие сведения о панелях, секциях, настройках и элементах управления

Новый элемент управления (контролл) регистрируется методом add_control()Элемент управления – это элемент HTML-формы на странице настройщика темы, например, поле для ввода текста, кнопки выбора цвета и так далее. В каждой секции можно встроить неограниченное количество элементов.

Ниже представлены скриншоты, как выглядят панель, а также стандартная секция “Свойства сайта” с базовыми настройками: название, логотип, краткое описание.

Несмотря на богатые возможности и огромный потенциал, по умолчанию WordPress предоставляет не так уж и много контроллов:

  • Текстовое поле input
  • Радиокнопки (группа переключателей)
  • Чекбоксы (флажки)
  • Загрузчик изображения
  • Кнопка выбора цвета
  • Выпадающий список

Вот собственно и все. Учитывая современные реалии, иногда их очень не хватает для более удобной группировки, или динамического управления данными. Думаю, что в будущих версиях, этот недостаток обязательно исправят. А пока этого не произошло, я хотел бы познакомить вас с небольшим фреймворком, позволяющим расширить возможности базового настройщика темы. Вы можете скачать его здесь.

Скачать Cody Framework (версия 1.1.0, размер файла 3.1 Mb)

Cody Framework

Всего в новом фреймворке содержатся около 20 новых элементов управления. Вместо того, чтобы их просто перечислить, я постараюсь привести код каждого элемента с короткими пояснениями. Подключение фреймворка очень простое. Распакуйте файлы и разместите папку cody-framework в корневой папке с вашей темой. Затем произведите подключение, разместив в самом начале файла function.php следующий код:

function cody_framework_include( $wp_customize ) {
	require_once get_template_directory() . '/cody-framework/admin.php';
}
add_action( 'customize_register', 'cody_framework_include' );

Хук customize_register создает подключение фреймворка только в момент загрузки страницы настройщика темы. Это значит, что ни в административной части, ни во фронтенде он не будет нагружать ваш сайт.

20
новых элементов управления для настройщика темы

Прежде чем мы перейдем непосредственно к созданию настроек, коротко покажу, как создать новую панель и секцию. Параметры каждого элемента вы можете подробнее прочитать в кодексе.

Создаем новую панель. Обратите внимание, что если в панели нет ни одной секции, она не отобразится.

/**
 * New theme options panel
 */
$wp_customize->add_panel( 'cody_framework',    // id панели
	array(
		'title'        => __( 'Pro options theme', 'mytheme' ),
		'description'  => __( 'This is panel description', 'mytheme' ),
		'priority'     => 10,          // приоритет, который влияет на расположение панели
	)
);

Создадим новую секцию в панели.

$wp_customize->add_section(
	'decoration',       // id секции
	array(
		'title'       => __( 'Decoration', 'mytheme' ),
		'description' => __( 'This is description', 'mytheme' ),
		'priority'    => 10,
		'panel'       => 'cody_framework'  // id родительской панели
        )
);

Всё. Теперь можно создавать новые настройки.

#1 Простое текстовое поле input

/**
 * Text slider
 */
$wp_customize->add_setting( 'slider_text' , array(
	'default'         => 'Слайдер',
	'transport'       => 'postMessage'
));
$wp_customize->add_control(
	new CF_Input_Text_Control(
		$wp_customize, 'slider_text', array(
			'label'       => __( 'Slider text', 'serious' ),
			'description' => __( 'You can specify vertical text for a block. Leave the field blank if you want to hide it', 'serious' ),
			'section'     => 'home_page',
			'type'	      => 'text',
			'relation'    => 'children'
		)
	)
);

#2 Простое текстовое поле textarea

$wp_customize->add_setting( 'textarea' );
$wp_customize->add_control (
	new CF_Textarea_Control (
		$wp_customize,
		'textarea',
		array(
			'label'       => __( 'Label', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'textareas',
			'type'        => 'textarea',
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#3 Текстовый редактор

Представляет собой стандартный текстовый редактор WordPress. Параметры:

  • params – массив аргументов параметра $settings у функции wp_editor()
  • relation – задает отношение к элементу Switcher (возможные значения: children или пусто)
$wp_customize->add_setting( 'text' ); // lowercase letters only
$wp_customize->add_control(
	new CF_WPEditor_Control(
		$wp_customize, 'text',
		array(
			'label'       => __( 'Textarea', 'mytheme' ),
			'description' => __( 'This is section description', 'mytheme' ),
			'section'     => 'home_page',
			'type'        => 'wp_editor',
			'params'      => array(
				'textarea_rows'    => 15,
				'media_buttons'    => true,
				'drag_drop_upload' => false,
				'teeny'            => true,
				'quicktags'        => false,
			),
			'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#4 Динамические текстовые поля input

$wp_customize->add_setting( 'multi_field', array(
	'default'           => '',
));
$wp_customize->add_control(
	new CF_Multi_Input_Control(
	$wp_customize, 'multi_field', array(
			'label'       => __( 'Multiple inputs', 'mytheme' ),
			'description' => __( 'Add more and more and more...', 'mytheme' ),
			'settings'    => 'multi_field',
			'section'     => 'inputs',
			//'relation'  => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

Элемент управления создает динамически изменяемую группу текстовых полей, как показано на картинке ниже.

#5 Простые радиокнопки

$wp_customize->add_setting( 'simple', array(
	'default'     => '2',
));
$wp_customize->add_control(
	new CF_Radio_Simple_Control(
		$wp_customize, 'simple', array(
			'label'       => __( 'Simple radio', 'mytheme' ),
			'description' => __( 'This is description. Very, very big description of control', 'mytheme' ),
			'section'     => 'radio_checkbox',
			'choices'     => array(
				'1'   => __( 'One', 'mytheme' ),
				'2'   => __( 'Two', 'mytheme' ),
				'3'   => __( 'Three', 'mytheme' ),
			),
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#6 Текстовые радиокнопки

$wp_customize->add_setting( 'text_radio', array(
	'default'     => '2',
));
$wp_customize->add_control(
	new CF_Radio_Text_Control(
		$wp_customize, 'text_radio', array(
			'label'       => __( 'Text radio', 'mytheme' ),
			'description' => __( 'This is description. Very, very big description of control', 'mytheme' ),
			'section'     => 'radio_checkbox',
			'choices'     => array(
				'1'   => __( 'One', 'mytheme' ),
				'2'   => __( 'Two', 'mytheme' ),
				'3'   => __( 'Three', 'mytheme' ),
				'4'   => __( 'Four', 'mytheme' ),
			),
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#7 Радиокнопки картинкой

$wp_customize->add_setting( 'image_options', array(
	'default'     => '2',
));
$wp_customize->add_control(
	new CF_Radio_Image_Control(
		$wp_customize, 'image_options', array(
			'label'       => __( 'Image radio', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'radio_checkbox',
			'choices'     => array(
				'1'   => '1col.png',
				'2'   => '2cl.png',
				'3'   => '2cr.png',
				'4'   => '3cm.png',
				'5'   => '3cr.png',
			),
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#8 Переключатель switcher

$wp_customize->add_setting( 'switch', array(
	'default'           => false,
));
$wp_customize->add_control(
	new CF_Switch_Control(
		$wp_customize, 'switch', array(
			'label'       => __( 'Check me', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'type'        => 'checkbox',
			'settings'    => 'switch',
			'section'     => 'radio_checkbox',
			'relation'    => 'parent'    // This parameter specifies a relationship to all children controls
		)
	)
);

Обратите внимание на параметр relation. Если он установлен в значении parent, то все ближайшие последующие элементы управления с параметром children будут скрыты при условии, что чекбокс не активен.

#9 Выпадающий список

Пример показывает, как вывести пользовательские предустановленные параметры в выпадающем списке.

$wp_customize->add_setting( 'lists', array(
	'default'     => 'right',
));
$wp_customize->add_control(
	new CF_List_Control(
		$wp_customize, 'lists', array(
			'label'       => __( 'Lists', 'mytheme' ),
			'description' => __( 'Description', 'mytheme' ),
			'section'     => 'design',
			'type'        => 'post_types',       // posts, post_types, tags, categories, terms, users, menu
			'args'        => array(),
			'choices'     => array(
				'full'    => '1col.png',
				'left'    => '2cl.png',
				'right'   => '2cr.png',
				'middle'  => '3fm.png',
			),
			//'multi'       => 0,                // Multiselect
			//'relation'    => 'children'        // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

Параметры:

type – тип данных (posts – выводит все опубликованные записи, post_types – список зарегистрированных типов записей, tags – метки записей, categories – категории записей, terms – список таксономий, users – список пользователей, menu – список зарегистрированных меню).

args – через параметр args можно изменять параметры выборки для каждого типа данных (для posts смотри функцию get_posts, для post_types – get_post_types, для tags – get_tags, categories – get_categories, terms – get_terms, users – get_users, а для menu смотри передаваемые параметры функции wp_get_nav_menus).

choices – произвольный выпадающий список (параметр type перебивает choices).

#10 Список шрифтов Google

$wp_customize->add_setting( 'google_font_setting', array(
	'default'          => '',
));
$wp_customize->add_control(
	new CF_Fonts_Control(
		$wp_customize, 'google_font_setting', array(
			'label'       => __( 'Google Font Setting', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'select_fields',
			'settings'    => 'google_font_setting',
			//'multi'       => 1,              // This option allows to create a multiselect (1 - true, 0 - false)
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#11 Выбор цвета с прозрачностью

$wp_customize->add_setting( 'alpha_color_setting', array(
		'default'    => 'rgba(209,0,55,0.7)',
		'type'       => 'theme_mod',
		'capability' => 'edit_theme_options',
		'transport'  => 'postMessage'
	)
);
$wp_customize->add_control(
	new CF_Color_Control(
		$wp_customize, 'alpha_color_setting', array(
			'label'        => __( 'My color', 'mytheme' ),
			'description'  => __( 'Description hey', 'mytheme' ),
			'section'      => 'colors_fields',
			'settings'     => 'alpha_color_setting',
			'show_opacity' => true, // Optional.
			'palette'      => array(
				'rgb(150, 50, 220)',
				'rgba(50,50,50,0.8)',
				'rgba( 255, 255, 255, 0.2 )',
				'#00CC99' // Mix of color types = no problem
			),
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#12 Выбор цветовой схемы (палитры)

Позволяет создавать группы цветовых схем заранее предустановленных разработчиком темы. Цветовые схемы записываются в виде многомерного массива в параметр choices:

'choices'     => array(
	'1'   => array(
		'0'   => __( 'Big', 'mytheme' ),
		'1'   => '#f1f1f1',
		'2'   => '#f1cc00',
		'3'   => '#f1bf43',
	),
	'2'   => array(
		'0'   => __( 'Small', 'mytheme' ),
		'1'   => '#ffcc00',
		'2'   => '#bbaa23',
		'3'   => '#543211',
	),
	'3'   => array(
		'0'   => __( 'Large', 'mytheme' ),
		'1'   => '#123232',
		'2'   => '#232321',
		'3'   => '#456321',
	),
),

Пример настройки в кастомизере:

Цветовые схемы в настройщике
Цветовые схемы в настройщике
$wp_customize->add_setting( 'schemess', array(
	'default'     => '2',
));
$wp_customize->add_control(
	new CF_Color_Scheme_Control(
		$wp_customize, 'schemess', array(
			'label'       => __( 'Color scheme', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'colors_fields',
			'choices'     => array(
				'1'   => array(
					'0'   => __( 'Big', 'mytheme' ),
					'1'   => '#f1f1f1',
					'2'   => '#f1cc00',
					'3'   => '#f1bf43',
				),
				'2'   => array(
					'0'   => __( 'Small', 'mytheme' ),
					'1'   => '#ffcc00',
					'2'   => '#bbaa23',
					'3'   => '#543211',
				),
				'3'   => array(
					'0'   => __( 'Large', 'mytheme' ),
					'1'   => '#123232',
					'2'   => '#232321',
					'3'   => '#456321',
				),
			),
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#13 Выбор даты

$wp_customize->add_setting('data'); // lowercase letters only
$wp_customize->add_control(
	new CF_Date_Picker_Control(
		$wp_customize, 'data', array(
			'label'       => __( 'Select date', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'non_value',
			'type'        => 'date_picker',
			//'relation'  => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#14 Простая разделительная полоса

$wp_customize->add_setting( 'separator' );
$wp_customize->add_control(
	new CF_Separator_Control(
		$wp_customize, 'separator', array(
			'settings'	=> 'separator',
			'section'  	=> 'non_value',
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#15 Уведомление

$wp_customize->add_setting('custom_info', array(
	'default'           => '',
 
));
$wp_customize->add_control(
	new CF_Notice_Control(
		$wp_customize, 'custom_info', array(
			'label'       => __( 'A custom notice', 'mytheme' ),
			'description' => __( 'There are times that you just need to say something.', 'mytheme'),
			'settings'    => 'custom_info',
			'section'     => 'non_value',
			//'relation'  => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#16 Range slider

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

  • min – максимальное число диапазона
  • max – минимальное число диапазона
  • step – шаг изменения числа при движении ползунка
  • unit – не выполняет какую-либо практическую задачу, а лишь является пояснением для пользователя, выводится в элементе настройщика темы
$wp_customize->add_setting( 'slider' , array(
	'default'     => 0,
));
$wp_customize->add_control(
	new CF_Range_Slider_Control(
		$wp_customize, 'slider', array(
			'label'       => __( 'Range slider', 'mytheme' ),
			'description' => __( 'Help', 'mytheme' ),
			'min'         => 0,
			'max'         => 1240,
			'step'        => 10,
			'unit'        => 'px',
			'section'     => 'non_value',
			//'relation'  => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#17 Слайдер

Еще один динамический элемент управления. Его основная задача – создание сгруппированных данных с динамическим управлением. Каждая группа разделена логически. Параметры контрола:

  • img – динамическая загрузка изображения
  • link – простое поле input для вставки абсолютных ссылок (в принципе, можно использовать для хранения и других данных)
  • title – простое поле input для вставки заголовка
  • desc – textarea для вставки произвольного текста
  • check – чекбокс
  • relation – параметр для создания зависимости от Switcher

Контрол позволяет создавать, например, слайдеры с неограниченным количеством элементов. В этом его основная цель. Впрочем, можно использовать и для других задач.

$wp_customize->add_setting( 'services', array(
	'default'           => '',
));
$wp_customize->add_control(
	new CF_Slider_Control(
		$wp_customize, 'services', array(
			'label'       => __( 'Services box', 'mytheme' ),
			'description' => __( 'Use images with transparent backgrounds with a width and height of 600*350 pixels', 'mytheme' ),
			'settings'    => 'services',
			'section'     => 'home_page',
			'img'         => true,
			'link'        => true,
			'title'       => true,
			'desc'        => true,
			'check'       => false,
			'relation'    => 'children'
		)
	)
);

#18 Выбор изображений

$wp_customize->add_setting( 'gallery', array(
	'default'     => '',
));
$wp_customize->add_control(
	new CF_Images_Control(
		$wp_customize, 'gallery', array(
			'label'       => __( 'Gallery', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'custom',
			'multi'       => 0,
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#19 Выбор пиктограмм fontawesome

$wp_customize->add_setting( 'icons', array(
	'default'     => '',
));
$wp_customize->add_control(
	new CF_Icons_Control(
		$wp_customize, 'icons', array(
			'label'       => __( 'Icons', 'mytheme' ),
			'description' => __( 'This is description', 'mytheme' ),
			'section'     => 'custom',
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

#20 Режим работы

Позволяет удобно формировать данные, например, о времени работы компании в течение недели. Элемент управления доступен начиная с версии 1.1.

/**
 * Work schedule
 */
$wp_customize->add_setting( 'work_schedule' , array(
	'default'         => '',
	'transport'       => 'postMessage'
));
$wp_customize->add_control(
	new CF_Work_Schedule_Control(
		$wp_customize, 'work_schedule', array(
			'label'       => __( 'Work schedule', 'mytheme' ),
			'description' => __( 'Displays work schedule of company', 'mytheme' ),
			'section'     => 'contact',
			'type'	      => 'text',
			//'relation'    => 'children'    // This parameter specifies a relationship to CF_Switch_Control
		)
	)
);

Обратите внимание на новые параметры в некоторых элементах управления:

  • relation – задает отношение к элементу управления “Переключатель switcher”. Может принимать либо parent, либо children. По умолчанию “пусто”. Если параметр relation у переключателя в значении parent, то все последующие элементы со значением children будут скрыты, пока переключатель не станет в активном режиме.
  • multi – задает порядок выбора элементов в выпадающих списках. Может принимать значение true или false (по умолчанию). Если true, то пользователь может выбирать несколько значений.
17 comments to post “"Расширяем Theme Customizer. Создание страницы настроек темы для WordPress"
  • Ян Александров
    Вадим22 Apr 2019 03:06

    Здравствуйте! А как выводить ваши кастомные поля? Тоже через get_theme_mod()?

    Reply
    • Ян Александров
      Yan AlexandrovAuthor3 Jul 2019 16:29

      Да, через get_theme_mod( 'ваша настройка' );

      Reply
  • Ян Александров
    Олег18 Apr 2020 14:10

    Здравствуйте, мне нужно предоставить клиенту возможность выбора количества card в row. И выбирать категории, откуда берутся карточки постов. Подскажите способ реализации данной задачи в customizer.

    Reply
  • Ян Александров
    Макс23 Jun 2020 10:39

    Здравствуйте!

    Theme checker ругается на отсутствие sanitization callback function при использовании слайдера изображений.

    Какую функцию можно использовать для этой цели?

    Reply
    • Ян Александров
      Ян АлександровAuthor23 Jun 2020 11:14

      Привет.
      Добавь функцию очистки json, что-то вроде этого:

      function sanitize_json( $input ) {
          return array_map( 'sanitize_text_field', wp_unslash( json_decode( $input ) ) );
      }

      А в sanitization callback function укажи название функции.

      Reply
      • Ян Александров
        Макс23 Jun 2020 13:46

        Варинат с wp_json_encode не подходит, юзаю твой вариант, благодарю )

      • Ян Александров
        Макс23 Jun 2020 14:19

        В итоге сделал такую фуркцию под свой слайдер:

        function sanitize_json( $input ) {

        $arr = wp_unslash( json_decode( $input ) );
        $new_arr = array();

        foreach ( $arr as $value ) {
        $new_arr[] = array_map( ‘sanitize_text_field’, ( get_object_vars( $value ) ) );
        }

        return json_encode( $new_arr );
        }

  • Ян Александров
    Макс23 Jun 2020 12:18

    Может просто использовать wp_json_encode?

    Reply
    • Ян Александров
      Ян АлександровAuthor23 Jun 2020 13:50

      wp_json_encode – просто обёртка для json_encode и не проводит ни каких очисток.

      Reply
  • Ян Александров
    Сергей23 Jun 2020 20:34

    Добрый день при попытке подключит в functions выдаёт ошибку “Cannot redeclare cody_framework_include() (previously declared in E:\1SERVER\domains\test.local\wp-content\themes\twentysixteen\functions.php:2) in E:\1SERVER\domains\test.local\wp-content\themes\twentysixteen\cody-framework\admin.php on line 69”
    После того как подключаему функцию в файле functions переименовал с cody_framework_include на cody_framework_include_1 ошибка пропала.
    Но теперь по попытке задать любой из 20-и типов выдаёт ошибку (пример для инпутов) Uncaught Error: Class ‘CF_Input_Text_Control’ not found in
    я так понимаю почему-то не работают файлы подключаемые в cody-framework/admin.php подскажите может кто сталкивался

    Reply
    • Ян Александров
      Дмитрий21 Jul 2020 17:05

      Это происходит, потому-что вы функцию второй раз декларируете. Нужно в functions.php вставить только require_once get_template_directory() . ‘/cody-framework/admin.php’;

      Reply
  • Ян Александров
    Александр17 Aug 2020 16:14

    Кривое какое то дополнение, сток стили кастомайзера перебивает и js ошибки всякие, допилите и будет вам счастье

    Reply
  • Ян Александров
    Илья31 Aug 2020 03:25

    Здравствуйте у данного расширения есть репозиторий на github?

    Reply
    • Ян Александров
      Ян АлександровAuthor31 Aug 2020 11:48

      Пока нет.

      Reply
  • Ян Александров
    Сергей12 Sep 2020 17:09

    А как работает слайдер? Появляется одна кнопка, но она не работает

    Reply
  • Ян Александров
    Алекс11 Jan 2021 00:03

    Охренеть. Да что б ты был здоров.
    😊 спасибо большое

    Reply
  • Ян Александров
    Максим2 Apr 2021 17:32

    Ну либо на 5.7 уже не работает, либо очень сложно написано, и банально на чистой теме не работает даже скопировав код из примеров…
    Обидно что просадил на это 2 часа…

    Reply
Leave a Reply

B I PHP JS

Made with by CodyShop