Archive Images In Genesis Child Themes

Already got a handle on Genesis framework archive images? Jump ahead using one of these quick links:

Attached vs featured images in WordPress
Settings for Genesis content archives
How Genesis decides which image to add to archives
Double images in Genesis post archives
Which images will be output in my Genesis archives?
Genesis child themes can customize this behavior

Using images from the WordPress Media Library is normally a straightforward process. When your site uses a child theme based on the Genesis framework from StudioPress, there’s more opportunity for confusion. That confusion can sometimes end up in double images appearing in archives on a Genesis-powered site. The good news is that we can clear up the confusion by clarifying a few terms and explaining the programming code that drives image use in Genesis.

Attached vs Featured Images in WordPress

First, let’s clarify some basic terms. WordPress has 2 basic types of images: attached images and featured images. The WordPress Codex entry on image and file attachments states:

If a media file is uploaded within the edit screen, it will automatically be attached to the current post being edited. If it is uploaded via the Media Add New SubPanel or Media Library SubPanel it will be unattached, but may become attached to a post when it is inserted into post. There also is an option on the Media Library SubPanel to attach unattached media items.

Let’s restate that definition in simpler form: an attached image is the one uploaded while you are editing the post or added to the post from the media library.

In core WordPress, an attached image is not the same as a featured image. According to the Codex entry on featured images, a WordPress featured image (previously called post thumbnail) is an “image that is chosen as the representative image for Posts, Pages or Custom Post Types.” But that language is a little unclear. A WordPress featured image is not the representative image for multiple posts; instead, the featured image is the representative image for the single piece of content on which it is specified. Themes must explicitly declare their support for featured images, and Genesis does this in the genesis_theme_support() function found in /genesis/lib/init.php.

To specify a WordPress featured image for content, you edit the content and click the Set featured image link in the Featured Image metabox, similar to the sample shown nearby. Your selected WordPress featured image will be displayed in the metabox, and when you update the content, you’ve set a WordPress featured image specific to that piece of content. We’ve tried to be sticklers to this point and consistently refer to this image as the “WordPress featured image.” Our reason for doing so will be clear shortly.

Settings for Genesis Content Archives

If things were as simple as the difference between attached images and WordPress featured images, there wouldn’t be much confusion, and we’d be wrapping up this post. Unfortunately, Genesis tries to simplify things for its users but does so with some inexact phrasing, and that can create a bit of confusion.

For archives, Genesis adds an image to output if a setting is enabled in Genesis->Theme Settings. The screenshot below shows the Genesis metabox for Content Archives and its Include the Featured Image? setting. This setting controls whether an image should be added to each archive entry; we think the use of “Add” over “Include” might make that clearer. Further, the “Featured Image” mentioned in the setting is not the same as the WordPress featured image.

There’s another important but often overlooked element to the Genesis Content Archives settings. In Genesis, if you display the entire post content in archives, all of your images in the post are displayed. That makes complete sense. But if you opt to display a limited amount of content or to display excerpts, images are stripped from the display. Let’s repeat that in simpler form: full content includes post images, anything less than full content does not include post images.

How Genesis Decides Which Image To Add To Archives

The next step in the process is for Genesis to figure out which image to add to the post content you choose to display.

That processing starts with the genesis_do_post_image() function, which in turn calls the genesis_get_image() function.

The genesis_get_image() function in /genesis/lib/functions/image.php returns one of 4 things, in this order:

1. the WordPress featured image;
2. the first attached image – which is the first image included in the post;
3. a fallback image (which doesn’t exist in most cases);
4. no image.

As we observed earlier, take note that the Genesis setting prompts for display of the Featured Image, but if you enable the setting, you can get something other than the WordPress featured image, as Genesis makes its way through those 4 possibilities. We think a clearer prompt would be Add a featured or attached image?

Double Images in Genesis Post Archives

A few facts bang together in a busy intersection. First, the Genesis setting can add an attached image even though the prompt refers to a “Featured Image.” Second, many users don’t understand that adding an image to a post makes it an attached image. Third, some users don’t pay attention to the fact that displaying all post content includes images. That can lead to a problem: double images in Genesis post archives.

If you’re seeing double images in archives in your Genesis child theme, it’s likely that these things are all true:

1. you’ve enabled the Genesis setting to display a Featured Image in archives (which we now know is much more than that);
2. you’ve opted to display the entire Post Content (as opposed to excerpts) in archives; and
3. you’ve specified a WordPress featured image or added an image to post or page content, especially at the very start of the post.

