Cover Block Refactor Dev Note

Prior to the WordPress 5.9 release, the Cover blockBlock Block 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. was refactored in ways that changed the block HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. structure, and these changes were merged into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and released in 5.9. These changes were not noted in a Dev Notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. at the time, or in the 5.9 release notes, so theme and pluginPlugin A 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 authors were not alerted to this change.

This is a retrospective Dev Note to outline the reasons for, and the nature of these changes, and also to highlight two regressions that this change introduced. Patches for these regressions will be included in the 5.9.1 release.

The changes

Background opacity

In order to allow the opacity of the Cover block to be set when only a background color was set, the background color style had to be moved from the main block wrapper to the same nested <span> element that is used to set the background image. This means that a Cover block with a background color set changed from:

<!-- wp:cover {"overlayColor":"vivid-cyan-blue"} -->
<div class="wp-block-cover has-vivid-cyan-blue-background-color has-background-dim">
<div class="wp-block-cover__inner-container">
    <!-- wp:paragraph {"align":"center","placeholder":"Write title…","fontSize":"large"} -->
        <p class="has-text-align-center has-large-font-size">Cover with no background color opacity
        </p>
    <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

to:

<!-- wp:cover {"dimRatio":70,"overlayColor":"vivid-cyan-blue","isDark":false} -->
<div class="wp-block-cover is-light">
    <span aria-hidden="true" class="has-vivid-cyan-blue-background-color has-background-dim-70 wp-block-cover__gradient-background has-background-dim"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:paragraph {"align":"center","placeholder":"Write title…","fontSize":"large"} -->
            <p class="has-text-align-center has-large-font-size">Cover with background color opacity</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Regressions introduced by the change

  1. When Cover blocks are edited they are automatically migrated to this new structure, but all existing blocks in post content need to have the old version of the CSSCSS Cascading Style Sheets. in place in order to be correctly supported in the site frontend. Some of these deprecated styles where inadvertently removed which meant that those blocks with a custom opacity set defaulted back to an opacity of 0.5. This regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. has been fixed with this GitHub pull request and will be included in the 5.9.1 release. In the meantime the addition of this custom CSS to a 5.9 site will also fix this issue.
  2. Currently the background gradient class is also being applied in cases where the gradient is not set. This issue is fixed with this GitHub pull request, and will be included in the 5.9.1 release. If you created/edited a theme/plugin in the last 3 months that is now relying on the wp-block-cover__gradient-background always being in place you will need to review this change. The alternative class .wp-block-cover__background has been added in 5.9.1 to enable selection of the background span in all contexts.

Default background color

Previously when adding a Cover block with a white background the paragraph text was invisible as it was also set to white. The Cover block was updated to only set the text to white if the background was dark. This required the addition of an additional is-light class on the blocks outer wrapper.

When a background image is used, a ‘best guess’ approach is taken to determine if light or dark text should be used based on the ‘average’ color of the image. This can lead to imperfect results if an image is largely ‘light’, but the text is placed over a dark patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing., as outlined in this GitHub issue. In these instances the text can be manually updated to a more suitable color. This was considered to be less of a UXUX User experience issue than white text being invisible by default over a white background.

#5-9, #dev-notes