Image captions

Have been thinking what's the best way to do this. Generally there seem to be four options:

- Hard-coding the caption tags when the image is inserted. That seems like the easiest/most compatible way. Will only need few lines of css added to wp_head(). Disadvantages: cannot be removed later without editing the posts, no backwards compatibility.

- Filtering the content and adding them to each image. This will require a regexp filtering for the blog and similar js for TinyMCE. Advantages: backwards compatible, can be disabled. Disadvantages: the regexp have to run on each page load and may have to check image sizes (captions on thumbnail sized images don't look good). That could be problematic/quite slow when the image is hosted elsewhere and width/height are not set.

- A combination of the above two. A shortcode can be added around the image tag when inserting the image, then either rendered or removed when displaying the post (or perhaps the whole image tag can be a shortcode). Still won't be backwards compatible, but display of captions could be enabled/disabled on demand.

- The captions can be handled entirely with JavaScript?. This seems the most flexible way. It would be backwards compatible and could be enabled/disabled at any time. Disadvantages: may conflict with some plugins that also use js to change the images (that is also a possibility for all methods).

Also think that we will need another checkbox in the miscellaneous settings to enable/disable the captions globally.

Support for image captions, first run. Uses shortcode around the img tag for the caption's settings, so <img/> or <a><img /></a> becomes

[wp_caption]<a><img /></a>[/wp_caption]

This way seems most compatible and at the same time futureproof. Any king of tags can be generated while processing the shortcode, or if captions are not needed, the shortcode can be filtered out and the default tag(s) returned.

Currently the captions are rendered similarly to the gallery page:

<dl>
<dt><a><img /></a></dt>
<dd>caption text</dd>
</dl>

This is supported in both TinyMCE and on the blog. All images that have alt text (attachment excerpt) will have captions when inserted in the editor. Also while editing older posts, if the images are edited and have alt text, the caption will be added. To stop showing caption for an image, the caption text should be deleted while editing the image (with the new popup), or the shortcode can be deleted from the HTML editor.

The basic styles for the captions are in the Default and the Classic themes' style.css files. The users would have to copy/paste them in their current theme's style.css, similarly to the alignment classes.

(In [8239]) Image captions from azaozz. see #6812

Sometimes I get the raw wp_caption code surrounding the image in the RTE.

Editing the image and clicking "Update" will sometimes fix it. FF3 on Mac OS.

Fix for showing of raw shortcode in the editor: creates the caption HTML before inserting new image, rather than on TinyMCE cleanup.

(In [8245]) Image caption fixes from azaozz. see #6812

This patch includes several fixes: captions are properly created in tables and in lists, all tags are properly removed when deleting a caption, the "align" buttons can be used to align the captions.

(In [8260]) Image caption fixes from azaozz: captions are properly created in tables and in lists, all tags are properly removed when deleting a caption, the align buttons can be used to align the captions. see #6812

Fix for single and double quotes entered in the captions, also simplifies the HTML tags on the site, renames the css classes to use dashes.

(In [8289]) Use dash instead of underscore for CSS names. Props azaozz. see #6812

(In [8290]) Fix quotes in captions. Props azaozz. see #6812

Caption styles in the default theme are not correct. Dashes instead of underscores, that sort of thing.

Additional: My bad, I see that was intentional. Well, if you're going to use dashes, then you should probably make the shortcode actually produce them, because on trunk it's still making underscores and such.

Never mind. I'm a moron and forgot to update the wp-include directory.

Fixes image resizing inside captions, adds edit alt field to the advanced tab.

(In [8307]) Fix image resizing inside captions, add edit alt field to the advanced tab. Props azaozz. see #6812

Support for disabling captions. To disable, define the constant DISABLE_IMAGE_CAPTIONS as true:

define('DISABLE_IMAGE_CAPTIONS', true);

either in wp-config.php or in the theme's functions.php.

That constant is complete bloat, and I don't think it's worth having in WP.

Agree, renamed to CAPTIONS_OFF, also renamed the shortcode to "caption" (the old one is still registered for back compat).

You don't need a constant to not display the captions. Just either don't use the shortcode or hide them using CSS.

Instead of a useless constant, simply make a checkbox for captions on/off on the image insertion screen.

This is so that themes that provide their own captioning can disable WP's.

(In [8313]) Rename wp_caption shortcode to caption. Allow themes to disable captioning. Use dashes instead of underscores in class names. Props azaozz. see #6812

Went with the patch to get the other changes. We change how disabling is done if need be.

Replying to Otto42:

You don't need a constant to not display the captions. Just either don't use the shortcode or hide them using CSS. Instead of a useless constant, simply make a checkbox for captions on/off on the image insertion screen.

It's very easy to stop displaying the captions on the blog. Registering an empty shortcode that returns the <img> tag would do it (the <img> tag is the content of the [caption] shortcode).

Not so easy to disable the adding of captions when inserting or editing an image in the editor though. Of course it can be done with another checkbox in the user's settings, or a checkbox/cookie from js, but that would make it harder for themes/plugins. They will have to support both states, disabled and enabled, as it would be an user setting.

(In [8321]) Denote CAPTIONS_OFF as temporary. see #6812

Removes the disabling of captions, but leaves couple of hooks so a plugin can do it easily.

(In [8358]) Removes the disabling of captions, but leaves couple of hooks so a plugin can do it easily. see #6812

I don't even see why that filter hook for disable captions is necessary. You've already got a filter to replace the captions system entirely. So disabling captions is as easy as this:

function no_caption($deprecated, $attr, $content) { return $content; };
add_filter('img_caption_shortcode', 'no_caption', 10, 3);

Why have yet another useless filter hook?

Replying to Otto42:

I don't even see why that filter hook for disable captions is necessary. You've already got a filter to replace the captions system entirely. So disabling captions is as easy as this: {{{ function no_caption($deprecated, $attr, $content) { return $content; }; add_filter('img_caption_shortcode', 'no_caption', 10, 3); }}} Why have yet another useless filter hook?

That would stop the captions from displaying on the site, but not in the visual editor and the user will still be able to enter them.

(In [8607]) Removes the disabling of captions, but leaves couple of hooks so a plugin can do it easily. For 2.6.1, see #6812