add_settings_section()WP 2.7.0

Создает новый блок (секцию), в котором выводятся поля настроек. Т.е. в этот блок затем добавляются опции, с помощью add_settings_field().

Такой блок вы можете видеть на страницах настроек WordPress или плагинов - это группы настроек разделенные заголовком.

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

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

Хуков нет.

Возвращает

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

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

add_settings_section( $id, $title, $callback, $page );
$id(строка) (обязательный)
Идентификатор секции, по которому нужно "цеплять" поля к секции. Строка, которая будет использована для id атрибутов тегов.
$title(строка) (обязательный)
Заголовок секции.
$callback(callable|null) (обязательный)
Коллбэк (функция), которая заполняет секцию описанием. Вызывается перед выводом полей. См: do_settings_sections().
$page(строка) (обязательный)

Страница на которой выводить секцию.

Должен совпадать с параметром $page в do_setting_sections( $page );

Или может совпадать с параметром $menu_slug из add_menu_page(), add_theme_page(), add_submenu_page().

Обычно $page и $menu_slug называются одинаково.

Примеры ярлыков страниц WP: general, reading, writing, discussion, media, и т.д.

$args(массив) (WP 6.1)

Аргументы, используемые для создания раздела настроек. См. do_settings_sections().

Возможные элементы массива:

  • before_section(string) - HTML перед HTML секции.
  • after_section(string) - HTML после HTML секции. По умолчанию: ''.
  • section_class(string) - Имя класса для секции. Если этот параметр указан, то в before_section нужно указать плейсхолдер %s для sprintf() на месте которого появится указанный здесь класс. По умолчанию: ''.

По умолчанию: []

Примеры

1

#1 Демо

add_settings_section(
	'eg_setting_section',
	__( 'Example settings section in reading', 'textdomain' ),
	'wpdocs_setting_section_callback_function',
	'reading'
);

/**
 * Settings section display callback.
 *
 * @param array $args Display arguments.
 */
function wpdocs_setting_section_callback_function( $args ) {

	// echo section intro text here

	// id: eg_setting_section
	echo '<p>id: ' . esc_html( $args['id'] ) . '</p>';

	// title: Example settings section in reading
	echo '<p>title: ' . apply_filters( 'the_title', $args['title'] ) . '</p>';

	// callback: eg_setting_section_callback_function
	echo '<p>callback: ' . esc_html( $args['callback'] ) . '</p>';
}
1

#2 Пример использования в ООП виде (с классом php)

class custom_setting {

	function __construct() {
		/**
		 * register wp_setting_init to the admin_init action hook
		 */
		add_action('admin_init', array($this,'wp_setting_init'));
	}

	function wp_setting_init() {
		// register a new setting for "reading" page
		register_setting('reading', 'page_limit');

		// register a new section in the "reading" page
		add_settings_section(
			'wp_custom_setting_section',
			'WP Custom Setting Section',
			array($this,'wp_custom_setting_section_cb'),
			'reading'
		);
	}

	/**
	 * callback functions
	 */

	// section content cb
	function wp_custom_setting_section_cb() {
		esc_html_e('Page limit is 10','text-domain');
	}

}

new custom_setting();
0

#3 Еще примеры смотрите

Смотрите в примерах, на странице API настроек.

Заметки

  • Global. Массив. $wp_settings_sections Storage array of all settings sections added to admin pages.

Список изменений

С версии 2.7.0 Введена.
С версии 6.1.0 Added an $args parameter for the section's HTML wrapper and class name.

Код add_settings_section() WP 6.1.1

function add_settings_section( $id, $title, $callback, $page, $args = array() ) {
	global $wp_settings_sections;

	$defaults = array(
		'id'             => $id,
		'title'          => $title,
		'callback'       => $callback,
		'before_section' => '',
		'after_section'  => '',
		'section_class'  => '',
	);

	$section = wp_parse_args( $args, $defaults );

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

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

	$wp_settings_sections[ $page ][ $id ] = $section;
}