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