HTML5 Galleries & Captions in WordPress 3.9
WordPress 3.6 introduced HTML5 versions of popular template tags, starting out with comments, the comment form, and the search form. With the 3.9 release we add galleries and captions to that list. Now, when adding HTML5 support for those features, WordPress will use <figure>
and <figcaption>
elements, instead of the generic definition list markup.
To declare that your theme supports these new HTML5 features, add the following call to your theme’s functions.php
file, preferably in a callback to the after_setup_theme
action:
add_theme_support( 'html5', array( 'gallery', 'caption' ) );
For forward compatibility reasons, the second argument with the specific parts can’t be omitted when registering support. Otherwise a theme would automatically declare its support for HTML5 features that might be added in the future, possibly breaking its visually because of it.
For both galleries and captions not only the markup changes when a theme declares its support for them, there are also peripheral changes that come with it.
Galleries
By default, galleries will not include inline styles anymore when in HTML5 mode. This caters to the trend of disabling default gallery styles through the use_default_gallery_style
filter, a filter that even the last two default themes used. With that, theme developers can always start with a clean slate when creating their own set of gallery styles.
We also took the opportunity to remove the line breaks between rows of images. Not only did they encourage an inferior way of positioning elements, more importantly they were non-semantic html elements that are meant for presentational use, and they made it harder to style galleries.
Captions
Up until now, captions received an additional 10 pixels of width, to keep text flowing around the caption, from bumping into the image. As @nacin put it, this has vexxed theme developers for years, and even resulted in the addition of a filter in WordPress 3.7 to manipulate the caption width.
We were not able to completely remove the inline style in HTML5 mode, it’s still necessary to force captions to wrap, but we’re no longer the adding 10px of width. We also removed caption styles in the editor, bringing it on par with how non-captioned images are displayed:
Twenty Thirteen and Twenty Fourteen have been updated to support both features, while retaining backwards compatibility with older WordPress versions. There is a remote possibility however, that child themes that use element selectors to overwrite gallery or caption styles can lose those customizations. Please test your child themes with the current development versions of the last two default themes.
If there are any questions about the current implementation, feel free to leave a comment below.
andrei1709 5:08 am on April 15, 2014 Permalink
Awesome! Thank you very much for this update
Manuel Schmalstieg 12:07 pm on April 15, 2014 Permalink
Glad to see that the HTML5 mode removes the BR tags from the gallery markup. That’s great news for responsive theme development!
Morten Rand-Hendriksen 3:12 pm on April 15, 2014 Permalink
This is great and long overdue. I always say WordPress is at the forefront of web standards and the two thing that have been lagging behind are the galleries and comments. This is a major milestone that will change the way we think about built in features.
glueckpress 9:15 am on April 16, 2014 Permalink
(goes updating themes)
Justin Kopepasah 6:43 am on April 17, 2014 Permalink
This is great news. I was happy when the filter was introduced and now I am elated to see the ability to implement HTML5 galleries completely. Definitely adding this to my latest theme.
car57 6:52 pm on May 14, 2014 Permalink
I am not a developer, so would you be so kind as to explain what is meant by:
To declare that your theme supports these new HTML5 features, add the following call to your theme’s functions.php file, preferably in a callback to the after_setup_theme action:
add_theme_support( ‘html5′, array( ‘gallery’, ‘caption’ ) );
I have a functions.php file for a child theme. I don’t know what code to insert to have “a callback to the after_setup_theme action”
TIA
Knut Sparhell 12:39 am on May 15, 2014 Permalink
A callback is a function (or class method) that is added to an action by add_action(). In this case
add_action( 'after_setup_theme', 'my_theme_setup' );
. Inside my_theme_setup() function you can add the theme support. It could also be added in other actions, like ‘init’ or ‘wp_loaded’, but not before ‘after_setup_theme’ has fired. If you just add the support in the outer scope of functions.php it may be executed too early in the load process. The internal data structures to receive this theme addition may not have been initialised before ‘after_setup_theme’.The outer scope of functions.php (and plugins) should only add actions and filters, nothing else. All things you want to do should be inside a “callback” (a function or a class method, to be precise).
See http://code.tutsplus.com/articles/the-beginners-guide-to-wordpress-actions-and-filters–wp-27373
car57 7:56 pm on May 14, 2014 Permalink
no matter how i add php to functions.php, this script is never run. Still getting old-style dl with inline css. Sigh.
paulinelephew 12:02 pm on July 23, 2014 Permalink
Hi there,
I am using the Argo theme and I have no caption displaying with galleries.
I have tried about everything (including contacting the theme support a zillion times and they won’t get back to me).
I inserted the lines below in function.php and nothing happens:
add_action( ‘after_setup_theme’, ‘argo_setup’ );
add_theme_support( ‘html5′, array( ‘gallery’, ‘caption’ ) );
the website is http://www.terredalizes.fr
If anyone can help it is greatly appreciated!
Cheers,
Pauline