Where should I put code from the tutorials?

In this tutorial I discuss the whys and hows of creating a site utility plug-in.

To put this in bit of context:

I’ll be posting tutorials – both user and developer focussed – to help you get the most out of Event Organiser. One of the big advantages of Event Organiser ( & Pro ) is how versatile the plug-in really is, and I hope to demonstrate this through guides on how to tweak the plug-in.

Invariably this tweaking involves some custom code, so the obvious question is…

Where should I put code from the tutorials?

Don’t put code in Event Organiser (or any other plug-in)

You should avoid making any alterations to the plug-in files (neither the core and pro versions) – just as you shouldn’t make alterations to WordPress itself.

Why? Firstly your changes will be lost with an update (… you do keep your plug-ins and WordPress up to date, right? ). Secondly, by editing either a plug-in or WordPress you may accidentally, and perhaps at first without noticing, break it.

So we’ve established where not to put the code, where should be you put?

Put it in a site utility plug-in

What is a site utility plug-in? Simply put it’s a plug-in that you create to keep all the code snippets for your site. Creating one is very easy, and I’ll show you how.

You can think if it as functions.php that is associated with your site, rather than your theme.

Why is the the best method?

• It separates your code from plug-ins and themes (which will change, or be updated)
• Site utility plug-ins make it easy to active/disable features you add through the plug-in’s admin page.
• You can have as many ‘utility’ plug-ins as you like – one for each feature even – so you can easily turn each one on or off

What about functions.php?

As a rule, code in functions.php should relate to your theme. If you would want that code if you switched themes, don’t add it in there.

Adding code snippets into functions.php will (in general) still work, but

• If you add it to functions.php and then update your theme – your changes are lost.
• Even if you add it to your child theme’s functions.php – when you switch themes you must take your code with you.
• Editing a site utility plug-in using the built-in plug-ins editor is safer than editing functions.php through the theme editor. A mistake in functions.php can bring your site down, whereas WordPress will disable the plug-in if it detects an error.

Please note that it’s a complete myth that using functions.php makes your site noticeably quicker. Trust me. I’ve done tests.

For a long time functions.php was promoted as the place to put your code. Many a tutorial was written on ‘How to achieve X without a plug-in’ which invariably involves them telling you to put code that would more sensibly live in a plug-in in your theme’s functions.php.

Even since those days (if we can claim to have escaped them) tutorials will often recommend to put code in your functions.php when it isn’t entirely the correct thing to do.

I’ll admit, even in my tutorials I will say ‘put this code in your site utility plug-in or functions.php‘ – I say the latter part through gritted teeth (and some tears) since I know some may not know what I mean by the former – but now you do!

So, hopefully I’ve convinced you why this next part is important.

How to create a site utility plug-in

Simply create a php file (let’s call it site-utility.php) within a folder ( site-utility ). The only thing we need to add to this file is a comment header at the top. A comment header tells WordPress about the plug-in, so that its able to recognise it as such. An example would be:

/*
Plugin Name: My Site Utility Plug-in
Description: Code snippets for my site
Version: 1.0
License: GPL
Author: Name
Author URI: url
*/

Feel free to change the details.

Now simply upload that folder containing your file to your wp-content/plugins folder. (Strictly speaking the site-utility.php file doesn’t need to live in its own folder, but it helps keeps things organised). The final step is to head to your site’s Plug-ins admin page and activate your plug-in, and you’re ready to go!

Now, whenever you want to add code, simply head to the plug-in editor and select your utility plug-in, rather than your the theme editor.

Download an example plug-in

I’m not the first person to recommend this. Ryan Imel of WP Candy (one of the many people who’ve discussed this before me), wrote an excellent and far more detailed summary of utility plug-ins.

Ryan was even kind enough to make you a blank utility plug-in to get you started.