WordPress как на ладони
Очень Удобный и Быстрый Хостинг для сайтов на WordPress. Пользуюсь сам и вам рекомендую!

Произвольные поля

Carbon Fields 1.6

Поле - это строительный блок для каждого контейнера в Carbon Fields. В контейнер можно поместить безграничное количество полей.

В предыдущей статье рассказано, как создать контейнер и прикрепить к нему поля, а в этом материале рассмотрим доступные из коробки поля. Примеры кода будут относится только к созданию полей, чтобы не плодить повторов относительно предыдущих и будущих статей о Carbon Fields.

Процесс создания контейнера (блока для полей, группы полей), очень простой: создается контейнер и в него добавляются поля. Как раз про все виды таких полей пойдет речь в этой статье.

Использование и параметры

Новое поле создаётся с помощью метода make():

Field::make( $type, $name, $label=null )
$type(строка) (обязательный)
Тип поля (текстовое, чекбокс и т.д.). Этот параметр отвечает за то, какой PHP класс будет включен в работу, чтобы реализовать функционал поля. К примеру, если передать text, то подключится класс Text_Field, который создаст простое текстовое поле.
$name(строка) (обязательный)
Имя поля. Используется в виде ключа для хранения в базе (таблица *_postmeta).
$label(строка)
Заголовок поля. Отображается только в админке и предназначено для кастомизации поля. Если данный параметр не передать, то автоматически будет подставлен параметр $name. В данном случае, если имя поля начинается с crb_, то при выводе вместо заголовка эта приставка будет отсечена.
По умолчанию: null

Carbon Fields по умолчанию сохраняет все поля с указанным именем, добавляя к его началу знак подчеркивания _, (например bgcolor станет _bgcolor). Однако при создании или выводе поля указывать его не обязательно - функция carbon_get_post_meta() (и её аналоги) обработают _ автоматически.

Такие поля с префиксом _ считаются в WordPress скрытыми и не отображаются, например, в списке произвольных полей у записей при редактировании.

Carbon Fields - фабрика по созданию метаполей и метаблоков делает процесс создания метаблоков максимально простым, так как после объявления создаёт объект, который не нужно присваивать к переменной. API полей поддерживает метод передачи параметров по цепочке, например:

// Создаем поле с выбором картинки, ключом 'my_photo' и заголовком "Моя фотка"
Field::make( 'image', 'my_photo', 'Моя фотка' )

// Создаем заголовок поля "Custom Sidebar" автоматически из ключа поля
Field::make( 'choose_sidebar', 'crb_custom_sidebar' )

// Метод цепочки - создаем выпадающий список
Field::make( 'select', 'crb_pay', 'Какой вид платежей предпочитаете?' )
	// Добавляем опции (варианты ответов)
	->add_options( array( 'Наличные', 'Электронная валюта', 'Нет предпочтений' ) )
	// Добавляем пояснение к полю, которое будет отображено под выпадающим списком из ответов
	->help_text( 'На основе вашего выбора мы подберем самые выгодные тарифы.' )

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

Параметры по умолчанию

При создании любого поля ему можно задать значение по умолчанию, то есть значение, которое поле сразу будет отображать при отображении контейнера. Если пользователь не заполнит поле, то именно это значение будет сохранено. Определить такое значение можно с помощью метода set_default_value:

Field::make(...)->set_default_value($default_value)

Обязательные поля

Если поле должно быть обязательно для заполнение, используйте метод set_required при создании поля:

Field::make(...)->set_required(true)

Такое поле будет помечено красной звёздочкой и, если не заполнено, не позволит сохранить запись (или другой объект WordPress), пока не будет заполнено:

Обязательное для заполнения поле

Текст справки

Текст справки используется как подсказка для пользователя, который будет использовать это поле. Обычно отображается под полем и содержит больше информации о том, что оно должно содержать: требования, примеры, ссылки и т. д. Разрешены теги HTML.

// Общий вид
Field::make(...)->help_text($text)

// Пример
Container::make('post_meta', 'Custom Data')
		 ->show_on_post_type('page')
		 ->add_fields( [
			 Field::make('text', 'crb_smile', 'Настроение')
				 ->help_text('<p><b>Какое настроение</b> у Вас было при написании <i>этой статьи?</i></p>')
		 ] );

Демонстрация отображения текста справки для текстового поля

Ширина

Вы можете установить ширину полей, которые находятся рядом друг с другом, и они будут выравниваться в одной строке. Чтобы задать ширину поля %, используйте:

// Общий пример
Field::make(...)->set_width(50)

// Реальный пример
Container::make('post_meta', 'Музыка')
		 ->show_on_post_type('page')
		 ->add_fields( [
			 Field::make('text', 'crb_song_author', 'Имя исполнителя')
				 ->set_width(50),
			 Field::make('text', 'crb_song_name', 'Название песни')
				 ->set_width(50)
		 ] );

