Introduction
The WordPress customizer is a great tool that lets you easily make changes to the theme of a site. One way it's helpful is when we want to use a theme that has multiple color schemes. For instance the UConn Health Clinical theme is a good example. Each clinical site has a different accent color (like aging, or dental). That color is chosen in the customizer from a select box.
In this post, I'll show you how to add a select box that will let you pick a color scheme that can be used across the site.
To do that, we'll use
- the WordPress customizer
- leafo's scssphp
Setup
We need to do three things in order to print styles to the <head> of our site from the customizer
- Register customizer settings and interfaces.
- Compile CSS from sass files.
- Print the CSS to the head of the theme.
In general we break things out into classes, but for the sake of brevity, I'm going to pretend that all of this happens within the functions.php file.
Registering Your Customizer
The first thing to do is hook into the customize_register action. This will allow you to add your own customizer sections, panels, and settings. To do that, the function that you use will take a customizer instance as an argument so that you can use its methods.
Next, it's time to create a section within the WordPress customizer that will hold the settings. There are some default settings within the customizer, however it's nice to keep everything within one or more sections devoted specifically to the theme. That way users will know what's part of WordPress and what's part of the theme itself. To do that, we'll use the add_section method on the $wp_customizer instance that's passed into the function.
After registering the section, it's time to register settings and controls. These will allow you to make and save choices about the theme to the database. To do this, we'll use the add_setting and add_control methods on the instance. The add_setting method creates space in the database for the choice. The add_control method creates the interface for the user. In this case, the control will be a select box with options for the names of the different schemes.
So far so good. Now when a user makes a choice for the color scheme, it will be saved in the database in the wp_options table as a theme_mod.
Defining Color Schemes
Because the choice is saved as a theme_mod, you can retrieve it with the get_theme_mod function.
This function takes two arguments.
- The name of the setting you want to retrieve
- A default in case retrieval fails
Based on this, you can write a function using a switch/case statement that will give you a color scheme.
The next thing to do is create a separate directory for sass files to be used by the customizer. In that directory, create a variables.scss file which will be imported into your main sass file. The variable names will be the same as those you define in the array that's returned from the previous function.
These sass variables are now available throughout your customizer sass application. The !default statements are there only as a safeguard. They'll be overwritten by your choices in the next step.
Compiling CSS
Next it's time to turn the sass files into css which can be used in the theme. To do that, you'll need to
requireleafo's scssphp library in your functions.php file. There are several ways to do this depending on how you manage PHP libraries. That's a little outside the scope of this tutorial, but worst comes to worst, you can download it and place the appropriate directories in your project.- hook into the
customize_save_afterWordPress action - set an import path for leafo
- call the
get_color_settingsfunction to get the color scheme - set a formatter for leafo. This will define how the CSS appears once printed to the page. I like the compressed formatter for this.
- compile the CSS
- save the css to the database as an option.
Kind of a lot! But that's ok. Each step builds on the last.
Printing the CSS
Now that the CSS is stored in the database, the last thing to do is print it to the page so that it does something. In general, it's useful to have these styles come after all the other theme and plugin styles. To ensure that happens, you can print them directly inside a style tag. The hook to use to do this is wp_head. So to finish the application, you need to
- hook into
wp_head - retrieve the
customizer_cssoption data you saved above. echothe CSS onto the page
Wait! We're not quite done...
Yeah... sorry. You might think that was it right? But there's one more thing I like to add.
Imagine - let's say you change your secondary color for the red theme from orange to pink. It looks amazing! But right now, if someone wants to make that change, they need to:
- select a new color scheme in the customizer
- publish the change
- go back to their "real" choice
- publish again
This is kind of a hassle if you have more than one site. Even with only one site it's kind of ridiculous. Wouldn't it be better if you just had a button that would let handle all that for you? Of course it would!
So, let's go back to where we register the customizer controls and add one. Then we'll make sure it re-compiles the css.
This code will create an input button which will submit a GET request with the name 'color-scheme-refresh'.
Now we need to watch for $_GET to have the color-scheme-refresh property and then re-run the function to compile the css.
Conclusion
Hooray!
You did it!
Now you can add customizer options for styles and update theme (relatively) painlessly. I think the important thing here is to keep the functions' behavior separate. For instance, with one function to register/display customizer controls and another to keep track of the color schemes, you can maintain the application more easily.
Working with the WordPress customizer is a great introduction to many of the more abstruse aspects of WordPress development. The first time I tried to make an application like this, it took a really long time. There were database interactions, component display interactions, a variety of hooks and functions, etc...
Hopefully this brief guide will help you build your own customizer applications.