Основы использования

Meta Box

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

Создание метабоксов

Добавление метабоксов происходит на хуке rwmb_meta_boxes, например:

add_filter( 'rwmb_meta_boxes', 'prefix_register_meta_boxes' );
function prefix_register_meta_boxes( $meta_boxes ) {

	$prefix = 'field_prefix_';

	$meta_boxes[] = array(
		'id'         => 'personal',
		'title'      => 'Личная информация',
		'post_types' => 'post',
		'context'    => 'normal',
		'priority'   => 'high',

		'fields' => array(
			array(
				'name'  => 'Как Вас зовут?',
				'desc'  => 'Формат: {Имя} {Фамилия} {Отчество}',
				'id'    => $prefix . 'name',
				'type'  => 'text',
			),
		)
	);

	// Ещё метабоксы
	// $meta_boxes[] = ...

	return $meta_boxes;
}

В результате, на странице редактирования записи появится вот такой бокс:

Параметры метабокса

Каждый метабокс поддерживает следующие параметры:

id(строка)
ID метабокса. Если отсутствует, то будет создан из title, используя функцию sanitize_title().
title(строка) (обязательный)
Заголовок метабокса.
post_types(строка/массив)
Тип или типы постов, для которых отображать метабокс. Если тип поста один, то передавать в виде строки, если несколько - в массиве. Обязательно писать с маленькой буквы, как в slug.
По умолчанию: post
style(строка)

В каком стиле показывать метабокс:

  • default - в стиле WP - контейнер с белым фоном.
  • seamless - контейнер без белого фона.
    По умолчанию: default
context(строка)

Где будет выведен метабокс. Возможные значения:

  • normal - под редактором контента. Значение по умолчанию.
  • advanced - под normal секцией.
  • side - справа в сайдбаре.
  • form_top вверху формы редактирования поста, над его заголовком. Добавлено в версии 4.13.0.
  • after_title - под заголовком поста, ниже ссылки на пост. Добавлено в версии 4.13.0.
  • after_editor - после редактора контента, но до normal секции, тем самым метабокс как бы прилипает к редактору контента. Добавлено в версии 4.13.0.
  • before_permalink - перед ссылкой на пост. Добавлено в версии 4.13.0.
priority(строка)
Приоритет блока для показа выше или ниже остальных блоков: high или low.
По умолчанию: default
autosave(true/false)
Сразу сохранять значения полей, без сохранения записи. true - да, false - нет.
По умолчанию: false
media_modal(true/false)
Добавлять или нет метаполя в модальное окно при просмотре или редактировании вложения. Работает, когда в post_types указано attachment.
По умолчанию: false
fields(массив)

Массив описывающий метаполя, которые будет содержать метабокс.

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

array(
	array(
		'id'    => 'name',
		'type'  => 'text',
		'name'  => 'ФИО',
		'desc'  => 'Формат: {Имя} {Фамилия} {Отчество}',
	),
)
  • id используется как мета ключ (meta_key) под которым будет сохраняться значение в таблице метаполей (wp_postmeta).
  • type определяет тип поля.
  • Описание остальных общих параметров поля смотрите ниже, в описании параметров fields.

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

validation(массив)

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

Чтобы включить проверку (валидацию), нужно добавить параметр validation, который в свою очередь имеет еще два параметра:

  • rules - правила проверок каждого поля. Правила для каждого поля описываются в виде вложенного массива.
  • messages - тексты сообщений об ошибках. Тот же формат, что и rules.

Для примера, давайте добавим два правила проверки для поля field_id: обязательное его заполнение и минимальная длина ввода 7 знаков.

'validation' => array(
	'rules'  => array(
		'field_id' => array(
			'required'  => true,
			'minlength' => 7,
			// другие правила
		),
		// правила для других полей
	),
	// сообщения об ошибках для проверок required и minlength
	'messages' => array(
		'field_id' => array(
			'required'  => 'Пароль обязателен!',
			'minlength' => 'Пароль должен быть не менее 7 символов.',
		),
		// сообщения для других полей
	)
),

Модуль валидации работает с помощью jQuery плагина jQuery Validation Plugin. Плагин поставляется в комплекте с полезным набором методов проверки и API для написания собственных методов. Сообщения об ошибках по умолчанию на английском языке, но имеют перевод на русский (и еще 36 других языков).

