This is a tutorial for beginners, and we were all beginners once.

To a beginner I remember custom fields looking quite pointless. I couldn’t quite grasp what they were for.

Then, after building a few WordPress sites, I watched an excellent tutorial from Chris Coyier over at CSS Tricks and it really opened my eyes. There’s a link at the bottom of this post to Chris’s excellent video series. And that link was generated using a custom field.

To whet your appetite, here’s an example of a search function I built for THET using custom fields. You can select from three options and then WordPress will search through all the posts custom fields until it finds a match.

That’s a really powerful way to harness WordPress custom fields, but we’re going to start with something a little easier.

The project

In this tutorial, we’re going to stick with something simple. All you’ll need is some basic PHP, together with feeling comfortable working with some WordPress files; specifically single.php which you’ll find in http://your-wordpress-url.com/wp-content/themes/your-theme/single.php.

To keep things both easy and hopefully useful, we’re going to create a couple of custom fields which display a credit and a link to a flickr image. I’m using it in this post! The image at the top of the field (custom fields, gettit?!) came thanks to a flickr user called innoxiuss. And if you scroll to the bottom of this page you’ll see a credit that looks like this:

Well that credit is generated thanks to two custom fields and a little bit of php code.

What is a WordPress Custom Field?

Okay. So think of a custom field as a bit of data. It can be anything at all, as long as it’s an alpha numeric string that can be stored in the WordPress database. So a custom field is not an image, it’s the URL of the image.

A custom field has two properties, a name and a value.

For example, the name could be image and the value could be www.yoursite.com/image.jpg.

But here’s the thing: it doesn’t have to make that much sense. The name could be fruit and the value could be apple. And as pointless as that looks, there are instances where that information could come in useful.

Let’s take the real world example of the flickr credit on the bottom of this page. There are actually two custom fields in there. The first is the flickr user and the second is the URL of the photo.

Name: flickr_attribute_url
Value: http://www.flickr.com/photos/innoxiuss/2665404220/

Name: flickr_attribute_name
Value: innoxiuss

How to add a Custom Field

Custom fields are added on the Edit Post page, and it looks like this…

If you can’t see it, then scroll to the top and under ‘Screen Options’ make sure that ‘Custom Fields’ is ticked.

All you have to do is click on the ‘Enter new’ link (in blue) and enter a name for your data under ‘Name’.

Next enter your data’s value under ‘Value’.

Finally, click on the ‘Add Custom Field’ button and you’re done. This is what it might look like…

You can add as many custom fields as you like, and on some posts I have over 20. Here you can see I’ve added two, making sure that the names are unique.

And that’s it. You now have two custom fields each containing a snippet of data.

But without rolling up our selves and getting our hands dirty with some PHP, this isn’t going to do a thing.

Adding the PHP

Here’s the code we’ll be using. Have a read through and see if it makes sense…

Okay, let’s take a moment to go through the code.

First of all, make sure you have created the custom fields in your WordPress post, and that you have the names of the fields exactly right. After all, if there’s no custom field data there’s nothing to do!

We check for the data in the first line:

We use the WordPress function get_post_meta to grab the value for ‘flickr_attribute_name’. If there’s no data there then this statement will be null and the if won’t run. If there is something in that custom field then the code will carry on executing.

But hold on a minute, what’s all that other stuff? Well, the get_post_meta function has the following parameters:

We set our $post_id as the current post using $post->ID. Our $key is the name of the custom field which is ‘flickr_attribute_name’. And finally we set $single to true.

What is single? If it’s set to true it returns a single result as a string. If it’s set to false it returns multiple results as an array. We’ll get on to arrays in later tutorials, but for now we’re going to keep it simple. We only have one value for our flickr credit so we leave it as true.

So now we know we have some data, let’s carry on with the code. We put our content in a DIV so we can style it to our liking

And we also create two variables with our custom field data in. The get_post_meta function works exactly as we described it above.

Again, note that we set the $single parameter to true, because we know there is only one bit of data. How do we know this? Well, in this instance it’s because we’ve set the custom field up ourselves in the WordPress backend.

Finally, we throw together the rest of the HTML, and close off the if statement.

Bringing it together

So we have our custom fields in WordPress and we’ve entered some data into them. We’ve also created the snippet of easy PHP which’ll read this data and display it on the page.

But where does it go?

Well, for this snippet I’ve chosen to put it on the bottom of the single.php page in the wp-content folder, as this is the page that displays single posts.

