Genesis Explained Image Functions

In the previous part of the Genesis Explained series I talked about the formatting functions. Fortunately this subseries doesn’t require you to read each of the previous parts, but I would encourage you to read the entire series in order. I mentioned in the previous article that I was going to skip a few files and jump into the genesis/lib/functions/image.php file. I recommend opening the file up so you can see the functions I’m talking about.

Speaking of the functions, here is a list of all the functions in the file as of Genesis 1.6.

• genesis_get_image_id(): returns the ID number for an image attached to the post. The First attached image is the default.
• genesis_get_image(): returns attached or featured image per the arguments.
• genesis_image(): echoes genesis_get_image()
• genesis_filter_attachment_image_attributes(): used to filter wp_get_attachment_image_attributes
• genesis_get_additional_image_sizes(): helper function used to return the additional image sizes set with add_image_size().
• genesis_get_image_sizes(): returns array of image sizes.

Several of these are just helper functions, things you may not use on a regular basis, but there are some very important functions you need to learn if you will be doing much more than skinning Genesis.

genesis_get_image($args = array())

As you see the args are an array, but what does that mean? Well, short version is you need to send your args as an array. I’ll demonstrate that in a minute. For now, lets look at the defaults.

$defaults = array(
		'format' => 'html',
		'size' => 'full',
		'num' => 0,
		'attr' => ''
	);

This shows 4 different arguments that can be passed in the array.

• Format: This controls the type of information returned
  • html (default): returns the image formatted for html, no need to setup img tags or anything.
  • url: returns a url for the image. You can use this for a link or to build your own html string.
  • src: returns the image “src” which is the image location relative to the index url. If your image were in “http://example.com/wp-content/uploads/2011/05/img.jpg” then it would return “wp-content/uploads/2011/05/img.jpg”
• size: controls the size of the image returned based on WordPress image sizes
  • full (default): Original image size
  • large: returns WP large image size
  • medium: returns WP medium image size
  • thumbnail: returns WP thumbnail size
  • “X”: additional image sizes as set with add_image_size(). The name value should be used, not dimensions.
• num: the attached image to return. 0 is the default and will return the first attached image if no featured image is set. Using a value of 1 or greater will return the 2nd or greater attached image, but will override the featured image.
• attr: allows you to set the attributes for the img tag returned set as an array with the attribute as the key and the attribute values as the string (the example should clarify that)

There are a few filters available as well. You can filter the defaults with genesis_get_image_default_args. genesis_pre_get_image lets you change the args after the args are processed, in other words it lets you override the args not just the defaults. Finally you can filter the final returned value with genesis_get_image.

So here it is in action

$img = genesis_get_image( array(
    'format' => 'html',
    'size' => 'thumbnail',
    'num' => 1,
    'attr' => array (
        'class' => 'alignleft'
        ) ) );

I could have skipped the format line since that is a default, but I just wanted to show all the values. This will return the thumbnail for the second attached image with class=”alignleft.” Pretty cool.

genesis_image($args = array())

Normally I would just say “this echos genesis_get_image() to save you a bit of code.” It does do that, but there is one really nice feature beyond that. This function will return “false” if there is no image set, so you can do a very simple if/else to return a default image.

if( FALSE === genesis_image( array( 'size' => 'thumbnail' ) ) )
    echo '<img src="http://example.com/default-image.jpg" />';

This will automatically echo the image if it is there, otherwise it returns false and that will load the default image.

genesis_get_image_sizes()

This returns an array with all the different image sizes. This is mostly useful in building widgets or setting up theme options where you need to retrieve the available image sizes and pair them with their dimensions. You will have to do a foreach when working with it, like this:

$image_sizes = genesis_get_image_sizes();

echo '<ul>';
    foreach ( $image_sizes as $name => $size ) {
        printf ('<li>%s: ( w:%s h:%s )</li>', $name, $size['width'], $size['height'] );
    }
echo '</ul>';

This just returns an unordered with of the image sizes with the width and height.

The functions for working with images are a little difficult to get use to because you have to work with array values, but once you do get use to them you will find they are incredibly flexible and powerful.

Next time I will be digging into the options.php file. Till then take time to add your desires to the Child Theme Wish List and subscribe the RSS feed so you don’t miss any tutorials.