Using the Vimeo API in WordPress

This post describes a rather simple use case of the Vimeo API in the frame of a WordPress theme. This practical example is taken from the Kunstraum Kreuzlingen website, for which I implemented a WP theme in early 2012.

The objective

What do we actually want to achieve?

We want to embed a video gallery – a series of videos – without slowing down the page.

Imagine a page with about 5 or 10 little embedded videos. If each of them is an iframe containing a flash player, as would be the case with the usual embedding method, this will slow down the rendering of the page, even on a fast machine.

It would be much smarter to have simply a series of thumbnails – little jpg images – instead of the embedded flash players, and load the full video player only when there is user action. As soon as the user clicks on it, the video will load and autoplay – so from the user’s perspective, the behaviour is practically the same, but the page loads much more fluidly.

How do we implement this?

In the WordPress backend, the way we handle it is very simple: we use a dedicated custom field for a Vimeo link – let’s call it Vimeo-clip. This allows us to link a related Vimeo-hosted file to any post. It’s also possible to attach several videos with this method, just by using several times the same custom field.

On the public frontend, we show those videos in two different ways:
(1) on the individual posts.
(2) on a dedicated page where we list all the videos.

This second case is where the speed gain is most important, so that’s what we will examine here:

Step 1: add the vimeo API code to your functions file

We use the simple example provided by Vimeo and place it in our functions.php file

Step 2: build your loop in your WP theme

Here is where we need to start thinking. What do we have, and what do we want to build? In our case, the main loop of the page will be “query for each post that has the needed custom field“. A very basic example could look like this:

WP_Query( array ( 'meta_key' => 'Vimeo-clip', ) );

Then, for each result, we will run a nested loop that will execute the Vimeo API query. In our case, it will check for the vimeo key (the ID number of the video), request the corresponding thumbnail from video, and build the following HTML markup:

Let’s quickly analyze this piece by piece.

The first div is our container element. Nothing special here.
The a href item has several import elements:
- the https://vimeo.com/couchmode/40485391 link is there as a fallback, if the user doesn’t have javascript enabled, or if you run into jQuery conflicts and break javascript on your site. We only need the vimeo key to build this link.
- The data-vimeo="40485391" item – that’s our vimeo key, ready to be used by jQuery!
- The jstrigger-vimeo css class: that’s the trigger for our javascript.
The div.vimeo-play-icon is there for our CSS, it will hold the “play” icon, on top of the video thumbnail (not very semantic markup, maybe we could invent something even smarter…)
the img.vimeo-thumbnail – that’s where the Vimeo API comes into play, as it will provide us with the actual thumbnail of the video.
the final a href element is linking back to the main post. But we could very well imagine requesting the title from the vimeo API here.

Now that we know what we need, we can write a custom loop that will provide that result:

As you can see, to make it easier for the user, our function will clean the input of the custom field: you can paste the whole vimeo URL, or only the item key – both will work.

Step 3: create a javascript action

Now that we have generated the markup, we will write a javascript that will launch the player:

This script will replace the whole div with the standard vimeo embed code, and will immediately autoplay the video (with the autoplay=1 flag).

Step 4: CSS styling

The last step we need is to style our markup with CSS, notably for adding the “play” icon. Here is a simple example:

And that’s it!

If you want to improve, fork or flattr this piece of code, go ahead :)