Block-based Widgets Editor in WordPress 5.8

WordPress 5.8 introduces a new 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.-based widgets editor to the Widgets screen (Appearance → Widgets) and CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. (Appearance → Customize → Widgets). The new editor allows users to add blocks to their widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. areas using the familiar block editor interface introduced in WordPress 5.0. This gives users powerful new ways to customise their sites using the rich library of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and third party blocks. Existing widgets and third party widgets will continue to work and can be used alongside blocks.

Opting out of the block-based widgets editor

The block-based widgets editor is enabled in WordPress 5.8 by default. There are several ways to restore the classic editor:

  • A theme author may include remove_theme_support( 'widgets-block-editor' ). Learn more.
  • A site administrator may use the new use_widgets_block_editor filterFilter Filters 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.. Learn more.
  • A user may install and activate the Classic Widgets plugin.

New Widgets screen

The widgets.php adminadmin (and super admin) screen (Appearance → Widgets) now loads a block-based widgets editor which exists in the @wordpress/edit-widgets package.

The editor is built using ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. and is similar to the editor used for posts and pages (@wordpress/edit-post) and uses many of the same subsystems: @wordpress/interface and @wordpress/components for UIUI User interface, @wordpress/block-editor for block editing, @wordpress/data and @wordpress/core-data for persisting changes, and so on.

A new filterable function, wp_use_widgets_block_editor(), is used by widgets.php to determine whether to load the new block-based editor or the classic editor.

The Widgets screen is extendable via block editor APIs such as registerPlugin, registerBlockType, registerBlockVariation, and so on.

The Widgets screen uses new REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. endpoints which are detailed in a seperate dev note.

New Customizer control

The Widgets section in the Customizer (Appearance → Customize → Widgets) now loads a new control (WP_Sidebar_Block_Editor_Control) which contains an embedded block-based widgets editor that exists in the @wordpress/customize-widgets package.

The editor is built using React and uses @wordpress/block-editor and @wordpress/components to implement its block editing interface. It does not use @wordpress/data or @wordpress/core-data to persist changes. Instead, the existing Customizer JavaScript API is used.

A new filterable function, wp_use_widgets_block_editor(), is used by WP_Customize_Manager to determine whether or not to log the new block-based editor control or the classic editor control.

The block-based widgets editor in the Customizer is extendable via block editor APIs such as registerBlockType, registerBlockVariation, and so on.

New block: Legacy Widget

Existing widgets and third party widgets can be edited in the block-based widgets editor via the new Legacy Widget block. This block has an identifier of core/legacy-widget and exists in the @wordpress/widgets package. The Legacy Widget block is compatible with most third party widgets.

Broadly speaking, the Legacy Widget block has three states:

  1. Select. When first inserted, the block displays a list of widgets available to choose from. The list can be customised using the widget_types_to_hide_from_legacy_widget_block filter.
  2. Edit. When selected, the block displays the widget’s control form fields. This is determined by the widget’s WP_Widget::form() implementation.
  3. Preview. When not selected, the block displays a preview of how the widget will look once saved. This is determined by the widget’s WP_Widget::widget() implementation. A “No preview available.” message is automatically shown when widget() does not output any meaningful HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers.. Learn more.

The Legacy Widget block is not available in other block editors including the post editor, though this can be enabled for advanced use cases.

New widget: Block

Blocks added to widget areas are persisted using the same widget storage mechanism added in WordPress 2.8. Under the hood, each block is serialised into HTML and stored in a block widget. This is represented by a new WP_Widget_Block subclass that extends WP_Widget. A block widget is a specialised case of the HTML widget and works very similarly.

If blocks are added to a widget area, and then the block-based widgets editor is disabled, the blocks will remain visible on the frontend and in the classic widgets screen.

Tips to prepare for the new block-based widgets editor

Use the widget-added event to bind event handlers

The Legacy Widget block will display a widget’s control form in a way that is very similar to the Customizer and is therefore compatible with most third party widgets. Care must be taken, however, to always initialise event handlers when the widget-added jQuery event is triggered on document.

( function ( $ ) {
    $( document ).on( 'widget-added', function ( $event, $control ) {
        $control.find( '.change-password' ).on( 'change', function () {
            var isChecked = $( this ).prop( 'checked' );
            $control.find( '.password' ).toggleClass( 'hidden', ! isChecked );
        } );
    } );
} )( jQuery );

Use block_categories_all instead of block_categories

The block_categories filter has been deprecated and will only be called in the post and page block editor. 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 developers that wish to support the widgets block editor should use the new block_categories_all filter which is called in all editors. See #52920 for more details.

Allow migrating from widgets to blocks

Many core and third party widgets have a functionally equivalent block. For example, core’s Recent Posts widget is analogous to core’s Latest Posts block.

In order to avoid duplicate functionality, is is recommended that plugin authors provide a way for users to convert their existing widgets to any equivalent block. WordPress 5.8 provides a mechanism for doing this using block transforms:

  1. Configure your widget to display its instance in the REST API by setting show_instance_in_rest to true in $widget_options.
  2. Add a block transform to your block from the core/legacy-widget block.
  3. Hide your widget from the Legacy Widget block using the widget_types_to_hide_from_legacy_widget_block filter.

There is a guide containing more detailed instructions in the Block Editor Handbook.

Don’t use @wordpress/editor

Many legacy widgets call the wp.editor.initialize() JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. function to instantiate a TinyMCE editor. If a plugin or block uses the @wordpress/editor package and enqueues wp-editor as a script dependency, this will re-define the wp.editor global, often resulting in a wp.editor.initialize is undefined error.

