W3cubDocs

/WordPress

add_settings_section( string $id, string $title, callable $callback, string $page )

Add a new section to a settings page.

Description

Part of the Settings API. Use this to define new settings sections for an admin page. Show settings sections in your admin page callback function with do_settings_sections(). Add settings fields to your section with add_settings_field().

The $callback argument should be the name of a function that echoes out any content you want to show at the top of the settings section before the actual fields. It can output nothing if you want.

Parameters

$id

(string) (Required) Slug-name to identify the section. Used in the 'id' attribute of tags.

$title

(string) (Required) Formatted title of the section. Shown as the heading for the section.

$callback

(callable) (Required) Function that echos out any content at the top of the section (between heading and fields).

$page

(string) (Required) The slug-name of the settings page on which to show the section. Built-in pages include 'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using add_options_page();

More Information

The callback function receives a single optional argument, which is an array with three elements. Example:

add_settings_section(
	'eg_setting_section',
	'Example settings section in reading',
	'eg_setting_section_callback_function',
	'reading'
);
function eg_setting_section_callback_function( $arg ) {
	// echo section intro text here
	echo '<p>id: ' . $arg['id'] . '</p>';             // id: eg_setting_section
	echo '<p>title: ' . $arg['title'] . '</p>';       // title: Example settings section in reading
	echo '<p>callback: ' . $arg['callback'] . '</p>'; // callback: eg_setting_section_callback_function
}

Source

File: wp-admin/includes/template.php

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

	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 ] = array(
		'id'       => $id,
		'title'    => $title,
		'callback' => $callback,
	);
}

Changelog

Version Description
2.7.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/add_settings_section