WordPress Plugin – Creating your own Spotify Plugin – Part 3

The Spotify Album Widget Class

The last part of our WordPress plugin tutorial deals with the widget class, that handles the configuration of the instance and also the rendering of it when used in blogs. We will provide the full source below first and then breakdown each section and function.

 

WP_Widget

To start off, we need to create our widget class DOWidgetSpotifyAlbums that extends the WP_Widget class.
This provides our basis for creating a widget including some class methods we will be overriding to do so:

-form
-update
-widget

For the full set of methods, you can refer to the WordPress Developers Documentation

 

Constructor

The constructor takes care of a few items including the options that we have setup in the first two tutorial articles in this series. This is mainly so that we can extract the Spotify API Host for use in REST call later.

In addition, we will setup the following local variables:

$widget_ops = class name for registering later, and a description
$control_ops = if we wish to set parameters like the width and height (not used here)

Finally we pass this into the parent constructor of WP_Widget and get our widget setup.

 

Widget Instance Admin

We will now examine the form function now in more detail. The snippet is pretty straight forward with the first part setup to grab our instance’s Album ID value if it’s already saved from before, or to set it to NULL. The latter part of the function simply renders our instance’s display when open in the WordPress Dashboard.

The form is simple and only has a label and a field for the Album ID

One important note is to remember that we are now dealing with instances when working with widgets. This means that our widget can be placed on the same page/post multiple times, each being an instance, and we have to be careful about uniquely naming our items.

Within the code, you will see two other WP_Widget functions:

get_field_name
get_field_id

This is to ensure that our HTML element ids and names are uniquely created according to the instance. If you didn’t do this, you will run into all sorts of problems.

 

Instance Update

The update function is pretty straight forward, you have two variables, the $new_instance which contains all the values after you save, and the $old_instance, which holds the instance’s previous values.
The function is expected to return an instance so you can perform all manners of validation, checking or other logic here before returning the final instance.

 

Widget Instance Form

Please note the difference between the widget function and the form function. The one covered earlier is what you see when you administer your blog on the WordPress Dashboard, in the Widgets menu under Appearance etc. The one in this section handles the rendering on the actual blog when used.

Since it is a pretty large function, we will cover it in parts.

In the snippet below, before rendering our album information we need to get our parameters first.

Preparing the Data
$txtAlbumId is the instance’s album ID saved, and the functionality is covered in the sections above.
$spotifyAPIHost is the general plugin’s option, which is covered in Part 2 of the series.
Read Part 2 Here

Displaying Wrappers
The rest of the calls are just wrappers for the plugin, including any before/after widget markup you have that was set in register_sidebar. Usually used when your widget is in the sidebar and you wanted some extra definition to your widget visually.

In the snippet above, we left out the meat of our Widget display rendering, and here’s the rest of it.
Remember what we are trying to accomplish:

Given a Spotify Album ID
-Show the album cover art
-Show the list of tracks for the album

For this, we will use a combination of jQuery and handlebars. If you don’t know how to use either I highly recommend reading up on those.

Track Template.
In the snippet below, we see a the first script node, of type=”text/x-handlebars-template”.
This is essentially the HTML template we will use PER track, and will be used in Handlebars for every track we find.
For those unfamiliar with handlebars, it’s a much more comprehensive way of building up HTML markup against JSON data, without having to use String appends.

In the template here, we are expecting an array named items, and each item is expected to be a JSON object with track information such as the name, and an external url to Spotify.

Album Container.
The next section are placeholder containers for our album art, the list of tracks etc, which our jQuery will use after we make the Spotify call.

We move onto the rest of the code, which includes the call to the Spotify API.
There are a few parts here of interest.

Handlebars.registerHelper.
Right at the beginning of this snippet, we will register a handlebars helper function called Index.
Handlebars actually has a built-in {{@index}}, but only problem is that it starts at 0, and we want our tracks listing to start at 1, so this is a helper function that does just that.

jQuery Ready.
When we are ready to make the call, this section fires off. We make two calls and for the sake of the tutorial, i decided to make two parallel jQuery.ajax calls instead of chaining them based on the success of the first.

Another note about the Spotify API is that at the time of writing, they did not have JSONP support so we were able to call it directly for JSON data. This may change in the future.

Call 1: Getting Album Info.
The first call will get the album information including the name, artists, but the piece of information we’re interested in is the album art.

The call will return a JSON object back and which is handled in our “success” function and the result in the “data” variable.
In the snippet below, you will see that I am extracting the parts i need and placing them into the containers above.
For some of the data like the images and artists, i do a pretty simple check, not the prettiest, but it will work

data.name
data.images[0].url
data.artists[0].name

If you want to see what other data is available, here’s an example call: https://api.spotify.com/v1/albums/1RJDe9Eo8473Kg4pdUVGDM/

Call 2: Getting Album Tracks.
The second call will get the album tracks and their information.

The call will return a JSON object and within it an “items” array for each track.
Unlike the first call, we have a dynamic number of tracks, so the code here is leveraging the Handlebars template we mentioned earlier, and meshing the data together along with the HTML Template. If you forgot already, the template is covered above including it’s reference to the “items” array and the track link and name.

 

Summary

This pretty much sums up the Spotify Albums WordPress Plugin. It’s a really small plugin but covers many areas to expose new developers to a few things.

We have covered:

  • WordPress Options Pages
  • WordPress Widget API
  • Some sample jQuery and Handlebars to perform our rendering
  • Some core classes to wrap and manage all our code together

Next Steps:
I intend on pushing this into WordPress, and even though there’s a lot of better Spotify WordPress Plugins, I wanted developers to have a working plugin as well as these sets of tutorials to guide them in the development of their own.

If you would actually like to see us expand this plugin to do more, let us know.

Here are the other parts of this series:




Leave a Reply

Your email address will not be published. Required fields are marked *