Don’t use functions like is_admin() that won’t work in a REST API request

Because the Legacy Widget block makes REST API requests in order to render widgets, admin-only functions like is_admin() and is_plugin_available() are not available.


Written by @andraganescu and @noisysocks.
Thanks to @talldanwp, @isabel_brison, @kevin940726, and @get_dave for reviewing.

#5-8 #dev-notes #feature-widgets-block-editor #widgets #block-editor

Help Test the Widgets Editor for WordPress 5.8

Remember the 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. based Widgets Editor? In case you missed it, this new feature had both a previous call for testing and a merge proposal ahead of WordPress 5.6. After months of hard work, it’s back and better than ever! For a quick refresher, the block based Widgets Editor is an upgrade to the widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. areas provided by WordPress through themes, that enables users to add blocks right next to widgets to their headers, footers, sidebars and other widget areas.

Help test this feature

This is a call for testing for the new block based Widgets Editor. Please report your findings on GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ in the Gutenberg repository as issues or in the comments below. If you have triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. access, labeling any issue with [Feature] Widgets Screen or [Feature] Widgets Customizer,  depending on the issue, would be very helpful. Alternatively, you can simply include “[Widgets Screen]” in the title to help those who can set the labels appropriately. Check out the instructions below for more detailed information.

What’s new?

The most important addition since the last call for testing is that the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. now supports editing blocks and widgets in widget areas with live preview. Compared to the first iteration of this project, where the widget areas in the Customizer were read only, now you can add widgets and blocks with live preview, scheduling and sharing right from the Customizer.

The main benefit of upgrading the widgets functionality to blocks comes from the ability to directly edit widgets using the familiar block interaction that you use when editing a page or post on your site.  Being able to use blocks opens up tons of new creative possibilities, from no-code mini layouts to tapping into the vast library of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and 3rd party blocks to create content. 

For developers, unlocking blocks in widget areas also offers a core path to upgrade widgets to blocks and get ready for the future. With more aspects of content creation and management moving to blocks, including the upcoming block based theme format, this also helps bring consistency to the user experience. 

Is it ready?

This is currently betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. software and it has a host of known bugs. But it is also intended to be merged into core for the 1st beta of WordPress 5.8. As a merge candidate the goal of the testing is not to discover a bugbug A 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. free feature, but to observe if there are blockers for merging. During WordPress 5.8 beta releases, the bug list will be prioritized ahead of the release candidaterelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta)..

What to test:

Please keep in mind that it’s recommended that you test this feature on a development siteDevelopment Site You can keep a copy of your live site in a separate environment. Maintaining a development site is a good practice that can let you make any changes and test them without affecting the live/production environment. rather than a production siteProduction Site A production site is a live site online meant to be viewed by your visitors, as opposed to a site that is staged for development or testing.. For information about how to set up a development site, please refer to the Setting Up a Development Environment documentation.

Test using the WordPress Beta Tester Plugin and set it to:

– Update channel to “Bleeding edgebleeding edge The latest revision of the software, generally in development and often unstable. Also known as trunk.

– Stream options to “Beta/RCrelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). only”

You can install the WordPress 5.8 Beta 1 in two ways:

  • Install and activate the WordPress Beta Tester 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 (select the “Bleeding edge” channel and “Beta/RC Only” stream).
  • Direct download the beta version here (zip).

For users:

Migrating from classic widgets

  1. Be on the latest version of WordPress (5.7.1)
  2. Go to Appearance > Themes
  3. Go to Plugins > Add new
    • Install and activate a plugin that provides widgets
  4. Go to Appearance > Widgets
    • Add some core widgets. For example, Search or Recent Posts.
    • Add some 3rd party widgets (aka widgets provided by a plugin)
  5. Go to Plugins > Add new
    • Install and activate the latest version of the GutenbergGutenberg The 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
  6. Go to Gutenberg > Experiments
    • Check “Enable Widgets screen in Customizer”
  7. Go to Appearance > Widgets
    • Are all the widgets you added there?
    • Can you customize their settings?
    • Can you drag and drop widgets to different places?
  8. Go to Appearance > Customize > Widgets
    • Are all the widgets you added there?
    • Can you customize their settings?

Adding blocks next to widgets

  1. Be on the latest version of WordPress (5.7.1)
  2. Go to Appearance > Themes
    • Install and activate a theme that has support for sidebars
  3. Go to Appearance > Widgets
    • Add some core widgets.  For example, Search or Recent Posts.
  4. Go to Plugins > Add new
    • Install and activate the latest version of the Gutenberg plugin
  5. Go to Gutenberg > Experiments
    • Check “Enable Widgets screen in Customizer”
  6. Go to Appearance > Widgets
    • Click the inserter plus button in the top bar
    • Add some blocks
      • Do they work?
    • Save
      • Are they published on the front end next to the widgets?
  7. Go to Appearance > Customize > Widgets
    • Click the inserter plus button in the top bar
    • Add some blocks
      • Do they work?
    • Edit some of the block contents
      • Does the preview update accordingly?
    • Edit some of the classic widget’s contents
      • Does the preview update accordingly?
    • Publish
      • Are they published on the front end next to the widgets?

Opting out of the new widgets screen

  1. Be on the latest version of WordPress (5.7.1)
  2. Go to Plugins > Add new
  3. Go to Appearance > Widgets
    • Is the classic interface present?
  4. Go to Appearance > Customize > Widgets
    • Is the classic interface present?

What to notice:

  • Did it crash?
  • If it worked, did the editor perform as expected?
  • Was it intuitive for you to add blocks and third party widgets (ie from other plugins)?
  • Were you able to properly customize widgets as you wanted? 
  • Did it work using Keyboard only?
  • Did it work using a screen reader?

