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

Если вы занимаетесь профессиональной разработкой тем для 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 создает подключение фреймворка только в момент загрузки страницы настройщика темы. Это значит, что ни в административной части, ни во фронтенде он не будет нагружать ваш сайт.

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

/**
 * 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, то пользователь может выбирать несколько значений.