WordPress Customizer is a great tool for users to preview how settings would change their site layout and design. When developing Themes, you should always use the WordPress Customizer. In this tutorial you will learn how to develop a WordPress Customizer custom control for creating flexible lists.

WordPress core has several customizer controls defined which you can use when defining the Customizer settings. If you develop your own themes or even plugins that will use the WordPress Customizer, I am sure that you will get into a situation where you will need to create a custom control.

Our Flexible List will be able to:

  • Add new items
  • Remove existing items
  • Confirm the items

When we confirm our items, the change will trigger the Customizer and we will be able to save it.

For this tutorial, I will assume that we will use this control in a theme. But you can easily implement the code inside your plugin by changing the path to the assets.

Customizer Custom Control Assets

In this fictional theme, I have a folder css where I will have the CSS files and also a folder js where I will put the JavaScript files. Our CSS file will be customizer-controls.css and our JavaScript file will be customizer-controls.js.

Create them and let them be empty. Now let’s enqueue them. Put this inside the theme’s functions.php:

Using the hook customize_controls_enqueue_scripts we are enqueueing the scripts and styles that will be only usable inside the WordPress Customizer.

CSS

Our CSS is really simple. It will only have one rule and that rule will define the remove button on each of our items.

JavaScript

Our JavaScript file will have a little more code. First, we will define the function serialize from Locutus because we will serialize our data which will be saved.

You can see that function’s code minified in our JavaScript file. Let’s now define our operations add, remove and confirm:

The element .list-control-add will get the ID of our control that is set as an attribute data-id. We are then appending a new list item to our control element. By doing it like this, we are ensuring that the code will work on more than one Customizer Custom Control Flexible List.

The element .list-control-confirm will also get the ID of our control and then get the values from all the inputs of that setting. Once that is done, the array is serialized and set in our hidden input. When that input value’s has been changed, the WordPress Customizer will be triggered so that our option can be saved.

The last element .list-control-remove will remove the current item we want to remove.

Customizer Custom Control Class

We now have all our assets set and we can create the actual class for our Customizer Custom Control Flexible List. You can add that code inside your theme’s functions.php:

This is really simple right? We are just extending the class WP_Customize_Control. The only thing we just need to set is the method render_content.

In this method we are iterating through values and displaying all the values as items. Notice also that we are first unserializing the data to get an actual array. Once we are done with that, we are serializing it again and setting it in our hidden input that is connected to the WordPress Customizer.

Now you can use the custom control when creating new Customizer settings. You can read about using custom controls in the Theme’s handbook.

Conclusion

WordPress Customizer is really awesome. By defining your own Customizer settings, you can deliver your users a great experience when managing the theme or plugin.

Are you using the WordPress Customizer inside your theme? Have you ever created a custom control on your own? 

Posted by Igor Benic

Web Developer who mainly uses WordPress for projects. Working on various project through Codeable & Toptal. Author of several ebooks at https://leanpub.com/u/igorbenic.

One Comment

  1. Great post Igor. I only have one recommendation. Instead of serializing the data, I would prefer you take the approach of encoding the data in JSON.

    Reply

Leave a reply

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