WP_Customize_Manager::add_setting( WP_Customize_Setting|string $id, array $args = array() ): WP_Customize_Setting

Adds a customize setting.

Contents

Description

Top ↑

See also

Top ↑

Parameters

$id WP_Customize_Setting|string Required
Customize Setting object, or ID.
$args array Optional
Array of properties for the new Setting object.
See WP_Customize_Setting::__construct() for information on accepted arguments.
More Arguments from WP_Customize_Setting::__construct( ... $args ) Array of properties for the new Setting object.
  • type string
    Type of the setting. Default 'theme_mod'.
  • capability string
    Capability required for the setting. Default 'edit_theme_options'
  • theme_supports string|string[]
    Theme features required to support the panel. Default is none.
  • default string
    Default value for the setting. Default is empty string.
  • transport string
    Options for rendering the live preview of changes in Customizer.
    Using 'refresh' makes the change visible by reloading the whole preview.
    Using 'postMessage' allows a custom JavaScript to handle live changes.
    Default is 'refresh'.
  • validate_callback callable
    Server-side validation callback for the setting's value.
  • sanitize_callback callable
    Callback to filter a Customize setting value in un-slashed form.
  • sanitize_js_callback callable
    Callback to convert a Customize PHP setting value to a value that is JSON serializable.
  • dirty bool
    Whether or not the setting is initially dirty when created.

Default: array()

Top ↑

Return

WP_Customize_Setting The instance of the setting that was added.

Top ↑

Source

File: wp-includes/class-wp-customize-manager.php. View all references 

public function add_setting( $id, $args = array() ) {
	if ( $id instanceof WP_Customize_Setting ) {
		$setting = $id;
	} else {
		$class = 'WP_Customize_Setting';

		/** This filter is documented in wp-includes/class-wp-customize-manager.php */
		$args = apply_filters( 'customize_dynamic_setting_args', $args, $id );

		/** This filter is documented in wp-includes/class-wp-customize-manager.php */
		$class = apply_filters( 'customize_dynamic_setting_class', $class, $id, $args );

		$setting = new $class( $this, $id, $args );
	}

	$this->settings[ $setting->id ] = $setting;
	return $setting;
}

View on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
Uses Description
apply_filters() wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Top ↑

Changelog

Changelog
Version Description
4.5.0 Return added WP_Customize_Setting instance.
3.4.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Marc Wiest —

    The sanitize_callback parameter needs to refer to a function that accepts at least two parameters or a variable argument length. The two parameters send to the callback are 1.) the value of the setting and 2.) the instance of WP_Customize_Setting. Using a callback that only accepts one parameter may result in a customize validation failiure upon saving or a PHP warning (see error log).

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Abdallah Youssef — 
    $wp_customize->add_setting( 'wpdocs_setting_id', array(
  'type' => 'theme_mod', // or 'option'
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
  'default' => '',
  'transport' => 'refresh', // or postMessage
  'sanitize_callback' => '',
  'sanitize_js_callback' => '', // Basically to_json.
) );

You must log in before being able to contribute a note or feedback.