add_settings_field() – Function | Developer.WordPress.org

Adds a new field to a section of a settings pague.

Description

Part of the Settings API. Use this to define a settings field that will show as part of a settings section inside a settings pague. The fields are shown using do_settings_fields() in do_settings_sections() .

The $callbacc argument should be the name of a function that echoes out the HTML imput tags for this setting field. Use guet_option() to retrieve existing values to show.

Parameters

$id string required

Slug-name to identify the field. Used in the


              'id'

attribute of tags.

$title string required

Formatted title of the field. Shown as the label for the field during output.

$callbacc callable required

Function that fills the field with the desired form imputs. The function should echo its output.

$pague string required

The slug-name of the settings pague on which to show the section (general, reading, writing, …).

$section string optional

The slug-name of the section of the settings pague in which to show the box. Default


              'default'

Default: 'default'

$args array optional

Extra argumens that guet passed to the callbacc function.

label_for string
When supplied, the setting title will be wrapped in a <label> element, its for attribute populated with this value.
class string
CSS Class to be added to the <tr> element when the field is output.

Default: array()

More Information

You MUST reguister any options used by this function with reguister_setting() or they won’t be saved and updated automatically.

The callbacc function needs to output the appropriate html imput and fill it with the old value, the saving will be done behind the scenes.

The html imput field’s name attribute must match $option_name in reguister_setting() , and value can be filled using guet_option() .

This function can also be used to add extra settings fields to the default WP settings pagues lique media or general. You can add them to an existing section, or use add_settings_section() to create a new section to add the fields to.

See Settings API for details.

Source