Список всех возможных правил проверки:
Название Описание
required Обязательно поле.
minlength Минимальное количество символов для ввода.
maxlength Максимальное количество символов для ввода.
rangelength Заданный диапазон количества символов. Массив.
min Минимальное значение.
max Максимальное значение.
range Заданный диапазон значений. Массив.
email Проверка на email.
url Проверка на ссылку.
date Проверка на дату.
dateISO Проверка даты в формате ISO.
number Проверка на десятичное число.
digits Требует только цифры.
creditcard Требует номер кредитной карты.
equalTo Требует, чтобы элемент был таким же, как другой. Значение должно быть идентификатором другого поля.
remote Запрашивает удаленные данные для проверки поля на валидность. Значением может быть ссылка на ресурс, куда будет послан запрос для получения данных валидации, или же объект с кастомизированными настройками запроса, смотрите jQuery.ajax. Запрос к серверу осуществляется через jQuery.ajax и получает ключ-значение (имя поля и его значение) в виде GET параметров. Ответ возвращается в виде JSON и должен быть true, если значение поля валидно, иначе false, undefined или null.

Подробнее о параметрах читайте в документации jQuery Validation Plugin.

default_hidden(логический)

По умолчанию метабокс скрыт (true) или нет (false). Отображение метабокса можно переключить, используя флажок в "Настройка экрана" (в верхнем правом углу).

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

Параметры fields (поля)

Ниже описаны общие параметры для всех типов полей. Однако у каждого поля могут быть свои индивидуальные параметры - они описаны на отдельной странице.

id(строка) (обязательный)
ID поля. Должен быть уникальным. Используется как meta_key при сохранении в базу данных. Хорошая практика - использовать только цифры, буквы и символы подчеркивания.
type(строка) (обязательный)

Тип поля (текстовое, галерея и т.д.). Список типов:

Тип поля Описание
autocomplete Текстовое поле с функцией автозаполнения.
background Устанавливает настройки фона. Добавлено в версии 4.13.0.
button Кнопка. Обычно используется для каких-либо действий на основе JavaScript.
button_group Выбор одного или нескольких вариантов, нажав кнопку (кнопки) из группы. Добавлено в версии 4.13.0.
checkbox Флажок (галочка).
checkbox_list Список флажков (галочек).
color Выбор цвета.
custom_html Произвольный HTML контент.
date Выбор даты.
datetime Выбор даты и времени.
divider Горизонтальная линия.
fieldset_text Группа текстовых полей.
file Выбор файла (или файлов) с жёсткого диска с использованием дефолтного оформления браузера, как <input type="file" />.
file_advanced Выбор файла (или файлов) из медиабиблиотеки с помощью всплывающего окна WordPress.
file_input Добавление файла через URL или выбор из медиабиблиотеки.
file_upload Загрузка файла через перетаскивание его в специальную область.
heading Заголовок.
hidden Скрытое текстовое поле.
image Такое же как file, только для изображений.
image_advanced Такое же как file_advanced, только для изображений.
image_select Такое же как radio + select, вместо радиокнопок используются изображения.
image_upload
plupload_image
Такое же как file_upload, только для изображений.
key_value Добавляет группу с неограниченным количеством пар ключ-значение. Своего рода клонируемое поле.
map Карта Google.
number Поле для ввода цифровых значений, HTML5 поле type="number".
oembed Вставка медиа элементов с сайтов, типа Youtube, Vimeo и других поддерживаемых WordPress.
password Поле для ввода пароля.
post Выпадающий список с постами, имеется поиск.
radio Радиокнопка.
range Ползунок HTML5.
select Выпадающий список.
select_advanced Красивый выпадающий список с использованием библиотеки select2.
single_image Выбор или загрузка одного изображения через всплывающее окно WordPress. Добавлено в версии 4.13.0.
slider Ползунок jQuery UI.
switch Переключатель в стиле iOS. Добавлено в версии 4.13.0.
taxonomy Выпадающий список с терминами выбранной таксономии. Не сохраняет ничего в метаданные. Дублирует функционал метабоксов "Рубрики" или "Метки", то есть устанавливает посту термины.
taxonomy_advanced Такое же, как taxonomy, но сохраняет ID выбранных терминов через запятую виде строки. Не устанавливает посту термины.
text Текстовое поле.
text_list Группа из текстовых полей. Похоже на fieldset_text.
textarea Текстовая область.
time Выбор времени.
user Выпадающий список с пользователями сайта, имеется поиск.
video Загружает или позволяет выбрать видео из медиабиблиотеки с помощью всплывающего окна WordPress.
wysiwyg Визуальный редактор WordPress.
name(строка)
Заголовок поля. Если оставить пустым, то поле ввода станет по ширине 100%.
desc(строка)
Описание поля, отображается под ним.
label_description(строка)
Описание заголовка (name), отображается под ним.
std(строка)
Значение поля по умолчанию.
before(строка)
Пользовательский html код, выводится до html поля.
after(строка)
Пользовательский html код, выводится после html поля.
multiple(логический)
Имеет ли поле несколько значений? Например, как это может делать поле select.
По умолчанию: false
clone(логический)

