Return True - Coding Tutorials, hints & tips in PHP, jQuery, CSS & HTML

What’s This Then?

The Attached Image is a simple plugin that packs quite a punch. It shows the first image attached to the current post. For example. If you have your home page set to 5 posts and you use this plugin it will show the first image attached to each of those posts. For a working example see celeborama.net which uses it to grab the picture you see floated to the left of each post.

It was inspired by a plugin wrote by Kaf Oseo, but when support & updates were no longer available & a recent upgrade of WordPress meant it didn’t work exactly like it used to, I decided to take on the challenge of remaking it using the newest WordPress functions available.

What’s It Do?

It has a lot of features, if you want to see them all then check the options list a litte further down the page. For now though here are some of the major ones that most people look for:

• Can show the full, medium or thumbnail sized image attached to the current post.
• Can make a hyperlink around the image that points to the post the image is attached to, the full image, the attachment page or a custom URL using custom fields on a post by post basis.
• If more than one image is attached to a post then the image to be shown can be changed using the WordPress gallery page. Just pull the image you wish to show right to the top of the list and press save.
• Can be returned instead of echoed so the output can be stored in a variable for developers to use as they wish.
• Can show a default image if no image is available. Also changeable on a post by post basis via custom fields.
• and more…

How Do I Install It?

It’s actually really simple to install. The hard bit is deciding where you want the image to go, but that’s entirely up to you. Here are the instructions you need to get it up and running:

1. First go and get the plugin. Either from here or using WordPress’ new plugin installer (available since WP 2.7). Just search for the attached image or Paul Robinson.
2. Unzip & place the folder into the wp-content/plugins folder. (I’m going to assume you’ve done this)
3. Go to the plugins page of WP & activate the plugin. (Also assumed as done)
4. Go into the template editor & find where you would like the image to show. It must be within the loop which looks something like this:

       <?php if (have_posts()) : ?>
   		<?php while (have_posts()) : the_post(); ?>
           	<!-- Some HTML will be here -->
           <?php endwhile; ?>
       <?php endif; ?>
     

5. At the point you have found, place <?php the_attached_image(); ?>
6. Go to the ‘The Attached Image’ options page under the WordPress Appearence menu.

So What About The Options

Functionality Options

This option allows you to switch on and off the perma functionality for in post image. This checks the post content for an image and grabs the image with the number you have asked for. If that number of image is not available it will show your specified default or return with nothing. Just press the checkbox & put in a number. It starts at 1 not 0 like some may think, so if you want to get the first image in the post press the checkbox & type 1 then save. This type of functionality can also be accessed on a post per post basis using the custom fields as explained later in this documentation. This has been extended with a new option to pick a thumbnails size to use. This will only work if the images were uploaded with WP, if they were not or they are linked in from a external source it will default to showing the full sized image.

General Options

Well The Attached Image now comes with a options page so you can alter what it does from the comfort of your WordPress dashboard. The Attached Image is all about adding a feature to your blogs design & because of that I have added it under the Appearance menu. Here is a description of all the options and what they do. First the general options:

Image Size

This is the size of image you would like to use. As of version 2.2 it supports WordPress’ generated thumbnails, medium size, large size images, and of course the original full size image. You can now specify a size using a function call to override the options page. This is great if you want to call the plugin twice on two template pages & want to use different size image. Use img_size= and then either full, large, medium or thumb. Use ampersands (&) to seperate parameters.

CSS Class

This is the class that you would like placed in the image tag. The default is attached-image and can be styled as normal through a CSS stylesheet. This option is so anyone who already has a class can use that if they wish. You can also call a different CSS class using function call parameters again options are seperated by ampersands (&). CSS class’ parameter is css_class Don’t use spaces in CSS class names when using this method. An example of both image size & css class together would be this. the_attached_image('img_size=thumb&css_class=custom-class');

Custom Image Size

Here you can input a custom image size. Beware, this uses the inbuilt width & height attributes of the image tag & as such can degrade picture quality if used too aggressively. Please use with caution.

