Customizer Background Control

This proof-of-concept plugin adds a background image control to the Customizer.

The background control consists of six possible settings:

• Image upload (required)
• Image ID
• Background repeat select box
• Background size select box
• Background attach select box
• Background position select box

How to Include the New Control

• Drop a copy of this repository folder into your theme or plugin
• Requirecustomizer-background-control.php from your theme or plugin

Example

/**
 * Register customizer panels, sections, settings, and controls.
 *
 * @since  1.0.0
 * @access public
 * @param  object  $wp_customize
 * @return void
 */
function background_image_customize_register( $wp_customize ) {

	// Load customizer background control class.
	require_once( trailingslashit( plugin_dir_path( __FILE__ ) ) . 'customize/class-customize-background-image-control.php' );

	// Register background control JS template.
	$wp_customize->register_control_type( 'Customize_Custom_Background_Control' );
	
	// Add Sections, Panels, Settings, and Controls Here
	
}
add_action( 'customize_register', 'background_image_customize_register' );

How to Add a Background Control

Although this is a single Customizer control, settings need to be registered for each field that displays (repeat, size, attach, etc). The only required setting is image_url. If a image_id setting is registered, the ID will also be saved.

I realize this is quite a bit of setting syntax for a single control. I experimented with auto-registering settings, but that made it difficult to use alternate defaults or sanitization.

Another approach might be to register a single setting and have the control save all the fields into a serialized array rather than individual settings. Defaults could be passed as an array in the when the setting is registered. This would definitely decrease the amount of syntax required to set up the control and seems a bit more elegant, I just haven't had time to experiment with it yet.

// Registers example_background settings
$wp_customize->add_setting( 'example_background_image_url', array(
	'sanitize_callback' => 'esc_url'
) );

$wp_customize->add_setting( 'example_background_image_id', array(
	'sanitize_callback' => 'absint'
) );

$wp_customize->add_setting( 'example_background_repeat', array(
		'default' => 'repeat',
		'sanitize_callback' => 'sanitize_text_field'
) );

$wp_customize->add_setting( 'example_background_size', array(
		'default' => 'auto',
		'sanitize_callback' => 'sanitize_text_field'
) );

$wp_customize->add_setting( 'example_background_position', array(
		'default' => 'center-center',
		'sanitize_callback' => 'sanitize_text_field'
) );

$wp_customize->add_setting( 'example_background_attach', array(
		'default' => 'scroll',
		'sanitize_callback' => 'sanitize_text_field'
) );

// Registers example_background control
$wp_customize->add_control(
	new Customize_Custom_Background_Control(
		$wp_customize,
		'example_background',
		array(
			'label'		=> esc_html__( 'Example Background', 'custom-background' ),
			'section'	=> 'custom_background_section',
			// Tie a setting ( defined via $wp_customize->add_setting() ) to the control.
			'settings'    => array(
				'image_url' => 'example_background_image_url',
				'image_id' => 'example_background_image_id',
				'repeat' => 'example_background_repeat',
				'size' => 'example_background_size',
				'attach' => 'example_background_attach',
				'position' => example_background_position
			)
		)
	)
);

Suggested Setting Defaults and Sanitization

Setting	Default	Sanitization
background_image_url	null	esc_url
background_image_id	null	absint
background_repeat	repeat	sanitize_text_field
background_size	auto	sanitize_text_field
background_attach	scroll	sanitize_text_field
background_position	center-center	sanitize_text_field