New Embeds Feature in WordPress 4.4

WordPress has been operating as an oEmbed consumer for quite some time now, allowing users to easily embed content from other sites. Starting with version 4.4, WordPress becomes an oEmbed provider as well, allowing any oEmbed consumer to embed posts from WordPress sites.

Here’s how that looks:

Feature Plugin Merge Proposal: oEmbed

In order to achieve this, WordPress’ oEmbed consumer code has been enhanced to work with any site that provides oEmbed data (as long as it matches some strict security rules). For security, embeds appear within a sandboxed iframe – the iframe content is a template that can be styled or replaced entirely by the theme on the provider site.

Related ticket: #32522

What That Means for Developers

First of all, this new feature means that any post (or basically any public post type) will now be embeddable. If you’re using pretty permalinks, the embeddable content will be available at example.com/your-post/embed/.

If you’re a developer, make sure you do not add an embed rewrite endpoint yourself!

Functions and Hooks

Here are the four most useful functions related to embeds:

  • get_post_embed_url() — Retrieves the URL to embed a specific post in an iframe, e.g. https://make.wordpress.org/core/2015/10/28/new-embeds-feature-in-wordpress-4-4/embed/
  • get_post_embed_html() — Retrieves the full embed code for a specific post.
  • get_oembed_endpoint_url() — Retrieves the oEmbed endpoint URL for a given permalink, e.g. https://make.wordpress.org/core/?oembed=true&url=<url>. This is used to add the oEmbed discovery links to the HTML <head> for single posts.
  • get_oembed_response_data() — Retrieves the oEmbed response data for a given post, according to the oEmbed specification.

Of course the return values of these functions are all filterable, making it easy for you to customize this new feature.

Customizing The Output

The embed template mentioned earlier can be customized similarly to any theme template file. Use embed_head and embed_footer to add custom code in the beginning and the end of the template.

Note that an X-WP-embed:true header will be sent when that template is used, so you can easily target embedded posts in your application.

Further Improvements

We’re currently tweaking the embeds functionality to sort out the last few bugs. Here’s a short list of tickets that are being worked on and their purposes:

  • #34204 — Improved support for IE7+. This will also introduce a enqueue_embed_scripts hook that can be used to enqueue JavaScript and CSS.
  • #34451 — Improved support for embedding posts on non-WordPress sites
  • #34278 — Add support for embeds in the theme template hierarchy, allowing you to override the template easily in your theme.
  • #34207 — Leverage the REST API structure for the oEmbed endpoint.
  • #34462 — Add a <blockquote> fallback for the iframe.

Disabling The Feature

Don’t like these enhanced embeds in WordPress 4.4? You can easily disable the feature using the Disable Embeds plugin if you really want to.

#4-4, #dev-notes, #embeds, #feature-oembed

REST API: Welcome the Infrastructure to Core

Hi from the REST API team! We’re extremely excited to announce the API infrastructure has now been merged into core as of r34928 (plus a couple of fix up commits we won’t mention). Huzzah!

Sincere thanks to every single one of the contributors, we wouldn’t be where we are today without you. It takes time and effort to produce great things, and it’s impossible to make things great without everyone helping. This has been a truly collaborative effort, and I wish I could do more than just give you props.

(Important note: if you have a 2.0 beta already installed, you must upgrade to beta 5.)

What’s included in 4.4?

As mentioned in the merge proposal, the API comes in two parts: infrastructure and endpoints. In 4.4, the infrastructure is now available as part of core, while the endpoints continue to only be available in the plugin.

You can think of the infrastructure as an “API construction kit”. WordPress 4.4 will make it possible for everyone to build RESTful APIs in a much easier fashion, which will benefit people building custom APIs for their site. The infrastructure handles the routing, argument handling, JSON serialisation/deserialisation, status codes, and all that other lovely REST stuff.

For client authors, this doesn’t help you much right now. Hold tight, the team is working as fast as we can on the endpoints to get them ready for a future release. In the meantime, you can make sure sites you want to work with have the plugin installed, which isn’t a change from the current state.

For plugin and theme authors, you can start building new APIs immediately using the infrastructure now in core. This can start replacing your existing custom admin-ajax endpoints or other bespoke code you already have.

To authenticate with the API, only built-in cookie authentication is available out of the box right now. The OAuth 1 plugin will continue to work with WP 4.4 and the API plugin, as will the Basic Auth plugin for local development.

It’s super easy to get started, and there’s even a guide available to kick-off. (Note: the WP_REST_Controller class is not included in WordPress 4.4.) This documentation will be migrated across to developer.wordpress.org soon.

If you want to access any of the built-in data in WordPress without building it out yourself, you’ll need the endpoints as well. These will continue to be packaged in plugin form, and version 2.0 final will be released to accompany 4.4 before the end of this cycle.

What if I’m using the API already?

If you’re on version 2 of the API, you’ll need to update the API to beta 5 or later before updating to the latest version of core. This new version will use the new infrastructure in core if available, or fallback to a compatibility library otherwise.

Important note: Earlier 2.0 betas (1 through 4) are incompatible with WP 4.4. Your site will fatal error if you don’t upgrade to beta 5 or later. You must upgrade to the latest API to run trunk and to run WP 4.4 when it’s released.

If you’re on version 1 of the API, you won’t hit any fatal errors straight away, but endpoints will stop working with 4.4. We’re still planning on releasing a final version 1 release for compatibility, but now would be a great time to consider migrating forward to version 2. Apart from security releases, version 1 has ceased being actively maintained.

Looking forward for the API

Now that the API is past this first hurdle, it’s important to keep looking forward. Our immediate next step is to improve and polish the endpoints for phase two of our merge. There’s a lot of work still to be done here, so we’d love you to join us on GitHub.

The infrastructure of the API will now be maintained via Trac, so new issues and patches should be sent there instead under the “REST API” component. Issues with endpoints should still be filed on GitHub. Don’t worry if you’re not sure; you can file issues on either Trac or GitHub, and they’ll be triaged into the correct place as needed. (It’s more important to make sure the issue is filed in the first place!)

The team wants to keep pressing forward with the API and keep up our rate of progress, if not improve it even further, and we’d love your help. We still need help from content writers on our documentation, designers and developers on our authentication plugins, and developers on the endpoints. If you want to help, we can always use a hand, and we’d love to help get you started. We’re available in the #core-restapi room on Slack, and we’d love to see you at the weekly meeting at Monday 23:00 UTC 2015.

We look forward to continuing to work on the API and getting these endpoints happening. Thanks again to everyone who got us here.

(Then again, maybe a REST API is more of a Shelbyville idea…)

#4-4, #dev-notes, #json-api, #rest-api

Comment Object and Query Features in 4.4

Without comments, a website is as effective at creating a community as the Chicago Cubs are at winning World Series titles. WordPress 4.4 is a rebuilding release and the comments system is much improved under the hood.

This release lays the groundwork for future features and improvements.

A New Classy and Strong Comment Object

The new WP_Comment class provides a single organized comment object that models its row in $wpdb->comments. You may be familiar with this approach from WP_Post, which inspired the caching implementation used in WP_Comment.

This was a prerequisite to many of the other comment-related bug fixes and features added in 4.4. The WP_Comment class is marked final to retain flexibility while it is young.

See #32619.

Comment Queries for the Whole Family

WP_Comment_Query has new query parameters for traversing your comments family tree.

  • parent__in takes an array of comment parent IDs to return all matching children.
  • parent__not_in takes an array of comment parent IDs and does not return any matching children.
  • hierarchical can be set to either threaded, flat, or false.
    • threaded returns a tree for matched comments, with the children for each comment included in its children property.
    • flat returns a flat array of matched comments plus their children.
    • false does not include descendants for matched comments. This is the default behavior.
  • orderby has a new option comment__in, useful when querying by comment__in the matched results will return in the same order.

See #8071 and #33882.

#4-4, #comments, #dev-notes

Under the hood of Twenty Sixteen

Twenty Sixteen is the new default theme for WordPress 4.4. This year the process has been done differently, with an exciting exploration of how default themes are created. The theme has been developed on GitHub and you can follow along here. The theme has also been synced every night with the WordPress.org theme repository. This has meant more people have been able to use them theme earlier than previous default themes.

As Beta 1 is now out, it’s a great time to explore a little more about what Twenty Sixteen contains and how the contributions have shaped this default theme so far.

Features of Twenty Sixteen

This theme is designed to be a fresh take on the traditional blogging format. It includes:

  • Multiple menu positions and a social menu.
  • Optional sidebar.
  • Custom color options and beautiful default color schemes.
  • Harmonious fluid grid using mobile-first approach.
  • Custom background and header.
  • Overflow displaying large images.
  • Ability to add intro to post using custom excerpt.

Contributions to Twenty Sixteen

During development, there have been some amazing contributions along the way. These include:

  • Lots of accessibility improvements. The Accessibility team have done amazing work reviewing and ensuring Twenty Sixteen is better than any other default theme for accessibility.
  • Improved js handling and tidying in files. Thanks to contributions, the theme js and that of other default themes has been reviewed and optimised.
  • Numerous design enhancements including sub menus.
  • Travis testing integrated with the repo.
  • Device and browser testing. Everyone really helped put this theme through it’s paces.
  • The addition of singular.php.
  • Responsive image support (on the way).
  • Prefixing cleaning up to focus on browsers using.
  • Sanitisation and escaping.
  • Adding of core comments navigation.
  • Hyphenated post titles for better language support.
  • Numerous bug fixes, code tidying and countless tiny improvements.

A big thank you to everyone that has helped make Twenty Sixteen the theme it is. It’s been incredible to see everyone so engaged and active over on GitHub.

With Twenty Sixteen on GitHub, if you have a bug you’d like to report you can do so using GitHub right here.

#4-4, #dev-notes

4.4 Taxonomy Roundup

We’ve made lots of improvements to the Taxonomy component for WordPress 4.4. Let’s round ’em up, pardner!🐴

Term Meta

The most significant improvement is the introduction of term meta #10142. Use the new term meta API – add_term_meta(), update_term_meta(), delete_term_meta(), and get_term_meta() – to store arbitrary data about taxonomy terms, in the same way you would for posts, users, or comments. The term query functions get_terms() and wp_get_object_terms() now support a ‘meta_query’ parameter, with syntax identical to the corresponding argument for WP_Query, etc.

Term meta was built with performance in mind. When fetching terms using get_terms() or wp_get_object_terms(), metadata for located terms is loaded into the cache with a single database query; disable this by passing 'update_term_meta_cache' => false in your query parameters. When querying for posts using WP_Query, we have another trick up our sleeves: term meta for terms belonging to matched posts is lazy-loaded, so that all relevant term meta is only fetched the first time you call get_term_meta() in the loop.

Developers who have previously implemented term meta in their own plugins or client sites should prepare their customizations for WordPress 4.4, to ensure that nothing’s broken in the transition.

WP_Term and unique term IDs

For the last few releases, we’ve been working hard on the taxonomy roadmap. A major achievement was the complete splitting of shared taxonomy terms in 4.3, which ensures that terms can be uniquely identified by their term_id. In 4.4, we begin taking advantage of this uniqueness: the $taxonomy parameter is now optional in get_term() and get_term_field(), functions that previously required both $term_id and $taxonomy.

Under the hood, we’ve introduced WP_Term, a new class that properly models a term object #14162. Everywhere where terms can be retrieved – one at a time, as in get_term() or get_term_by(), or in bulk, as in get_terms() and wp_get_object_terms()– you should expect WP_Term objects to be returned, rather than stdClass. For 4.4, this change doesn’t affect much, aside from making our term-caching internals somewhat more sane. But in the future, WP_Term will allow for more extensive caching throughout the Taxonomy component, as well as the potential for method chaining and other developer conveniences.

Other goodies

We’ve made lots of smaller improvements to Taxonomy as well. Some highlights:

  • Registering a taxonomy with 'public => false' now prevents the taxonomy from being queried publicly. (Imagine that!) #21949
  • The $taxonomy parameter for get_term_by() is optional (and ignored) when fetching by term_taxonomy_id. #30620
  • Argument arrays are now filtered in get_terms(), register_taxonomy(), and in the Categories post edit metabox. #33026 #33369
  • Accented characters in term names are no longer ignored when checking for duplicates, allowing for, eg, tags ‘foo’ and ‘fóó’ to coexist. #33864
  • Term relationships caches are properly busted during wp_remove_object_terms(). #34338

#4-4, #dev-notes, #taxonomy

Document title in 4.4

WordPress 4.1 introduced a way for themes to support a new way of rendering the document title, letting Core handle its generation and output. The next step followed just recently (#31078), deprecating wp_title() and replacing it with a more comprehensive way to generate titles.

UPDATE 12 November – wp_title has been reinstated until alternative usages have been identified and a path forward for them defined.

Plugin authors can now check for theme support and have a few new filters available that will allow them to change or replace the title in a reliable way:

  • 'pre_get_document_title' short-circuits wp_get_document_title() if it returns anything other than an empty value.
  • 'document_title_separator' filters the separator between title parts.
  • 'document_title_parts' filters the parts that make up the document title, passed in an associative array.

This latest change makes the new API (almost) feature complete and theme authors are discouraged from using wp_title() in the future. If it was decided to add a UI to let users choose the make up of their document title, or another improvement to how title generation works, we now have a forward compatible way to handle these things.

To upgrade themes from using wp_title() to declaring theme support for core’s title-tag without breaking backwards compatibility with WordPress 4.0 and older, theme authors can check if the callback function exists and add a shiv in case it does not:

if ( ! function_exists( '_wp_render_title_tag' ) ) :
	function theme_slug_render_title() {
?>
<title><?php wp_title( '-', true, 'right' ); ?></title>
<?php
	}
	add_action( 'wp_head', 'theme_slug_render_title' );
endif;

#4-4, #dev-notes, #wp_title

4.4 Dev Chat, October 14: Suggest items for today's agenda

Here are my agenda items for today’s Dev Chat in the #core channel on Slack.

Time/Date: Wednesday, October 14, 2015 16:00 UTC-4:

  • 1 week til Beta 1
  • Component Updates

Please suggest any other agenda items for today’s chat. The band’s taking requests.

#4-4, #agenda

Week in Core: Sept. 28 – Oct. 11, 2015

Welcome back to the latest issue of Week in Core, covering changes from Sept. 28 – Oct. 11, 2015, changesets [34659][35029]. Here are the highlights:

https://make.wordpress.org/core/2015/10/07/%F0%9F%8E%89-one-more-committer-for-4-4/

See that ↑ right there? That’s an oEmbed. And it’s loaded from inside this site.

Feature Plugins Merged

The Responsive Images, oEmbed Provider, and the “baby” REST API feature plugins have been merged into core. Grab the latest version of trunk and test them out.

WordPress logo with wordmark below

Responsive images in your posts. Just upload and insert!

Potent Notables

These changes were big enough to merit their own blog posts:

Deeper Reading

Some commits pack in a lot of info, from detailed background to best practices in using hooks. Here are a few worth reading the entire commit message:

  • WP_Term class introduced [34997] #14162
  • Fix scalability performance problem for previewing multidimensional settings in the Customizer. [35007] #32103
  • Ensure that wp.customize.Widgets.savedWidgetIds is defined up front. [34883] #33901
  • The history and implementation of oEmbeds. [34903] #32522
  • Improve role-related arguments in WP_User_Query. [34875] #22212
  • Use wp_installing() instead of WP_INSTALLING constant. [34828] #31130
  • Introduce *_network_option functions for Multisite installs. [34777] #28290
  • Ensure that comment permalinks reflect pagination. [34735] #34068, #34073

Continue reading

#4-4, #week-in-core

Tweaks to user searching and management

A few improvements have been made to user searching and user management in WordPress 4.3 and the upcoming 4.4. Here’s an overview:

  • 4.3: Performing a search on the Users screen now searches the user’s username, email address, display name, nicename, and URL, instead of just their username and nicename. See #27304
  • 4.4: Performing a search on the Network Admin -> Users screen previously required the use of a * wildcard character at the beginning and/or end of the search term, otherwise the search required an exact match. This is no longer the case, so finding users on Multisite is no longer frustrating and inexplicably dysfunctional. This, combined with the changes in 4.3, means searching for a phrase such as “@gmail.com” now works as you would expect. See #32913
  • 4.4: It’s now possible to filter the Users screen by users who have no role (in addition to being able to filter the screen by individual roles), if there are such users. See #22993
  • 4.4: Users with multiple roles (it’s possible to programatically give a user multiple roles, although this isn’t possible via the UI) are now shown as having multiple roles on the Users screen. This helps avoid obfuscation of a user’s roles. If your plugin facilitates the assignment of multiple roles to an individual user, you should test it against trunk and look at using the new get_role_list filter introduced in [34963] if necessary. See #22959

Any other improvements you think could be made? Leave a comment.

#4-3, #4-4

4.4 Dev Chat, October 7: Suggest items for today’s agenda

Here are my agenda items for today’s Dev Chat in the #core channel on Slack.

Time/Date: Wednesday, October 7, 2015 16:00 UTC-4:

  • Feature Plugin Merge Window CLOSES
  • Already Committed!
    • Responsive Images
    • oEmbed
  • Twenty Sixteen
  • Components
    • Customizer
    • Multisite
    • Shortcodes
    • Post By Email
  • Gardening
    • 7 weeks, 1186 commits Since 4.3
    • 207 in the past 7 days Timeline
    • We’ve closed 573 tickets on the milestone since 4.4 started
    • Always fun to look at Ticket Graph
    • Can we get below 3000 tickets (getting closer…)?
      • We have moved some .org tickets to Meta
      • We need to close 63 non-.org, non-4.4, non-4.3.2 tickets AND every new ticket that is submitted
  • 2 weeks til Beta

Please suggest any other agenda items for today’s chat. The band’s taking requests.

#4-4, #agenda