Adding oEmbed Handlers to WordPress

In the past week, I’ve added a couple of oEmbed handlers to my WordPress theme to enable easy embedding of external media, specifically SpeakerDeck (example) and Meetup.com (example). It’s really easy, and I figured I’d share the knowledge for those who want it.

oEmbed wha?

oEmbed is a standardized format to allow for easy embedding of external content in a website. A service that supports oEmbed functionality will have an “endpoint URL” that all requests point to. Usually, you just pass the URL of the item you want to embed to that endpoint, and it returns the HTML required to embed it. This is what allows you to embed YouTube videos in WordPress by putting the URL on its own line in the editor.

Here’s how!

We need to hook into an action in WordPress to make sure we’re adding the oEmbed handler at the right time, and then use a built-in WordPress function to register a new URL pattern to look for. In this case, the init hook will do the trick.

In your theme’s functions.php file, add the following code (replacing ag with your own function prefix if desired):

add_action( 'init', 'ag_add_oembed_handlers' );
function ag_add_oembed_handlers() {
	wp_oembed_add_provider( '#https?://(www\.)?speakerdeck.com/.*#i', 'https://speakerdeck.com/oembed.json', true );
}

Now if you put a SpeakerDeck URL on its own line in the WordPress editor, you’ll have an embedded SpeakerDeck presentation!

Explaining the code

The wp_oembed_add_provider function accepts three parameters:

  1. Pattern to look for in post content
  2. oEmbed endpoint for service
  3. Whether the first parameter is a regex pattern instead of a simple wildcard string (defaults to false)

First parameter: pattern to look for

The first parameter can be either a wildcard string (using an asterisk * for the wildcard) or it can be a full-blown regex pattern. I prefer regex, because I’m nerdy and that’s what I’m supposed to prefer. Let’s look at the regex pattern I used:

#https?://(www\.)?speakerdeck.com/.*#i

We’ll work from the outside in. # is marking the beginning and end of the pattern. The i at the very end is telling it to use a case insensitive search.

A ? means that the item immediately preceding it is optional. It’s used twice here: for the “s” in “https” and the “www.” before the domain. Since the “s” and “www.” are optional, all of the following URLs would match this pattern:

 https://speakerdeck.com/aliso/advanced-actions-and-filters
 http://speakerdeck.com/aliso/advanced-actions-and-filters
 https://www.speakerdeck.com/aliso/advanced-actions-and-filters
 http://www.speakerdeck.com/aliso/advanced-actions-and-filters

At the end of the pattern is .*. The period will match any character except for a line break character (\r or \n). The asterisk is similar to the question mark in that it applies to the item immediately preceding it. It means “0 or more of the previous item.” This accounts for the rest of the URL after speakerdeck.com/.

Second parameter: oEmbed endpoint

If a service supports oEmbed, you can usually find the oEmbed endpoint in the developer or API documentation for that service. When in doubt, use Google: “_______ oembed endpoint” usually gets you the information you need.

Third parameter: is it regex?

When this is set to true, the function treats the first parameter as a regex pattern. The other option is to use a simple wildcard string, which would look something like this:

https://speakerdeck.com/*

It’s not as powerful or flexible as regex, but it still gets the job done.

What about Meetup.com? You added that too, right?

The code for adding oEmbed support for Meetup.com looks very similar to the code for SpeakerDeck. I can use the same function and just add another line to it.

add_action( 'init', 'ag_add_oembed_handlers' );
function ag_add_oembed_handlers() {
	wp_oembed_add_provider( '#https?://(www\.)?speakerdeck.com/.*#i', 'https://speakerdeck.com/oembed.json', true );
	wp_oembed_add_provider( '#https?://(www\.)?meetup.com/.*#i', 'http://api.meetup.com/oembed', true );
}

That’s it! Once I added that to my theme, I could embed SpeakerDeck presentations and Meetup events. Now go add oEmbed handlers to your own site! Have fun!