Lee Willis

I recently posted about my GitHub embed plugin for WordPress. The plugin performs a neat trick of hooking into WordPress’ oEmbed infrastructure to allow you just to paste in a URL and retrieve an embed for a service that doesn’t natively support oEmbed.

This post is just a quick walk through explaining the approach. In general the plugin:

• Registers an oEmbed handler for the selected URLs (http://github.com/{something} in our example)
• Registers an internal oEmbed handler for that URL
• Handles the oEmbed call itself, retrieving the details it needs via the 3rd party’s API and then passing WordPress back an oEmbed response

Effectively you make your own site an oEmbed provider for the service you want to embed. Here’s the key bits of code:

First – we register an oEmbed handler, and point it to an internal URL:

function register_oembed_handler() {
    $oembed_url = home_url ();
    $key = get_key();
    $oembed_url = add_query_arg ( array ( 'github_oembed' => $key ), $oembed_url);
    wp_oembed_add_provider ( '#https?://github.com/.*#i', $oembed_url, true );
}
add_action ( 'init', 'register_oembed_handler' );

Note: get_key() just generates a site-specific key to stop other people using your oEmbed service.

Next, we tell WordPress to look out for an inbound oEmbed request:

function handle_oembed() {

    if ( ! isset ( $_GET['github_oembed'] ) ) {
        return;
    }
    // Check this request is valid
    if ( $_GET['github_oembed'] != $this->get_key() ) {
        header ( 'HTTP/1.0 403 Forbidden' );
	die ( 'Sad Octocat is sad.' );
    }

    // Check we have the required information
    $url = isset ( $_REQUEST['url'] ) ? $_REQUEST['url'] : null;
    $format = isset ( $_REQUEST['format'] ) ? $_REQUEST['format'] : null;

    // Call the 3rd party service, and create an oEmbed response here

}
add_action ( 'init', 'handle_oembed' );

All we need to do now, is retrieve the details we need using whatever API tools are available, then create an oEmbed response, e.g.

    $response = new stdClass();
    $response->type = 'rich';
    $response->width = '10';
    $response->height = '10';
    $response->version = '1.0';
    $response->title = $repo->description;
    $response->html = 'Your info here';
    
    header ( 'Content-Type: application/json' );
    echo json_encode ( $response );
    die();

And that’s it in theory, simple as pie. If you want to see working example, checkout out the github embed plugin on github:

WordPress offers an “oEmbed” service for a number of external services. If you’re not familiar with this, then it offers an easy way to embed external content into your posts and pages, without having to mess around finding embed code, pasting it in, and hoping the important bits don’t get stripped out.

Instead, WordPress’ oEmbed support allows you to simply paste in the URL to the page from your browser, and WordPress does all of the hard work contacting the provider and agreeing how they can embed it.

I wanted to use this to embed a summary of a GitHub repository, but unfortunately GitHub doesn’t support oEmbed – although they do have a fairly simple API that can be used to retrieve information about the repository.

I could have written a shortcode to interrogate the API, but I wondered if I could achieve an oembed style user experience instead. The result is the Github Embed plugin which is available from WordPress.org. The plugin allows you simply to paste in the URL to either a GitHub profile, or a repository, and have information embedded into your post automatically.

As you might expect, the plugin is also hosted on GitHub, and is embedded below …

It needs a bit of UI love, and pretty sure it can show some more useful information, but it’s usable now.