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.
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
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
divis our container element. Nothing special here.
a hrefitem has several import elements:
data-vimeo="40485391"item – that’s our vimeo key, ready to be used by jQuery!
div.vimeo-play-iconis 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…)
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 hrefelement 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.
This script will replace the whole
div with the standard vimeo embed code, and will immediately autoplay the video (with the
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!