Этот метод не установит ширину полей в контейнерах, которые отображаются на страницах добавления и редактирования термов WordPress (рубрик, тегов и т.д.).

CSS классы

Пользовательские CSS классы могут быть добавлены с помощью метода add_class(), например:

Field::make(...)->add_class('my-custom-class')

Добавление css класса полю

Условная логика

set_conditional_logic( $rules )

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

Данные в метод set_conditional_logic() передается в виде двумерного ассоциативного массива, аргументы передаются в виде пары ключ => значение.

field(строка) (обязательный)
Имя поля, к которому применяется правило. Имя должно быть таким же, как определено в контейнере.
value(строка/массив)
При каком значении поля, за которым "следим", отобразить или скрыть текущее поле. Вы можете использовать массив только, когда compare выставлено в IN или NOT IN.
По умолчанию: ""
compare(строка)
Оператор сравнения. Используются =, <, >, <=, >=, IN, NOT IN.
По умолчанию: =

Можно определить relation и установить ему значение AND (по умолчанию), или OR. Значение relation определяет отношение, когда существует более одного правила.

Container::make('post_meta', 'О еде')
		 ->show_on_post_type('page')
		 ->add_fields( [
			 Field::make('radio', 'love-eat-night', 'Любите покушать ночью?')
				  ->add_options(array(
					  'yes' => 'Да',
					  'no' => 'Нет',
				  )),

			 Field::make('text', 'night-meals', 'Какие блюда?')
				  ->set_conditional_logic(array(
					  'relation' => 'AND',
					  array(
						  'field' => 'love-eat-night',
						  'value' => 'yes',
						  'compare' => '=',
					  )
				  )),

			 Field::make('text', 'night-meals-not', 'Почему?')
				  ->set_conditional_logic(array(
					  'relation' => 'AND',
					  array(
						  'field' => 'love-eat-night',
						  'value' => 'no',
						  'compare' => '=',
					  )
				  )),
		 ] );

Text (текстовое поле)

Текстовое поле - это простейший и наиболее популярный вид поля. Оно отображает поле ввода текста.

Отображение текстового поля в админке

Создание поля

Field::make('text', 'crb_subtitle', 'Подзаголовок статьи')

Вывод значения поля

// Вывод за пределами цикла
echo carbon_get_post_meta(get_the_ID(), 'crb_subtitle');

// Вывод в любом месте сайта, где $post_id - ID поста
echo carbon_get_post_meta($post_id, 'crb_subtitle');

// Вывод в цикле
echo carbon_get_the_post_meta('crb_subtitle');

Textarea (область текста)

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

Отображение области текста в админке.png

С помощью метода set_rows($rows = 0) можно задать высоту поля, где $rows - количество строк.

Создание поля

Field::make("textarea", "short-biography", "Краткая биография")
		->set_rows(4) // Высотка поля в строках. Необязательный параметр.
		->help_text('Расскажите вкратце о себе.') // Подсказка. Необязательный параметр.

Вывод значения поля

// Вывод за пределами цикла
echo carbon_get_post_meta(get_the_ID(), 'short-biography');

// Вывод в любом месте сайта, где $post_id - ID поста
echo carbon_get_post_meta($post_id, 'short-biography');

// Вывод в цикле
echo carbon_get_the_post_meta('short-biography');

// Выводим с учетом переноса строки, благодаря wpautop()
echo wpautop( carbon_get_post_meta(get_the_ID(), 'short-biography') );

Rich Text (визуальный редактор)

Произвольное поле в виде WordPress tinyMCE именуемый визуальным редактором.

Отображение WordPress tinyMCE визуального редактора в админке

Создание поля

Field::make("rich_text", "short-biography", "Краткая биография")
			 ->help_text('Расскажите вкратце о себе.')

Наследует php класс Textarea_Field, а это значит, что все методы Textarea присуще и Rich Text.

Вывод значения поля

Выводятся значения данного типа поля точно также, как и у Textarea - с помощью carbon_get_post_meta().

Date (дата)

Выводит поле для вывода даты (date picker), функционал которого реализован на jQuery UI. Выбранное значение хранится в формате YYYY-MM-DD.

Отображения поля для выбора даты в админке

Создание поля

Field::make("date", "crb_event_meeting_date", "Дата")
			 ->help_text('Когда состоится мероприятие?') // Подсказка. Не обязательно.

Вывод значения поля

Это обычное текстовое поле, потому значения его выводятся точно также, как и у Text - с помощью carbon_get_post_meta().

Time (время)

Метаполе предназначенное для выбора времени. По принципу работы похоже на поле типа Date.

Отображения поля для выбора времени в админке

Создание поля

Field::make("time", "crb_event_meeting_time", "Время")
			 ->help_text('В какое время состоится мероприятие?')

