WordPress 5.4 introduces apply_shortcodes() as an alias for do_shortcode()

WordPress 5.4 introduces a new function – apply_shortcodes(). It’s an alias for the current do_shortcode() function.

The semantics of do_* implies the function displays the result of the shortcode. But that’s not actually the case. In fact, do_shortcode() needs to be echoed to display its result.

Here is the current implementation:

echo do_shortcode( '[wporg]My Text[/wporg]' );
// Displays the result of the shortcode

Semantically, we should be able to do this:

do_shortcode( '[wporg]My Text[/wporg]' );
// but it doesn’t display anything…

As you may know, do_shortcode() is used in countless plugins and themes. So there is currently no option to deprecate it. But if the community can start building a consensus around the alias, apply_shortcodes(), then deprecation may eventually become a real option in the future.

There is a precedent for making this move. It’s the same process the core team followed with get_permalink() and get_the_permalink().

apply_shortcodes is meant to get better semantics: instead of performing an action and outputting to the current buffer, the idea is to apply filters to the input and return a result. The process is simpler, cleaner and more maintainable – not to mention easier to teach new developers.

apply_shortcodes() can be used the same way do_shortcode() is currently used:

echo apply_shortcodes( '[wporg]My Text[/wporg]' );
// Displays the result of the shortcode

Themes/Plugins authors and WordPress developers are invited to start using apply_shortcodes() instead of do_shortcode().

To be clear, there is no plan for deprecating the former function right now. But the sooner developers can all switch to the much more semantic apply_shortcodes(), the sooner the core team can plan to deprecate the old function. With WordPress 5.4, apply_shortcodes() is now the recommended way to display the result of a shortcode.


For reference, see the related Trac ticket: #37422

Copy review: @marybaum

#5-4, #dev-notes, #shortcodes

An updated Button component in WordPress 5.4

As the @wordpress/components package becomes the vehicle that implements more and more of the WordPress design system, and as that system matures, its components get more consistent and more coherent.

WordPress 5.4 adds a number of changes and enhancements to the Button component.

Button sizes

In keeping with the overall design direction of the project, the button default height is now 36px. So you no longer need to use the previous isLarge prop variation.

The Button still supports the isSmall variation.

import { Button } from '@wordpress/components';

const regularButton = <Button>My Button</Button>;
const smallButton = <Button isSmall>My Button</Button>;

To keep all the button variations consistent, their styles now declare specific heights.

If you’ve been relying on the previous buttons’ dynamic heights to make them adapt to their content, you’ll want to override the new fixed heights. Make sure you add the rule below:

height: auto;

Icon support

In previous versions, the components package offered a Button component for regular buttons and an IconButton for buttons with icons.

WordPress 5.4 merges those components. To show buttons with icons, pass an extra icon prop to the regular Button component. You can also mix text and icons.

import { Button } from '@wordpress/components';

const myIcon = (
  <svg xmlns="http://www.w3.org/2000/svg" viewport="0 0 20 20">
    <path r="M5 4l10 6-10 6V4z" />
  </svg>
);

const SimpleIconButton = <Button icon={ myIcon } label="Button label" />;

const IconAndTextButton = (
  <Button icon={ myIcon }>
    Button Text
  </Button>
);

Note: the IconButton is still available, but it’s officially deprecated.

Classname changes

In previous versions, icon buttons relied internally on the components-icon-button. With the merger of the Button and IconButton components, WordPress removes this class name and replaces it with .components-button.has-icon.

Recommendation: Don’t rely on any internal className a component might use. If you want to target a specific component, prefer adding your own className prop and use that instead.

Going further

Try out the Button component or the other wordpress/components. Check out the components Storybook.

#5-4, #block-editor, #components, #dev-notes

Dev Chat summary – February 12, 2020 (5.4 week 5)

@davidbaumwald facilitated the chat on this agenda.
@audrasjb and @marybaum took care of publishing the meeting notes.

Full meeting transcript on Slack

This devchat marked week 5 of the 5.4 release cycle.

Announcements

WordPress 5.4 Beta 1 was released on Tuesday 11 as expected 🎉

Highlighted posts

Upcoming releases – 5.4

As mentioned, WordPress 5.4 Beta 1 was released on February 11th, 2020.

Please help by testing the Beta and reporting any bugs on WordPress Trac (or Gutenberg GitHub repository).

The Docs squad has published the first two dev notes:

The idea is to publish dev notes as soon as possible during the beta cycle and then publish the Field Guide before Release Candidate.

@audrasjb offered a quick update on Automatic Updates for Plugins and Themes. Because there is still work needed, along with extensive testing, decision is to start by managing autoupdates in a feature plugin and then merge into Core for 5.5.

Work on this feature plugin will start in the coming weeks.

Components check-in

@valentinbora is the new Administration Component maintainer.

