Embeds Changes in WordPress 4.5

After the introduction of the embeds feature in WordPress 4.4 there have been a few significant changes in 4.5 to make embeds more robust and easier to customize. 🎉

Embed Code Adjustments

Tickets: #35804, #35894

There were two minor changes to the <iframe> embed code:

  1. The iframe’s title attribute has been adjusted to better describe its content for improved accessibility.
  2. The iframe is now hidden using a different technique to prevent images from not being displayed properly in Firefox, working around a known bug in that browser.

Discovery Improvements

Ticket: #35979

Since WordPress 4.4, oEmbed discovery has been turned on by default. Using auto discovery, WordPress tries to find embeddable content when a URL is pasted on a new line in the editor. [36880] prevents timeouts from happening when requesting the URL by limiting the response size to 150KB.

Embedding Static Front Pages

Ticket: #34971

Previously, embedding a static front page was not possible due to not having an /embed/ endpoint. Now embed is a reserved slug that can’t be used for new pages/posts. When https://example.com/foo/embed/ is an existing page, embeds fall back to https://example.com/foo/?embed=true.

Embed Template Changes

Displays select embed template and template part locations, as well as various areas of an example embed view. Covers embed.php, the_embed_site_title(), embed-content.php, the_excerpt_embed(), and print_embed_sharing_options().

Tickets: #35322, #35630, #34561

  • The site icon in the embed template used to fall back to an image located inside /wp-admin/. This was problematic when the directory is not accessible to the public. That image is now loaded from inside /wp-includes/.
  • Thanks to an adjusted click event handler, links inside the iframe now work even when they’re inserted dynamically after the page load.
  • By far the biggest changes affect the way the embed template is loaded 💪🏽. Most notably, the old wp-includes/embed-template.php file has been deprecated and split into five new template parts that can be individually overridden by themes:
    • embed.php
    • embed-404.php
    • embed-content.php
    • header-embed.php
    • footer-embed.php

The five new template parts live in /wp-includes/theme-compat/ and allow core to gracefully fall back should themes prefer not to override any or all of them.

Previously, the embed template could only be changed using the embed_template filter. This filter can now be leveraged directly within the template hierarchy via the already-existing {$type}_template filter (where $type equals “embed”).

See get_query_template() and locate_template() for more information.

See [36693] for the relevant changeset.

Embeds in the Template Hierarchy

Ticket: #34278

In addition to the new base embed.php template and related template parts, themes can now implement embed templates for specific post types and post formats within the confines of the template hierarchy. The embeds template cascade looks like this:

  • embed-{post-type}-{post_format}.php
  • embed-{post-type}.php
  • embed.php
  • wp-includes/theme-compat/embed.php

Note that this is the first time direct theme-compat inheritance has been integrated with the template hierarchy. This approach allows core to provide basic, yet standardized templates and template parts for handling post embeds.

To leverage the core embed template parts, simply use standard get_template_part() calls within your themes. The template hierarchy will do the rest.

For example:

  • If the theme is leveraging its own version of embed.php template, it would likely call template parts directly, e.g. get_template_part( 'embed', 'content' );
  • If the theme is relying on the core embed template parts – i.e. not providing its own embed-content.php file – the template hierarchy would fall back to using wp-includes/theme-compat/embed-content.php, and so on.

See [36876] for the relevant changeset.

For more information on extending embeds within the scope of the template hierarchy, check out the new Embeds section in the Template Hierarchy reference in the Theme Developer handbook.

#4-5, #dev-notes, #embeds

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

oEmbed Update: September 28th

As of today, the current version of the oEmbed feature plugin is 0.9.0. These are the biggest changes since last week:

  • There is now an is_embed conditional tag to more easily target embedded posts.
  • New: Support for embedding video and audio attachments.
  • You can now copy the whole embed code and not only the post’s URL in the sharing dialog.
  • There were major JavaScript improvements. It is more robust and also a bit faster too.
  • We now show a read more link instead of the word count in the excerpt.
  • Improved input sanitization.

These were all areas discussed in last week’s chat and I’m happy with what we achieved. The plugin has been installed on WordPress.com, although it has been temporarily deactivated 🙁. Nonetheless I’m looking forward to publishing another post regarding the plugin tomorrow…

There are only some smaller issues left, so now is a great time to test and review the plugin! Our weekly chat is today (September 28 2015 9pm UTC) in the #feature-oembed Slack channel

Note: We received some feedback regarding weird link previews in Slack for WordPress.org links. This is a Slack bug and not our fault. We already reached out to them and hope it gets fixed soon.

As always, the latest version of the plugin is available on the plugin repository. Errors and suggestions can be either reported on GitHub or our #feature-oembed Slack channel.

Next chat: October 5 2015 9pm UTC

#embeds, #feature-plugins, #feature-oembed, #update

oEmbed Update: September 22nd

Today I just tagged version 0.8.0 of the oEmbed feature plugin. Despite the small version number the plugin saw some major improvements compared to last week. The changelog:

  • Added translations for Spanish, French, Italian, Finnish, Hebrew. There are now 13 translations in total!
  • Majorly improved embed handling: There’s now a 404 view for non-existent posts and we redirect to the right URL when post slugs change. The latter needs to be fixed in core though, see #33920.
  • Improved REST API support thanks to a review from the team
  • Better support for multisite and WordPress installs in a subdirectory
  • Now the plugin properly supports emojis too! 😀

This was only possible because of great feedback from plenty of users. The plugin is running smoothly on lots of sites now, including WordPress.org itself! It will also ship to WordPress.com this week if everything goes as planned.

We’re very happy with the plugin’s current form. Our priority tasks are now reviewing inline documentation and making sure the plugin is as secure as possible. If these are areas you’d like to work on, your help would be highly appreciated!

As always,the latest version of the plugin is available on the plugin repository. Errors and suggestions can be either reported on GitHub or our #feature-oembed Slack channel.

Next chat: September 28 2015 9pm UTC

#embeds, #feature-plugins, #feature-oembed, #update

oEmbed Update: September 16th

We’re constantly refining the oEmbed feature plugin and have been receiving some very good feedback over past seven days.

The following things changed in the plugin compared to last week:

  • There are now 8 translations: Danish (Denmark), German (Germany), German (Switzerland), Japanese, Greek, English (Australia), Arabic and Arabic (Morocco).
  • Full Right-to-Left language support.
  • Various performance improvements.
  • Dashicons are now included as inline SVGs in the CSS for better IE compatibility.
  • Added new filters to the embed template, allowing for better customization

Besides that I wrote a post on make/flow about the oEmbed plugin and also pinged several teams asking for feedback. Following best practices is very important to us.

In our weekly chat on Monday we discussed several things:

  • The plugin is active on the Make blogs, but some server settings need to be changed for it to work properly.
  • We learned that the plugin runs great on several sites, even with +100k daily users!
  • To make sure the plugin works under any conditions, go give it a try and report any bugs to us.
  • There was even some “homework” for next week:

    To help test the plugin, take a couple of minutes to sit down with someone and watch them use the plugin. Take some notes, then post details and findings in a GitHub issue.

We opened a couple of issues according to the feature plugin checklist to help us get ready for the core merge window.

As always,the latest version of the plugin is available on the plugin repository. Errors and suggestions can be either reported on GitHub or our #feature-oembed Slack channel.

Next chat: September 21 2015 9pm UTC

#embeds, #feature-plugins, #feature-oembed, #update

oEmbed Update: September 9th

Another week, another status update for the oEmbed feature plugin!

The following things changed in the plugin compared to last week:

  • Further accessibility improvements (props @afercia, @joedolson) by removing headings from the iframe content.
  • Better embeds for image attachments
  • thumbnail_url, thumbnail_width and thumbnail_height are now sent in the oEmbed endpoint response if available.
  • Major refactoring to make an possible core merge easier (props @pfefferle)
  • Many bug fixes thanks to improved test coverage. About 90% of the codebase is covered now!

On Monday there was also our weekly chat. The following things were discussed:

  • @pento will be working on implementing the plugin WordPress.com, giving us a larger userbase with hopefully great feedback.
  • In general, we need more testers. So if you have a website, no matter if large or small, go give it a try!
  • The core merge window is getting closer. We opened a couple of issues according to the feature plugin checklist to help us get there.
  • We’ll reach out to various core teams to get feedback on different aspects of the plugin, like inline docs, accessibility, user flow, etc.

As always,the latest version of the plugin is available on the plugin repository. Errors and suggestions can be either reported on GitHub or our #feature-oembed Slack channel.

Next chat: September 14 2015 9pm UTC

#embeds, #feature-plugins, #feature-oembed, #update

oEmbed Feature Plugin Update

After kicking off the oEmbed feature plugin a couple of weeks ago, it’s high time for another status update.

In case you have missed it, the oEmbed API plugin makes WordPress an oEmbed provider, allowing you to embed blog posts just like YouTube videos or tweets. Of course everything happens with security and ease-of-use in mind.

oEmbed Feature Plugin

Embedding a post is super simple!

We made some great progress over the last few weeks. The highlights are:

  • Improved test coverage, which led to many fixed bugs
  • Auto-resizing of the embedded iframe so it looks great on every screen
  • It seamlessly integrates with the REST API, but also works perfectly without it

The plugin is very stable so far. We’re looking into bringing it to WordPress.com for testing, but of course we also need your help to bring this further! Download the plugin from the repository — play with it, break it, and help us fixing all bugs that may appear. We’re always looking for areas to improve.

We’re now mainly working on getting it into shape for an eventual core merge proposal and implementing the different oEmbed response types. This means supporting embedding attachment posts and posts with different post formats.

Please, test and report both errors and suggestions either on GitHub or our #feature-oembed Slack channel. Anyone is welcome to join us!

Next chat: September 7 2015 9pm UTC

#embeds, #feature-plugins, #feature-oembed, #updates

oEmbed Chat Summary – July 20th, 2015

Yesterday we held our first weekly chat in #feature-oembed. Hooray! There were quite a few participants already, which is great.

Logs can be found here: https://wordpress.slack.com/archives/feature-oembed/p1437426031000036


  • There’s a proof-of-concept oEmbed implementation in the develop branch on GitHub (demo):
  • We agreed on keeping the embeds simple and minimally styled.
  • As expected, there was quite a discussion about the direction to pursue. There are basically two ways for doing this:
    1. WordPress has an oEmbed endpoint and returns HTML people can embed
    2. WordPress has no endpoint. We scrape the referenced websites to get data for a preview. Kinda like Facebook, Slack or Twitter show previews for links.
  • We decided on first finishing the HTML, as we need that anyway. After that we can focus on the next steps.

Development happens on GitHub, where we’ll be filing a couple of issues to work on until Monday. Anyone is welcome to contribute to the plugin.

Next chat: Monday, July 27, 2015 21:00 UTC

#chats, #embeds, #feature-plugins, #feature-oembed, #updates

Kicking off the oEmbed Feature Plugin

On Monday during the feature plugin chat we proposed a new plugin to explore making WordPress itself an oEmbed provider.

That means that instead of just embedding YouTube videos or tweets you would be able to paste the URL of a blog post and a short preview gets embedded right away.

There’s already a proof-of-concept plugin on GitHub, where development will happen. Luckily, @melchoyce made some mockups for embedded WordPress posts. Here’s an example with the Twenty Fifteen theme:



We will be holding weekly chats in the #feature-oembed Slack channel on Mondays, 21:00 UTC. If you want to get involved with this feature plugin, you should definitely join us.

Time/Date: July 20 2015 9pm UTC


  1. Why we’re doing this — @swissspidy
  2. Exploring the mockups — @melchoyce
  3. The current state of the plugin — @swissspidy
  4. Open Floor – If you have something you’d like to discuss, leave a note in the comments

Regarding point no. 4, there are many things that we need to keep in mind, for example:

  • Embedded content should be easily customisable
  • oEmbed requires lots of trust. Security is very important, while still maintaining ease of use.
  • There are also alternatives to oEmbed, see #32955

I suggest you to read the initial discussion on #32522 to see where we’re at.

#embeds, #feature-plugins, #feature-oembed, #kickoff, #updates

Two big patches for 2.9 just went in. […

Two big patches for 2.9 just went in.

[12025] by Andy Peatling allows themes to use register_theme_directory() to specify a wp-content-relative path containing theme directories. WP will additionally scan that. Primary use case is BuddyPress adding its themes without requiring copying.

[12023] by Viper007Bond enables smart embeds along with oEmbed support. For instance, to embed a YouTube or Vimeo video, just paste the URL in your browser on a blank line. It’ll grab the correct embed code for you. Much easier than wrangling with embed code vomit or remembering special shortcodes.

#2-9, #buddypress, #embeds, #themes