WordPress Plugin – Creating your own Spotify Plugin – Part 2

Creating Plugin Classes and Option Pages

In the previous article, we got as far as defining our directory structure, setup our main.php and have added content inside it for the plugin metadata, includes, as well as initializing our core class, DOSpotifyAlbums, which is covered in this article.

Here are the other parts:

Before we begin, we will create the following classes and their relationship:

  • DOSpotifyAlbums – the core class for our Plugin
  • DOSpotifyAlbumsSettings – the class for the Plugin Settings
  • BaseOptions – the base class for the settings page for all our child settings pages to extend
  • GeneralOptions – the class for our settings page: extends BaseOptions

Lets take a look at the first class, our core plugin class – DOSpotifyAlbums:

 

$options

Right at the beginning of our class declaration, we have an $options variable declared. When working with WordPress Plugins, there are a lot of configuration settings that you will need to save. For example, if your plugin provides a Feedback form, you might need settings for feedback length, default fields, editable messages etc.

In our case, we’re trying to get Spotify Album information through the REST API and we will need to store some of these settings somewhere, this is where the $options come into play.

For now, lets have it declared and move on:

 

Constructor

Moving onto our next part in the code, the constructor, there are a few things we’re doing including:

  • Calling add_action to hook a callback to the ‘init’ function during plugin initialization
  • Check if we’re in Admin mode and if we are, setup the options variable using the Options API: get_option
  • Lastly, initialize another class, for Options in the Admin Dashboard: DOSpotifyAlbumsSettings

Placeholder Methods

Lastly we will prepare some callbacks for now, the init we have hooked up on the plugin initialization, but there are others as well such as when you Activate and Deactivate a plugin.

 

DOSpotifyAlbumsSettings Class

In our core class, everything was pretty simple but it gets more detailed from here. Within the constructor we made a call to another class DOSpotifyAlbumsSettings, and it is within this class where we start the setup of our options pages; the menu/pages that appear in the Administrator Dashboard.

As always, lets take a look at the entire php file first:

We see a similar structure as in the core class, a constructor that:
-creates a reference to our core class (so that we can reference the options later)
-initializing a callback with add_action for menu page initialization

Essentially, our create_setting_pages will be called and we initialize our page classes here.
When your plugin expands, you can place all your other option page classes here but for now we have just one:

The GeneralOptions class, and we will pass in our instance of DOSpotifyAlbums as a reference.
Lets take a look at the entire file – class.GeneralOptions.php:

 

The GeneralOptions Structure

We have a few functions here that we will cover in detail each but keep in mind our class extends from BaseOptions, so you will need to review that as well in terms of how the two classes interact. In brief, it will be enough to know the BaseOptions class makes the following calls:

  • handle_post();
  • render_header();
  • render_page();
  • render_footer();

This means that any extending class like GeneralOptions will be able to override them to perform it’s own rendering and logic.
Looking at the GeneralOptions shell again below, we have three functions.

Our constructor will setup the necessary references to our plugin ($core), handle_post is mainly meant for AFTER the page is saved, and to handle the POST call with any updated form data, and lastly, the render_page will provide the HTML for our form and save button.

 

Constructor

In detail, our constructor will setup $core, which is our DOSpotifyAlbums instance. In addition, we will check our options for the following option ‘doSpotifyAPIHost’. This will be our only option we are saving for our plugin, and if this is not set initially, we will set it to the default API host, and update it in our Options API with update_option:

https://api.spotify.com (October 2016 at time of writing)

The next important call here is the add_menu_page call.
This is the main call that allows us to create the options menu page you see in the Dashboard interface on the side menu.
The snippet below is pretty much self explanatory on what each parameter does.

 

Rendering the Option Page

We will jump around the code a bit and cover handle_post after render_page. The reason is because of the order, since we will be showing/rendering the form before we save and process the form.

In the snippet below, it’s pretty much HTML to render our form, along with an input text field for the API Host, and a submit button to trigger the form.

Some interesting items here include:

1. get_admin_page_title() – the page title that we set in the add_menu_page
2. A hidden form field “update” to use in our handle_post later
3. Make note of the “name” of the text field, because that is what we will be processing later
4. The value of the input text references the option, if it’s saved: doSpotifyAPIHost

When you load up the options page for our plugin, the content here (and some additional header/footer HTML) is what you will see.

 

The BaseOptions page

Lets take a look under the cover, the parent class BaseOptions, because a lot of the rendering of the page is done in the parent class. Here is the entire class file for reference:

 

The BaseOption Page Layout

Some of the items in BaseOptions has been covered in the GeneralOptions section above.
If you recall, there were two main calls: handle_post and render_page. These are just two of the overriden methods from the base class as seen below.

The full layout of an options page will include:

-Header
-Page Content
-Footer

The header and footer we want to keep standard across all child option pages so that’s why the implementation is in BaseOptions instead of GeneralOptions. But the choice is up to the developer if they wish to extend this plugin and override the header/footer content.

The functions for render_page and handle_post are empty here because we expect the child option page to handle these on their won, such as their own forms/html of what to show and save, and how to handle the form POST data.

 

The header/footer

The remaining functions inside our BaseOptions class are here and they handle the rendering of the header and footer sections across all child option pages.

Most of this is just HTML markup so there is nothing specific to cover, but do take a look and reference this as one way of promoting your site/plugin, and to provide some useful information about your plugin.

 

Summarizing

Lets backtrack a bit and discuss everything we covered because in Part 2 we covered a lot of material.
We covered 4 main classes here:

-DOSpotifyAlbums
-DOSpotifyAlbumsSettings

These we have referred to as our core classes. We keep our plugin variables and other logic in here as we extend our plugin and some of these variables and/or logic will be Plugin-wide, therefore residing in the first class, DOSpotifyAlbums. Other administration/dashboard related items (such as option page initialization) will be in the second class, DOSpotifyAlbumsSettings.

These two classes serve as the main entry points but aren’t direct representations of a WordPress object, which is where the next two classes come into play. GeneralOptions is essentially our options page in the dashboard, with functions written to render the form features. However since we plan on extending this plugin, we wish to reuse and standardize certain areas of the options page such as the header and footer, and this is why we have the parent class BaseOptions.

At this point, we have all the pieces except for the Widget, the final piece of the tutorial, which renders our Album information on the WordPress blogs itself. Move onto Part 3 for the next in the series.




Leave a Reply

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