For developers:

Make sure to go through the general “How to” documentation available in the Gutenberg codebase for specific instructions. 

Test upgrading classic widgets to blocks.

  • The new block based widget editor introduces a new filterFilter Filters 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. `widgets_to_exclude_from_legacy_widget_block`. It is used to hide widgets that have block equivalents.
  • We now have a documented way to upgrade widgets to blocks via block transforms.The transform may be added to the legacy widget via typical block extending. This in turn enables users to migrate widgets they already have configured to new block equivalents  provided by plugins.

Test enabling and disabling theme support

  • Test widget areas provided by themes, particularly “dynamic” sidebars, which appear depending on other factors.

Test 3rd party widgets compatibility.

  • The most common case is for widgets that work in the Customizer but not in the stand alone widgets editor. Previously, developers opted to present the widget UXUX User experience differently in the widgets screen compared to the Customizer. However, the best practices are preserved in the Customizer.
  • We’re having an audit of extension points and how well supported they are. Please add missing things that you may find.

Considerations around Opt-in vs Opt-out

Because there is not enough data and stories, a decision has not yet been made on whether the block based Widgets Editor will be opt-out by default or an option for each theme to opt into. Currently, we’re providing the following options for opting out:

  • The Classic Widgets plugin which allows users to easily opt out of the new blocks in widget areas feature and see the classic widget editor only.
  • The `widgets-block-editor` theme supports which allows theme authors to opt out of supporting blocks in widget areas. This also reverts WordPress adminadmin (and super admin) to the classic widget editor.
  • The `gutenberg_use_widgets_block_editor` filter which allows administrators to opt out of supporting blocks in widget areas in cases where this is required. Like the two above, this also reverts WordPress admin to the classic widget editor.

A recent discussion in the Core Editor chat is a good summary on why we’re opting out via a plugin for users. Briefly, it seems to be the cleanest and least prone to maintenance requirements mode possible, versus settings in other plugins or user settings.

This is a difficult decision to make since supporting blocks in widget areas is an important part of the roadmap of WordPress and it will eventually be the default experience. Today, it’s important to determine the impact and significance of the current work on backwards compatibility.

Thank you!

Thank you for helping with testing the new Widgets Editor! Since it is one of the major focuses of WordPress 5.8 any help in this early stage is immensely valuable as it will help determine how viable it is for merging.

Later updates

Monday, May 17th – updated the instruction steps for the user section and added a step to enable the Customizer widgets block editor. This is essential to test the most important addition, adding blocks to widget areas using the Customizer.

Monday, June 14th – updated the instruction steps with newer recommended versions for testing (WordPress 5.8 Beta 1 and Gutenberg Plugin 10.8). Thanks to all the testers and all the feedback below. It was instrumental in advancing the state of the editor, and it’s now better than ever.

Friday, June 25th – updated the instructions to test using the WordPress Beta Tester Plugin.

#5-8, #call-for-testing, #customizer, #feature-widgets-block-editor, #gutenberg, #testing, #widgets

Call for Testing the Widgets Screen in Gutenberg 9.1

Thank you to @andraganescu and @mapk who collaborated with me on this post.

Introducing the Widgets Screen

After the GutenbergGutenberg The 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/ 8.9 release moved the new 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. based Widgets Screen out of experimental status, Gutenberg 9.1 released today includes design updates that now put the project in a great spot for a call for testing. This new functionality replaces the previous adminadmin (and super admin) Appearance > Widgets screen.

Image showing the layout of the new Widgets Screen.

The new Widgets Screen both replicates the functionalities of the previous screen and unlocks the ability to add blocks to widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. areas (also called sidebars) in any theme that supports this new screen.

Image showing the Inserter in the context of the new Widgets Screen.

Help test this feature

This is a call for testing for this new feature. Please report your findings on GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ in the Gutenberg repository as issues or in the comments below. If you have triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. access, labeling any issue with [Feature] Widgets Screen would be very helpful. Alternatively, you can simply include [Widgets screen] in the title to help those who can set the labels appropriately. Check out the instructions below for more detailed information.

Finally, testing should cover all the features you’d expect from the previous editor, as the new one should offer “feature parity”, meaning all the things previously available should still be available. Of note, it would be particularly helpful when testing to focus on the feature of adding blocks alongside classic widgets and to focus on any backward incompatibility issues that the block editor might introduce in relation to using widgets in themes.

Testing Flow

Here is a basic flow for testing:

  1. Have a site using WordPress 5.5.
  2. Make sure you use a theme that supports widget areas (e.g. TwentyTwenty).
  3. Go to the website’s admin.
  4. Install and activate the Gutenberg 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. If you already have it installed, make sure you are using at least Gutenberg 9.1.
  5. Go to Appearance > Widgets.
  6. Notice that it visually resembles the Block Editor now.
  7. If you have a 3rd party widget installed, search for it in the Block Library and add it.
  8. Adjust any required settings and Preview your widget.
  9. Now drag that Widget into another Widget Area on your screen.
  10. Go back to the first Widget Area and add an Image block.
  11. Below the Image block add a Latest Posts block.
  12. Save your changes and view them on the frontend.
  13. Go back to the Widget screen and drag the Image block into the “Inactive Widgets” Area.
  14. Save and check out the frontend of the website.
  15. Share your experience in the comments below or in GitHub directly.

What to notice:

  • Did it crash?
  • If it worked, did the editor perform as expected?
  • Was it intuitive for you to add blocks and third party widgets (ie from other plugins)?
  • Did it work using Keyboard only?
  • Did it work using a screen reader?

