Retina theme custom headers

[nacin]

We should support retina custom headers. Not sure how — ideas welcome.

I may be oversimplifying this, but could we just create a 2x header image by default if they've uploaded/cropped a large enough image? Adding an additional retina image form field/button/link, would just add clutter to the UI I would think (and would likely end up confusing the majority of users). Just my 2 cents.

Assuming core adopts some descendent of devicepx.js, the -1x/-2x filename pattern would work fine here.

If the cropped region of the uploaded image is sufficiently (1.5x) larger than the target area, save the 1x-resized version with the -1x filename tag and also save a -2x version.

(This seems to agree with lessbloat's comment above.)

HiDPI Header image support - proposal

There's actually several cases to be considered, so I'm going to bullet point the major bits.

Enabling Support

• Theme must enable HiDPI support specifically by including a "hidpi"=>true in their add_theme_support( 'custom-header' ) arguments.

Why: Because not all themes will be capable of taking advantage of HiDPI headers, as you'll see below.

Image Creation

There's a couple cases to consider. I'll take them in order.

Fixed-width headers

• If hidpi support is enabled, and the uploaded image is > 1.5x the fixed width the theme specifies, then the image resizing code will create two images, one with the proper width, and one with up to 2.0x the width. The image will be saved as part of the same normal attachment, but with the size scaled down in the meta.

• That is to say that normally creating an image via the header creation causes the "full" image to be the cropped version of the image, while the thumbnail/medium/large sizes get generated as per usual. In this case, a new size even larger than "full" called "hidpi" will be created as well. The filename of this image will reflect the actual size of the image, but the width/height in the imagemeta will be altered to reflect the intended display size. This will have the effect of having the img tag generated to have the smaller width/height pieces, allowing for the hidpi effect on capable screens.

Flexible-width headers

• With flex-width headers, there's a desired width and a maximum width. If hidpi support is enabled, and the image uploaded width is greater than max-width and also greater than 1.5x the minimum-width, then the same logic as fixed width is applied. For an example for twentytwelve, the image uploaded would need to be greater than 2000px wide to get the above logic applied, however in such a case the resulting image would be half as wide as expected. So uploading a 1999px wide image would result in a 1999px wide header, but uploading a 2002px image would result in a 1001px wide header (with a 2002px wide one for hidpi cases).

• The proposed flexible width handling may lead to user confusion if the theme doesn't choose sensible max widths (IMO, a 2000px max-width is a bit ridiculous... scale it back, guys). This is one reason why hidpi support must be explicitly enabled by the theme for any of this logic to occur.

Image display

There's two cases to consider here as well.

IMG tags

• Right now, themes should call get_header_image() to get the bare URL of the header image, then call get_custom_header()->width and get_custom_header()->height; to get the width/height, and then generate the img tag themselves.

• Proposed approach: get_header_image_tag($size) and associated header_image_tag($size) functions to produce the entire IMG tag, with the necessary width and height parameters. These would be wrappers similar to the various get_attachment functions that do much the same work. A size parameter of "hidpi" could be passed to obtain the hidpi version of the image if needed. The theme would have to do its own detection (or use JS replacement methods that I'm planning on providing in #21038, perhaps making this automatically handled; more on that over there, later).

Make CSS an option

• Currently, the image tag method above is pretty much the only way to implement custom headers. However, another way to do it would be for the theme to simply provide a DIV with a "custom-header" class, and have WordPress itself output the necessary CSS to do the background-image code and so forth. The advantage in this case is that the HiDPI handling could be done entirely in the CSS, including the alternate image for the device-pixel-ratio case, if such an image was available. The CSS would be output in the wp_head call, similar to how the custom-background CSS is output currently.

• To indicate that the theme supports this approach, an argument of "output_css" => true or similar could be added to the add-theme-support function call. This would be the preferred way, for obvious reasons. Alternatively, if the class name is chosen wisely, the CSS output could simply be on by default, since a theme that didn't include the necessary DIV with the class would simply not have the CSS take effect anywhere.

Suggestions? Criticism? Comment.

Per ​the IRC meetup yesterday, HiDPI support for user-uploaded images is no longer part of 3.5's scope, due to the complexities of implementation. With the media UIs and image APIs improving quite a bit in this release, it ideally becomes more feasible in a future version. It is unfortunately too much at once to try it in 3.5 while everything it would be built upon is also shifting around.

Combined with the fact that HiDPI support everywhere on the internet remains a total hack, this also gives browser makers and standards bodies some more time to come up with a sane way to handle HiDPI support.

Otto42 will be watching #21390 (and related tickets) closely to make sure the right hooks are in place so this can be attempted in a plugin.

This applies to #21038 (user content), #21455 (backgrounds), #21389 (headers).