Вывод значения поля

Это обычное текстовое поле, потому значения его выводятся точно также, как и у Text - с помощью carbon_get_post_meta().

Формат времени

set_time_format( $string )

С помощью этого метода можно указать формат времени (как будет отображаться и сохраняться).

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

Интервалы времени

set_interval_step( $array )

С помощью этого метода вы можете указать, с каким шагом бегунок у часов, минут и секунд будет перемещаться.

Field::make('time', 'time', 'Time')
	->set_interval_step(array(
		'hour'   => '2',
		'minute' => '5',
		'second' => '10',
	))

Теперь пользователь сможет выбрать только:

  • 0, 2, 4, 6 часов и т.д.
  • 5, 10, 15 минут и т.д.
  • 10, 20, 30 секунд и т.д.

Ограничения

set_restraints( $array )

С помощью этого метода можно ограничить диапазон времени, которое можно ввести в поле.

Field::make('time', 'time', 'Time')
	->set_restraints(array(
		'hourMin' => '9',
		'hourMax' => '18',
	))

Теперь можно выбрать только диапазон от 9 до 18 часов.

Поддерживаемые аргументы:

  • Часы: hourMin - нижняя граница (по умолчанию 0), hourMax - верхняя граница (по умолчанию 23).

  • Минуты: minuteMin - нижняя граница (по умолчанию 0), minuteMax - верхняя граница (по умолчанию 59).

  • Секунды: secondMin - нижняя граница (по умолчанию 0), secondMax - верхняя граница (по умолчанию 59).

  • Миллисекунды: millisecMin - нижняя граница (по умолчанию 0), millisecMax - верхняя граница (по умолчанию 999).

  • Микросекунды: microsecMin - нижняя граница (по умолчанию 0), microsecMax - верхняя граница (по умолчанию 999).

Опции

set_timepicker_options( $array )

С помощью метода можно установить некоторые опции поля

Field::make('time', 'time', 'Time')
	->set_timepicker_options(array(
		'currentText' => 'Текущее время',
	))

С полным перечнем опций вы можете ознакомиться на оф. странице Timepicker.

Date Time (дата и время)

Объединение таких типов полей как Date и Time. Это означает, что вы можете использовать все методы, которые доступны этим типам полей (описаны выше).

Отображение поля для выбора даты и времени в админке

Создание поля

Field::make('date_time', 'date_and_time', 'Дата и время')

Вывод значения поля

Это обычное текстовое поле, потому значения его выводятся точно также, как и у Text - с помощью carbon_get_post_meta().

Вышеописанным методом set_timepicker_options(array) данному полю можно передать параметры, которые подробно описаны на официальных сайтах данных модулей:

Color (цвет)

Поле для выбора цвета, основано на Iris.

Отображение поля для выбора цвета в админке

Цвета представлены шестью шестнадцатеричными цифрами с префиксом # (например, белый - #FFFFFF)

Создание поля

Field::make( 'color', 'my_color', 'Выберите цвет' )

Вывод значения поля

Это обычное текстовое поле, потому значения его выводятся точно также, как и у Text - с помощью carbon_get_post_meta().

Пример изменения фона заголовка сайта у темы twentysixteen:

function my_styles_method() {
	// #FF0000
	$color      = carbon_get_theme_option('my_title_color');
	$custom_css = "
		.site-branding .site-title a{
			background: {$color};
		}
	";
	wp_add_inline_style( 'twentysixteen-style', $custom_css );
}

add_action( 'wp_enqueue_scripts', 'my_styles_method' );

Checkbox (одиночный чекбокс)

Поле для одного флажка и меткой рядом с ним. Данное поле работает по принципу Правда/Ложь, Да/Нет и т.д.

Отображение поля с одним флажком в админке

set_option_value( $value )

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

Создание поля

Field::make("checkbox", "crb_show_sidebar", "Показать сайдбар")
				  ->set_option_value('yes')// Не обязательно. По умолчанию ``yes``

Вывод значения поля

Значение этого поля выводится точно также, как и у поля типа Text. В подавляющем случае не важно, какое значение хранится в поле, главное его наличие. Если в поле что-то есть - делаем первое, если ничего нет - второе. На примера кода выше формируем логику нашего скрипта:

if ( carbon_get_the_post_meta('crb_show_sidebar') ){
	// Показываем сайдбар
}
else {
	// Ничего не делаем или делаем что-либо взамен отсутствия сайдбара
}

Select (выпадающий список)

Создает выпадающий список, в котором можно выбрать только один вариант ответа.

Отображение выпадающего списка в админке

Создание поля

Field::make("select", "crb_adv_side", "Расположение блока с рекламой")
				  ->add_options(array(
					  'top' => 'Перед контентом',
					  'sidebar' => 'В сайдбаре',
					  'bottom' => 'После контента',
				  ))

Вывод значения поля