Является ли поле повторяемым, можно ли его клонировать.

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

Чтобы сделать поле повторяемым, нужно включить параметр - 'clone' => true. После этого под полем появится кнопка + (Add Clone):

$meta_boxes[] = array(
	'id'         => 'clients',
	'title'      => 'Информация о клиентах',
	'post_types' => 'post',

	'fields' => array(
		array(
			'name'       => 'Имя клиента',
			'id'         => 'fio',
			'type'       => 'text',
			// параметры клонируемого поля
			'clone'         => true,         // повторяемое поле
			'sort_clone'    => true,         // Можно ли сортировать клоны?
			'clone_default' => true,         // Клонировать значение по умолчанию?
			'add_button'    => '+ добавить', // Текст кнопки добавления клона.
			'max_clone'     => 10,           // Максимальное количество клонов. Число.
		),
	),
);

По умолчанию: false

clone_default(логический)
При clone = true. Копировать значение по умолчанию повторяемых полей?
По умолчанию: false
max_clone(число)
При clone = true. Максимальное число повторений поля.
По умолчанию: 0 (без ограничений)
sort_clone(логический)
При clone = true. Возможность перетаскивать и тем самым менять сортировку у повторяющихся полей.
По умолчанию: false
add_button(строка)
При clone = true. Текст кнопки повторяемого поля.
По умолчанию: + Add more
class(строка)
Пользовательский CSS класс.
attributes(массив)

Позволяет добавлять полям произвольные атрибуты для HTML тега, например data-* чтобы потом использовать его в в javasript.

Атрибуты доступны почти всем типам полей: text, url, email, checkbox, radio, date, time, datetime и т.д.

Параметр должен содержать массив в виде 'key' => 'value', где key - сам атрибут, а value его значение.

array(
	'id'   => 'name',
	'name' => 'Name',
	'type' => 'text',
	'attributes' => array(
		'disabled'  => true,
		'minlength' => 10,
		// Пример добавления атрибута `data-*`:
		'data-option1'  => 'value1',
		'data-option2'  => json_encode( array( 'key1'=>'value1', 'key2'=>'value2' ) ),
	),
),

class, disabled, required, readonly, maxlength и pattern - это общие атрибуты, которые зарегистрированы глобально, поэтому их можно указывать не внутри параметра attributes, а прямо в параметрах поля. Например:

array(
	'id'   => 'name',
	'name' => 'Name',
	'type' => 'text',
	// упрощенная установка напрямую, без обертки в 'attributes'
	'disabled'  => true,
	'required'  => true,
	'readonly'  => true,
	'maxlength' => true,
	'pattern'   => true,
),

По умолчанию: array()

Функции получения значений

В плагине предусмотрены несколько вспомогательных функций для получения данных метаполей:

rwmb_meta( $field_id, $args, $post_id )
Получает значение указанного поля. Обертка для двух следующих функций rwmb_get_value() и rwmb_the_value().
rwmb_get_value( $field_id, $args, $post_id )
Получает значение указанного поля. Тоже что и rwmb_meta().
rwmb_the_value( $field_id, $args, $post_id, $echo )
Выводит значение поля на экран. В отличии от rwmb_get_value() все выводит на экран в читаемом виде, и если, например, попытаться вывести значения checkbox list, то мы получим названия полей, а не их значения.
  • $field_id(строка) (обязательный)
    ID поля. Указывается в параметре id при регистрации поля.

  • $args(строка/массив)
    Дополнительные аргументы для некоторых типов полей (изображение, файл и т.д.). Можно указать в виде массива или строки в формате: param1=value1&param2=value2.
    По умолчанию: array()

  • $post_id(число/null)
    ID поста, метаполе которого надо получить. Если нет, используется текущий ID поста.
    По умолчанию: null
Код всех трех функций
/**
 * Get post meta.
 *
 * @param string   $key     Meta key. Required.
 * @param array    $args    Array of arguments. Optional.
 * @param int|null $post_id Post ID. null for current post. Optional.
 *
 * @return mixed
 */
function rwmb_meta( $key, $args = array(), $post_id = null ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $key, $args, $post_id );
	/*
	 * If field is not found, which can caused by registering meta boxes for the backend only or conditional registration.
	 * Then fallback to the old method to retrieve meta (which uses get_post_meta() as the latest fallback).
	 */
	if ( false === $field ) {
		return apply_filters( 'rwmb_meta', rwmb_meta_legacy( $key, $args, $post_id ) );
	}
	$meta = in_array( $field['type'], array( 'oembed', 'map' ), true ) ?
		rwmb_the_value( $key, $args, $post_id, false ) :
		rwmb_get_value( $key, $args, $post_id );
	return apply_filters( 'rwmb_meta', $meta, $key, $args, $post_id );
}