In 2014, Administration was proposed to be moved from a component to a focus so it wouldn’t end up as a dumping ground for tickets. That decision led to its removal from the Components page, but not anywhere else.

Recently, this component returned to the Components page as per this Meta ticket, and it turned out that Administration still has a lot of tickets. The long term idea is to triage all the tickets that are there and, as part of that process, move those tickets to other components with the administration focus.

@whyisjake is now a Security Component maintainer.

Open floor

@whyisjake told the group that he’s going to help Two-Factor Authentication, currently developed on GitHub, move toward becoming a feature plugin for WordPress Core.

A first step: a proposal on Make/Core. @desrosj and @clorith are also interested in the project, which has been a discussion topic in the core-passwords Slack channel and in this GitHub pull request.

@whyisjake shared that he attended the CMS Security Summit last week, and Two-Factor Authentication was a major takeaway from the event, as was bringing automatic updates into Core.

@xkon added that #49200 needs input, so the team asks for yours. If you have any interest at all in cryptographic signature for plugins and themes, please follow the discussion on the dedicated Slack channel, core-signatures, and consider helping out.

#5-4, #auto-update, #security, #two-factor

Dev Chat Agenda for February 12, 2020 (5.4 Week 5)

Here is the agenda for the weekly meeting happening later today: Wednesday, February 12, 2020, at 09:00 PM UTC.

Announcements

  • This week marks week 5 of the 5.4 release cycle 🙌

Highlighted Blog Posts

Upcoming Releases – 5.4

  • Beta 1 Released

Components Check-in

  • News from components
  • Components up for adoption (Filesystem API and Rewrite Rules)
  • Components that need help
  • Cross component collaboration

Open Floor


If you have anything to propose for the agenda or specific items related to those listed above, please leave a comment below.

This meeting is held in the #core channel. To join the meeting, you’ll need an account on the Making WordPress Slack.

#5-4, #agenda, #core, #devchat

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 Core Widget used the <tfoot> element to display the calendar’s navigation links. But since the HTML 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 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 CSS adjustments.

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

Before this change:

After this change:


For full details, see the related ticket on Trac: #39763

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

Formal deprecation of some unused Customizer classes in WordPress 5.4

WordPress 4.9 deprecated the WP_Customize_New_Menu_Control and WP_Customize_New_Menu_Section PHP classes and wp.customize.Menus.NewMenuControl JavaScript class. The Core Team initially planned to remove them entirely in WordPress 5.0.

Deprecated items

Given how much time has elapsed since then, WordPress 5.4 leaves in place WP_Customize_New_Menu_Control and WP_Customize_New_Menu_Section to prevent potential backwards compatibility issues. 5.4 also formally deprecates them using _deprecated_file() and _deprecated_function() calls.

As a reminder:

_deprecated_file() is used to mark a file as deprecated and inform when it has been used. There is a deprecated_file_included hook that can be used to get the backtrace up to what file and function called the deprecated function. The behavior is to trigger an error if WP_DEBUG is true.

_deprecated_function() is used to mark a function as deprecated and inform when it has been used. There is a deprecated_function_run hook that can be used to get the backtrace up to what file and function called the deprecated function. The behavior is to trigger an error if WP_DEBUG is true.

Removed item

WordPress 5.4 removes the wp.customize.Menus.NewMenuControl JS class completely. This JS class can’t be used anymore starting with WP 5.4.


For reference, see the related Trac ticket: #42364

#5-4, #dev-notes

Dev Chat summary – February 5, 2020 (5.4 week 4)

The chat was facilitated by @davidbaumwald on this agenda.

Full meeting transcript on Slack

This devchat marked week 4 of the 5.4 release cycle.

Highlighted posts

Upcoming Releases – 5.4

We are currently in week 4 since WordPress 5.4 kick-off.

Further informations:

@audrasjb pointed out that it would be good to add more bug scrubs to help ticket triage and punting when necessary, to help contributors to focus on tickets that are realistically going to land in 5.4.

In addition to the scrub he scheduled for early Friday morning and Monday, @davidbaumwald will host another on Sunday.

Reminder: Beta 1 is the deadline for Feature Request and Enhancement type tickets. The full list of such tickets can be found with this Trac query.

Gutenberg Navigation Block

@noisysocks noted that including this block in the release could generate confusion for end users, as it will appear as a standalone block without any of the accompanying features (Full Site Editing and a new nav-menu.php page) that will make this block actually useful. He felts unsure if we want to remove this block from the 5.4 scope or not.

@jorgefilipecosta agreed with the concerns being raised by Robert. He said he was operating under the assumption that the navigation block needed to be part of 5.4. But from his side, he think we can change that assumption. He also think the navigation block by itself without Full Site Editing is not very useful for most users.

Note: the Navigation Block was officially removed from the release scope two days after the dev chat.