Значение этого поля выводится точно также, как и у поля типа Text и является ключом массива. То есть если было выбрано "В сайдбаре", то carbon_get_the_post_meta('crb_adv_side') вернет sidebar.

Добавление пунктов выпадающего списка

add_options( $options )

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

Установка значения по умолчанию

set_options( $options )

Метод, который задаёт выпадающему списку значение по умолчанию.

Метод set_options() должен вызываться первым, иначе перезатрёт массив значений в add_options(). Удобнее использовать привычный метод set_default_value().

Правильный пример:

Field::make( "select", "crb_adv_side", "Расположение блока с рекламой")
				 ->set_options(array('sidebar' => 'В сайдбаре'))
				 ->add_options(array(
					  'top' => 'Перед контентом',
					  'bottom' => 'После контента',
					  'sidebar' => 'В сайдбаре надо мне!',
				 ))

В данном примере ключ массива аргумента в set_options() совпал с одним из ключом в add_options(), потому текст пункта списка будет перезаписан и выбран по умолчанию.

Неправильный пример:

Если же поменять местами методы, то выпадающий список будет состоять лишь из 1 пункта "В сайдбаре":

Field::make("select", "crb_adv_side", "Расположение блока с рекламой")
				 ->add_options(array(
					  'top' => 'Перед контентом',
					  'bottom' => 'После контента',
					  'sidebar' => 'В сайдбаре надо мне!',
				 ))
			->set_options(array('sidebar' => 'В сайдбаре'))

Если передается индексированный массив (без ключа), будут использованы индексы по умолчанию (0, 1, 2 ...) элементов.

Ещё пример

Создание поля:

<?php
use Carbon_Fields\Container;
use Carbon_Fields\Field;

Container::make( 'theme_options', 'Настройки темы' )
		 ->add_fields( array(

			 Field::make( "select", "money", "В какой валюте отображать награду?" )
				  ->add_options( array(
					  'tugrik'  => 'Тугрики',
					  'fantik'  => 'Фантики',
					  'monetka' => 'Монетки',
				  ) )

		 ) );

Вывод значений:

$money = carbon_get_theme_option('money');

if( $money === false  )
	$text = 'Награда не предусмотрена';

if( $money == 'tugrik' )
	$text = 'Награда: 1 Тугрик';

if( $money == 'fantik' )
	$text = 'Награда: 5 Фантиков';

if( $money == 'monetka' )
	$text = 'Награда: 10 Монеток';

echo "<p>$text</p>";

Пример - как отображать на главной записи только из определенной рубрики:

<?php
use Carbon_Fields\Container;
use Carbon_Fields\Field;

$categories = get_categories();

$cats[0] = 'Показать все';

if ( $categories ) {
	foreach ( $categories as $cat ) {
		$cats[ $cat->term_id ] = $cat->name;
	}
}

Container::make( 'theme_options', 'Настройки темы' )
		 ->add_fields( array(

			 Field::make( "select", "show_cat", "Рубрика" )
				  ->add_options( $cats )

		 ));

function show_cat( $query ) {
	if ( $query->is_front_page() && $query->is_main_query() ) {
		$query->set( 'cat', carbon_get_theme_option('show_cat') );
	}
}
add_action( 'pre_get_posts', 'show_cat' );

Radio (радиокнопки)

Выводит поле с радиокнопками. Соответственно, позволяет выбрать только один вариант ответа. Поле создается и принимает те же методы, как и Select (выпадающий список). Разница лишь в визуальном оформлении.

Отображение радиокнопок в админке

Создание поля

Field::make( "radio", "crb_adv_side", "Расположение блока с рекламой" )
				  ->add_options( array(
					  'top'     => 'Перед контентом',
					  'sidebar' => 'В сайдбаре',
					  'bottom'  => 'После контента',
				  ) )

Вывод значения поля

Значение этого поля выводится точно также, как и у поля типа Text и является ключом массива. То есть если было выбрано "В сайдбаре", то carbon_get_the_post_meta('crb_adv_side') вернет sidebar.

Set (множественный чекбокс)

Создает список из флажков, каждый из которых может быть выбран. Данный вид поля принимает все методы типов полей Select и Radio.

Отображение множественного чекбокаса в админке

limit_options( $count )

С помощью этого метода можно ограничить количество выводимых пунктов. Остальные пункты будут скрыты и отображены только по нажатию кнопки "Показать все варианты":

Результат работы метода limit_options у множественного чекбокса

Field::make( "set", "crb_adv_side", "Расположение блока с рекламой" )
				  ->add_options( array(
					  'top'     => 'Перед контентом',
					  'bottom'  => 'После контента',
					  'sidebar' => 'В сайдбаре',
				  ) )
				  ->limit_options( 1 ) // Сколько пунктов отобразить?

Вывод значений