Backward compatibility testing

The best way to test for backward compatibility issues is to install plugins that provide widgets and try to add them to widget areas using the new Widgets Screen. If you already have a website using widgets and you use the Gutenberg plugin, the widgets you have set up should just appear in the new editor. Outside of testing what you commonly install, try popular plugins that provide widgets and see if:

  • The plugin widget can be added to any widget area.
  • The plugin widget can be set up and customized in the new Widget Screen.
  • The plugin widget renders well on the website’s frontend.

The new Widgets Screen is expected to introduce some backward incompatibility, mainly because the block based editor does not contain the same HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. as the previous screen. We do aim to support all of the previous screen’s hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., filters and actions, in both the admin and the frontend, as these are the correct extension points for WordPress.

Extendability testing

The new Widgets Screen should prefer blocks over corresponding widgets. That means that if a block is registered by a plugin and it covers the exact same role that a widget currently has, the developer of the block can use the new widgets_to_exclude_from_legacy_widget_block filterFilter Filters 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. to add the widget they replaced with the new block to an exclusion list.

All the widgets that have block equivalents will not be available to use through the LegacyWidget block.

Testing extendability should not focus solely on previous available hooks and filters but also imagining new points of extensibility in the new block based Widgets Screen.

Disabling the new Widgets Screen

Users of the plugin who do not want to test the new Widgets Screen or who require the old screen, can use a simple filter to disable the new Widgets Screen. Just place this in your theme’s functions.php file:

add_filter( 'gutenberg_use_widgets_block_editor', '__return_false', 100 );

Thank you!

Thank you for helping with testing the new Widgets Screen! Since it is one of the major focuses of WordPress 5.6 any help in this early stage is immensely valuable. If you would like to suggest improvements to this call for testing, leave them in the comments!

#5-6, #core-editor, #widgets

Accessibility improvements to widgets outputting lists of links in 5.5

When lists of links are displayed on a page for navigational purpose, it can become difficult for users utilizing assistive technologies to navigate between these lists while maintaining an understanding of the purpose of the links. The <ul> element also does not convey proper context.

Starting in WordPress 5.5, a new theme support feature (navigation-widgets) has been added to address this issue. When support is declared, all default widgets included in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that produce lists of links will be output wrapped in the <nav> element. Note: the markup produced inside this wrapper will remain unchanged.

Additionally, an aria-label attribute (which is spoken to users using assistive technologies) is automatically generated based on the widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user.’s title field and added to the nav element to help distinguish each navigation widget from other nav elements on the page (such as a primary navigation).

The feature is fully opt-in. Theme developers must declare HTML5 support for navigation-widgets. For many themes, this may need some additional CSSCSS Cascading Style Sheets. rules or adjustments to ensure the widgets remain properly styled when outputting the new markup.

Theme developers are highly encouraged to utilize this improvement in their themes. This new theme support feature is an easy way to improve semantics and accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) in all of the sites using your theme.

Widgets affected

The following default Core widgets are impacted by this change:

  • Navigation menuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site.
  • Archives
  • Categories
  • Pages
  • Recent posts
  • Recent comments
  • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.
  • RSS

How to declare support

Theme developers are encouraged to declare support for navigation widgets in their functions.php file. This can be done by calling add_theme_support() and passing the preexisting html5 feature with the new navigation-widgets type.

Example

// Declare support for navigation widgets markup.
add_theme_support( 'html5', array( 'navigation-widgets' ) );

// This can be combined with other HTML5 types if supported.
add_theme_support(
	'html5',
	array(
		'navigation-widgets',
		'comment-list',
		'comment-form',
		'search-form',
		'gallery',
		'caption',
		'style',
		'script'
	)
);

For reference, see the related documentation on DevHub.

As mentioned above, an aria-label will be generated for each widget based on the widget’s “Title” field. Below is a screenshot when aria-label attributes are not present to illustrate the problem for users utilizing a screen reader.

The screenshot above shows how the absence of aria-label attributes contributes to a poor experience when utilizing a screen reader. Props @afercia.

The screenshot below shows how the user’s experience is improved when by aria-label attributes.

The screenshot above shows how aria-label attributes helps users utilizing a screen reader to distinguish navigation elements from each other. Props @afercia.

Markup changes

Below is what the output markup looks like when support for navigation-widgets is not declared.

<!-- Without declaration for HTML5 `navigation-widgets` feature support -->
<div class="widget widget_archive">
	<div class="widget-content">
		<h2 class="widget-title">Archives</h2>
		<ul>
			<li><a href="mywebsite/2020/07/">July 2020</a></li>
			<li><a href="mywebsite/2019/12/">December 2019</a></li>
		</ul>
	</div>
</div>

Below is what the new output markup will look like when support for navigation-widgets is declared.

<!-- When the theme declares HTML5 `navigation-widgets` feature support -->
<div class="widget widget_archive">
	<div class="widget-content">
		<h2 class="widget-title">Archives</h2>
		<nav role="navigation" aria-label="Archives">
			<ul>
				<li><a href="mywebsite/2020/07/">July 2020</a></li>
				<li><a href="mywebsite/2019/12/">December 2019</a></li>
			</ul>
		</nav>
	</div>
</div>

Forcing navigation-widgets support

Support for HTML5 navigation-widgets feature can be forced on a site by using the new navigation_widgets_format filterFilter Filters 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.. This hook determines the type of markup used in widgets that contain navigation links.

This filter accepts two different values: html5 and xhtml. Returning any other value to this filter will output the old markup without these accessibility improvements.

