The WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.?Create a ticket in our bug tracker.
If you have ever added a custom link to an image blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. and then tried to do the same on a Gallery image, you will understand the frustration and confusion of not having consistency between different types of image blocks. This inconsistency is because the coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. Gallery block stores the details of the included images as nested <img> elements within the block content. Therefore, the images within a gallery look and behave different from images within an individual image block. There are some long-standing open issues related to this:
The only way to fix this with the Gallery block in its current state is to try and replicate the additional functionality that the Image block has in the Gallery block, and vice versa. While this would be possible, it would lead to an additional maintenance overhead to keep the UIUIUser interface and underlying code in sync between the two blocks.
To make the behavior of images consistent between the Image Block and Gallery, while avoiding code duplication, the core Gallery block has been refactored to save the individual images as nested core Image blocks using the standard core innerBlocks APIs. To make this work with the innerBlocksAPIAPIAn API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., the gallery structure also had to change from an ordered list to a collection of figure elements within a figure. This structure change also brings the core Gallery block into line with the W3C WAI guidelines on the grouping of images.
The structure change means that Gallery images now have the ability to add custom links, or custom styles, for each image. An example of the flexible Gallery layouts this opens up can be seen below.
Gallery images will also automatically inherit new functionality that is added to the Image block, including those added by plugins. Below is an example of a Gallery block making us of the Image wave style and vintage filterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. option added by the CoBlocks pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party.
Other benefits include being able to use the standard move, drag and drop, copy, duplicate, and remove block functionalities. Keyboard navigation also benefits from the adoption of the standard block model by the Gallery block.
Accessing the new Gallery Block
To access the new Gallery block you will need to download the latest version of the GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ plugin. At the time of writing the change is still under an experimental flag, so once the plugin is installed check for an experimental setting ‘Enable the refactored gallery block’ and enable it if it is present:
If this flag is not present it means that the changes have been taken out of the experimental phase.
Currently, only new gallery blocks added after the experimental flag is turned on will be in the new format, all existing galleries will be editable and viewable in the current format. You can manually transform an old format gallery to the new format by clicking the ‘Update’ button that will appear in the block toolbar.
What theme and plugin authors need to do before 5.9
To support the new Gallery block format, plugin and theme authors should aim to do the following before the December release of this change in WordPress 5.9.
Add additional selectors to target the new nested image block in both the editor and front end (existing selectors must remain to support the existing gallery block content). The new structure can be seen below.
Test block transformations. Temporary transformation filters have been added to handle the transformation of 3rd party blocks to and from the new core gallery block format. However, block plugins with gallery transforms should still be tested with the Gutenberg plugin to ensure these transformations work correctly.
In the future, the temporary transformation filters may be deprecated, and plugin authors will then need to update their transformations to handle the new Gallery format. Notice will be given ahead of this change being made.
Additional context and considerations
Other existing solutions
Third-party block developers are currently solving some of the problems caused by the limitations of the core Gallery block by implementing their custom Gallery blocks. These include some of the missing functionality, like the ability to add custom links to individual images. This can be problematic for site owners and content editors due to a large number of Gallery blocks that offer very similar functionality, but none of which appear to provide a close match to the functionality available with individual core Image blocks.
There do not appear to be any examples of plugins that already solve this problem in a way that utilizes Image blocks as inner blocks.
Backwards compatibility considerations
This is a breaking change due to the fundamental change in the underlying Gallery structure. Due to the large number of Gallery blocks already in use, along with themes and plugins that may rely on the existing structure, the following steps have been taken to mitigate the impact of this change on theme and plugin developers as much as possible:
For the initial release in the Gutenberg plugin, there will be no automatic migrationMigrationMoving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. of existing gallery content. This means that all existing gallery content will behave the same in the editor and front end as it does now, so will be compatible with existing plugins and themes. Only new gallery blocks added after this change will have the new structure in the editor and the front-end. The plan is to add automatic migration of existing gallery content when loaded in the editor to the 5.9 WordPress release.
While the refactored gallery works effectively with these plugins and themes, there may be edge cases in other plugins and themes that have not been accounted for. Themes that heavily modify the gallery CSS based on the existing <ul><li></li></ul> will definitely need to be updated if the same style changes need to be applied to the new gallery format. Therefore, it is recommended that theme and plugin authors test the changed gallery block well in advance of the 5.9 release.
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:
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.
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_stylefilterFilterFilters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., 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 htmlHTMLHyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. elements that are meant for presentational use, and they made it harder to style galleries.
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.
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.