Значение поля представляет собой индексируемый массив с вариантами ответов в виде ключей массива, передаваемого в метод add_options(). К примеру, если мы выбрали "После контента" и "В сайдбаре", то данные будут храниться в таком виде:

array(2) {
  [0]=>
  string(6) "bottom"
  [1]=>
  string(7) "sidebar"
}
$crb_adv_side = carbon_get_the_post_meta('crb_adv_side');

if( in_array('top', $crb_adv_side) ){
	// Это событие не произойдет, так как мы в примере не выбрали флажок 'Перед контентом'
	echo 'Реклама ПЕРЕД контентом статьи';
}

if( in_array('sidebar', $crb_adv_side) ){
	echo 'Реклама в сайдбаре';
}

if( in_array('bottom', $crb_adv_side) ){
	echo 'Реклама ПОСЛЕ контента статьи';
}

Relationship (связь)

Это поле позволяет выбрать и упорядочить сообщения любого типа сообщений. Полезно для создания связей между любыми типами записей.

Field::make('relationship', 'crb_relationship')
	->set_post_type('post') // Не обязательно, так как по умолчанию 'post'
set_post_type( $type )

Этот метод позволяет указать какой тип записей отображать для выбора, к примеру post (по умолчанию), page или произвольный тип записи. Можно передать массив с перечислением типов записей:

Field::make('relationship', 'crb_relationship')
	->set_post_type(['post', 'page']) // Загрузит в список для выбора записи и страницы

Если постов в выбранном типе записи много, то загрузка страницы, где отображается данный вид поля заметно притормаживает, так как собирает информацию для вывода по каждому посту. К примеру, на сайте с 5 000 записей страница с этим полем грузится в течение 1-2 секунды (php7, HDD).

set_max( $max )

Этот метод , где $max число - ограничивает количество постов, которые могут быть выбраны. Если при выборе количество выбранных постов превышает разрешенное - пользователь получит соответствующее предупреждение и лишний пункт не добавится в список выбранных.

Field::make('relationship', 'crb_relationship')
	->set_max(5) // Можно будет выбрать только 5 постов
allow_duplicates( $allow )

Этот метод ограничивает возможность добавление в набор одинаковых постов.

  • $allow = false - запрещено выбирать одинаковые посты (по умолчанию)
  • $allow = true - разрешено выбирать одинаковые посты
Field::make('relationship', 'crb_relationship')
	->allow_duplicates(true) // разрешено выбирать одинаковые посты

Вывод значений

Данные хранятся в метаполе в виде нумерованного массива, где каждый элемент массива упорядочен так, как было выбрано в админке:

array(5) {
  [0]=> string(2) "13"
  [1]=> string(4) "1088"
  [2]=> string(4) "1090"
  [3]=> string(4) "1092"
  [4]=> string(4) "1086"
}

Поэтому пропускаем их через foreach и на основе ID поста получаем нужную информацию, к примеру сформируем блок "Похожие статьи":

// Получаем массив с ID выбранных в админке постов
$post_ids = carbon_get_the_post_meta( 'crb_relationship' );
?>

<div class="relation-post">

	<ul class="posts-list">
	<?
	foreach ( $post_ids as $post_id ) {
		printf( '<li><a href="%s">%s</a></li>', get_permalink( $post_id ), get_the_title( $post_id ) );
	}
	?>
	</ul>

</div>

У данного поля много хуков, позволяющих вмешаться в его работу и добиться нужного результата.

Association (ассоциации)

Ассоциации - расширенная версия поля Relationship. Здесь можно указать для выбора пост, терм, пользователя или комментарий.

Отображение поля ассоциаций в админке

Методы поля Relationship также применимы к данному виду поля, потому читайте о них выше.

Создание поля

Field::make('association', 'crb_association')
	->set_types(array(
	  array(
		'type' => 'post',
		'post_type' => 'page',
	  ),
	  array(
		'type' => 'post',
		'post_type' => 'post',
	  ),
	  array(
		'type' => 'term',
		'taxonomy' => 'category',
	  ),
	  array(
		'type' => 'term',
		'taxonomy' => 'post_tag',
	  ),
	  array(
		'type' => 'user',
	  ),
	  array(
		'type' => 'comment',
	  ),
	))

Вывод значений

Если вывести значение поля привычным carbon_get_the_post_meta( 'crb_association' ), то получим:

array(5) {
  [0]=>  string(2) "13"
  [1]=>  string(4) "9540"
  [2]=>  string(1) "1"
  [3]=>  string(2) "16"
  [4]=>  string(2) "88"
}

Так как в поле могут использоваться различные объекты WordPress, то знание ID объекта ничего не даёт. Например, ID пользователя и ID поста могут быть одинаковы, что выводить в данном случае? Поэтому для данного поля предусмотрен параметр association, который указывает carbon_get_the_post_meta() возвращать данные о принадлежности поля:

