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 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!

#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 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 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 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

Addition of TinyMCE to the Text Widget

Note: Update: A follow-up post has been published regarding Fixes to Text widget and introduction of Custom HTML widget in 4.8.1.

In its first couple years, WordPress lacked rich/visual text editing. Before TinyMCE was incorporated in WordPress 2.0, users had to edit post content as raw HTML with some support from the Quicktags buttons. When widgets were introduced in WordPress 2.2, the Text widget was included which allowed a user to add content to their sidebar. Nevertheless, unlike the post editor, the Text widget did not incorporate TinyMCE, nor did it include Quicktags. For twelve years, since TinyMCE was added to core in 2005, users have had to hack around with HTML in their Text widgets to do things as simple as make text bold or add links. This has been featured even as recently as the 4.7 release video. Well, as of WordPress 4.8, the Text widget is finally getting the same treatment as the post editor with the introduction of TinyMCE for visual text editing, while still supporting raw HTML editing via a Text tab but now with the additional help of Quicktags:

Text widget: visual tab Text widget: text (HTML) tab

A primary reason for the long delay in incorporating TinyMCE into the Text widget was the difficulty of cleanly instantiating another copy of the WordPress visual editor dynamically after the page has loaded. Since WordPress 3.3 there has been the wp_editor() PHP function for instantiating an editor for the initial page load, but there was no facility for instantiating editors afterward, such as when adding a new Text widget to a sidebar. So in #35760 a new JS API was introduced for dynamically instantiating WP editors on the page: wp.editor.initialize(). This JS API is used for the new TinyMCE-powered Text widget; for more, please see Editor API changes in 4.8.

Note that by default the Text widget only features buttons for bold, italic, unordered list, ordered list, and link. If you want to add additional buttons to the toolbar, you may use a plugin to enqueue the following JS to add the blockquote button, for example:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	if ( editor.settings.toolbar1 && -1 === editor.settings.toolbar1.indexOf( 'blockquote' ) ) {
		editor.settings.toolbar1 += ',blockquote';
	}
});

Likewise, a custom button can be added via code like:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',mybutton';
	editor.addButton( 'mybutton', {
		text: 'My button',
		icon: false,
		onclick: function () {
			editor.insertContent( 'Text from my button' );
		}
	});
});

A reason for why there is no “Add Media” button for the editor in the Text widget is that WordPress 4.8 also includes dedicated media widgets for adding images, video, and audio to sidebars. Another reason is a current technical limitation whereby arbitrary media embeds (oEmbeds) fail to work properly outside the context of post content (see #34115). For this reason if you try to embed a video or something else by pasting in a URL it will not currently expand into the embedded content. The same is true for shortcodes: they are not processed by default since many shortcodes presuppose a global $post as the context within which they expect to be running. Plugins may opt-in selectively to support individual shortcodes by filtering widget_text as they have had to do for many years now.

While not supporting shortcodes, the updated Text widget does have some of the same filters applying to it as the_content, in particular:

  • wpautop
  • wptexturize
  • capital_P_dangit
  • convert_smilies

The Text widget has supported a “filter” instance property which was reflected in the UI via a checkbox for whether or not to automatically add paragraphs and line break tags (wpautop). For the updated Text widget, this checkbox is removed entirely in favor of aligning its behavior with the post editor where this behavior is always enabled. These filters only apply on Text widgets that have been updated/touched after the 4.8 upgrade. When a Text widget is modified in 4.8, the filter instance prop gets set to a static string “content both the filter instance property and a new visual property will be set to true and then it will apply a new widget_text_content filter which then apply the above functions to the widget text. For Text widgets created prior to 4.8, they will be opened in a legacy mode with the old behavior when it is determined that TinyMCE could mutate the content undesirably; such legacy instances will be saved with visual=false instance property. Read more about Fixes to Text widget and introduction of Custom HTML widget in 4.8.1.

Important: When pasting HTML into the “Text” (HTML) tab of the Text widget, any extraneous line breaks should be removed or else unwanted paragraphs and line beaks may result. This is particularly important when you paste in script or style tags (as in the case of 3rd-party JavaScript embeds), since auto-inserted paragraphs will cause script errors; this will be fixed in #2833. This behavior aligns with longstanding behavior in the post editor, so it is not new, although it does differ from how the Text widget has previously behaved. As noted above, for previously-existing Text widgets that had the “auto-add paragraphs” checkbox unchecked (and thus the filter instance prop set to false), the previous behavior of not doing wpautop will be maintained: only once the widgets are modified will any extraneous line breaks need to be removed. Any such Text widgets created prior to 4.8 will be go into a legacy mode as of 4.8.1 to prevent any data loss. Going forward, arbitrary HTML should be placed into the new Custom HTML widget instead.

The incorporation of TinyMCE into the Text widget has necessitated constructing the widget’s form fields differently than how they are normally done. Widgets in core have historically utilized static HTML for their control form fields. Every time a user hits “Save” the form fields get sent in an Ajax request which passes them to the WP_Widget::update() method and then the Ajax response sends back the output of WP_Widget::form() which then replaces the entire form. (Note widgets in the Customizer behave differently since there is no Save button in the widget, as updates are synced and previewed as changes are made; read more about Live Widget Previews.) This worked for static HTML forms in the past, but TinyMCE is a JavaScript component. To avoid having to rebuild TinyMCE every time the user hits Save on the admin screen, the Text widget puts the title field and TinyMCE text field outside of the container that is “managed” by the server which gets replaced with each save. (A similar approach has also been employed by the new media widgets in 4.8.) The fields in the Text widget’s UI sync with hidden inputs which get synchronized with the server; in the Customizer, changes to the TinyMCE field will be previewed after 1 second with denouncing. The container for the Text widget’s fields is .text-widget-fields and the traditional container for a widget’s input fields as rendered by WP_Widget::form() is .widget-content:

Themes should already account for the most common HTML elements within the text widgets and provide appropriate styles for them—the addition of the editor toolbar increases the likelihood its elements will be used in the future. Most default themes needed additional styles for ordered and unordered lists within widgets, so theme authors are encouraged to double-check their themes and test them with content in the text widget that includes markup provided by the editor toolbar.

Initial groundwork for shimming JavaScript into widgets was added in 3.9 via the widget-added and widget-updated events. A more recent proposal for making JavaScript more of a first class citizen in widgets can be found in #33507 and the media widgets incorporate some of its patterns that were also prototyped in the JS Widgets plugin. The synchronization of a widget’s state (instance properties) via hidden text fields can be eliminated once a widget’s state can be fully represented in a JavaScript model.

The Text widget is implemented as a Backbone.js view which is available at wp.textWidgets.TextWidgetControl. Instances of this view are then stored in the wp.textWidgets.widgetControls object. The widget’s control JS will only instantiate for a given widget once it is first expanded, when the widget-added event fires. What’s more is that the widget will only first initialize once the container is fully expanded since TinyMCE is not able to initialize properly inside of a container that is animating. In order to capture when TinyMCE inside the Text widget is initialized, you should use a TinyMCE event like tinymce-editor-setup. Note also that due the Document Object Model, when a widget is moved to a new location in a sidebar and this the TinyMCE iframe is moved in the DOM, this dynamically-created iframe is reloaded and thus emptied out. For this reason, every time a Text widget is moved to a new location the TinyMCE editor in the widget will be removed and then re-initialized. Keep this in mind when extending.

Keep also in mind that the Text widget will likely undergo many more changes with the incorporation of the Gutenberg editor, and that widgets themselves will likely see many changes to align with Gutenberg’s editor blocks which are now being prototyped.

#4-8, #dev-notes, #editor, #widgets