Using Customizer to add a CSS background image to widget in WordPress

March 25, 2016| 2 comments

Here is a guide to add a single background image to a widget using the Customizer in WordPress, I have written up on this topic before utilising some Genesis code used in the Altitude Pro theme to be able to use on other  Genesis themes but here I just want to break it down to one single image for any WordPress theme.

This is to get an easier understanding of how it works and so you can build on it for more.

Register and Position the Widget Area

<?php
add_action( 'widgets_init', 'genesischild_extra_widgets' );
/**
* Register new Widget area and position it after the header.
*/
function genesischild_extra_widgets() {
genesis_register_sidebar( array(
'id' => 'hero',
'name' => __( 'Hero Home Page', 'genesischild' ),
'description' => __( 'This is the Hero Home Page area', 'genesischild' ),
) );
}
add_action( 'genesis_after_header','genesischild_hero_widget' );
/**
* Position the Hero Area.
*/
function genesischild_hero_widget() {
genesis_widget_area( 'hero', array(
'before' => '<section class="herocontainer"><div class="wrap hero">',
'after' => '</div></section>',
));
}
view raw widget-register.php hosted with ❤ by GitHub

Add a New Panel, Section, Setting and Control for the Customizer

<?php
add_action( 'customize_register', 'genesischild_register_theme_customizer' );
/*
* Register Our Customizer Stuff Here
*/
function genesischild_register_theme_customizer( $wp_customize ) {
// Create custom panel.
$wp_customize->add_panel( 'featured_images', array(
'priority' => 70,
'theme_supports' => '',
'title' => __( 'Featured Images', 'genesischild' ),
'description' => __( 'Set background images for certain widgets.', 'genesischild' ),
) );
// Add Featured Image for Hero Widget
// Add section.
$wp_customize->add_section( 'hero_background' , array(
'title' => __( 'Hero Background','genesischild' ),
'panel' => 'featured_images',
'priority' => 20,
) );
// Add setting.
$wp_customize->add_setting( 'hero_bg', array(
'default' => get_stylesheet_directory_uri() . '/images/hero-bg.jpg',
) );
// Add control.
$wp_customize->add_control( new WP_Customize_Image_Control(
$wp_customize, 'hero_background_image', array(
'label' => __( 'Add Hero Background Here, the width should be approx 1400px', 'genesischild' ),
'section' => 'hero_background',
'settings' => 'hero_bg',
)
) );
}
view raw add-customizer-option.php hosted with ❤ by GitHub

This will give us a new panel area in the Customizer called Featured Images which has our new section called Hero Background which contains our add_setting and add_control which is the image itself, in the add_setting you will see a default location for the image and in the add_control is a label where you can publish a message to the user, in particular about size.

customizer-new-panel
customizer-new-panel

 

customizer-new-section
customizer-new-section

 

customizer-new-setting and control
customizer-new-setting and control

Create the CSS Output

<?php
add_action( 'wp_enqueue_scripts', 'genesischild_css' );
/**
* Output CSS for background image
*/
function genesischild_css() {
wp_enqueue_style( 'genesischild', get_stylesheet_directory_uri() . '/style.css' );
$handle = 'genesischild'; // Swap in your CSS Stylesheet ID
$css = '';
$hero_bg_image = get_theme_mod( 'hero_bg' ); // Assigning it to a variable to keep the markup clean.
$css .= ( !empty($hero_bg_image) ) ? sprintf('
.herocontainer {
background: url(%s) no-repeat center;
background-size: cover;
}
', $hero_bg_image ) : '';
if ( $css ) {
wp_add_inline_style( $handle , $css );
}
}
view raw output-css.php hosted with ❤ by GitHub

wp_add_inline_style is used to output the CSS with the $handle variable being passed the main CSS id handle of the theme. To get the URL of the background image get_theme_mod is used to retrieve the value of the add_settings name, in our example hero_bg

This value get_theme_mod( ‘hero_bg’) is then assigned to a variable which is used in the conditional statement for the CSS output – so if the value is not equal to blank it will output and use the URL for the background image in the inline CSS – if no image is chosen in the Customizer then it is equal to blank and no CSS will output.

The conditional statement is formatted using the ternary operator.

2 comments

  • Rupy
    4 years ago Reply

    Thanks it is really helpful

  • Jamie Ross
    9 years ago Reply

    Hello,
    Thank you for this tutorial. I’m wondering if you could clarify the steps and code if one is using the Agency Pro theme?

    I have 3 different custom widget areas that I registered using my functions.php file (each one configured to be displayed on a different page), and I’d like to allow the client to change the background image in the Customizer for those page. But I’m confused about the steps based on your tutorial how I would apply it to Agency Pro.

    Agency Pro already has a lib/customize.php file, but not a lib/output.php file – do I need to create output.php?
    Do I need to remove my new widget code from functions.php and put it in a file called widget-register.php?
    Would I also need to create an add-customizer-option.php file, or can I also put that code in functions.php?

    Thanks in advance.

Leave your comment