$association = carbon_get_the_post_meta( 'crb_association', 'association' );

var_dump( $association );
/*
array(5) {
  [0]   =>  array(3) {
	["id"]      => string(2) "13"
	["type"]        => string(4) "post"
	["post_type"]   => string(4) "page"
  }
  [1]   =>  array(3) {
	["id"]      => string(4) "9540"
	["type"]        => string(4) "post"
	["post_type"]   => string(4) "post"
  }
  [2]   =>  array(2) {
	["id"]      => string(1) "1"
	["type"]        => string(4) "user"
  }
  [3]   =>  array(2) {
	["id"]      => string(2) "16"
	["type"]        => string(7) "comment"
  }
  [4]   =>  array(3) {
	["id"]      => string(2) "88"
	["type"]        => string(4) "term"
	["taxonomy"]    => string(8) "category"
  }
}
*/

Теперь у нас все карты на руках, чтобы отделить зерна от плевел:

$association = carbon_get_the_post_meta( 'crb_association', 'association' );

foreach ( $association as $item ) {

	// Пост (записи, страницы и т.д.)
	if ( $item['type'] == 'post' ) {
		// получаем данные поста по его ID
		$post = get_post( $item['id'] );
	}

	// Термы (рубрики, теги и т.д.)
	if ( $item['type'] == 'term' ) {
		// получаем данные терма по его ID
		$term = get_term( $item['id'] );
	}

	// Комментарии
	if ( $item['type'] == 'comment' ) {
		// получаем данные комментария по его ID
		$comment = get_comment( $item['id'] );
	}

	// Пользователи
	if ( $item['type'] == 'user' ) {
		// получаем данные пользователя по его ID
		$user = get_user_by( 'id', $item['id'] );
	}

}

У данного поля много хуков, позволяющих вмешаться в его работу и добиться нужного результата.

File (файл)

Отображает поле загрузки файла с миниатюрой предварительного просмотра загруженного файла. Используется встроенный интерфейс управления файлами WordPress.

Отображение поля для загрузки файла в админке

set_type( $mime_type )

Этот метод устанавливает допустимый для выбора тип файлов. $mime_type по умолчанию пустой и для выбора доступны любые файлы медиабиблиотеки, но может быть: audio, video, image.

set_value_type( $value_type )

Этот метод указывает, как хранить значение поля. $value_type по умолчанию id, но можно изменить на url, чтобы получать затем ссылку на файл, а не его ID.

Полный список доступных аргументов: alt, author, caption, dateFormatted, description, editLink, filename, height, icon, id, link, menuOrder, mime, name, status, subtype, title, type, uploadedTo, url, width.

Создание поля

Field::make("file", "crb_price_list", "Каталог цен (PDF)")
				  ->set_value_type('url') // сохранить в метаполе ссылку на файл

Вывод значения

Так как в примере мы указали хранить в произвольном поле ссылку на файл, то вывод её будет осуществляться таким образом:

$file = carbon_get_the_post_meta( $post_id, 'crb_price_list' );

// Проверяем, есть ли значение в произвольном поле
if( $file ){
	printf('<a href="%s">Скачать прайс-лист</a>', $file);
}

Image (изображение)

Отображает кнопку загрузки изображения. Если изображение прикреплено, то отображается его миниатюра. Используется встроенный интерфейс управления файлами WordPress.

Смотрите видеоурок к полю File, там также рассказывается о поле Image.

Поддерживаемые форматы изображений: jpg, jpeg, gif, png и bmp.

Поле Image является полным аналогом поля File, потому ему доступны все те же методы. Различие лишь одно - при открытии медиабиблиотеки видны только изображения, так как по умолчанию метод set_type('image').

Создание поля

Field::make("image", "photo", "Фото")

Вывод поля

// получим ID картинки из метаполя термина
$thumbnail_id = carbon_get_term_meta( $term_id, 'photo');

// или получим ID картинки из метаполя поста
$thumbnail_id = carbon_get_post_meta($post_id, 'photo');

// И так далее, функция получения зависит от контейнера

// ссылка на полный размер картинки по ID вложения
thumbnail_url = wp_get_attachment_image_url( $thumbnail_id, 'full' );
?>

<!-- выводим миниатюру рубрики на экран -->
<img src="<?php echo $thumbnail_url; ?>" alt="" />

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

Map (карта Google)

Поле в виде карты от Google и полем для поиска объекта.

Отображение поля карты Google

Создание поля

Field::make("map", "crb_company_location", "Местоположение")
	->help_text('Перетащите указатель на карту, чтобы выбрать местоположение')

Вывод значения

К примеру, если выбрать "Москва" на карте, то данные будут следующими:

// С передачей 3 аргумента в виде 'map'
$map_data = carbon_get_post_meta($post->ID, 'crb_company_location', 'map');

var_dump($map_data);

