I’m currently working on a lengthy set of articles that are intended to provide an in-depth look at the WordPress Theme Customizer. Yes, there has been a lot of material already written on this subject.
Some of the best articles are:
- Otto’s guide to the WordPress Theme Customizer
- The comprehensive Codex article on the Theme Customization API
- And an open source example of how to use the Theme Customizer
And though I’ve done work with the Theme Customizer in the past, there have been a few gotchas that I’ve found when trying to work with the customer starting from the ground up.
I don’t plan to document them all here, but if you happen to be working with the Theme Customizer and you’re specifically trying to get the “Live Preview” function working and it’s not, perhaps this will help.
WordPress Theme Customizer: Always Include The Footer
Let’s say, for example, that you’re adding a new setting to the existing `colors` section of your – or any given – WordPress theme.
Before going any further, assume that for the purposes of the code below that I’m using one of WordPress’ provided sections for adding a new setting. Specifically, I’m using the `colors` section.
And the option that I want to introduce will allow the user to change the color of anchors across the entire site. Additionally, the changes should occur without the page refreshing which means that we’re going to need to hook into `customize_preview_init`
In order to do this, I’m going to define two functions:
- `tmx_register_theme_customizer` which is hooked to `customize_register`
- `tmx_customizer_live_preview` which is hooked to `customize_preview_init`
You can find these two functions in the following code both of which can live in your `functions.php` file.
From here, if you launch the Theme Customizer, then you’ll notice that this code will add a color picker to the Theme Customizer that allows the user to select the color they want to apply to the anchor’s throughout their site:
Now Do It Live!
But there’s a problem: We need to use JavaScript in order to take advantage of the color picker and apply it to the anchors.
Once you include this JavaScript file and then begin working with the color picker you may notice that although it’s supposed to be happening live, nothing is actually happening at all.
Or Not…!
If all is working well for you, then you’re good to go; however, if you’re not seeing any changes, then there’s a very subtle theme development practice that you’re likely missing and that would be the call to `wp_footer`:
Because we’re register the Theme Customizer JavaScript in the footer – which is how it should be done – the call to `wp_footer` must be present, so that the `customize_preview_init` can actually enqueue the JavaScript at the end of the file thus connecting the various components together.
Is That All?
For now, yes – here’s the Gist in its entirety; however, working with the Theme Customizer can be a bit of a mixed bag as it’s something that can actually replace the theme options panel, but it also requires that we re-think how we’re setting up our theme options.
In my upcoming series on the Theme Customizer, I plan to cover exactly that, but if you’ve hit a snag with Live Preview not working with your implementation of the Theme Customizer, check out the provided Gist and the code and see if that helps.
Leave a Reply
You must be logged in to post a comment.