A few weeks ago, I released a widget that displays World Cup data highlights in a WordPress sidebar, and I’d like to tell you how it works. As an avid futbol (soccer!) fan and citizen of the Internet, I came across an awesome World Cup API for accessing live data on the 2014 FIFA World Cup that inspired me to create this plugin. (The Top Scorers widget is active in the sidebar on this post so you can see it in action.)
Creating a Base Widget Class
Since I would be creating multiple widgets using the same basic functionality to call and access the Kimono Labs API, I set up a base WorldCup_Widget class that would extend the WP_Widget that I would extend further for each generated widget.
The base class would, at the very least, need to include the API key and a function for wrapping my API calls. In my main widget (worldcup-widget.php) file, I included something like the following (along with other basic boilerplate):
In the above snippet, the worldcup_api_call function takes an api endpoint (players, teams, clubs, stats, matches) and additional parameters, submits an API request, and transforms the returned results from JSON to a PHP Array. By default, this function will return json decoded version of this data.
Giving this functionality to a base class ensures that the widgets have easy access to the entire breadth of the World Cup API. The boilerplate functions for __construct(), widget( $args, $instance ), update( $new_instance, $old_instance ) and form( $instance ) functions will all be adapted and moved to their own files under a new class that extends the base WorldCup_Widget (that is already set to extend the WP_Widget class)! The base slug used to identify the widget in WordPress is set in this file as well, providing a base string to prepend to all of the unique widget slugs.
Extending The New Base Widget
In the plugin folder, I created a widgets directory that houses all subsequent widget classes where the first widget for the plugin will be (/widgets/widget-main.php). This first widget lets the user select a team and theme. The output is then displayed in their sidebar— exciting!
This new class WorldCup_Widget_Main extends WorldCup_Widget, which extends WP_Widget and is located in /widgets/widget-main.php.
The constructor is a little different from the basic boilerplate in that the WP_Widget::construct is referenced directly instead of a traditional Parent::construct() usage. The rest mostly remains the same; we pass along a unique slug, widget title, css class name and widget description.
Creating The Views
Next, I’m going to dive into the fun stuff of displaying, updating and editing the widget. To do this, I’ll use the views structure that the boilerplate has supplied.
The /views/admin.php will be used to display the edit screen for the widget and /views/widget.php will be used to display the sidebar front view of the widget. Functional information will be commented in the source below, but is mostly the same documentation supplied by the boilerplate.
This widget will use and store two variables to manipulate in the views: the $selected_team and the $theme.
Here is the annotated code for our admin view of this widget (/views/admin.php):
Here is the annotated code for our front-end view (/views/widget.php).
Enable The Widget
To add this widget to the WordPress plugin, go back to the main worldcup-widget.php and add two more lines to make sure the new widget gets pulled into the site and created:
You can find the latest code regarding this plugin on the 30lines github: https://github.com/30lines/worldcup-widget.
Feel free to fork it and play with it locally. If you make anything cool, be sure to let us know!
If you want to bundle it as part of this WorldCup Widget plugin on WordPress, just submit a pull request and after review I’ll add it to the next update.
As of version 1.0.4, there are three widgets that do the following:
- Display group stage information
- Display top goal scorers
- Display selected team record/match stats and upcoming matches