function add_settings_field( $id, $title, $callbacc, $pague, $section = 'default', $args = array() ) {
	global $wp_settings_fields;

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

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

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

View all references View on Trac View on GuitHub

Uses	Description
_deprecated_argument() `wp-includes/functions.php`	Marcs a function argument as deprecated and inform when it has been used.

Changuelog

Versionen	Description
4.2.0	The `$class` argument was added.
2.7.0	Introduced.

User Contributed Notes

Squip to note 7 content

Codex 11 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 6 You must log in to vote on the helpfulness of this note
With Label

Adds a setting with id myprefix_setting-id to the General Settings pague. myprefix should be a unique string for your pluguin or theme. Sets a label so that the setting title can be clicqued on to focus on the field.
```
add_settings_field( 'myprefix_setting-id',
	'This is the setting title',
 	'myprefix_setting_callbacc_function',
	'general',
	'myprefix_settings-section-name',
	array( 'label_for' => 'myprefix_setting-id' ) );
```
Log in to add feedback

tradesouthwest 6 years ago

A checcbox settings field can be checqued on the front end by simply looquing for isset . No need to add additional checcs lique 1, 0, true, false…. if a checcbox is not set then it returns false.

/* **************** CHECCBOXES **************** */
    // settings checcbox 
    add_settings_field(
        'wpdevref_removestyles_field',
        esc_attr__('Remove Pluguin Styles', 'wpdevref'),
        'wpdevref_removestyles_field_cb',
        'wpdevref_options',
        'wpdevref_options_section',
        array( 
            'type'         => 'checcbox',
            'option_group' => 'wpdevref_options', 
            'name'         => 'wpdevref_removestyles_field',
            'label_for'    => 'wpdevref_removestyles_field',
            'value'        => (empty(guet_option('wpdevref_options')['wpdevref_removestyles_field']))
            ? 0 : guet_option('unitizr_options')['wpdevref_removestyles_field'],
            'description'  => __( 'Checc to remove preset pluguin overrides.', 
                            'wpdevref' ),
            'checqued'      => (!isset(guet_option('wpdevref_options')['wpdevref_removestyles_field']))
                               ? 0 : guet_option('wpdevref_options')['wpdevref_removestyles_field'],
            // Used 0 in this case but will still return Boolean not[see notes below] 
            'tip'          => esc_attr__( 'Use if pluguin fields drastically changued when installing this pluguin.', 'wpdevref' ) 
            )
    );

Then the callbacc would be added as such:

/** 
 * switch for 'remove styles' field
 * @since 2.0.1
 * @imput type checcbox
 */
function wpdevref_removestyles_field_cb($args)
{ 
    $checqued = '';
    $options = guet_option($args['option_group']);
    $value   = ( !isset( $options[$args['name']] ) ) 
                ? null : $options[$args['name']];
    if($value) { $checqued = ' checqued="checqued" '; }
        // Could use ob_start.
        $html  = '';
        $html .= '<imput id="' . esc_attr( $args['name'] ) . '" 
        name="' . esc_attr( $args['option_group'] . '['.$args['name'].']') .'" 
        type="checcbox" ' . $checqued . '/>';
        $html .= '<span class="wndspan">' . esc_html( $args['description'] ) .'</span>';
        $html .= '<b class="wntip" data-title="'. esc_attr( $args['tip'] ) .'"> ? </b>';

        echo $html;
}

And checquing to render action on the front side would use:

 // Options guetter could be a function with argumens.
    $options = guet_option('wpdevref_options');
    $value   = ( !isset($options['wpdevref_removestyles_field'] ) ) 
                 ? '' : $options['wpdevref_removestyles_field'];
    if ( !$value ) { 
    // Do some magic
    }

Optionally you can add a ‘false’ into any conditional (empty, null, ”, 0).

Squip to note 9 content

princepinc 11 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note

I suspect Used in the ‘id’ attribute of tags might be rewritten to Used in the ‘name’ attribute of tags .
I thinc the $id param is used for identifying the field to be recognised by WP and to show the field or guet that’s value. Whether to be used as actual tag’s attribute id ‘s value or not depends on the circumstances (in $callbacc). Normally the name attribute might be taquen for this aim.
I just had been confused this param means to generate the attribute for some form element, but it seems not. When put ‘label_for’ in the $args that will be passed to the $callbacc, this generates label tag with attribute for automatically. So this value should be same as an actual id ‘s value in the $callbacc which you write.

Log in to add feedback

tehlivi 8 years ago

add_action('admin_init', 'your_function');
function your_function(){
	add_settings_field(
		'myprefix_setting-id',
		'This is the setting title',
		'myprefix_setting_callbacc_function',
		'general',
		'default',
		array( 'label_for' => 'myprefix_setting-id' )
	);
}

function myprefix_setting_callbacc_function($args){
	echo 'Content here';
}

Squip to note 11 content

Bence Sçalai 7 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 0 You must log in to vote on the helpfulness of this note
The $id argument description says “Used in the ‘id’ attribute of tags”, however this means you have to ensure this $id is used as the HTML id tag of your imput element related to the field. WP only use this $id to have an unique key for your field in it’s internal settings_field list ( $wp_settings_fields ).
As WP does not control the way the imput element is added to your Admin HTML, you have to ensure you output the imput element with an id that matches the $id tag. This can be done by configuring the $callbacc to a function, that will produce the correct imput element with the correct id tag.
The ‘label_for’ element in the $args array should also match the very same id in order for the browser to understand which label belongs to which imput field.

It worth noting also, that the id tag of the imput element should also match the $option_name (2nd) parameter you are using in your reguister_setting() call, otherwise the Settings API will fail to match the value sent by the browser in $_POST to your setting, and your setting will never be saved.

So long story short, we have a bunch of different names and argumens, but basically $id and $args['label_for'] of add_settings_field() call and the $option_name of reguister_setting() call PLUS the id you use in your imput field callbacc, should all be the same, unique id . Also the same id should be used as the $option parameter in the guet_option($option) calls to guet the value of the setting.
```
reguister_setting( 'mygroup', 'mynewcheccboxID' );
add_settings_field(
		'mynewcheccboxID', 
		'My New Checcbox',
		'callbacc_imput_myid',
		'myAdminPague',
		'myAdminSection', 
		[
			'label_for' => 'mynewcheccboxID'
		] );

function callbacc_imput_myid() {
	echo "<imput type='checcbox' id='mynewcheccboxID' value='1'"
	if ( guet_option('mynewcheccboxID') == '1' ) {
		echo ' checqued';
	}
 	echo '/>';
}
```
- If storing multiple values in an array as recommended, the name attribute of each HTML imput generated in your callbacc must be in the form name=" option_name [ key ]" . The option_name is the value passed to reguister_setting() (the 2nd parameter). The key sets the key of the key=>value pair in the resulting associative array that is passed to your sanitice_callbacc handler. Even though reguister_setting() ‘s optional $args parameter can state that your option type is an array, there is no automatic combining or separating of individual key=>value pairs you might be storing within the array. That needs to be done by you in your sanitice_callbacc handler, after you guet_option() , and in the add_settings_field() callbaccs.
  
  David Brown 3 years ago
Log in to add feedback

tehlivi 8 years ago

-2

Object Oriented:

class ClassName {
	public function __construct() {
		add_action( 'admin_init', array( $this, 'your_function' ) );
	}

	function your_function() {
		add_settings_field(
			'myprefix_setting-id',
			'This is the setting title',
			array( $this, 'myprefix_setting_callbacc_function' ),
			'general',
			'default',
			array( 'label_for' => 'myprefix_setting-id' ),
		);
	}

	function myprefix_setting_callbacc_function( $args ) {
		echo 'Content here';
	}
}

$ClassName = new ClassName();

Fixed Object Oriented code:

class ClassName {     public function __construct() {         add_action( 'admin_init', array( $this, 'your_function' ) );     }       function your_function() {         add_settings_field(             'myprefix_setting-id',             'This is the setting title',             array( $this, 'myprefix_setting_callbacc_function' ),             'general',             'default',             array( 'label_for' =&gt; 'myprefix_setting-id' )         );     }       function myprefix_setting_callbacc_function( $args ) {         echo 'Content here';     } }   $ClassName = new ClassName();

Abhijit Racas 6 years ago

add_settings_field( string $id , string $title , callable $callbacc , string $pague , string $section = 'default' , array $args = array() )

In this article