Plugins & Themes Automatic Updates

For reference, see the two related Trac tickets: #48850 and #49199.

@audrasjb updated the current work on the related tickets:

  • Technical aspects of the feature still need a lot of review from deeply experimented core committers
  • Design changes need to be validated by the design team

According to @audrasjb, there is a quite solid basis, but the Core team still needs to take some decisions about this feature, as we are approaching beta 1.

@desrosj made a deep review of the technical changes, and shared his concerns about the feature and also an alternative patch.

@mapk, @karmatosed and @audrasjb iterated on the user experience and their work is close to be finalized.

Email notifications are handled by @desrosj and will need copy review. @marybaum is available to help on that side.

The release Team will take the final decision about implementing automatic updates for Plugins & Themes in WordPress 5.4 before Beta 1 is released, and will publish a post on Make/Core to announce their progress on this specific topic.

#5-4, #auto-update, #gutenberg

Navigation block exclusion from WP 5.4

After plenty of great discussions about the Navigation block recently, the Gutenberg Team, including Dev Lead @jorgefilipecosta and me ( I’m the Design Lead), has decided not to include it in the WordPress 5.4 release.

We’ve been sharing this decision with the Release Squad for 5.4 and among many seasoned contributors to get a perspective on how everyone felt about this. The general consensus: people understand why the Gutenberg Team has made this call, and they support the decision.

Navigation block

Historical context

The Navigation block was a priority project for 2019. It was also planned for the WordPress 5.4 release. So we absolutely did not make this decision lightly. Ultimately, we recognize that although the block itself is ready to merge into Core, the Gutenberg Team believes this move is premature.

Why?

As I said, the Navigation block is usable right now. But we don’t think it’s useful yet – at least not until it has an intuitive place to live.

It’s hard to imagine cases where users would want to add a Navigation block to the post or page content. It’s much more likely that a given user would want to add a Navigation block to Header or Footer block areas – maybe even a Sidebar. However, that functionality in Gutenberg just isn’t ready.

Now, let me add this: if a user does want a set of links in a page, the new Buttons block in WordPress 5.4 can probably meet that need.

Buttons block

As I look back at the WordPress Project’s to-do list for 2019, the Navigation block didn’t exist in a vacuum. There was also the matter of Themes registering content areas which is still in progress as we speak. Both of those should co-exist and be released together. To include the Navigation block without a proper home isn’t really useful for users, and it doesn’t seem to justify a feature mention in the 5.4 release.

Going forward

Our next steps include adding a few more features to the block:

  • Creating a new page from within the block (19775).
  • Creating a Navigation block based on existing menu structures (18869).
  • Indicating “current” menu items visually (20076).

So that’s what’s happening with the Navigation Block and WordPress 5.4.

I want to ask you, personally, to join us in Core and in the Gutenberg Team discussions and give us your thoughts. Please review this block, to help further testing around it.

I’ll be picking up usability testing for this block again soon, and I’m looking forward to hearing from you how we can improve it.

And don’t forget to install the Gutenberg plugin to test the Navigation block in near-real-world conditions. With your feedback, we can make this block a great success.

#5-4, #gutenberg

Dev Chat Agenda for February 5, 2020 (5.4 Week 4)

Here is the agenda for the weekly meeting happening later today: Wednesday, February 5, 2020, at 09:00 PM UTC.

Announcements

  • This week marks week 4 of the 5.4 release cycle 🙌

Highlighted Blog Posts

Upcoming Releases – 5.4

  • Additional bug scrubs leading up to Beta 1
  • Nav Block and Auto-Updates Progress Report

Components Check-in

  • News from components
  • Components up for adoption (Filesystem API and Rewrite Rules)
  • Components that need help
  • Cross component collaboration

Open Floor


If you have anything to propose for the agenda or specific items related to those listed above, please leave a comment below.

This meeting is held in the #core channel. To join the meeting, you’ll need an account on the Making WordPress Slack.

#5-4, #agenda, #core, #devchat

REST API: Introduce dashboard namespace

Summary

We propose to introduce a dashboard REST API namespace prefix, for use on endpoints specifically relating to the WordPress admin dashboard.

Motivation

WordPress core currently contains two namespace prefixes: wp and oembed. These represent two separate APIs offered by WordPress: the general REST API which exposes structured WordPress data objects to external clients, and the OEmbed implementation.

The general design of WordPress distinguishes between the core, and the Dashboard “application” built on top of it. These two have not traditionally been formally separated, however the design and clean slate of the REST API allows us to consider these separately as we evolve the Dashboard.

With the push towards removing admin-ajax handlers in favour of new REST API endpoints, there are naturally API endpoints being introduced which are not useful outside of the administrative interface. Endpoints for Dashboard Widgets, pointers, and other features are specific to the Dashboard application, and are not broadly applicable to public-facing WordPress sites or third-party applications.

