Creating handlers for Video Embed Field

Video Embed Field is a module that provides a simple interface for placing videos on your Drupal site. It works by simply providing a field of type ‘Video Embed’ which allows a user to paste in the link to a video from Youtube or Vimeo. The module then provides formatters to show the video and specify settings for it, for example: autoplay,width, height of player, skin color, or as a thumbnail.

My hope with the module is to make videos really simple to add to any Drupal site, without a lot of configuration or headache.

To allow support for other providers (that is, other than the 2 default providers: Youtube and Vimeo) the module also provides a hook for defining other ‘handlers’. A handler provides callbacks to get information about a video so video_embed_field can display that video. I built a Facebook handler in response to this issue (thanks mototribe) and placed it in a submodule called video_embed_facebook. I want to walk through it and describe how to build your own handlers for whatever service you desire.

The first step is to implement hook_video_embed_handler_info This hook simply returns an array of data about your handler so it can be used by video_embed_field. Lets take each part out and show how it works: The full hook for facebook looks like this:

The first things to note are that the array key for the handler – in this case facebook – needs to be unique, otherwise you could clobber another handler. Basically, if your handler is for facebook, its probably not a good idea to use ‘youtube’ as the key. The second thing to note is the ‘domains’ key in the info array.

This tells video_embed_field which handler to call. You can specify as many as you like here – for example, many providers have short urls like youtu.be, those should be included here. The goal is to make sure that whatever link the user copies from the provider and pastes here will work. Alright, lets take the rest apart callback by callback: 'function' => 'video_embed_facebook_handle_video', The function is the main callback, it is required and provides the embed code for a video, given the videos url and the settings for the current display. In the case of facebook it looks like this:

As you can see, I have the the basic embed code for a facebook video there with some placeholders for settings. I’m using format_string to take the placeholders and replace them with the appropriate values. I’ve taken the parsing of the url for the videos id and put it in a seperate function as we’ll use that a few times throughout the module. Once we have the placeholders, I’m just returning a very simple render array for use with drupal_render. If we couldn’t parse an id out of the url, then we’ll just fail nicely and show nothing. The next function worth talking about is the thumbnail callback which is defined here: 'thumbnail_function' => 'video_embed_facebook_handle_thumbnail', The implementation is fairly similar to the embed code callback.

We’re getting the id of the video from our same function, but this time we’re returning an associative array of data. The ‘id’ key is used as the filename for the thumbnail and must be unique inside that provider – using the video id is generally an easy way to accomplish this. The video’s thumbnails are stored locally so image styles can be applied to them. The ‘url’ key is the url to the thumbnail, for facebook we’re using their graph api to request the videos thumbnail. Facebook is a bit complicated, as their videos have specific permissions (e.g. ‘public’, ‘friends’, ‘friends of friends’), for this module we’re not adding any authentication so the only videos that we can show are public ones. Once you figure out how to get the thumbnail from the provider, this callback is fairly straightforward. We’re also providing a form for our settings, and a set of defaults for those same settings. The defaults look like:

and the form like:

In the form function, the $defaults parameter corresponds to either the defaults from the info hook, or whatever settings were saved for this style by the user. These should be used for the #default_value keys in your form. Note that the keys for each element in the form correspond to the values in the $defaults array. This should always be the case, each element should have a default with the same name. This is a pretty straight forward implementation of Forms API but have a look at the reference if you get stuck here. The final thing worth talking about is the ‘data_function’ which would look something like this:

This function allows handlers to provide extra data from an api to the theme functions (specifically the template) for the video_embed. This function is optional, any data that is provided will show up in the $data key inside the template. I didn’t implement it in this module as the facebook graph api, which provides this data, requires OAUTH for most videos (even public ones) and that seemed like overkill in this case. If you get stuck at any part while adding your own handler, check out the video_embed_field.api.php file included in the module. If you’re still stuck please feel free to post a question in the issue queue. As a final note – the function to parse the id from the url looks like this (in case you were curious) – I’m just using preg_match and a regular expression to find the part I care about: