Posts about php

Customising WordPress Without Modifying Core, Theme Or Plugin Files

2013-06-05 12:19

WP Customizer and that's what this plugin is for. When WordPress does support such a way, this plugin will thankfully be obsolete.

A standard WordPress install is incredibly powerful and flexible. For a lot of people, WordPress out of the box plus one of the stock WordPress themes is enough. But the possibilities for customization are endless; you can add plugins and other themes. Sometimes these do just what you want. Sometimes you need to ... tweak WordPress.

A very high proportion of the customization advice you'll find on the web starts with these lines ... add the following to the end of your theme's functions.php or even worse, advises that you modify the source code of your theme or your plugins. This is bad for many reasons:

Editing your theme's functions.php makes theme specific customizations; change your theme and your customizations will no longer get loaded.
When your theme and plugins get updated you'll find all your careful hand crafted customizations get overwritten and lost.
A lot of theme and plugin authors won't offer support for changes you might have made to the source code.
Your customizations might work; but you might also inadvertently make some other changes which will stop things working.

WordPress doesn't yet support a way for site specific customizations to be made and loaded without touching theme, plugin or core files; that's why I wrote WP Customizer and that's what this plugin is for. When WordPress does support such a way, this plugin will thankfully be obsolete.

There's another, not entirely altruistic, reason behind this plugin. One of the most common support requests I get for WP Biographia is to help with clashes between someone's theme's CSS and the plugin's CSS. Once that's been resolved, the next question is almost always how do I load this custom CSS? The answer is now straightforward. Put your CSS file in a directory in the root of your WordPress installation, install WP Customizer, tell it to load custom CSS files and where to find them and you're done. No editing of functions.php. No learning now to hook into the wp_enqueue_scripts action, no learning how to call wp_register_style and wp_enqueue_style. It should all just work.

But WP Customizer works with more than just custom CSS files. You can also load custom PHP functions and custom Javascript and jQuery files as well. What's more, you can configure these to load just for your site's publicly visible front end, just for your site's admin pages or even both.

WP Customizer uses the file system as a data-store metaphor and allows you to main a library of common customisations that are independent of the theme and plugins you're currently using. Out of the box, the plugin looks for custom files to load in the root of your WordPress installation in a set of named directories which should be relatively self explanatory, functions, admin_functions, common_functions and so on for CSS and for scripts.

But you can just as easily create your own directory structure, put together in a way that makes sense to you, perhaps something along the lines of ... site/front-end/css, site/front-end/functions, site/admin/scripts and so on

... you're limited only by the limitations of your file system and the way of organising things that make sense to you.

One final word of caution though. In order to use this plugin, you have to know how to write the code that lives in the customisation files themselves. That means knowing how to write PHP functions to exercise the WordPress API. How to write JavaScript and jQuery that works with WordPress. How to write CSS. This plugin can't help you with that. But there's ample tutorials and information out there on the interwebs to help you.

Just remember, when you read something that says just add the following code to your theme's functions.php, ignore this little piece of advice and add it a local customisation file and load that through WP Customizer instead. Your WordPress site will thank you for it someday.

To download or install WP Customizer, either search for WP Customizer from the WordPress Dashboard or go to plugin’s page on the official WordPress plugin repository. If you want to fork the source code of the plugin, you can find it on the plugin’s GitHub page at https://github.com/vicchi/wp-customizer.

If you've been running your blog or site on WordPress for any period of time, you may well have come across a message about a deprecated function or argument in your PHP log file or across the top of a page on your site. The message might look something like this ...

Notice:  get_bloginfo was called with an argument that is **deprecated** since version 2.2! The siteurl option is deprecated for the family of bloginfo() functions. Use the url option instead. in /var/web/htdocs/site/wp-includes/functions.php on line 2712

... this often appears after you've installed or upgraded a new theme or plugin. This message is helpful but really only 50% useful. The PHP file and line number that's being reported isn't where the deprecated function or argument is being used; it's where it's being reported from. Often, even after you've searched through the source code of the new plugin or theme you're still none the wiser about where the troublesome piece of PHP that WordPress is telling you about actually lives. WordPress is a complicated mix of PHP, JavaScript and CSS; there's a lot more going on under the hood than most of us are remotely aware of.

Thankfully WordPress also helps provide an answer, through an undocumented action hook called deprecated_argument_run; that's undocumented in the WordPress Codex, it is documented in the core WordPress source code, if you know where to look. The clue to unlocking this problem is a comment in wp-includes/functions.php which says There is a hook deprecated_argument_run that will be called that can be used to get the backtrace up to what file and function used the deprecated argument. So here's how to get that backtrace.

Put the following code somewhere on your site, maybe in your theme's functions.php, where it will get called by WordPress. Now I know this seeminly contradicts what I said in an earlier post but this is a temporary piece of debugging code and not a permanent feature of your site; I might just make it a plugin some day though.

[php] add_action ('deprecated_argument_run', 'deprecated_argument_run', 10, 3); [/php]

Now add the hook function that gets called when a deprecated argument is detected.

[php] function deprecated_argument_run ($function, $message, $version) { error_log ('Deprecated Argument Detected'); $trace = debug_backtrace (); foreach ($trace as $frame) { error_log (var_export ($frame, true)); } } [/php]

Reload a page on your site and you'll see a back trace in your PHP error log of precisely where the deprecated argument is being used.

This technique isn't limited to deprecated arguments, there's also action hooks for deprecated functions (deprecated_function_run), deprecated files (deprecated_file_included) and something being incorrectly called (doing_it_wrong_run), all of which can use the same form of back trace technique.

You'll probably need to ensure that WP_DEBUG is enabled in your wp-config.php and don't forget to remove your debug code and disable WP_DEBUG after you've finished.

Although I fly a lot these days, I don't fly on internal routes in the US that much and so flying Virgin America, which has onboard wifi, is still something that brings out the childish geek in me. In homage to a certain Mr. Aaron Cope, once again I am in the sky as I write this and starting to think that maybe I will only write blog posts from airplanes from now on.

While sitting in a hotel room about a week or so back, I realised that while vicchi.org has been the home of my blog for years and the current incarnation may have 267 pieces of bloggage tucked away in the bowels of WordPress (that's 268 with this post), the theme has been pretty much static since sometime in 2007. The same goes for my other web presence over at garygale.com.

But back to this blog for a moment. Like a lot of people I started out with a stock WordPress install and theme. Then I went through the discovery of the WordPress theme repository, installing and uninstalling too many plugins, before finally becoming confident enough to start hacking the PHP and CSS of an existing theme into something vaguely approaching what I wanted. And thereby hangs the problem. My theme, which started out as Chandra Maharzan's rather wonderful Cleanr, suffered from the problem that each time the theme was updated I needed to go through the changes and manually apply them to my hacked version. Scalable and fun this is not.

Enter the notion of WordPress child themes. These allow you to take an existing WordPress theme and build on top of that theme but without actually modifying or adding to the original theme. You start with just inheriting from the parent theme's CSS and then you can add, adapt and otherwise hack as much or as little of the parent's templates and PHP functions as you need. As you're not actually touching the parent theme at all, any updates to that theme are automagically passed onto the child theme, so the need to keep a hacked theme in line with the original simply goes away.

I still rather liked the clean typography and colour scheme of my version of Cleanr so I was able to easily modify my child theme's CSS to migrate this. I based the child theme on the WordPress Twenty Ten theme but changed the way in which post date formats were displayed, removed the built-in biography display so I could use my own WP Biographia plugin and modified the parent theme's header image display to use my own imagery and to also rotate the images on page refresh.

Putting together a child theme to give my blog a long overdue facelift has been surprisingly easy; to see just how easy, the source code to the originally named Twenty Ten - Vicchi is over on GitHub to download, fork or otherwise hack around.

One web presence down, one to go. Next it was time to give my personal vanity page some facelift attention. The original design for this site was heavily influenced by Christian Heilmann's approach to web technologies. Chris and I worked together at Yahoo! and he taught me so much about how web pages worked. The original version of this site was dynamically generated from RSS feeds fed through Yahoo's YQL. Sadly, the YQL API got ever more flaky over the last few years and I ended up having to transition over to use the SimplePie PHP library just to keep the site up and running. It wasn't the world's fastest loading site but it was nice and dynamic and at the time, that was important, to me at least.

But in keeping with the clean and spare layout of my blog, I'd been intrigued by the less-is-more approach that about.me had taken. But despite having my own page on about.me's site I wanted to host my own under my garygale.com domain.

A random browse through GitHub yielded The Personal Page, a clean, lightweight home page design that appealed to me. One GitHub fork later, plus a photo of me taken at last year's Geo-Loco conference in San Francisco that I didn't look too appalling in and the new, Personal Page'd version was up and running. Really, it took all of about half an hour and that's including testing and finding a social media icon set that integrated nicely with the look and feel of the site. Of course, the web site's code is also up on GitHub for the aforementioned hacking around.

All of the above verbiage can be boiled down to the simple fact that armed with a little knowledge of CSS, PHP and HTML it's very, very easy to create a new and, I hope, effective web presence, all of which is powered by open source tools and techniques and that, utterly appeals to the grown up geek in me.

Written and posted on Virgin America flight VX837, between Chicago O'Hare and San Francisco International airports, roundabout overhead Maryville, MO (40.347, -94.873)

In a way, this was all Matt Whatsit's fault; he writes very profane and very funny blog posts and reading his recent The Five Stages Of P****d Wife (which you should read if you haven't already, err, read it) made me laugh, hell, it made me ROFL and LMAO at the same time but it also made me think, though not necessarily about wives or drunkenness ...

Now background reading and general swotting up on a topic is all very well but to really learn how to do something you just have to roll your sleeves up and do it yourself. Though it's probably stretching a comparison too far, you don't learn to drive a car through reading the highway code; you actually get behind the wheel (preferably under supervision) and ... drive. You don't learn about what food tastes good from a recipe book; you ... taste the stuff yourself.

And so it is with writing code and using new and unfamiliar APIs. It was definitely the case with my recent (reacquaintance of, and) foray into JavaScript and the addition of support for Nokia's Ovi Maps API to the Mapstraction project, with the added benefit of having to teach myself how to move from my (by now very dated) knowledge of version and revision control under CVS to git.

So, first JavaScript and Mapstraction and the Nokia Maps API and now to PHP and the WordPress API. There's a lot of WordPress plugins that do geo-related stuff with your blog but none of them actually do what I want. WP Geo comes close, but it uses Google Maps and Google Maps only. Now I have nothing against Google Maps or the Google Maps APIs but I want maps from the company I work for on my blog.

When I came to add Nokia's Maps API to Mapstraction I at least had a head start. I'd done some JavaScript and I was at least familiar with the Mapstraction API. But writing a WordPress plugin was another thing entirely. Despite hosting my blog on WordPress since 2004 and being able to hack a moderate amount of PHP, I'd never needed to use the WordPress API. Until now.

Bearing in mind the old adage about walking before you can run I decided the best way to tackle this was to write a WordPress plugin for something much more simplistic and this is where Matt Whatsit comes in. At the foot of each post is a nice little biography; in Matt's case it read "Stole some Chewits in 1979. The guilt still haunts me".

So I searched for a plugin that would give me this capability. There's lots. But as with the desire for a geo-related plugin, none of them did exactly what I wanted. The closest I could find was Jon Bishop's WP About Author plugin. So, as all WordPress plugins are licensed under the version 2 of the GNU Public License, I took Jon's plugin and hacked it to do what I wanted it to do. The result is what I've called WP Biographia and you should be able to see the results of it at the foot of this post, if you're reading it from this URL.

I now know, or at least understand at a conceptual level with much web searching of the WordPress Codex, how to write and structure a WordPress plugin. I still need to know how to write and structure a WordPress widget but that will form part of the next version of WP Biographia. By then, I should be armed with enough WordPress API knowledge to start to write what I really wanted to write, which is my geo-related plugin, which may, or may not be called WP Mappa. I'm only a quarter of the way there, but it's a quarter more than when I started this.

In the meantime, WP Biographia is now part of the official WordPress plugin repository and is also up on github as well. It also now has a resident page here on my blog which I'll update as and when I make sufficient changes and improvements to warrant a new version.

Starting to code again is addictive and I seem to have managed to rack up a few github repositories of recent. WP Biographia is but one of what I've christened, in line with the theme of Gary's Bloggage, Gary's Codeage. For now, it's a holding pen for those code projects that live in github but for which I've yet to write a formal page on. These may appear sometime in the not too distant future as and when time permits.

Photo Credits: ficek1618 on Flickr.

Gary Gale

Customising WordPress Without Modifying Core, Theme Or Plugin Files

Tracking Down Use Of Deprecated WordPress Functions Or Arguments

Revisiting The Online Me (On A Plane)

WP Biographia Is But A Quarter Of The Way To WP Mappa