/**
 * Get post meta.
 *
 * @param string   $key     Meta key. Required.
 * @param array    $args    Array of arguments. Optional.
 * @param int|null $post_id Post ID. null for current post. Optional.
 *
 * @return mixed
 */
function rwmb_meta( $key, $args = array(), $post_id = null ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $key, $args, $post_id );
	/*
	 * If field is not found, which can caused by registering meta boxes for the backend only or conditional registration.
	 * Then fallback to the old method to retrieve meta (which uses get_post_meta() as the latest fallback).
	 */
	if ( false === $field ) {
		return apply_filters( 'rwmb_meta', rwmb_meta_legacy( $key, $args, $post_id ) );
	}
	$meta = in_array( $field['type'], array( 'oembed', 'map' ), true ) ?
		rwmb_the_value( $key, $args, $post_id, false ) :
		rwmb_get_value( $key, $args, $post_id );
	return apply_filters( 'rwmb_meta', $meta, $key, $args, $post_id );
}

/**
 * Display the value of a field
 *
 * @param  string   $field_id Field ID. Required.
 * @param  array    $args     Additional arguments. Rarely used. See specific fields for details.
 * @param  int|null $post_id  Post ID. null for current post. Optional.
 * @param  bool     $echo     Display field meta value? Default `true` which works in almost all cases. We use `false` for  the [rwmb_meta] shortcode.
 *
 * @return string
 */
function rwmb_the_value( $field_id, $args = array(), $post_id = null, $echo = true ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $field_id, $args, $post_id );
	if ( ! $field ) {
		return '';
	}
	$output = RWMB_Field::call( 'the_value', $field, $args, $post_id );
	/*
	 * Allow developers to change the returned value of field.
	 * For version < 4.8.2, the filter name was 'rwmb_get_field'.
	 *
	 * @param mixed    $value   Field HTML output.
	 * @param array    $field   Field parameters.
	 * @param array    $args    Additional arguments. Rarely used. See specific fields for details.
	 * @param int|null $post_id Post ID. null for current post. Optional.
	 */
	$output = apply_filters( 'rwmb_the_value', $output, $field, $args, $post_id );
	if ( $echo ) {
		echo $output; // WPCS: XSS OK.
	}
	return $output;
}

Кроме функций плагина, для получения значений можно использовать фукнции самого WP, для получения метаполей, это:

Получение или вывод значений полей

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

#1 Получение и вывод единственного значения

Допустим у нас есть поле с id my_date, и это простое текстовое поле: не multiple и не повторяемое. Тогда следующий код выведет конкретное значение поля в виде строки:

$value = rwmb_meta( 'my_date' );
echo $value;

#2 Получение и вывод поля с несколькими значениями

Допустим у нас есть поле типа checkbox_list в котором хранятся интересы - это multiple поле, поэтому оно вернет массив данных:

$interests = rwmb_meta( 'interests' );
foreach ( $interests as $interest ) {
	echo $interest;
}

Заметки для разработчиков

  • Если поле имеет одно значение, то rwmb_meta() возвращает его как есть, если поле имеет тип multiple или clone - возвращается массив.

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

  • Очень часто rwmb_meta() можно заменить функцией get_post_meta() для получения значения поля, так как она является лишь оберткой для get_post_meta() с некоторыми дополнениями, чтобы соответствовать тому, как плагин сохраняет метаднанные в базе данных.

  • Для некоторых полей rwmb_meta() добавляет дополнительные данные к возвращаемому значению (например, информацию об изображении), чтобы упростить работу разработчиков.

Читайте как устроена база данных Meta Box, чтобы лучше понимать когда и какие данные возвращаются.

Ошибка PHP: функция неопределенна

Если в теме или плагине используется функция rwmb_meta(), и возникла ситуация, когда Meta Box был отключен, php выдаст ошибку «Неопределенная функция rwmb_meta ...», а сайт перестанет работать...

Чтобы избежать подобных фатальных ошибок, добавьте в тему или плагин "заглушку":

if ( ! function_exists( 'rwmb_meta' ) ) {
	function rwmb_meta(){
		return false;
	}
}

Шоткод [rwmb_meta meta_key="key"]

Meta Box поддерживает вывод значения поля через шоткод. Это помогает вывести значение поля в контенте поста или виджета без редактирования файлов темы.

[rwmb_meta meta_key="field_id" post_id="15" ...]
Атрибуты шоткода
  • meta_key(обязательный)
    Ключ поля (ID).

  • post_id
    ID поста. Если не передан, будет использован ID текущего поста.

  • param
    Если передать другие атрибуты шоткоду, то эти атрибуты будут переданы функции rwmb_the_value() в качестве второго параметра $args. Шоткод работает на базе rwmb_the_value() - с теми же параметрами.