On my page it comes just before the section, which itself is just before the comments bit. But you could put it anywhere you want.

Just boot up your favourite PHP editor (I like Expresso on the Mac and, predictably, Dreamweaver on the PC) and type in the code.

Save your page, upload, and you should have a lovely flickr photo credit.

What next?

Don’t have flickr photos on your page? Well then this could be a bit pointless. But remember, this tutorial should just give you a basic idea of how custom fields work. Sure, you could have put this flickr information in the post itself but as we’ll see, we can do all kinds of funky things once we have the ability to search custom fields and display data based on their contents.

In the mean time there is some further reading below. Oh, and the further reading is displayed from data in custom fields!

Thank goodness for jQuery! jQuery has a handy little function which allows us to load JSON data using an HTTP GET request, and then process the contents as an array. And with some natty CSS to square things up as a grid, I have nine random (ish) photos from our Flickr group displaying in a nice 3×3 grid.

See it in action.

The full commented code is at the bottom of this post, but let’s go through it bit by bit.

What is JSON?

Since we’re talking about Flickr, let’s use they’re definition:

“JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format, which makes constructing API applications in JavaScript easy (though it can be used from other languages too!). “

Which means what exactly? Well, it’s a lot like any other feed or data – like an RSS feed, for example. A typical Flick JSON response might look like this:

Which is not altogether too hard to digest. To see the whole feed from Talk On Travel have a look here.

All we need to do is get that feed in a way our javascript can use, and then use it. Enter, stage left, jQuery…

Create our object and fill it with data

So how can jQuery help us out? With the handy $.getJSON(url, [data], [callback]) command.

It’s simpliest method would be something like:

Which would grab the info from a json feed at www.example.com/yourjsonfeed.json and then execute a function called functionName.

Then, you’d have to create a function like so:

In which data is automatically populated with the json feed. Nice, eh?

So now we have our data object, we need to know how to grab stuff out of it. Again, this is pretty easy stuff. We use some dot syntax like:

Which says… in data, go to (the first) item, then go to the media bit and grab the m bit.

Scroll back to the top of this page, and in our example you’ll see that this would be ‘http://farm4.static.flickr.com/3037/3081564649_4a6569750c_m.jpg’.

You can probably work out then what item.title and item.link would give us. Armed with that, you can get any information you need from this feed. All we have to do now is display it!

Getting this feed onto the screen

Does that make sense so far? Hope so. If you get lost, check out the excellent jQuery documentation – the links for which are at the bottom of this post.

Let’s sew it all together in a really simple function that just cycles through all the images in the feed. By default, Flickr returns 20 images.

As I’ve commented the code, you should be able to work it out from here…

But those aren’t my photos!?

I know, I know. Have a look at that feed address once more…

http://api.flickr.com/services/feeds/groups_pool.gne?id=998875@N22&lang=en-us&format=json&jsoncallback=?

Spot the 998875@N22 bit? Well that’s the Flickr user ID for Talk On Travel, another blog that I look after. You need to put your own ID in that string.

I recommend using http://idgettr.com/ to find out easily!

Over to you

That’s a simple introduction to JSON and Flickr, and I hope it puts you on the right path.

For more details on JSON and jQuery, and with another example of how to get photos from a Flickr JSON feed, check out http://docs.jquery.com/Ajax/jQuery.getJSON.

To read up on the Flickr JSON object, head over to http://www.flickr.com/services/api/response.json.html.

You can see my code in action at http://www.richardshepherd.com/flickr.html. Check out the source code to see what it’s doing.

Obviously, you can do a lot more with this, but it’s just a basic implementation to get you started.

Good luck!

It will be launched to no fanfare whatsoever next week, when I upload the widget to WordPress. Pending their most gracious approval, of course.

In the mean time you can head over and have a look at what it’s all about. In future posts I’ll even breakdown the code that has put the whole thing together.

It’s a widget I have developed for WordPress which allows you to include your Flickr photos in your blog, and display them with the rather funky Slimbox tool. Click on one of the photos and see what I mean. Slimbox, as well as looking great, allows you to navigate back and forth if you hover your mouse over the top left and top right of the picture.

The widget itself has a number of configurable options which are easy to set up and change. At the moment they include:

• API Key
• API Secret
• Set ID
• Number of photos
• Photos per row

Before I release the widget I’ll be adding some more options, including the Flickr username and an ability to style how the thumbnails are displayed. At the moment they are just 50px squares.

Stayed tuned for more phpFlickr fun.