Chapter 3 – Leveraging WordPress Plugins
So this is where the magic happens. To quote the first 3 sentences of the chapter “Plugins are awesome! If you didn’t know, now you know! Plugins can help you deploy a full-blown web application with little to no knowledge of actual code.” I agree. This is indeed true and very powerful but in my case, the learning goal of this book is how to build my own plugin to extend WordPress into a custom architected web app. This is done by using the WordPress Plugin Application Program Interface or API. I will assume you already know that you can install and activate one of tens of thousand of free and open source plugins, so we’ll move past the WordPress basics and talk about building custom plugins.
To create a bare bones custom WordPress plugin, let’s call it “My Awesome Plugin”, follow these steps:
- Create a new folder under wp-content/plugins called my-awesome-plugin.
- Create a new file in that directory call my-awesome-plugin.php
- Add a header to the plugin file that provides the name, URI etc (see the book or existing plugin for the correct format)
Even though the plugin does nothing, you can go to the admin and activate this plugin. That’s it. That’s a skeleton WordPress plugin. The authors provide a few sample lines of code to write something in the footer, but I think it’s more interesting to continue understanding what the plugin code and structure would be for a true web app.
Since a complex app would have a complex plugin with potentially thousands of lines of code and dozens of files, the authors provide an outline of the SchoolPress plugin hierarchy and a description of what might be found there.
/plugin/schoolpress/adminpages
Contains.php files for any dashboard pages you add through the plugin. For example, suppose you wanted a reports dashboard page:
- create /plugin/schoolpress/adminpages/report.php
- call code (see example) that:
- invokes add_action (‘admin_menu’, ‘sp_admin_menu’)
- write function sp_admin_menu that calls add_menu_page() with a parameter named sp_reports_page
- write function sp_reports_page() that loads /plugin/schoolpress/adminpages/report.php
/plugin/schoolpress/classes
Contains PHP class definitions. One class per file is suggested with the naming convention class.ClassName.php.
/plugin/schoolpress/css
Contains CSS files specific to your plugin. The authors suggest splitting custom css to admin.css and frontend.css.
- Load these files using add_action( ‘init’, ‘sp_load_files’)
- function sp_load_files() calls wp_enqueue_style() (checking is_admin()) for each CSS file
Note that although styles affecting the admin are clearly in the admin.css, front end styles may be included either in the frontend.css or in the theme’s css. As a general rule, include only basic, necessary, permanent CSS code in frontend.css that should be applied regardless of theme. Anything pertaining to color or layout that would change along with the theme belongs in the theme css.
/plugin/schoolpress/js
Just like CSS, this directory will hold an admin.js and frontend.js, with the same theme level consideration. Any third party JavaScript libraries go here as well.
- load these files using add_action ( ‘init’, ‘sp_load_scripts’)
- function sp_load_scripts() will contain calls of wp_enqueue_script() for each file.
/plugin/schoolpress/images
Contains plugin specific images.
/plugin/schoolpress/includes
This directory will serve as a catchall for php files that don’t belong anywhere else. The root directory should contain only one php file, the one with the plugin name we discussed earlier. A best practice is to add a general functions.php or helpers.php here to include all the supporting php code not included elsewhere.
/plugin/schoolpress/includes/lib
Contains any third-party libraries (that are not js because of course there is a separate directory for that.)
/plugin/schoolpress/pages
Contains .php pages that correspond to front end pages added by the plugin, typically added by embedding shortcodes.
- create a named page file in this directory — for example student_view.php
- include this file in your main plugin file (typically require_once)
- add any code you want to run before the headers are loaded in wp_head() inside this page using add_action ( ‘wp’, ‘sp_student_view_preheader’, 1) and define the function sp_student_view_preheader(). Because the header is not yet run, you can wp_redirect()
- add the shortcode declaration using add_shortcode(‘sp_student_view’, ‘sp_student_view_shortcode()
- output any HTML you want in the function sp_student_view_shortcode().
- Check code in the book on when and how to use output buffering so the HTML is output inside the HTML tag
/plugin/schoolpress/services
Contains php code for AJAX calls.
/plugin/schoolpress/scheduled
Contains php files related to cron jobs or other scheduled code.
/plugin/schoolpress/schoolpress.php
This is the main plugin code file. For a large project, it would contain other includes and constant definitions whereas for a small plugin, it might be the only file.