Default Image Path

A simple one. This is the path to a default image if you wish to use one. Empty or leave the box empty to disable it. Very Important the image path must be from the WordPress root & not your hosts root, it must also start with a forward slash (/). So if your blog is in http://example.com/blog/ and you kept the image default.jpg in the wp-content folder the path would still just be /wp-content/default.jpg and NOT /blog/wp-content/default.jpg. It is also NOT the ID of another image.

Image Link Location

Do you want a link to be placed on the image that is produced & if so where do you want it to point. The possible options are no link, post, image & attachment page. I think it’s pretty self explanitory what they do. You can also provide a custom link on a post by post basis, more on that in the custom fields section further down the page.

Image Alternate Text:

Allows you to choose what the default alternate text for the image should be. You can choose either image filename, image description, post title or post slug. The description is taken from the description field that you can fill in when uploading an image via WordPress’ uploader. If one isn’t provided it falls back to the images filename. A custom value may be input via custom fields, see Custom Field Info below.

Link Title Text:

This is the text placed in the title attribute of the hyperlink placed around the image. This will only have an effect if you do NOT have Image Link Location set to No Link. The options are the same as the alternated text & a custom value can be input via custom fields, see Custom Field Info below.

Advanced Options

Now for the advanced options. Please be careful with these. Selecting the wrong option can result in the plugin not working correctly. I will at some point try to add a reset to default for instances where accidents have occured, until then though please be careful. Thanks.

Generate An Image Tag:

Fairly obvious… Whether to make an image tag or just place the full URL to the selected size image onto the page. If a link location is selected then it will also create the selected hyperlink around the URL. This can be useful to some people so feel free to be inventive.

Echo or Return:

Also fairly obvious, if you are a coder. Tells the plugin whether to echo out the output or return the output ready for processing by PHP. Can also be used to do some inventive stuff with the output.

Hyperlink Rel Attribute:

This should allow the plugin to work with most, if not all lightbox scripts. Refer to the documention of the lightbox script for what to place in the rel attribute.

Image Order:

By default the plugin will use the image in the first position of the WordPress gallery page. The image to show can be changed by reordering the images on the WP gallery screen, however you can use this to change which image it will pick. If you change this to 3 it will always try to pick the 3rd image in the WP gallery order. If there isn’t 3 images it will pick the nearest it can get to the 3rd image.

What About Those Fancy Custom Fields?

Some of the options can be changed on a post by post basis through the use of custom fields. These are the available keys, what they do & the values they expect. All of the keys prepended with att so that they are easily recogniseable as for use with The Attached Image & to stop conflicts with other plugins that may use custom fields.

Key: att_custom_img

This field is used to show any image from the WordPress attachment database, even if it isn’t attached to the current post. It requires the ID of the image you wish to show. It can generally be found out in the media section of WordPress.

Key: att_default_pic

Allows you to override the default picture that is to be shown if no picture is available. Path rules are exactly the same as the previously mentioned option.

Key: att_width & att_height

Pretty obvious, but it allows you to change the width & height of the image. It again uses the in-built browser method of resizing, so again be careful. Also please remember these are two seperate keys, I have listed them together but you must use two custom fields one for width & one for height.

Key: att_custom_link

Allows you to chose a custom URL for the hyperlink to go to. It will override the setting chosen in the options page for that single post. If you have selected no link in the options using this will override it and create a hyperlink for that single post.

Key: att_custom_alt

Allows you to chose a custom alt attibute to be placed in the image tag.

Key: att_custom_link_title

Allows you to chose a custom title attribute to be placed in the hyperlink. Only has an effect if Link Image Location is NOT set to No Link.

Key: att_in_post_image

This feature was requested by Jake Garrison. It allows you to display an image that is inserted into the post & not attached via the WP uploader. It scans for img tags in the post and places it where ever you place the plugin call. Options are a number starting from 1 of the img tag you wish to pic from the post. 1 will pic the first, 2 will pic the second and so on. If there isn’t a img tag matches the number picked it will leave a blank space (return false). Example. If you choose 4 and there are only 3 images in the post in will return blank (return false).

