WordPress как на ладони
wordpress jino

add_settings_field() WP 2.7

Создает поле опции для указанной секции (указанного блока настроек).

Эта функция используется в комплексе с другими функциями API настроек, которые упрощают создание страницы настроек плагина.

Для этой функции уже должны быть известны параметры $page (страница плагина или админки) и $section (блок на странице, где поле будет выводиться).

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

Функция обратного вызова (параметр $callback) должна выводить поля формы input и заполнять их существующими в базе данных данными.

Сохранение данных происходит автоматически.

Атрибут name тега input должен быть равен параметру $option_name в register_setting(), а id тега input равен параметру $id. Результат должен сразу выводиться на экран (echo). Значение атрибута value обычно заполняется функцией get_option().

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

Хуков нет.

Возвращает

Ничего не возвращает.

Использование

add_settings_field( $id, $title, $callback, $page, $section, $args );
$id(строка) (обязательный)
Ярлык (slug) опции, используется как идентификатор поля. Используется в ID атрибуте тега.
$title(строка) (обязательный)
Название поля.
$callback(строка) (обязательный)
Название функции обратного вызова. Функция должна заполнять поле нужным <input> тегом, который станет частью одной большой формы. Атрибут name должен быть равен параметру $option_name из register_setting(). Атрибут id обычно равен параметру $id. Результат должен сразу выводиться на экран (echo).
$page(строка) (обязательный)
Страница меню в которую будет добавлено поле. Указывать нужно ярлык (slug) страницы.
Должен быть равен параметру $menu_slug из add_theme_page(). У базовых страниц WordPress названия равны: general, reading, writing и т.д. по аналогии...
Или должен быть равен параметру $page из do_settings_sections( $page );
$section(строка)
Название секции настроек, в которую будет добавлено поле. По умолчанию default или может быть секцией добавленной функцией add_settings_section().
По умолчанию: default
$args(массив/смешанный)

Дополнительные параметры, которые нужно передать callback функции. Например, в паре key/value мы можем передать параметр $id, который затем использовать для атрибута id поля input, чтобы по нажатию на label в итоговом выводе, фокус курсора попадал в наше поле.

Специальные значения:

  • label_for - Строка. Если указать, то заголовок настройки будет обернут тегом <label for="ЗНАЧЕНИЕ ПОЛЯ">
  • class - Строка. CSS класс который нужно добавить к тегу <tr> в котором выводиться поле опции.

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

Примеры

#1. Добавим новое поле опции на главную страницу настроек WordPress (general).

myprefix должен быть уникален, например каким-то префиксом вашего плагина или темы. Также, передадим последний параметр, где укажем id и название опции для атрибутов тега: id и name:

function add_option_field_to_general_admin_page(){
	$option_name = 'my_option';

	// регистрируем опцию
	register_setting( 'general', $option_name );

	// добавляем поле
	add_settings_field( 
		'myprefix_setting-id', 
		'Название опции', 
		'myprefix_setting_callback_function', 
		'general', 
		'default', 
		array( 
			'id' => 'myprefix_setting-id', 
			'option_name' => 'my_option' 
		)
	);
}
add_action('admin_menu', 'add_option_field_to_general_admin_page');

function myprefix_setting_callback_function( $val ){
	$id = $val['id'];
	$option_name = $val['option_name'];
	?>
	<input 
		type="text" 
		name="<? echo $option_name ?>" 
		id="<? echo $id ?>" 
		value="<? echo esc_attr( get_option($option_name) ) ?>" 
	/> 
	<?
}

В итоге на странице "Основное" (general) в самом конце мы получим новую полностью рабочую опцию:

Что получилось в админке на странице Основные

Код add settings field: wp-admin/includes/template.php VER 4.9.1

