Moving an “old format” Theme Customizer control to the new Backbone rendered format.
The problem
A recent interest in my old library for WordPress project and in particular for the multi image Theme Customizer control has moved me to deprecate the library set (now dating to a whole different era of my development skills and beliefs) and to extract the still valuable multi image control from it to a stand alone plugin.
Things are not that easy.
New ways
Recent changes to the Theme Customizer have deprecated the way the multi image control worked for a simple reason: times.
The “new way” to render a Theme Customizer control will use Backbone to pull in and render an Underscore template.
Back compatibility with “old way” controls is still there and perfectly working if those controls do not require any JavaScript code to run: mine does of course.
Moving the code
To begin I’ve laid out the new plugin registering its components and setting up a basic test for the custom control.
I’ve moved the code needed to render the control to an underscore template file and referenced it the function providing the template content on request.
Under the hood (so far)
What’s happening under the hood of the Theme Customizer, or at least that’s my understanding of it, is that the responsibility to render the control markup has transitioned to Backbone from PHP and this means:
- there is no control (pun) on the moment a Customizer control will be rendered on the page
- non WordPress core Customizer controls will be rendered after the core ones
- it’s asynchronous event fest and I better get there prepared
The last point in particular gave me some problems: before any user interaction with the control begins I need to set up the control to pick up those interactions binding event listeners to its UI: my old approach of waiting for the document to be ready ($(document).ready(function(){...});) did not work because Backbone was pulling in templates and rendering the Customizer controls after that.
Next
While a solution is in place for the above problem I still have issues saving the image selection: I will delve into the JavaScript side of things to make things work.