Key: att_in_post_image_size

Allows you to choose the thumbnail size for the in post image function. This only works if the image was uploaded via WP. If it wasn’t or is linked from an external source it will default to the full sized image.

Custom Queries

The ability to easily use custom queries was added as of version 2.5. There is now a second parameter for the query object. All you need to do is hand the query object over to the plugin. Here is an example:

//Custom Query Example
$my_query = new WP_Query('showposts=2&cat=3');
while($my_query->have_posts()) : $my_query->the_post();
  //Other Post Details
  the_attached_image('img_size=thumb&css_class=image', $my_query);
endwhile;

It should be fairly easy to follow. All you need to do is look for the variable that WP_Query() is assigned to & hand it to the attached image.

Wait Up… I Have More Questions!

Really? You do! Well then your already in the right place. You can either leave a comment on this post, or if you prefer, you can send me an email using the contact page.

What If I Find Something I Want Added Or I Find A Bug?

Well you wouldn’t be the first. Most of the features now included with The Attached Image are there through requests made in the comments section, just scroll down & have a read. If you have found a bug or you want to request a feature then the process is the same as the last question. Leave a comment on this post or drop me an email via the contact page.

Alright… Say I’m Feeling Kind…

Ahhh. Say no more. If you are feeling generous then you can buy me a cup of coffee or two using the Paypal donate button just below.

If that’s not your sort of thing then you can always donate some money straight towards my hosting bill with Dreamhost using the button below. Dreamhost take payment via Paypal so you know it is safe & secure.

That It?

Yep. I’d just like to say a thank you to everyone who has downloaded, used, supported, commented on or even just looked at my plugin. It might be me who writes it, but without you guys out there to use and appreciate it there wouldn’t be a point. Thank you so much.

Also a little extra thank you to Alisher, Brian Wood, Steve, Jasper Visser, Jennifer the scriptygoddess, and RougeDeals. All these lovely people suggested a feature that got added to The Attached Image or have identified & helped fix a bug. Also a final thank you to everyone who has linked back to me and helped popularise The Attached Image.

Ya, Finished Now

Actually no, not quite.

Legacy Overrides

These are a list of legacy parameters that allow you to override the values set in the options page. This is useful if you want to have more than one call the the_attached_image() on different pages in you template, but you want them to show different size images, or remove the link and other things. Basically it allows you to call the plugin twice, but have it do two different things. The parameters are entered in Query String format an example is the_attached_image('img_size=medium&link=image&css_class=featured-image');.

img_size

Changes image size to be pulled back by WordPress. Options are thumb, medium, large & full. Default is thumb.

css_class

The CSS class to place inside the image tag.

img_tag

Whether or not to echo the URL in an image tag. Options are true or false. Default is true.

echo

whether to echo or return the output. True will echo, false will return. Default is true.

link

Where you want the link to go. Will only work if href is set to true. Options are none, post, image and attachment. It is also possible to use a custom URL via the custom fields, please refer to the custom fields section above for more. Default is post.

default

The path to a default image if one is wanted. The path must start with a forward slash and be based from the wordpress directory, not your hosts directory. Options are false & a path to the image. Default is false. Can also be adjusted via custom fields, again check above for more.

width & height

Two seperate parameters that do the obvious thing. The set a custom width & height for all images. This only resizes using the image tag width & height attribute, as such quality will suffer greatly when resizing too much either way. Also adjustable using custom fields, check above for more.

image_order

Allows you to change which image the plugin uses from the WP gallery page. Normally, if there is more than one image, the plugin will pick the image marked in 1st. This allows you to change that. If there isn’t a picture at the position then it will take the pictures as near to that number as possible. Default is 1

rel

The rel attribute is generally used to add lightbox scripts. Just put the word shown by your lightbox instructions here and all should work as long as href is set to true & link is set to image, since there has to be a link and the URL to the full image for the lightbox script to work.

alt

