Creating Theme Options using object oriented programming (Part 1)

Object oriented programming

I've always wondered what is the benefit of the object oriented programming (oop), and never really grasped it, until I actually started writing code in that way. And now I'm hooked. I'll try to explain how you can code in OOP style, by explaining to you how to create Theme Options in Wordpress.

My first time encountering object oriented php was probably 2 years ago, when I was preparing a theme to be compatible with WooCommerce, and I stumbled upon classes, $this, private, public and self:: (among other oop keywords), and I must admit I was totally confused. Coming from a non programmer background, this was all new to me. I tried reading more about it, but was always afraid to tackle it.
Plus we rarely used oop in our themes – there was extending the menu walker class, but when you’re only modifying the existing code, you run into a problem of just blindly following what others did, and not fiddling with it too much. Especially if you need to deliver the end product as fast as possible.

This is a trap a lot of self thought programmers fall into – blindly copying code without understanding it what it actually does.

After some time, and raised experience, I released my own plugin, which is written using oop approach. Granted the backbone of the plugin was written on Devin Vinson’s boilerplate, but I had to actually make it work, and by doing that I learned a lot about how classes work, and how to you use them in WordPress.

The inspiration for this tutorial came from something I am currently doing for a firm I’m working for. It’s a Theme Options page. Originally a colleague created it by creating separate .php  files, in which he added sub menu pages, created a function which generated the layout, and called it based on saved settings in the database, and provided default settings he made. And it worked nicely. It was a lot of code, but it worked nonetheless. In the meantime I was assigned to review the code, and I also got the design from our designer for the options page. And I had to change a lot of code. A lot. Not only php code, but JavaScript as well.

When I redid the options for the headers (so that they would match the design),  I realized that I will have to do this for every subpage there is. And there are 5 similar pages to redo. Plus every page had a different ajax call that would save the option to the database. It was just impractical to do it, and basically waste time on poorly written code. So I remembered the one thing every tutorial will say about oop:

Writing oop code is like writing blueprints to a house – you have your basic elements that will make the house (classes, properties, constants and methods), and from it you can build lots of different houses (class instances).

In my case I want to create a class that will build me a sub menu page, based on it’s name and a set of predefined default values. So every time I create a new instance of that class (a new object), I’ll get a new sub menu page. The basic structure will be the same (names will of course depend on the name I provide), and default values will differ, but I will only have to code that one class. I’ll also only use one ajax callback to fetch my options and save them in the database.

This is so much more efficient, then writing endless code over and over. Basically with any kind of code repetition, you can use oop approach to solve it. That way any changes you need to do will be global, plus you can, if you want to, extend that class and add new methods. The elegance of it is brilliant. Now I’m not saying that we should change every single thing into oop type of programming. Sometimes procedural programming is a good way to go. For a simple code, procedural will probably be easier to code, and to understand. You can read more about procedural vs oop here and here.

Have in mind that I am by no means expert in this field, but I’ll do my best to go step by step and explain as I go. So let’s start.

Laying the php foundations

When creating something big as a theme page, it’s best to put all the files in a separate folder (.php, .js and .css). It’s always better to have a reasonable file structure inside your theme. I’ll be using Twenty Sixteen theme as a base theme, so that you can follow the file structure based on that. Inside the /inc folder we’ll put the  /theme-settings folder, which will contain /css and /js folders and theme-settings.php (for now). To have our theme-settings.php file visible to WordPress, we need to include it in the functions.php file.
Find the after_setup_theme action hook, and after it add

Now we can start working on out theme settings.

Following the guidelines

Before we start with adding our theme settings, I’d like to talk a bit about WordPress coding standards. They are a certain set of rules that will make your code consistent throughout your theme. Since it’s not really practical to memorize them all, there are few tools that can help you in maintaining those standards – and if you’re submitting a plugin or a theme to WordPress.org, this will make your, and reviewers life a lot easier.

First to mention are linters. Since I’m coding with SublimeText 3, I use jshint and csslint packages as my linters. To install them you’ll need node.js. Just follow the instructions and you’ll be good to go. I talked a bit about them in one of my earlier articles.

The next thing that I’ve only recently found out, and is a tremendous help, is a php code sniffer by squizlabs. The installation of it is a bit tricky on Windows machines, since you’ll either need pear or composer to install it, but after you’ve set it up, it’s a great tool to inspect your php code on the fly. With the code sniffer you’ll want to install the WordPress Coding standards sniffer. Once you’ve set it up in your sublime you’ll get notices what in your code is not up to WordPress coding standards, and you can fix it while you’re writing it :)
It’s a super helpful tool and I recommend that you use it, it will improve your coding style a lot.

Back to the theme settings.

First we’ll add a check to see if the user has the necessary capabilities to access theme settings. Generally this is something only administrators should have access to

Next, we want to add our settings page. This is necessary so that we can attach subpages to the main Theme Settings page.

If you look at the details of add_menu_page function, you’ll notice that fifth argument in the function is the callable function that will render our page, here I’ve created a function that will render the HTML based on what is (or isn’t) found in the database value for the options we are trying to save.

Here I’ve added a ‘dummy’ google maps control. Before we turn to styling and JavaScript, which are kinda essential here (I’ll explain this in a second), let’s add the ajax callback function, and let’s enqueue our style and script, as well as few localizations

You may notice a few comments here and there. These are comments that notify the php code sniffer that the echoed variables are safe, and need no escaping (or sanitizing in the case of global $_POST variables). You can read more about it here.

Ok, so now that we have all of our php code in, you may wonder a few things: 1. Where is the oop approach here?! 2. There is no checkbox, and the input field is hidden, what’s up with that?!

First one – this isn’t object oriented approach, glad you caught that one :D This is pure procedural code. When you’re creating a page, and including few underlying necessities (enqueuing scripts etc.), you don’t really need oop approach. No one is stopping you from creating a class here, define all your methods here and then instantiating it. But I don’t think that would benefit you much. We won’t be repeating this part of the code, so there is no real need of using oop here. We’ll get to that later on, don’t worry :)

Second – I told you that styling and JavaScript are kinda important, no? I personally don’t like the bare basic HTML controls. Regular checkboxes, radio buttons and input fields are so boring and ugly. So I’ve decided to spice it up a bit.

So create your settings-style.css file in the /css sub folder and add the following code

And also add your JavaScript in settings-custom.js file in the /js sub folder

Here we added two on click events. One is the checkbox toggle that will look for a settings data attribute in the checkbox label, and based on that will toggle the visibility of the input field – why show the field that cannot be used if you haven’t enabled the setting, right? The second event is the ajax save. It looks for the input fields, fetches their values and stores it in an object that you’ll convert to a JSON string. Also don’t forget your nonces. Always make sure that you write secure code – escaping on output and sanitizing the input is really important.

With all of that our complete code looks like

And renders out like this

Theme Settings screen

The rendered out Theme Settings screen

We’ve only scratched the surface here. And the object oriented programming is yet to come, but don’t be alarmed, we will get to it in the next part.

I’d like to mention that the settings on the main screen should be some global settings that you set – kinda like our google maps API key in the example above. You can save them ‘by hand’ (manually writing it in JavaScript), or you can check the input fields that have certain class ( .twentysixteen_setting for instance), and save them in JavaScript by going through each element with that class. I’ve done it this way because there are only 2 options to save, but you can customize this to your liking.

This is it for now, I’ll write up a second part soon where we’ll see how we can add sub pages using classes and object oriented approach. Stay tuned, and until then happy coding :)


Also published on Medium.

Join the Discussion