Themes: Add ability to show a random header image

[lancewillett]

Goal:

Add the option to load a different header image with each page load.

(Note: this is not intended to be a "random image rotator" that changes the image without a page load.)

Admin

If a theme has multiple headers defined with register_default_headers(), and the theme chooses to enable this feature, show a new option in checkbox in Appearance > Header that turns on the randomization.

Make the new option the first (or last) radio option in the form so that you choose not to use a single image, but to show any of them on any page or post. See attached screenshot "random-option-admin-example.png" for a visual example.

Theme Support

1. Themes wishing to use this feature should define multiple header images with register_default_headers().
2. Then turn it on with define( 'HEADER_IMAGE', 'random' ) to set it on by default for the theme. If set to "random" and a user visits Appearance > Header the "Show Random Image" option should be selected instead of one of the images.

When get_header_image() is called from a template, instead of returning the value in "header_image" theme_mod, the function should pick a random node from the global $_wp_default_headers variable and return its URL instead.

Reference:

• This was originally brought up in #14151.
• A further idea is to allow end users to rotate multiple header images that they've uploaded. See #15100 for the general idea.

[lancewillett]

As Nacin ​mentioned over on #17242:

It would be great to move away from them everywhere possible, and go in the direction of add_theme_support() with an array of extra arguments being passed to it.

This could be changed to use that technique also:

add_theme_support( 'random-header-image', array( 'on' => true ) ); where it'd be off by default.

[aaroncampbell]

I'd rather see the ability to upload several images and then just choose "random" in the ui. I don't particularly see why a theme should choose whether it supports random header images...that seems more like a user choice (as long as all the header images WORK with the theme, why should the theme care if they change on each page load).

[lancewillett]

Replying to aaroncampbell:

I don't particularly see why a theme should choose whether it supports random header images...that seems more like a user choice.

Good point. So you're saying don't add any theme support, but update core functionality to add the random option if multiple images exist?

That makes sense, and it's good for backwards compatibility.

[lancewillett]

Attached patch implements this for images registered with a theme (Twenty Ten, for example).

Ready for testing.

[lancewillett]

Second pass

[lancewillett]

Second pass at patch introduces two new functions:

get_random_header_image()

and

is_random_header_image()

• Check if random header image is in use.
• Always true if user expressly chooses the option in Appearance > Header.
• Also true if theme has multiple header images registered and no specific header image is chosen.

Theme does not have to explicitly add support for this feature—all that's needed an array of registered images.

In Appearance > Header form, show the random image option if this theme has multiple header images. The option is checked by default if no header has been set.

[ryan]

Looks good so far in my testing.

[nacin]

Patch looks good. But I don't really like this as a core feature currently. If I want to have random header images, then chances are I'll want to upload a series, rather than cycle through the ones registered in code.

I think we need better integration with the media library before doing something that feels, personally, half-baked.

[lancewillett]

Replying to nacin:

Patch looks good. But I don't really like this as a core feature currently. If I want to have random header images, then chances are I'll want to upload a series, rather than cycle through the ones registered in code.

I agree, but we have to start somewhere. The rotation of the default headers is a big improvement, in my opinion. It's better than nothing and paves the way for a better solution later.

There is an open ticket for allowing multiple uploaded header images, see #15100. I'd absolutely love to get that in 3.2 but realize we're very close to the freeze, so that's why this ticket is split out on its own.

[ryan]

Show uploaded headers

[ryan]

Patch shows uploaded headers in the header list. Uploaded headers have a post meta key named _wp_attachment_is_custom_header that isset to the stylesheet of the current theme. Currently uploaded and default headers are shown in the existing header selector and are part of the same pool when a random image is selected. I'm doubting someone who was uploaded headers will want to see the default headers in the random mix. I'm thinking we'll want to have separate header selector lists in the UI for the default and uploaded headers.

[jane]

Or instead of a Random: show random image radio button with each set (as I imagine Ryan's suggestion to work?), have option for Randomize Header Images: [] default header images only [] my uploaded header images only [] all header images

That's my UI suggestion. I semi-agree with Nacin, that maybe putting this in core right now is rushing it? Trying it out in the theme first is sort of the equivalent of trying it in a plugin, right?

[ryan]

Having it in the radio is convenient though. We don't have to do anything extra to clear the selection.

[ryan]

Separate default and uploaded

[ryan]

That separates the UI and the random pools for default and uploaded.

[ryan]

Needs some styling and markup validation work but otherwise pretty much complete.

[ryan]

Also needs caching for the attachment query.

[ryan]

(In [17757]) Allow selecting previously uploader headers and randomly serving previously uploaded or default headers. Props lancewillett. see #17240

[lancewillett]

Looking good! One issue I found in testing:

If I upload an image that needs a crop, it works beautifully and shows in the Uploaded list.

But, if I upload an image at the exact dimensions, it doesn't add the meta value and doesn't show in the list.

[ryan]

(In [17758]) Set meta when upload matches dimensions. see #17240

[lancewillett]

When a theme has multiple "default" images registered, and the HEADER_IMAGE definition is empty, we turn on randomness by default. That's fine, but in that case there is no way to remove the header image entirely.

Maybe the "Remove Header" action should not set the header_image theme mod to be empty but instead make it explicitly "remove-header" or something similar. That way get_header_image() knows to hide all header images from display.

Patch attached.

[kawauso]

is_random_header_image() will return true when no header image is selected, but this is conditional on $type being 'any'. The checked() call for the Random radio button on the Header screen uses 'default', so no radio buttons appear checked. Following patch adds a clause to catch this.

Also, shouldn't the default-header class and input name in show_header_selector() be called something more logical since they're also used for user uploaded headers?

[kawauso]

Allow for $type 'default' when no header is chosen

[ryan]

(In [17770]) Fix hiding of header image. Fix radio selection when falling back to randomized default headers. Props lancewillett, kawauso. see #17240

[ryan]

lancewillet, twentyeleven_admin_header_image() emits an img tag with empty src when the header is removed. This results in the broken image icon being displayed.

[ryan]

There are two divs with the available-headers id. Perhaps that should become a class.

The random radios need to have the vertical alignment fixed.

[lancewillett]

@ryan I can look at both those issues shortly.

[lancewillett]

The vertical alignment is super-tricky with this layout because it requires knowing the height of the thumbnail images. A better solution might be to put it above the thumbnails on its own line. That avoids it needing to line up visually with the thumbnails. (See attached screenshot "random-option-above.png" for an example.)

Patch has this random option fix, plus some text updates and fix for a missing end paragraph tag. Patch also changes "available-headers" to be a class attribute instead of ID.

[lancewillett]

[17773] fixes the twentyeleven_admin_header_image() empty img src issue.

[ryan]

In [17773]:

Remove h3s. see #17240

[lancewillett]

In [17775]:

Twenty Eleven: improve calls to get_header_image() - see #17240 and #17198

[scribu]

Related: #17291

[lancewillett]

@ryan A reminder that I added some minor fixes with 17240-random-input-fix.diff -- patch is ready for review and testing.

[ryan]

In [17814]:

Custom header admin UI fixes. Props lancewillett. fixes #17240