Over the weekend I gave my first talk at WordCamp Sacramento 2016. My topic was on the WordPress Customizer and how to start leveraging it to add custom settings for your theme. From WordPress Customizer Types to all of the live previewing, sanitation, and validation. The talk went really well even if I went too fast and forgot to mention a few things. But I had some good questions during my q & a and had several attendees approach me and tell me they enjoyed the discussion. Here are my slides from the talk.
I even had one group that came up and said I had completely changed their mind on the Customizer. That alone made the talk a great success in my book!
I’m working on turning that talk into a full blog post but for now I had several people asking for examples of all of the controls you can add to the WordPress Customizer. I’ve started making gists for each type that includes the setting, control, sanitization. Validation is really specific to each setting and theme, so I’ll do a future blog post on examples of validation.
If you want to use any of these in your code the settings and controls need to be within a customize-register hook. The sanitization and validation functions could be outside the hook, or called in a separate file for better organization. Many of the sanitization functions I use are straight from the WordPress Theme Review Team.
Normal WordPress Customizer Types
I’ve included a sanitization function in each of these gists, but if you look closely some of them are the same function used for different Customizer types. For instance the select and radio controls both use the themeslug_sanitize_select function. These controls both add a choices argument and the sanitization is first grabbing all of the choices and then checking the input to see if the array key matches any of those in our choices.
If you add more than one to a project I recommend moving your sanitize functions to their own file or at least grouped together in one place of your customize.php file.
Text
Textarea
Date
This date field is outputting the date as a string with a format of 10-25-2016. The sanitize function is going to make sure this is the same format, so if you want something different you’ll need to update the function.
Time
Similar to the date field time has a format associated with it. This field is only looking for hours and minutes and in military time.
URL
Checkbox
Radio Buttons
Select
Dropdown-Select
Number
Advanced WordPress Customizer Types
Color Control
Image Control
Using the WP_Customize_Media_Control is different than you would think, because the filename of the image you choose is not saved to the database, only the ID of the image is saved. So the sanitize_callback I use is absint, to make sure the ID is a valid positive integer.
To aid the user if they choose an incorrect file we’ll use a validate_callback to check the file extension of the file versus a list of approved types. In this example if they don’t choose a file, or if they choose something outside the approved list they’ll get an error notification.
More to Come
These are several common types that you’ll deal with when adding to your Customizer. In the future I’ll add more and include how to make your own control types.