Notes

Notes on programming-related problems that I’ve encountered while working on various projects.

Writing JavaScript Helpers for the WordPress Theme Customizer

I’ve talked before about how I think the addition of the WordPress Theme Customizer (well, soon to be called the Customizer) is one of the nicest additions to the core application in a long time. I’ve also talked about how I fear the direction that some developers will take it.

Regardless, if you’ve worked with the Customizer long enough – especially when it comes to the JavaScript aspect of it – then you’ve likely noticed that you can end up writing relatively repetitive code especially when you’re working with something such as a list of items or something similar.

When you end up reaching this particular point, having too much of the same code with the only variations being a few strings ends up being a bit of a code smell.

In order to prevent this, it’s often better to write helper functions that abstracts the repetitive functionality into a single, ahem, function that you can call with the strings that are unique to your use case.

Here’s what I mean.

Easily Install phpDocumentor Alongside MAMP Pro

In previous posts, I’ve talked about the WordPress Coding Standards, and the importance of documenting your code, but I’ve not actually spent a lot of time discussing how easy it is to actually generate documentation for your themes.

And by documentation, I mean an actual site that provides your DocBlocks such in a clean and organized fashion – you know, sites that are generated by tools like phpDocumentor.

phpDocumentor Example

An example of a site generated by phpDocumentor.

In other posts, I’ve mentioned that I use MAMP Pro for part of my development stack, so if you’re looking for steps to install phpDocumentor, it’s actually really easy to do.

Including a Template in a WordPress Plugin (Well, a Template Part)

Late last year, I wrote a post that provided a way on how to include a page template in a WordPress plugin. There’s an accompanying project on GitHub that’s been maintained and relatively-well updated since.

Although this post is similar in nature, it doesn’t exactly deal with templates, but parts of code that may be considered partials (or template parts, in WordPress).

Let’s say that you’ve got a single post and you want to append a template to the end of the content. The content can be a little more complicated that markup because that’s easy enough to do inline, isn’t it?

So, for all intents and purposes, let’s say that we have a partial that includes a form that can be used to submit some type of information.

Simplifying Code in WordPress: Option Arrays

Let’s say that you’re working on a plugin that has its own plugin settings page, and on that page there are options to determine what type of posts will support part of the functionality of the plugin.

For example, let’s say this plugin will be introducing a meta box for each post type that extends the type of information that the user can add to a post. The settings page allows you to control which post types will offer this information.

To give a concrete example, take a look at the following screenshot:

Simplifying Code: Options Arrays

Granted, it’s a small example but it makes the point: We have a plugin settings page that displays all of the post types that are in the current theme installation. If selected, we’ll save the values to an options array.

When it comes time to read the values, there are a couple of ways to go about doing it, but one that’s arguably simpler than all of the rest.

Adding Tabbed Navigation in WordPress for Custom Menus

One of the nicest features of the latter versions of WordPress includes the custom menu system. Although people can always introduce too many areas in which custom menus can be introduced, the core feature and customization options make it possible to do some really cool stuff with custom menus.

Case in point: With many of the popular front end frameworks that are now available, such as Foundation and Bootstrap, it’s really easy to add tabbed navigation in WordPress in templates, widgets, and so on.

Though there are a number ways of to do this, one flexible way that I’ve used multiple times requires two things:

  1. A function for retrieving the post IDs for the post types contained in a custom menu
  2. An instance of WP_Query

At that point, all you need is the name of the menu for which you want to retrieve the post IDs.

Adding Multiple Sections on WordPress Options Pages

One of the most confusing aspects of working with WordPress is the Settings API.

In an attempt to make a little bit easier to understand, I’ve written a series that takes a long look at the API as well as an example project that’s available for download for others to study (and to contribute to in order to improve).

But, as with most things in programming, there are still things that can crop up now and again that can leave you scratching your head. Case in point: Let’s say that you want to introduce two sections (or three or four, even) to a single options page.

Unless you do this correctly, you’re likely to notice that the ‘Save Changes’ button will only save the changes to the last group of options. Luckily, there’s an easy way to keep your options logically grouped while also maintaing serialization through a single ‘Save Changes’ button.

Updating a WordPress Post in the Save Post Action

For those who have worked with WordPress long enough, you’re likely familiar and comfortable with how hooks works – that is, you’re familiar and comfortable with the event-driven design pattern.

Sure, it’s a bit different than many other frameworks and foundations that use MVC, MVVM, and some other remix of the model-view paradigm, but I don’t think that’s really here nor there in terms of which is better. This is what WordPress uses and it’s easy enough – and powerful enough – to work with once you’ve got it.

But that’s not to say it’s not without it’s nuances.

For example, one of the challenges of working with event-driven design is understanding how hooks work throughout the page lifecycle, how it’s possible to actually get stuck in an infinite loop if you’re not careful, and how to work with the various hooks to prevent this from happening.

Two Solutions for “JavaScript Reference Error Is Not Defined”

If you’re working on any type of web site or web application that has any other dependencies either for its front-end framework – such as Bootstrap and Foundation – or from the site’s foundation – such as Rails or WordPress – there’s a chance that your own JavaScript sources may result in the following:

Reference Error [variable] is not defined.

In some cases, this can be simply referring to a variable that isn’t defined (perhaps the most popular is when jQuery’s $ function has been dereferenced and you’re trying to use $) and simply needs a definition.

But, in other cases, there are times where it may not be as simple.

A Dilemma: Hiding Elements with The WordPress Theme Customizer

When it comes to working with the WordPress Theme Customizer, one of the options that you’re likely to see in other themes (or that you’re likely to introduce in your own themes) is an option that is responsible for toggling the visibility of an element.

For example, if a text box is empty, you may want to hide an element. Or, more simply, perhaps a user will need to click on an checkbox to toggle whether or not to display an element.

But this presents a dilemma: Either we can send all of the information to the browser and control its visibility using a class name, or we can send less code to the browser but lose a smooth user experience when using the Theme Customizer.

How To Define a New WordPress Cron Schedule

Last year, I shared how to properly setup a WordPress cron job in which I walked through the process of defining a cron job in the operating system so that a job fires as a true scheduled task (rather than the faux tasks that WordPress provides).

This isn’t to say that the native WordPress scheduled tasks are bad – they just may not work as expected for those who are used to native cron jobs.

Another limitation of the the WordPress scheduling system is that it defines only a handful of intervals in which your tasks may run. These include:

  • hourly
  • daily
  • twicedaily

And these are fine for a lot of tasks, but if you’re looking to define a new WordPress cron schedule, you’ll need to define a custom filter.