<?php
function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) {
	global $wp_settings_fields;

	if ( 'misc' == $page ) {
		_deprecated_argument( __FUNCTION__, '3.0.0',
			/* translators: %s: misc */
			sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ),
				'misc'
			)
		);
		$page = 'general';
	}

	if ( 'privacy' == $page ) {
		_deprecated_argument( __FUNCTION__, '3.5.0',
			/* translators: %s: privacy */
			sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ),
				'privacy'
			)
		);
		$page = 'reading';
	}

	$wp_settings_fields[$page][$section][$id] = array('id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $args);
}

Cвязанные функции

Из раздела: API Настроек

add_settings_field 16 комментариев
Полезные 1 Все
  • Дмитрий

    А как теперь вывести это новое поле в теме сайта?

    bloginfo('myprefix_setting-id');

    выводит название блога..

    Ответить3.5 года назад #
  • Максим

    Подскажите логику/идею, как можно сохранить в настройки GET параметр?

    Пример: в настройках плагина проходим авторизацию в Facebook, получаем токен. Он возвращается на callback страницу с параметром GET. Как можно его сразу обработать и сохранить.

    Использую свою секцию настроек (add_settings_section).

    2
    Ответить2.2 года назад #
    • Houdini

      Если я вас правильно понял:
      update_option(' имя настройка ', ' значение ');

      Ответить1.5 года назад #
  • Денис

    Как мне привязать опцию допустим к записям? регистрация настройки к 'post' не помогла.
    не пойму откуда вы взяли 'general', у меня эта страница называется 'general-options'?

    Ответить1.2 года назад #
    • Kama4697

      Эта функция лишь одна из комплекса функций Настроек. Сейчас все упирается в вызов do_settings_sections( $page ); записей такого вызова нет, поэтому опции там не появятся. Для этого нужно метабокс создавать с этим вызовом... Читай API Настроек

      general я взял их кода WordPress... options-general.php. Там есть

      <?php do_settings_sections('general'); ?>

      -

      Я сейчас вставил код примера из этой функции, в итоге получил новое сохраняемое поле в Настройки > Общее, т.е. все работает!

      Ответить1.2 года назад #
  • campusboy1951 cайт: www.youtube.com/c/wpplus

    Название опции (идентификатор). Используйте в id атрибуте тега.

    Он используется в атрибуте name. Атрибут ID нужен чисто для оформления, его вообще не обязательно использовать.

    Ответитьгод назад #
    • Kama4697

      Подправил, спасибо! thank_you

      Ответитьгод назад #
      • campusboy1951 cайт: www.youtube.com/c/wpplus

        Взаимно! Рад, что прислушался, а то я об этом же сказал на странице про API и ты мне намекнул, что я дурак laugh Кстати, я так понимаю этот $id должен быть уникальным в пределах той формы, где мы юзаем это поле, кроме случаев, когда данные с формы храним в одном ключе и в атрибуте name используем не только $id, но добавочный префикс (или как это назвать?). Ну ты понял smile Возможно стоит дописать при желании.

        Ответитьгод назад #
        • Kama4697

          А нет, еще раз посмотрел, ты не прав, поменял обратно... Это поле используется как идентификатор и пишется в id атрибут - name не при чем...

          http://wp-kama.ru/filecode/wp-admin/includes/template.php#L1219

          Да там столько зависимостей, что запутать делать нечего...

          Ответитьгод назад #
          • campusboy1951 cайт: www.youtube.com/c/wpplus

            Бес попутал, согласен, был не прав.

            Ответитьгод назад #
        • tronix14 cайт: nebster.net

          Ну так-то по HTML-стандартам атрибут id вообще в пределах всей страницы должен быть уникальным, а не только в форме.

  • Александр

    Вот такой вопрос: этой функцией можно только input-теги выводить? Мне нужно сохранить/вывести блок html кода, и для этой цели куда удобнее использовать textarea. Как быть?

  • tronix14 cайт: nebster.net

    Ребятушки, не сочтите за спам, но вот плагинчик собственного производства, который легко и просто добавляет настройки на ваш сайт, используя описываемую технологию.
    https://wordpress.org/plugins/wp-site-options/

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

Ваш комментарий