// Выведет
array(4) {
  ["lat"]     => float(55.755826)
  ["lng"]     => float(37.6173)
  ["address"] => string(12) "Москва"
  ["zoom"]    => int(10)
}

// Без 'map'
$map_data = carbon_get_post_meta($post->ID, 'crb_company_location');

var_dump($map_data);

// Выведет
string(17) "55.755826,37.6173"

Хранение информации

Данные карты Google в таблице *_postmeta хранятся как совокупность нескольких метаполей.

Хранение данных карты Google в базе данных

В таблице приведены аргументы (названия полей) для функции carbon_get_post_meta(), позволяющие получить только нужное значение:

$field_name(строка)
Долгота и широта. Такое пример мы рассмотрели выше.
$field_name . '-lat'(число с плавающей запятой)
Широта.
$field_name . '-lng'(число с плавающей запятой)
Долгота.
$field_name . '-address'(строка)
Адрес.
$field_name . '-zoom'(число)
Уровень приближения.

В нашем примере имя поля crb_company_location, значит получить только адрес c помощью функции carbon_get_post_meta() (или её производных) можно так:

// С помощью функции Carbon Fields
$address = carbon_get_post_meta( $post->ID, 'crb_company_location-address' );

// С помощью нативной функции самого WordPress
$address = get_post_meta( $post->ID, '_crb_company_location-address', true );

Google Maps API

Carbon Fields в своём коде уже содержит ключ, необходимый для работы с Google Maps API. Если вы хотите использовать свой личный ключ, то вставьте данный код в файл своей темы или плагина:

add_action( 'carbon_map_api_key', 'crb_get_gmaps_api_key' );
function crb_get_gmaps_api_key( $current_key ) {
	return 'впишите сюда свой ключ';
}

Методы

Чтобы изначально отцентрировать карту на нужном объекте используйте метод

set_position( $lat, $lng, $zoom )
$lat(строка/число) (обязательный)
Ширина. Значение проходит через функцию floatval().
По умолчанию: 40.346544
$lng(строка/число) (обязательный)
Долгота. Значение проходит через функцию floatval().
По умолчанию: -101.645507
$zoom(число) (обязательный)
Уровень приближения от 0 (мир) до 20 (здания).
По умолчанию: 10

Separator (разделитель)

Создает визуальный разделитель между соседними полями.

Данный вид поля выполняет лишь визуальную функцию и ничего не принимает и не сохраняет.

Создание поля

// Общий вид
Field::make("separator", "crb_style_options", "Текст")

/* Пример как на скриншоте */
Field::make("separator", "crb_style_options_simple", "Простые настройки"),

Field::make('text', 'crb_text_1', 'Поле №1'),

Field::make("separator", "crb_style_options_hard", "Сложные настройки"),

Field::make('text', 'crb_text_2', 'Поле №2')

Текст имеет следующие стили, описанные в файле /carbon-fields/assets/bundle.css:

#poststuff .carbon-Separator h3, .carbon-Separator h3 {
	padding: 0;
	font-size: 28px;
	margin: 0;
	line-height: 1;
}

.carbon-container h3 {
	font-size: 17px;
	font-weight: 200;
	margin: 0 0 4px;
	color: #24282d;
}

Чтобы их переопределить, создайте свой файл CSS и подключите через функцию wp_enqueue_script() в момент срабатываниях хука admin_enqueue_scripts.

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

Не забывайте, вы можете создать панель виджетов и с помощью нативной функции register_sidebar.

Создание поля

Field::make("sidebar", "crb_custom_sidebar", "Выберите виджет")

Методы

disable_add_new()

Убирает возможность добавлять новые боковые панели на сайте, то есть пункт "Добавить новый" исчезает.

exclude_sidebars( $sidebars )

Добавляет возможность исключения одной или нескольких панелей виджетов из меню выбора. Параметр $sidebars может быть массивом (из ID или имени панели) или строкой (из ID или имени панели).

Вывод значений

Сайдбар можно вывести с помощью wordpress функции dynamic_sidebar:

if ( $sidebar = carbon_get_post_meta( get_the_ID(), 'crb_custom_sidebar') ){
	dynamic_sidebar( $sidebar );
}

Разработчики Carbon Fields предлагают использовать их функцию crb_dynamic_sidebar() вместо dynamic_sidebar().

Функция crb_dynamic_sidebar() не включена в плагин (библиотеку), поэтому вы должны самостоятельно объявить её в своей теме или плагине.

Функция перезаписывает параметры боковой панели и выводит виджеты боковой панели с указанным идентификатором.

