As my wife and I were each posting our daily photos this afternoon, she asks me to help her put a two line caption under one of her photos. Being somewhat knowledgable about such things, I tell her that I’d be happy to help. And what should have been a very simple task, turned into an hour and a half of messing around and re-writing the captioning capabilities in WordPress. Let me start with a little background. First, let me acknowledge that WordPress is a great blogging platform for text. And I have seen some really beautiful photography blogs created on this platform. But what most people don’t realize is that these photo-blogging themes have a ton of custom code. Out of the box, WordPress is still absolutely awful with regards to text mixed with media. And I do realize that they’ve been constantly updating things, but it’s frankly still a crude environment.
The multi-line captions are a good example. While WordPress 2.5 added the ability to have captions, instead of building it into the user interface and allowing the user / writer to create content to be used as a caption, they instead decided to have the photo import interface add an odd caption shortcode which WordPress will later replace with actual HTML. What this means is that unless you want to modify WordPress core files (a very bad idea since you’d have to do it every time you upgraded WordPress), you’re stuck trying to fix captions within the bounds of their already lacking system. So, without further rambling, here’s the long and the short of fixing the captioning system (a little bit).
Current Implementation (WordPress 2.5+)
Before fixing the captions, we need to understand exactly how it works out of the box. When you go to insert a photo into a post, if you type anything in the caption dialog, WordPress will insert an image surrounded by a “caption” shortcode. It goes through and replace this caption shortcode with actual HTML when it’s requested by a reader. However, instead of taking a block of text and including it, all it takes is one lousy string that can’t have anything but text.
Allowing Multiline Captions
Due to the existing implementation, there is really only so much we can work with. We need to take the caption and break it into multiple lines, but remember, WordPress won’t store more than a string for the caption. To fix this, I decided that I’d insert line breaks into the caption based on a text string — in my case, I chose the “|” symbol as I don’t ever see it being used in a caption. You can replace it with whatever you like. To override the existing caption code, edit your theme’s functions.php file and add the following code (note, clicking on the left-most button in the top right of the code box will open the source in an editor — perfect for copying and pasting).
Please note, this will not work when inserting images in the WordPress Gallery format.
/* *********************************************
Function to allow multi-line photo captions. This function will
split captions onto multiple lines if it detects a "|" (pipe) symbol.
********************************************** */
/* Override existing caption shortcode handlers with our own */
add_shortcode('wp_caption', 'multiline_caption');
add_shortcode('caption', 'multiline_caption'); </p>
<p>/* Our new function */
function multiline_caption($attr, $content = null)
{
extract(shortcode_atts(array( 'id' => '',
'align' => 'alignnone',
'width' => '',
'caption' => '' ), $attr));
if ( 1 > (int) $width || empty($caption) )
return $content;
if ( $id ) $id = 'id="' . esc_attr($id) . '" ';
$new_caption = str_replace("|", " ", $caption);
return '<div ' . $id . 'class="wp-caption ' .
esc_attr($align) . '" style="width: ' .
(10 + (int) $width) . 'px">' .
do_shortcode( $content ) .
'<p class="wp-caption-text">' .
$new_caption . </p></div>';
}
With this done, all that was left was to edit the caption of the desired photo with something like this: “First line of caption.|Second line of caption”.
Additional Resources
In searching the web for a solution, I found everything but what I needed. However, I did find some good resources for WordPress captions in general.