If you do all of the things in our preceding list together, you’ll get double images. The Genesis code will execute and add an image, and, since you’re displaying post content as opposed to excerpts, the images from post content will appear as well. This is especially noticeable if you add an image to the very start of a post, because those images will be displayed almost side by side. If you have long posts, and there’s no image close to the start of the post, the first image will be added to the start of the post, but that might be desirable behavior.

Genesis displays the entire post content when you’ve opted to Display post content and you have 0 as the number specified for Limit content to … characters. If you enter any positive, non-zero number for the Limit content to … characters setting, Genesis will strip HTML tags such as images. Therefore, showing some but not all post content is one way to solve the “double image” problem, even if you opt to show a large portion.

Which Images Will Be Output In My Genesis Archives?

With all of that background on how WordPress and Genesis work together to display images, here are a few simple guidelines to determine which images will be output in a Genesis archive.

There are 6 possible outcomes:

1. display no images;
2. display post images only;
3. display the WordPress featured image;
4. display the WordPress featured image plus images in the post;
5. display the attached image plus images in the post;
6. display a fallback image if one is provided; otherwise no image is displayed.

Let’s explain how to produce each outcome in turn.

Outcome #1 – display no images: This is the easiest to understand. It will occur if you do not have your Genesis Include the Featured Image? setting checked to display images and you are not displaying the full post content in archives. Excerpts and limited post content strip images, so the combination of no checkbox with displaying excerpts or limited post content (i. e., not full content) will produce no images.

Outcome #2 – display post images only: This occurs when you do not have your Genesis Include the Featured Image? setting checked to display images but you are displaying the full post content in archives. The first setting causes no images to be added to output, and the full post content display does not strip images. Thus, your post images are output.

Outcome #3 – display the WordPress featured image: This is the sweet spot for many users because it gives you complete control over the image displayed on each archive entry. To achieve this, 3 things must be true: your Genesis Include the Featured Image? setting must be checked to display images, you must be displaying excerpts or limited post content (i. e., not full content), and you must specify a WordPress featured image on each post where you want one to display.

Outcome #4 – display the WordPress featured image plus images in the post: This outcome is similar to #3 but can take on the bad quality of Outcome #5 depending on your image selection. To achieve it, 3 things must be true: your Genesis Include the Featured Image? setting must be checked to display images, you must display full content in archives (i. e., not excerpts or limited content), and you must specify a WordPress featured image on each post where you want one to display. Notice that the only change from Outcome #3 is that here, you’re displaying the full post content, which does not strip images. Therefore, your output is the specified WordPress featured image plus any images in the post. If you specify a WordPress featured image and you put that same image near the start of the post, you’ll see the “double image” problem.

Outcome #5 – display the attached image plus images in the post: This can easily become the “double image” problem if the first image in the post is at the top of the post. If images are deeper into long posts, this might be a good outcome. To achieve this, 4 things must be true: your Genesis Include the Featured Image? setting must be checked to display images, you must display full content in archives (i. e., not excerpts or limited content), you must insert at least 1 image somewhere in the post, and you must not specify a WordPress featured image.

Outcome #6 – display no image or a fallback image (if provided): This typically results in the display of no image because outputting the fallback image is extra work. If you’re running a custom plugin that creates a default fallback image, such as a default image for a category, then the fallback image will be output. But for this to happen, you have to push Genesis beyond its normal behavior; if you’re not doing that, your output will be no image.

Genesis Child Themes Can Customize This Behavior

All of the above is the default behavior with Genesis, but Genesis child themes can change all of it. Consider the StudioPress Going Green Pro theme. The functions.php of Going Green Pro contains code which:

1. first removes the action of adding an archive image in its normal location;
2. then adds it back to a different location in the archive and at the same time adds it to the single post view – provided you’ve enabled display of the featured image in your Genesis Include the Featured Image? setting.

Moving the archive image to a new location puts it above the post title, instead of its default position below it. It also adds the image to the single post display, something that’s not default behavior.

Not every Genesis child theme changes archive image behavior, and most don’t. Still, it’s important to understand that Genesis provides the flexibility to change how images are used, and your specific child theme may contain modifications to the defaults we’ve discussed.

Wrap Up

Together, WordPress and Genesis provide you plenty of fine-grained control to display images in archives to suit your needs. While Genesis could tweak its phrasing, there are a lot of things in play when it comes to displaying archive images. Some users focus on one detail, such as whether they’ve specified a WordPress featured image, but ignore another important detail, such as what portion of the post content they’re displaying.

With the right settings and behavior (and sometimes some custom programming), you can get WordPress and Genesis to display only the images you want on your post archives.