Introducing a new dashboard namespace prefix allows separating Dashboard-specific endpoints from the public WordPress REST API. This can also allow for future changes, deprecations, and new versions of the Dashboard API without requiring a version bump for the public REST API.

Detailed design

New endpoints for the Dashboard will live under dashboard/, initially with the namespace dashboard/v1 for the first version of endpoints.

Future iterations of the Dashboard that need to break API backwards compatibility can increment the version under the same namespace prefix as needed (e.g. dashboard/v2dashboard/v3). These new versions do not need to affect the public WordPress REST API.

This requires no code changes, as it simply designates the namespace for future use. The first endpoints to be added under this new namespace are expected to be the endpoints for Site Health (#48105) in WordPress 5.4.

How do we communicate this?

The new endpoints under the dashboard namespace prefix will collectively be called the Dashboard REST API to distinguish them from the public WordPress REST API.

There are no user-facing changes resulting from this proposal. Likewise, there is no effect on plugin, theme, or API client developers.

The difference between wp and dashboard needs to be communicated to core developers working on the Dashboard and related features. The announcement of this RFC on the Make/Core blog will serve as an initial announcement, but evergreen documentation should be added to the Core Handbook.

A new page will be added to the REST API Handbook under the “Best Practices” section, outlining design guidelines for new endpoints added to WordPress Core. The proposed text for this page is:

REST API

Core implementations of REST API endpoints should follow some simple rules to ensure WordPress provides a consistent public data interface.

Creating New Endpoints

Where possible, core features should use existing REST API endpoints rather than adding new ones. For example, a tag search feature should use the existing tag collection endpoint in the REST API rather than building one specifically for the feature.

When a new endpoint is required, care should be put into the design of the external API. In particular, the shape and schema of the resource, the namespace, the route (URL), and the available actions should match existing precedent in core.

REST API endpoints intended for public use and which represent “core” features of WordPress should be under the public REST API namespace (wp/v2). Endpoints which are only applicable for the Dashboard (e.g. Dashboard Widgets, pointers, or other UI settings) should be under the Dashboard REST API namespace (dashboard/v1). This ensures a clear distinction between APIs for general consumption and APIs built for specific UI features.

The design and implementation of the endpoint can be checked by the REST API team before committing to ensure it is consistent with the rest of the API. This helps us provide a more consistent experience for API consumers.

Drawbacks

Introducing a new core namespace could impact third-party plugins or other code which uses the same namespace string. This represents a minor backwards compatibility break, and investigation needs to be done as to whether we’re breaking any major plugins with this change.

It could also be argued that it fragments core’s API surface to introduce an entirely new namespace. Making the distinction of which namespace to use is tough, and this might lead to features that could have general applicability existing only as part of the Dashboard API, without a public API for use by external clients.

In addition, adding a new namespace opens the question of whether more even namespaces are needed. For example, should there be a Customizer namespace? Do other features need their own namespaces as well?

Alternatives

There are a few main alternatives to creating a dashboard namespace prefix.

The first is to use the current wp/v2 namespace for endpoints relating to administrative interfaces like Site Health. The main reason to avoid doing this is that it couples Dashboard-specific features to the public REST API. These features are rarely applicable or usable outside of the Dashboard application, especially in third-party plugin interfaces or external clients. In addition, this would also tie Dashboard API versioning to the public REST API, which could lead to the public REST API version being needlessly bumped for Dashboard-only changes.

Another alternative is to use a sub-namespace prefix of the existing wp prefix, such as wp/dashboard. This avoids any risk of impacting existing plugins as wp is already known to be reserved for core. However, this breaks the current precedent of <prefix>/v<version>, increasing the complexity of API namespacing. Given that it is unlikely that the dashboard prefix is currently being used, the simpler option of dashboard/v1 is preferred. This also discourages a proliferation of sub-namespaces under the wp prefix.

The final alternative is creating a separate namespace for each feature, such as site-health/v1. This could have the advantage of making endpoints more discoverable, and would reduce the overall length of each endpoint’s URIs. A dashboard prefix may also imply that its endpoints are “private” to WordPress and specific to the WordPress display context in cases where future endpoints may be useful in third-party tools. This approach has the disadvantage that plugin developers may worry that any namespace they pick could eventually be reappropriated by WordPress core.

Unresolved Questions

  • Should we use admin/v1 or dashboard/v1? To some dashboard is unclear and meaningless, to others admin is very specific to wp-admin whereas dashboard is more general idea of management.
  • Should we use dashboard/v1 or wp/dashboard/v1? The former could potentially clash with plugins, and is much more generic. We also need to pave the way for further namespaces that may be added to core in the future, where clashes may be more common.

Originally written by @rmccue as a WP-API Proposal.

#5-4, #rest-api, #site-health