// Force HTML5 markup.
function mytheme_force_semantic_nav_widgets( $value ) {
	return 'html5';
}
add_filter( 'navigation_widgets_format', 'mytheme_force_semantic_nav_widgets');

// Force legacy markup.
function mytheme_force_legacy_nav_widgets( $value ) {
	return 'xhmtl';
}
add_filter( 'navigation_widgets_format', 'mytheme_force_legacy_nav_widgets');

For reference, see the related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker.: #48170.

Props @whyisjake and @desrosj for proofreading.

#5-5, #accessibility, #dev-notes, #html5, #widgets

Changes related to Calendar Widget markup in WordPress 5.4

The HTML 5 specification permits the <tfoot> to precede the <tbody> element. That changed in HTML 5.1 and now <tfoot> must follow <tbody>.

Historically, the Calendar CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. used the <tfoot> element to display the calendar’s navigation links. But since the HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. 5.1 spec has changed, WordPress 5.4 moves the navigation links to a <nav> HTML element that comes right after the <table> element.

Moving navigation links outside of the <table> element offers better accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility), with clearer distinction between elements. And a <nav> element is the semantically correct element for any navigation system, in any context.

Here’s a sample of the Calendar Widget’s former HTML markup:

<div id="calendar_wrap" class="calendar_wrap">
	<table id="wp-calendar">
		<caption>February 2020</caption>
		<thead>
			<tr>
				<!-- Day Names -->
			</tr>
		</thead>
		<tfoot>
			<tr>
				<td colspan="3" id="prev"><a href="https://example.com/2020/01/">« Jan</a></td>
				<td class="pad"> </td>
				<td colspan="3" id="next" class="pad"> </td>
			</tr>
		</tfoot>
		<tbody>
			<!-- Calendar Grid -->
		</tbody>
	</table>
</div>

And here’s a sample of the Calendar Widget’s new HTML markup:

<div id="calendar_wrap" class="calendar_wrap">
	<table id="wp-calendar">
		<caption>February 2020</caption>
		<thead>
			<tr>
				<!-- Day Names -->
			</tr>
		</thead>
		<tbody>
			<!-- Calendar Grid -->
		</tbody>
	</table>
	<nav aria-label="Previous and next months">
		<span id="prev"><a href="https://example.com/2020/01/">« Jan</a></span>
		<span class="pad"> </span>
		<span id="next" class="pad"> </span>
	</nav>
</div>

If you’re a site owner, and especially if you’re a Theme author, you are invited to test this change thoroughly. You may need to make some CSSCSS Cascading Style Sheets. adjustments.

For example, here are the visual differences for Twenty Twenty, the current Bundled Theme.

Before this change:

After this change:


Update – February 25, 2020

Few HTML classes were introduced in get_calendar() for easier CSS targeting:

  • .wp-calendar-table for the <table> element.
  • .wp-calendar-nav for the navigation wrapper.
  • .wp-calendar-nav-prev for the previous month link.
  • .wp-calendar-nav-next for the next month link.

#prev and #next HTML IDs were also replaced with .wp-calendar-nav-prev and .wp-calendar-nav-next classes.


For full details, see the related ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.: #39763

#5-4, #dev-notes, #widgets

Porting Widgets to Blocks: Feb 18, 2019

All widgets we plan on porting to blocks have been merged! 🎉

Completed

  • Audio [2299]
  • Archives [7949]
  • Calendar [13772]
  • Categories [2102]
  • Custom HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. [1391]
  • Image [379]
  • Latest Comments [7941]
  • Latest Posts [870]
  • RSS [7966]
  • Search [13583]
  • Tag Cloud [7875]
  • Text
  • Video

Iterations

We have a couple of the more advanced widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. blocks with v2 designs. These are “nice to haves,” but not necessarily scoped to any particular release.

In Progress

Needs Feedback & Dev

Notes

  • The Classic Widget [13511] is going to be moved into the “widget area GutenbergGutenberg The 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/ support” project, since it impacts all of the widget screens.
  • You can track progress on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/https://github.com/WordPress/gutenberg/projects/20

#blocks, #gutenberg, #widgets

Porting Widgets to Blocks: Feb 4, 2019

There’s been a ton of work on porting widgets to blocks since my last update! Here’s where we’re at:

✅ Completed

  • Audio [2299]
  • Archives [7949]
  • Categories [2102]
  • Custom HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. [1391]
  • Image [379]
  • Latest Comments [7941]
  • Latest Posts [870]
  • RSS [7966]
  • Text
  • Video

✏️ Work in Progress

  • Classic Widgets [13511]
    • Could use some additional testing, thoughts, and reviews.
  • Search [13583]
    • Needs a final code review and sign-off.
  • Tag Cloud [7875]
    • Getting close! Could use some more code reviews and testing.

⌨️ Needs Dev

The following iterations on existing widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. blocks are “would-be-nice-to-tries”:

🗒 Notes

  • There’s an estimated ~4 weeks until this project is finished.
  • The Classic Widget [13511] is going to be moved into the “widget area GutenbergGutenberg The 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/ support” project, since it impacts all of the widget screens.
  • The MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. Widget [13335] issue has been closed in lieu of adding login/logout and RSS subscription support to the navigation menuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site. 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..
  • You can track progress on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/: https://github.com/WordPress/gutenberg/projects/20

#blocks, #gutenberg, #widgets

Status Update: Porting Widgets to Blocks

Per 9 Projects for 2019, all widgets will be ported over to GutenbergGutenberg The 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/ blocks. I went through and audited how close we are to completing this goal:

✅ Completed

  • Audio [2299]
  • Archives [7949]
  • Categories [2102]
  • Custom HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. [1391]
  • Image [379]
  • Latest Comments [7941]
  • Latest Posts [870]
  • Text
  • Video

✏️ Work in Progress

🖼 Has Design

  • Calendar [1462]
  • Classic Widgets [4770]
    • Any existing widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. will work by using the Classic Widget 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..
  • Navigation MenuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site. [1466]
    • This has a bunch of design ideas, but not a finished design. This block design is still a WIP.
    • Note: This is also its own 2019 project.

Additionally, the following completed widget blocks have v2 designs:

⌨️ Has PR

🙅🏽‍♀️ Deprecate?

There’s a couple widgets that I personally think can be deprecated:

  • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.: Feels anachronistic and out-of-place in modern WordPress.
  • Pages: Should be replaceable with a navigation menu block.

Next Steps

Given this list, I think our top priorities are:

  1. Reopen, finish up, and merge existing widget block PRs.
  2. Create a PR for Calendar — maybe two: one following the original design, and one following the more complex v2. The original can likely be completed and merged quickly, which would put us in a great place in terms of widget support.
  3. Review the Classic Widget block design to ensure it matches current Gutenberg patterns, and create a PR.
  4. Create v2 PRs for Archives, Calendar, Recent Comments, and Recent Posts. Having a working PR can help us establish whether or not the designs are feasible, and a better experience.

Navigation Menu, as a broader block that extends beyond just widgets, should be tackled separately from this effort.

@karmatosed has created a new GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ project we can use to track progress: https://github.com/WordPress/gutenberg/projects/20.

#blocks, #gutenberg, #widgets

Widget Improvements in WordPress 4.9

On the heels of adding TinyMCE rich editing to the Text widget and the media widgets in 4.8, there are another round of improvements coming to the Text widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. and Video widget in 4.9, among other improvements to widgets.

Shortcodes in Text Widget

