Adding Meta Fields to a Widget Sidebar Section in the Customizer

Authored by

On the Post Status Slack, an interesting question was raised by Richard Buff:

Another customizer question: I’m trying to add a custom control that’s meant to customize the appearance of a specific widget area (like change the background color). Example:

Add new control here to customize appearance of the widget area / sidebar

And I can do it, by passing the section id of that particular widget area (“sidebar-widgets-front-page-1”) when calling add_control. But because the customizer will hide any control in this panel/section that isnt an ‘active’ widget for the current view, my custom control gets hidden with CSS by default. Now I can certainly just unhide it with CSS…. but that seems hacky. Surely there is a better way? The fact that I can only find one other person on the entire internet asking this question leads me to think I’m approaching this wrong in the first place. Perhaps the Widgets panel in the customizer is only meant for customizing individual widgets…. and to customize actual widget areas, perhaps I should create my own custom section?

The fact is that the widget sidebar sections in the customizer were indeed only meant for to contain controls for individual widgets and the control at the bottom that contains the Add Widget button. Another challenge with the desire here is that Richard wants to add a control to the very top of the section before the section’s description itself (at least from his screenshot). The customizer API doesn’t directly allow you to register controls to appear here. However, this doesn’t mean that controls can’t be added there. (Also, better support for controls appearing outside of their normal contexts once core implements #38077, #37964, #30738.)

Check out this plugin which demonstrates a solution for implementing a control allows for the background color for a given sidebar to be managed: Customize Widget Sidebar Meta (on GitHub).

Here is a video showing the functionality:

Now, I’m currently at LoopConf 2.1 and yesterday I co-lead a workshop on the customizer, and during the afternoon I presented a deep-dive on the customizer JS APIs. It turns out that adding meta fields to a widget sidebar customizer section here provides a good demonstration of some the JS API, including:

  • Extending sections of a given type.
  • Dynamically creating controls with JavaScript.
  • Dynamically creating selective refresh partials with JavaScript.
  • Using partials as a construct for doing live preview even when server-side rendering isn’t necessary.

Another demonstration plugin I prepared for the workshop goes beyond these and tries to make use of as many of the JS API as possible: Customize Featured Content (on GitHub).

In the coming weeks I plan to write blog posts that deconstruct the various pieces of these example plugins to explain how they work and how you can use them to build advanced customizer plugins. I prepared presentation slides for the workshop that do just this, but they’re not in blog post form. Once these blog posts have been written and iterated on I then hope to reformulate them into the Customizer JavaScript API section of the Handbook, which is currently lacking on this topic. In the mean time, please take a look at the plugins and comment here with questions you have about how the customizer JavaScript works.

5 thoughts on “Adding Meta Fields to a Widget Sidebar Section in the Customizer”

  1. Hi Weston,

    I wanted to ask your opinion about one issue i have which is related to Customizer and widgets.

    I add a widget via the Customizer. It’s a simple widget, with basic loop, which displays 10 latest posts where each post have Featured Image. Because of the Featured Image, this widget run hundreds of queries, without the Featured Image the number of queries returns back to normal.

    It jumps from 36 to 123 as soon as i add Featured Image.

    It happens only when adding widgets and viewing the site via the Customizer, there is no such issue on the front end.

    Also tested with the default WP Recent Posts widget, the result was the same.

    Thank you.

    1. Vlad: Could you please post this question and sample widget code to WPSE? I have an answer for you but it would be better for posterity if the discussion was done in a more appropriate place.

  2. I was playing around with this, and I’m not able to get the live preview to refresh on the WordPress twenty-* themes. If I save the value and refresh the page the correct values are saved, so I’m not sure if things in core have changed revolving around how partials are done. If you have any links to changesets or suggestions/explanations, so I can better understand this that would be awesome! Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *