How to remodel the WordPress oEmbed functionality ?

It is very easy to embed content in WordPress website. Why am I saying this! Well the reason is pretty simple. Embedding content is indeed very simple, all you have to do is drag a YouTube link/URL and drop it in the post editor, after this, all you have to do is just watch how it automatically embed with your content. “That’s the power of oEmbed functionality of WordPress”.

With the introduction of WP-API, WordPress is also an oEmbed provider. Just as you embed the YouTube video into your WordPress content in the above example, other users of different websites can embed your WordPress content on their respective websites.

This new avatar of WordPress as an oEmbed provider takes full advantage of the WP-API to give XML or JSON structured data (embedded) to consumers of oEmbed. This all is done by providing them the info they might need to embed the entire page by themselves. Just like WordPress, the oEMbed functionality can be remodeled easily with filters and codes. Just as a demonstration, let’s check how these hooks can be used in order to embed a simple custom post type.

/**
 * Add the author div to the embed iframe.
 */
public function embed_author(){
   if('sp_status_update'!== get_post_type()){
   return;
   }

   $output = '&amp;lt;div class="wp-embed-author"&amp;gt;';
   $output .= '&amp;amp;amp;amp;mdash; ';
   $output .= get_the_author();
   $output .= get_avatar( get_the_author_meta( 'ID' ), 20);
   $output .= &amp;lt;/div&amp;gt;';
  
 echo $output;

Learn How oEmbed Functions

How does the custom post editor will recognize how URL are embedded in the editor? Well, this includes certain steps, let’s discuss those steps in a nutshell.

First step in this process starts with the DISCOVERY. First, you have to make your oEmbed support revealable. For this purpose, you’ve to add elements in the head of its XHTML document (existing). Now, these elements will guide the oEmbed consumer to the endpoints of API (Application Programming Interface). After this, it will represent the post embedded in a structured format. JSON (JavaScript Object Notation) and XML (Extensible Markup Language) both formats are supported by oEmbed.

There are support and element for both the formats (XML and JSON). The [wp_oembed_add_discovery_links] function is submitted on wp_head is mainly responsible for proper <head> tags & are easily customized via “oembed_discovery_links” filter.

Now, the JSON response in the organized version in the endpoint of API will look similar to this,

{
  "version": "1.0",
  "provider_name": "Website Name",
  "provider_url": "http://example.com",
  "author_name": "admin",
  "author_url": "http://example.com/author/admin/",
  "title": "",
  "type": "rich",
  "width": 600,
  "height": 338,
  "html": "long string of html"
}

The response in XML is also structured in the exact same way. WordPress will provide support for the responses. It takes full advantage of WP-API in order to stipulate both the formatted responses of XML and JSON. However you need to take special care of the XML responses.

This response is used by the editor to filter the “HTML” key. Also, it is used in pushing it on the page. The HTML version of oEmbed consists of these elements,
A “blockquote” along with title post.
A <script> tag, this tag is responsible for the correct and safe handling of the “iframes” messages.
“Iframes” sandbox.
You can fetch this HTML with “[get_post_embed_html]”. If you want to filter it, use “embed_html”.

All this magic happens in the “iframe” URL. It imports “in-built embed template” by default. However, you can reverse it and use your preferred embed template, if you want. All you have to do is use the filter “embed_template” and retreat your own template file to exchange it.

add_filter( 'embed_template', 'my_embed_template' );
function my_embed_template( $template ) {
    if ( 'custom_post_type' === get_post_type() ) {
      return '/path/to/custom-embed-template.php';
    }

    return $template;
}

How to customize oEmbed Title ?

Let us consider, we’re embedding a plugin for status update, so, first thing in your to-do list must be removing title from the oEmbed output. In order to perform that we have to hook a “the_title” filter.

add_filter( 'the_title', array( $this, 'remove_embed_title' ), 10, 2 );

While working in “remove_embed_title”, you’ll meet “is_embed” your helper function. It gives back “true” when you’re in oEmbed context. You can use this function to modify an oEmbed output.

Here’s the method, to discard the title,

/**
 * Remove the title from the Status Update oembed.
 *
 * @param string $title Post title.
 * @param int    $id Post ID.
 *
 * @return string
 */
public function remove_embed_title( $title, $id ) {
    $post = get_post( $id );

    if ( is_embed() &amp;&amp; 'sp_status_update' === $post-&gt;post_type ) {
      return '';
    }

    return $title;
}

How to Customize oEmbed Excerpt ?

As we are using a status update plugin, which is itself just a small piece of writing. But if you want to excerpt, you can use a filter hook, i.e., “the_excerpt_embed”.

add_filter( 'the_excerpt_embed', array( $this, 'get_excerpt_embed' ) );

If the post is custom post, then we type these codes to return full content as output:

/**
 * Returns the custom excerpt for the custom post type.
 *
 * @param  string $output Default embed output.
 * @return string         Customize embed output.
 */
public function get_excerpt_embed( $output ) {
    if ( 'sp_status_update' === get_post_type() ) {
      return get_the_content();
    }

    return $output;
}

Now, this code piece will ensure that the excerpt will always be the full content post for this status update plugin. When we talk about ”iframes”, an excerpt is an output in “div” alongside with a class “wp-embed-excerpt ”. In this output, you can try custom styles. Still, if you want something complex, you can output your content in the same “div” or if you want you can attach your content with “embed_content” action.

How to add More Content in oEmbed ?

Just after the snippet as output, the “oembed_content” action provides the location of the footer and the excerpts in order to output custom HTML of your own. For this test plugin, you’ll have to display the author’s avatar and name.

But first we need to add this action,

add_action( 'embed_content', array( $this, 'embed_author' ) );

Now, you can utilize the given action hook,

/**
 * Add the author div to the embed iframe.
 */
public function embed_author() {
    if ( 'sp_status_update' !== get_post_type() ) {
      return;
    }

    $output = '&lt;div class="wp-embed-author"&gt;';
    $output .= '&amp;mdash; ';
    $output .= get_the_author();
    $output .= get_avatar( get_the_author_meta( 'ID' ), 20 );
    $output .= '&lt;/div&gt;';

    echo $output;
}

How to add Custom Scripts and Styles to oEmbed ?

An oEmbed template also consists of a header & footer, just as same as a normal page template. Now, you can add items to the queue in style of your preference, as the “embed_head” provide you the location.

First, attach your procedure in this hook.

add_action( 'embed_head', array( $this, 'embed_styles' ) );

Now, use the hook to add your style in the queue using “wo_enqueue_style”.

/**
* Embed the plugin's custom styles
*/
public function embed_styles() {
echo <<<CSS
<style>
.wp-embed-excerpt, .wp-embed-author {
font-size: 24px;
line-height: 24px;
margin-bottom: 5px;
}

.wp-embed-author {
float: right;
}
</style>
CSS;
}

Conclusion

So, these methods are for primary hooks which you’ll need to act with to convert the output.

How, do you feel about the remodeling in oEmbed functionality of the WordPress? Mention in the comments what you had done. Let’s start a discussion. If you face any trouble, just mention it in the comments.

Shop Categories

Guest