Allows you to choose what the default alternate text for the image should be. You can choose either image filename, image description, post title or post slug. The description is taken from the description field that you can fill in when uploading an image via WordPress’ uploader. If one isn’t provided it falls back to the images filename. A custom value may be input via custom fields, see Custom Field Info above.

title_link

This is the text placed in the title attribute of the hyperlink placed around the image. This will only have an effect if you do NOT have Image Link Location set to No Link. The options are the same as the alternated text & a custom value can be input via custom fields, see Custom Field Info above.

If You Are Still Using An Old Version Without The Options Page

You should really upgrade to the latest version so you can use the new options page, but if you are one of those people who just loves the old school (and why not) then here is a list of parameters. Custom fields are still exactly the same so please use the list above.

img_size

Changes image size to be pulled back by WordPress. Options are thumb, medium, large & full. Default is thumb.

css_class

The CSS class to place inside the image tag.

img_tag

Whether or not to echo the URL in an image tag. Options are true or false. Default is true.

echo

whether to echo or return the output. True will echo, false will return. Default is true.

href

If you plan to use the link feature (which will automatically generate an href around the image) then you must set this to true first. Options are true or false. Default is false.

link

Where you want the link to go. Will only work if href is set to true. Options are none, post, image and attachment. It is also possible to use a custom URL via the custom fields, please refer to the custom fields section above for more. Default is post.

default

The path to a default image if one is wanted. The path must start with a forward slash and be based from the wordpress directory, not your hosts directory. Options are false & a path to the image. Default is false. Can also be adjusted via custom fields, again check above for more.

width & height

Two seperate parameters that do the obvious thing. The set a custom width & height for all images. This only resizes using the image tag width & height attribute, as such quality will suffer greatly when resizing too much either way. Also adjustable using custom fields, check above for more.

image_order

Allows you to change which image the plugin uses from the WP gallery page. Normally, if there is more than one image, the plugin will pick the image marked in 1st. This allows you to change that. If there isn’t a picture at the position then it will take the pictures as near to that number as possible. Default is 1

rel

The rel attribute is generally used to add lightbox scripts. Just put the word shown by your lightbox instructions here and all should work as long as href is set to true & link is set to image, since there has to be a link and the URL to the full image for the lightbox script to work.

alt

Allows you to choose what the default alternate text for the image should be. You can choose either image filename, image description, post title or post slug. The description is taken from the description field that you can fill in when uploading an image via WordPress’ uploader. If one isn’t provided it falls back to the images filename. A custom value may be input via custom fields, see Custom Field Info above.

title_link

This is the text placed in the title attribute of the hyperlink placed around the image. This will only have an effect if you do NOT have Image Link Location set to No Link. The options are the same as the alternated text & a custom value can be input via custom fields, see Custom Field Info above.

in_post_image

This feature was requested by Jake Garrison. It allows you to display an image that is inserted into the post & not attached via the WP uploader. It scans for img tags in the post and places it where ever you place the plugin call. Options are a number starting from 1 of the img tag you wish to pic from the post. 1 will pic the first, 2 will pic the second and so on. If there isn’t a img tag matches the number picked it will leave a blank space (return false). Example. If you choose 4 and there are only 3 images in the post in will return blank (return false). Can also be set via the custom fields, without setting this parameter using the key above. Warning: This will override the normal function of this plugin if set as a parameter. If you use custom fields the plugin will work as normal except for the posts it is used on.

in_post_image_size

Allows you to pick a thumbnails size for the in post function. Will only work if the image was uploaded via WP. If it wasn’t or it is linked from an external source it will default to the full sized image.

That’s all the parameters, but seriously you should upgrade to the latest version. There is tentative support for the parameter based system, but it is only there as a backup until I can safely assume everyone is using the new options system. Please don’t hesitate to leave a comment if you have problems switching over to the new system, it is a lot better.

Now are you finished?

Yes, now I’m done.

Update: 14/12/2009

I’ve just created a PDF file to show everyone some of the advanced uses available when using The Attached Image. Hope it is of use. Advanced Uses For The Attached Image PDF