One very longstanding request—for over 8 years—has been to support shortcodes in the Text widget (#10457). This is finally implemented in WordPress 4.9. It is no longer required to have plugins and themes do add_filter( 'widget_text', 'do_shortcode' ). CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. now will do_shortcode() at the widget_text_content filterFilter Filters 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. (added in 4.8) in the same way it is applied in the_content at priority 11, after wpautop() and shortcode_unautop(). If a 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 has added do_shortcode() to widget_text then this filter will be suspended while the widget runs to prevent shortcodes from being applied twice. If a Text widget is in legacy mode then it will manually do_shortcode() as well.

One reason for the long delay with adding shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. support in Text widgets was due to many shortcodes looking for a global $post when they run. Since the global $post varies depending on whatever the main query is, the shortcodes in a Text widget could render wildly different on different templates of a site. The solution worked out was to temporarily nullify the global $post before doing the shortcodes so that they will consistently have the same global state, with this global $post then restored after the shortcodes are done. So if you have shortcodes that depend on a global $post—or call get_post()—then you should make sure that they short-circuit when $post is null in order for them to behave properly if used in the Text widget.

As of [42185] this nullification of $post is only done for archive (non-singular) queries; for singular queries, the $post will instead be set to be the current main queried post via get_queried_object(). This ensures that the global $post is consistent and explicit. This setting of the $post global while applying filters (and shortcodes) is also now implemented for the Custom HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. widget. Additionally, to ensure that gallery shortcodes that lack ids do not end up listing out every attachment in the media library, a shortcode_atts_gallery filter has been added which makes sure the shortcode’s id attribute is set to -1 when the widget is rendered on archive templates. This allows you to embed the gallery for any currently queried post in the sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme.. You should make sure such a Text widget is not displayed on an archive template by either adding it exclusively to a sidebar that appears on singular templates, or by using a feature like Jetpack’s Widget Visibility to hide the widget on non-singular templates.

Media in Text Widget

One reason why shortcode support in the Text widget was needed in this release is because 4.9 also allows media to be embedded in the Text widget (#40854). There is now the same “Add Media” button in the rich Text widget as on the post editor, allowing you to add images, galleries, videos, audio, and other media. To support these, core also needed to support shortcodes like captionaudiovideo, and gallery. Note there are also dedicated widgets (Image, Audio, Video, and Gallery) for these media types as well.

Having separate media-specific widgets helps with discovery and allows us to provide streamlined interfaces for each media type. For example, the Image widget now has a field specifically for supplying the link URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org (see #41274), and the Video widget now provides more guidance to users when supplying external URLs (#42039). The media-specific widgets are closely aligned with blocks in GutenbergGutenberg The 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/; the existence of media inside the Text widget will align with eventual nested blocks in Gutenberg, and would be treated as Classic Text blocks in any future migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. from widgets to blocks.

Embeds in Text Widget and Video Widget

One shortcode not mentioned above is embed. This one was more difficult to support because oEmbeds have not been supported anywhere other than post content. This was because there were dependencies on having a post as context for the sake of caching, as the responses to oEmbed requests get stored in postmeta. However, as of #34115 if there is no post as context the oEmbeds will now get cached in an oembed_cache custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. instead. Since a Text widget will explicitly nullify the global $post while shortcodes are processed, this means oEmbeds will get cached in this custom post type. Similarly to how do_shortcode() now applies in the widget_text_content filter like it applies on the_content, so too now WP_Embed::autoembed() and WP_Embed::run_shortcode() both also now run on widget_text_content.

In WordPress 4.8 the Video widget was introduced with support for displaying an uploaded video file, a YouTube video, or a video from Vimeo. Each of these were displayed using MediaElement.js. Just as oEmbeds are now able to be displayed in the Text widget, so too now the Video widget has been expanded to support any oEmbed provider for video. See #42039.

Theme Styling Changes

As with the previously-introduced media widgets (#32417) and the new Gallery widget (#41914), some themes will need to be updated to ensure the proper styling is applied to media and embeds that appear in the widget area context, since previously they would only appear in post content. Please follow #42203 and #41969 for style changes that are made to the core bundled themes, as you may need to make similar changes to your themes.

Improved Theme Switching

A longstanding difficulty with widgets has been where they end up when switching from one theme to another. With #39693 this experience is improved in 4.9 by having logic that is able to better map widgets between the themes’ widget areas. As noted by @obenland in [41555], there are three levels of mapping:

  1. If both themes have only one sidebar, they gets mapped.
  2. If both themes have sidebars with the same slug (e.g. sidebar-1), they get mapped.
  3. Sidebars that (even partially) match slugs from a similar kind of sidebar will get mapped. For example, if one theme as a widget area called “Primary” and another theme has “Main” then the widgets will be mapped between these widget areas. Similarly, widgets would get mapped from “Bottom” to “Footer”.

The names for the widget areas used for the mapping groups were obtained by gathering statistics from all the themes on WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/.

Widget Saved State on Adminadmin (and super admin) Screen

With #23120 there is now an indication for whether or not changes to a given widget has been saved on the widgets admin screen. (Widgets in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. already had a saved state by virtue of being registered as regular settings.) When first opening a widget, the button will say “Saved” and appear disabled. Once a change is made to the widget (e.g. a change event triggered), then the button will become enabled and say “Save”. If you try leaving the admin screen at this point, an “Are you sure?” message will appear alerting that if you leave your changes will be lost. If you cancel, then the first widget with unsaved changes will be scrolled into view, expanded, and focused. Upon hitting “Save” the spinner will appear and then upon a successful save it will switch to “Saved” and become disabled. The “Close” link has been changed to “Done” and it only appears when the changes have been saved. Note that the HTML5 checkValidity method will now be called on the widget form prior to attempting to submit, and submitting will be blocked if it returns false. If you have JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.-based fields in the widget, make sure that you trigger change events whenever changes are written into any hidden inputs; this was already a requirement for widgets in the Customizer.

Related Tickets

  • #10457: Parse shortcodes in text widgets by default
  • #23120: There should be indication that widget settings have been saved
  • #34115: oEmbed not working on author page without posts
  • #38017: Add widget instance to remaining widget argument filters
  • #39693: Fix missing assignment of widgets on theme switch
  • #40442: Widgets: Rename “Custom Menu” widget to “Menu”
  • #40854: Allow media to be embedded in Text widget
  • #41274: Improve discoverability of link URL in Image widget.
  • #41610: Widgets: Change “close” to “done?”
  • #41914: Widgets: Add gallery widget
  • #41969: Ensure Gallery widget is styled properly across widget areas in bundled themes
  • #42039: Widgets: Enable oEmbed support for Video widget
  • #42203: Ensure media & embeds in Text widget are styled properly across widget areas in bundled themes

See full list of tickets in the Widgets component with the 4.9 milestone.

#4-9, #dev-notes, #feature-oembed, #media, #media-widgets, #widgets

Fixes to Text widget and introduction of Custom HTML widget in 4.8.1

The 4.8 release caused issues for many sites that had custom HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. in Text widgets, which until now had been common practice. So we’ve been working hard on fixes in the 4.8.1 release which aim to simultaneously serve the needs of novice users and advanced users alike: the rich Text widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. (introduced in 4.8), a legacy mode for the Text widget, and a Custom HTML widget.

For more background on the changes in 4.8, see Addition of TinyMCE to the Text Widget. To review, the Text widget in 4.8 includes TinyMCE—the same visual editor used for writing post content—and it looks like:

Text Widget Legacy Mode

The issues with the introduction of TinyMCE to the Text widget revolve around the ways that TinyMCE attempts to clean up HTML code by deleting empty elements (such as those for dashicons) and dropping attributes it may not recognize (such as HTML5 Microdata attributes). Also with the 4.8’s removal of the “automatically add paragraphs” checkbox, there were also issues related to paragraphs and line breaks being added incorrectly.

Note that the Text widget was already designed to preserve the old behavior of the widget until it was modified and thus upgraded, so there are many instances of Text widgets in the wild today that could very well begin to break upon being modified. For this reason the issues were not reported right away and instead started to trickle in steadily after the release.

There were various solutions that were considered, but the one that had the consensus among contributors was:

[Check if the Text widget] was previously saved from an older version of WordPress before TinyMCE was added to the Text widget. If it is such a pre-existing Text widget instance, then use heuristics to detect if TinyMCE would negatively impact the contents of the widget, including the auto-p checkbox being unchecked, whether there are empty tags, and whether there are spandivscript, or style tags. When the Text widget is in this legacy mode, it can have a notice that informs users of the new HTML Code widget and that it should be used going forward. Likewise, in the new mode when TinyMCE is present, when the Text (HTML) tab is selected, there can be a note (perhaps an adminadmin (and super admin) pointer) that encourages users to use the HTML Code widget instead. By implementing this, novice users with basic content in their widgets win, and advanced users with custom HTML content in their widgets will cease from being negatively impacted.

The Text widget in legacy mode looks the same as the Text widget before 4.8, but with the addition of a new notice:

The legacy mode will only be presented for widgets created prior to 4.8.0 that have instance data which match the logic in the WP_Widget_Text::is_legacy_instance() method. The legacy mode will not be presented to newly created Text widgets. Once a Text widget is opened and saved in legacy mode, it will permanently stay in legacy mode. There is a new instance property called “visual” which will be set to false when a widget is saved in legacy mode. When a new Text widget is created, it is opened in the default visual mode and the new instance will get saved with visual=true.

Text Widget Filters

There is a change in how the filter instance property was used in 4.8.0: in that release, when a Text widget was modified, the fact that it had been upgraded was stored by overloading the filter boolean property to also have the value of "content", indicating that the widget gets content filters applied like a post does. Since this string is a truthy value, I reasoned it would normally work the same in filters that check ! empty( $instance['filter'] ), but it would fail in cases where a 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 tried true === $instance['filter']. So 4.8.1 reverts the overloading of the filter property to again be a boolean, and this should improve compatibility for widget_text filters. Whenever a Text widget is modified with the default visual mode (with TinyMCE) it will get both visual=true and filter=true saved in its instance. When a Text widget is modified in the legacy mode, it will always get visual=false and its filter property will reflect the checked state of the auto-paragraph checkbox.

Another note on filters: special consideration was made for shortcodes in the Text widget given the frequency of plugins and themes adding shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. support (since the widget does not recognized them by default in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.). Plugins and themes have done add_filter( 'widget_text', 'do_shortcode' ) to add support. Since the widget_text filterFilter Filters 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. applies before the new widget_text_content filter (as of 4.8), it will apply before wpautop will have applied, resulting in the possibility of extra line breaks being added undesirably if the shortcode output has new line characters. So to help prevent that from happening, the Text widget will temporarily move the do_shortcode handler from widget_text to widget_text_content just in time while the filters are being applied. See the relevant logic.

Help Pointers

For users who are accustomed to pasting HTML into the Text widget, when an attempt is made to paste markup into the visual editor a pointer will be displayed informing them that they should paste it into the Text tab instead, or to alternatively use the new Custom HTML widget (see section below):

Likewise, when a user opens the Text tab, it will also open a pointer to inform them of the Custom HTML widget:

While pointers are normally displayed on upgrades, these pointers will be displayed even on new installs since they reflect changes to long-standing behavior for the Text widget that users have become accustomed to. Any tutorials that instruct users to use the Text widget for pasting in arbitrary HTML should be updated to instruct the users to select the Custom HTML widget instead.

Custom HTML Widget

For advanced users or for any use case where arbitrary HTML needs to be displayed in a widget (such as a signup form or a 3rd party JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. widget), there is now a dedicated “Custom HTML” widget that is specifically for this purpose. It looks very similar to the classic Text widget, except it has a monospace font and it lacks the auto-paragraph checkbox:

Since users are prompted (per the pointers above) to try using the Custom HTML widget instead of the Text widget for some use cases, it is important that the widget content be able to be freely copied between the Text widget and the Custom HTML widget. For this reason, the Custom HTML widget retains the application of the widget_text filters like the Text widget does. The type of widget for which the filter is applying can be determined by looking at the type of the WP_Widget instance being passed as the last filter argument. When the widget_text filter is applied, it will pass the second $instance parameter in the same format as the Text widget, with title, text (instead of content), and filter and visual properties that are always both set to false (as if the instance was in legacy non-visual mode). In addition to re-applying the widget_text filter, the Custom HTML widget has a dedicated widget_custom_html_content filter whereas the the Text widget has a dedicated widget_text_content filter.

In addition to filter compatibility, the Custom HTML widget also tries to retain theme styling compatibility by using the same widget_text CSSCSS Cascading Style Sheets. class name on the outer widget wrapper and textwidget on the inner wrapper around the content itself. For any themes that wish to style the Custom HTML widget alone, there are the widget_custom_html and custom-html-widget class names used on the outer and inner wrapper elements respectively. For themes that wish to style the Text widget alone and exclude the Custom HTML widget, the :not() pseudo selector can be used, for example .widget_text:not(.widget_custom_html) and .textwidget:not(.custom-html-widget) for the outer and inner wrappers, respectively.

The markup generated by a Custom HTML widget on the frontend will look like:

<section id="custom_html-6" class="widget_text widget widget_custom_html">
  <h2 class="widget-title">My Title</h2>
  <div class="textwidget custom-html-widget">My Content</div>
</section>

This same Custom HTML widget’s instance data will look like:

{
  "title": "My Title",
  "content": "My Content"
}

For more specifics on the Custom HTML widget, refer to the subclass: WP_Widget_Custom_HTML.

Here is a list of tickets related to the Text widget and Custom HTML widget which are closed in the 4.8.1 release:

  • #40907: Introduce widget dedicated for HTML code
  • #40951: New Text Widget – Switching Between Visual/Text Editor Strips Out Code
  • #40960: Set `’filter’ => ‘content’` on starter content “business info” widget
  • #40960: Widgets: The Text widget should respect the “Disable the visual editor when writing” setting
  • #40972: TinyMCE editor in Text widget does not have RTL contents
  • #40974: Updated text widget do not save text (when using paste)
  • #40986: Widgets: text widget and media widgets cannot be edited in accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) mode
  • #41021: Text widget does not show Title field or TinyMCE editor
  • #41158:  Increase tinymce panel z-index
  • #41361: Text widget can raise JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. error if customize-base is enqueued on widgets admin screen
  • #41386: Text Widget – Wording – Legacy Mode 4.8.1 betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.
  • #41392: Theme styles for Text widget do not apply to Custom HTML widget
  • #41394: Text widget: Rename legacy mode to visual mode and improve back-compat for widget_text filters

 

#4-8-1, #dev-notes, #tinymce, #widgets