// Объявляем функцию в файле темы или плагина
function crb_dynamic_sidebar($index = 1, $options = array()) {
	global $wp_registered_sidebars;

	// Получаем индекс боковой панели (панели виджетов), также как и dynamic_sidebar()
	if ( is_int($index) ) {
		$index = "sidebar-$index";
	} else {
		$index = sanitize_title($index);
		foreach ( (array) $wp_registered_sidebars as $key => $value ) {
			if ( sanitize_title($value['name']) == $index ) {
				$index = $key;
				break;
			}
		}
	}

	// Проверяем, существует ли такая боковая панель
	if ( empty( $wp_registered_sidebars[$index] ) ) {
		return false;
	}

	// Получаем текущие параметры боковой панели
	$sidebar = $wp_registered_sidebars[$index];

	// Обновляем параметры боковой панели
	$wp_registered_sidebars[$index] = wp_parse_args($options, $sidebar);

	// Отображаем сайдбар
	$status = dynamic_sidebar($index);

	// Восстанавливаем исходные параметры боковой панели
	$wp_registered_sidebars[$index] = $sidebar;

	return $status;
}

// Выводим сайдбар в нужном месте шаблона
if ( $sidebar = carbon_get_post_meta( get_the_ID(), 'crb_custom_sidebar') ){
	crb_dynamic_sidebar( $sidebar );
}

В чем преимущество crb_dynamic_sidebar() перед dynamic_sidebar() пока не понятно.

Данные о произвольных сайдбарах

Данные поля хранятся в таблице *_options в виде сериализованного массива:

Хранение данных поля для выбора сайдбара в базе данных

Используя нативную функцию get_option для запроса значений опций мы можем получить данные в виде массива:

// Получаем значений опции
$custom_sidebars = get_option('carbon_custom_sidebars');
var_dump($custom_sidebars);

// Вернет
array(1) {
  ["moj-sajdbar"] => array(2) {
	["id"] => string(11) "moj-sajdbar"
	["name"] => string(21) "Мой сайдбар"
  }
}

Header Scripts

Доступно только для контейнера настроек темы! Если указать другой контейнер, то поле отобразиться и данные будут сохраняться, но выводиться автоматически не будут.

Отображение текстовой области, содержимое которой будет автоматически выведено в секции <head> каждой страницы сайта.

Отображение поля для ввода js и css в админке для head

Полезно для вывода пользовательских javascript (например, кода Яндекс.Метрики или Гугл.Аналитикс), а также стилей, метатегов и т. д.

Создание поля

Field::make("header_scripts", "crb_header_script")

Вывод значения

Вывод данных происходит во время срабатывания хука wp_head, поэтому в теме обязательно должна быть прописана функция wp_head().

Доступно только для контейнера настроек темы! Если указать другой контейнер, то поле отобразиться и данные будут сохраняться, но выводиться автоматически не будут.

Отображение текстовой области, содержимое которой будет автоматически выведено перед каждой страницы сайта.

Отображение поля для ввода js и css в админке для footer

Полезно для вывода пользовательских javascript (например, кода Яндекс.Метрики или Гугл.Аналитикс), а также стилей.

Создание поля

Field::make("footer_scripts", "crb_footer_script")

Вывод значения

Вывод данных происходит во время срабатывания хука wp_footer, поэтому в теме обязательно должна быть прописана функция wp_footer().

HTML

Отображает произвольный html в админке. В большинстве подобных плагинов такое поле называется "Сообщение", что полностью отражает его суть.

Отображение произвольного html в админке

В данное поле можно передать не только произвольный html, но и JS и CSS.

Создание поля

Field::make("html", "crb_information_text", 'Предупреждение')
		 ->set_html('<h1>Предупреждение для авторов</h1><p>Пишите, пожалуйста, без ошибок - вас будут читать грамотные люди.</p>')

Заголовок поля нигде не отображается и его можно не писать, служит лишь для более удобного чтения кода в последующем.

Вывод значения

Сообщение выводится в админке автоматически в том порядке, в котором оно объявлено относительно других полей контейнера.

Gravity Form

Выпадающее поле со списком форм, созданных в плагине Gravity Form (платный).

Если плагин Gravity Forms не установлен или не активирован, пользователю будет показано соответствующее сообщение.

Создание поля

Field::make("gravity_form", "crb_gravity_form", "Выберите форму")

Существует хук crb_gravity_form_options, который можно использовать для переопределения параметров, передаваемых в поле. Читайте о хуке crb_gravity_form_options в отдельной статье.

Сложные поля (комплексные, повторяемые)

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

Или нужно использовать заготовленные "макеты" полей, чтобы в зависимости от контекста выбирать их из админки. К примеру, авторы статей хотят после своих материалов делиться, чем они вдохновлялись: фильмом, музыкой, стихотворением, поэмой. В наших силах создать макеты под любой вид таких под-материалов и выводить каждый из них с индивидуальным оформлением.

Данный вид полей имеет несколько видов и описан в отдельной статье о комплексных полях в Carbon Fields.

72 комментария
Полезные 3Вопросы 1 Все
    Войти