Categories
Web WordPress WordPress Plugins

WORDPRESS PLUGIN BOILERPLATE

What is Plugin Boiler Plate?
A foundation for WordPress Plugin Development that aims to provide a clear and consistent guide for building your plugins.

Every time I start working on a new plugin I find myself renaming files names, searching and replacing plugin-namePlugin_Name , the packages, sub packages names, etc. All these tasks take me around 5-10 minutes every time, and I don’t like repeat unnecessary tasks.

So I found an easy way to generate WordPress plugin basic structure with in seconds. Of course it saved a lot of time.

Please visit  WordPress Plugin Boilerplate to generate plugins boiler plate. Obviously it won’t generate all of the files you require for your plugin. You can add more files once you have your basic structure.

WordPress Plugin Boilerplate Generator Configuration
WordPress Plugin Boilerplate Generator Configuration

There is no standard way to write a plugin. People follow different ways to write plugins. Some plugins require OOP to be followed and some don’t. But this is the best OOP structure that I had ever found and used in my Plugins development.

Please visit WordPress Plugin Boilerplate GitHub repository to get the essence of the final plugin structure.

It is meant to be a starting point for plugin development, an object oriented way of creating a standardized plugin. Since it is coded with OOP principles, it is mainly intended for intermediate coders, but you can easily use it even as a beginner if you know what goes where. By the end of this article, you should know what’s what and how you can get started with it – regardless of your coding experience.
Lets dig deeper into it.

File Structure.
The boilerplate is meant to be used as a GitHub repository, so the main directory contains files commonly found in GitHub repos. The README.md file is a general readme and shows up on your main repository page as the description and details about the plugin. The .gitignore file is for setting files that git should ignore when working with files.
The main folder here plugin-name is where the plugin is stored. It should have at least one fine your-plugin-slug.php with all the plugin details (Plugin Name, Version, Description, Author, Plugin Slug).

<?php

/**
 * The plugin bootstrap file
 *
 * This file is read by WordPress to generate the plugin information in the plugin
 * admin area. This file also includes all of the dependencies used by the plugin,
 * registers the activation and deactivation functions, and defines a function
 * that starts the plugin.
 *
 * @link              www.authoruri.com
 * @since             1.0.0
 * @package           Your_Plugin_Slug
 *
 * @wordpress-plugin
 * Plugin Name:       Your Plugin Name
 * Plugin URI:        www.yourpluginurl.com
 * Description:       This is a short description of what the plugin does. It's displayed in the WordPress admin area.
 * Version:           1.0.0
 * Author:            Author Name
 * Author URI:        www.authoruri.com
 * License:           GPL-2.0+
 * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt
 * Text Domain:       your-plugin-slug
 * Domain Path:       /languages
 */

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}

/**
 * Currently plugin version.
 * Start at version 1.0.0 and use SemVer - https://semver.org
 * Rename this for your plugin and update it as you release new versions.
 */
define( 'YOUR_PLUGIN_SLUG_VERSION', '1.0.0' );

/**
 * The code that runs during plugin activation.
 * This action is documented in includes/class-your-plugin-slug-activator.php
 */
function activate_your_plugin_slug() {
	require_once plugin_dir_path( __FILE__ ) . 'includes/class-your-plugin-slug-activator.php';
	Your_Plugin_Slug_Activator::activate();
}

/**
 * The code that runs during plugin deactivation.
 * This action is documented in includes/class-your-plugin-slug-deactivator.php
 */
function deactivate_your_plugin_slug() {
	require_once plugin_dir_path( __FILE__ ) . 'includes/class-your-plugin-slug-deactivator.php';
	Your_Plugin_Slug_Deactivator::deactivate();
}

register_activation_hook( __FILE__, 'activate_your_plugin_slug' );
register_deactivation_hook( __FILE__, 'deactivate_your_plugin_slug' );

/**
 * The core plugin class that is used to define internationalization,
 * admin-specific hooks, and public-facing site hooks.
 */
require plugin_dir_path( __FILE__ ) . 'includes/class-your-plugin-slug.php';

/**
 * Begins execution of the plugin.
 *
 * Since everything within the plugin is registered via hooks,
 * then kicking off the plugin from this point in the file does
 * not affect the page life cycle.
 *
 * @since    1.0.0
 */
function run_your_plugin_slug() {

	$plugin = new Your_Plugin_Slug();
	$plugin->run();

}
run_your_plugin_slug();

Activation, Deactivation & Uninstall:
This file ( your-plugin-slug.php ) also includes activation and deactivation hooks. These hooks are fired when plugin is activated and deactivated. This file is a gateway to the functionality of the whole plugin. You can add your whole code in this file but its not recommended you should follow MVC separate your models, views and your controllers. Any code you want to run when the plugin is activated should go in includes/your-plugin-slug-activator.php. In this file, there is a class named Your_Plugin_Slug_Activator inside which there is a activate() method you should use.

<?php

/**
 * Fired during plugin activation
 *
 * @link       www.authoruri.com
 * @since      1.0.0
 *
 * @package    Your_Plugin_Slug
 * @subpackage Your_Plugin_Slug/includes
 */

/**
 * Fired during plugin activation.
 *
 * This class defines all code necessary to run during the plugin's activation.
 *
 * @since      1.0.0
 * @package    Your_Plugin_Slug
 * @subpackage Your_Plugin_Slug/includes
 * @author     Author Name <author@gmail.com>
 */
class Your_Plugin_Slug_Activator {

	/**
	 * Short Description. (use period)
	 *
	 * Long Description.
	 *
	 * @since    1.0.0
	 */
	public static function activate() {
		//activation code here
	}

}

The code you need to run on deactivation should be placed in includes/your-plugin-slug-deactivator.php. The deactivate() method within the Your_Plugin_Slug_Deactivator is what you’ll need to use.

<?php

/**
 * Fired during plugin deactivation
 *
 * @link       www.authoruri.com
 * @since      1.0.0
 *
 * @package    Your_Plugin_Slug
 * @subpackage Your_Plugin_Slug/includes
 */

/**
 * Fired during plugin deactivation.
 *
 * This class defines all code necessary to run during the plugin's deactivation.
 *
 * @since      1.0.0
 * @package    Your_Plugin_Slug
 * @subpackage Your_Plugin_Slug/includes
 * @author     Author Name <author@gmail.com>
 */
class Your_Plugin_Slug_Deactivator {

	/**
	 * Short Description. (use period)
	 *
	 * Long Description.
	 *
	 * @since    1.0.0
	 */
	public static function deactivate() {
		//deactivation code here
	}

}


Do you think this is a bit too complex? I don’t blame you! When you start using object oriented concepts you’ll see the benefit of this over procedural code. If nothing else, it provides a very obvious place to put your code which is in itself a huge help. For uninstallation, the recommended method is to use uninstall.php which is what WordPress Plugin Boilerplate does. Your code should be placed at the very bottom of that file. You should dump everything that your plugin has created it is a sign of good plugin development to clean what is of no use. WordPress will automatically call uninstall.php if found in the plugins main folder. You can also use uninstallation hook.

<?php

/**
 * Fired when the plugin is uninstalled.
 *
 * When populating this file, consider the following flow
 * of control:
 *
 * - This method should be static
 * - Check if the $_REQUEST content actually is the plugin name
 * - Run an admin referrer check to make sure it goes through authentication
 * - Verify the output of $_GET makes sense
 * - Repeat with other user roles. Best directly by using the links/query string parameters.
 * - Repeat things for multisite. Once for a single site in the network, once sitewide.
 *
 * This file may be updated more in future version of the Boilerplate; however, this is the
 * general skeleton and outline for how the file should work.
 *
 * For more information, see the following discussion:
 * https://github.com/tommcfarlin/WordPress-Plugin-Boilerplate/pull/123#issuecomment-28541913
 *
 * @link       www.authoruri.com
 * @since      1.0.0
 *
 * @package    Your_Plugin_Slug
 */

// If uninstall not called from WordPress, then exit.
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
	exit;
}

//write uninstallation code here.

Adding Hooks

Hooks are handled by WordPress Plugin Boilerplate amazingly, but it may seem a bit unwieldy at first. All your hooks should be placed within includes/class-your-plugin-slug.php. More specifically, inside the Your_Plugin_Slug class, within two methods:

  • define_public_hooks() when adding a hook that is used on the front-end for public.
  • define_admin_hooks() when adding a hook that is used on the back-end for admins.

Instead of using add_action() or add_filter() as usual, you’ll need to do things slightly differently. Here is how you add an action.

$this->loader->add_action( 'init', $plugin_public, 'display_message' );

Here we have a loader class Class Your_Plugin_Slug_Loader that automatically adds actions and filters for us.
The first parameter is the name of the hook, the second is a reference to the public or admin object. For public hooks this should be $plugin_public, for admin hooks it should be $plugin_admin. The third parameter is the hooked callback function.

While it seems more convoluted it standardizes the addition of hooks completely, splitting them into two distinct groups in the process.

Public And Admin Content

WordPress Plugin Boilerplate splits hooks into admin/public groups but that’s not all. It splits all your code in the same way by asking you to write public-facing code in the public folder and admin-facing code in the admin folder.

Both folders contain cssjs and partials folders. You should place used CSS/JS assets into these folders and write templates and other reusable bits of HTML into the partials folder. It’s okay to create new files in the partials folder, in fact, that’s what it’s there for!

You should write your hooked functions in these folders as well, within the class in the respective directories. When we hooked the display_message function to inti hook above, we told WordPress Plugin Boilerplate where to look for it as well. Since we added this to the public facing side, WordPress Plugin Boilerplate expects it to be defined within the Your_Plugin_Slug_Public class which is in the public folder. Simply create this function within the class and write everything else as required.

Resources And Dependencies:
You can add other resources and dependencies in includes folder, admin or public folder depending on the use of that resource.

At first, using WordPress Plugin Boilerplate may seem like a hassle, but it will pay off in the end. You will come back a year later and know where everything is, your plugin development will be standardized across products and other developers will be able to figure out what’s going on as well.

Finally, don’t forget that a plugin providing a simple widget may not need such a framework. While the use of WordPress Plugin Boilerplate won’t slow down your plugin it does clog up the view if all you need is a few simple lines of code!

Cheers!

  • plugin-boiler-plate-overview
  • plugin-boiler-plate-admin-overview
  • plugin-boiler-plate-includes-overview
  • plugin-boiler-plate-public-overview

And if you have enjoyed this post, feel free to share it or subscribe to my newsletter below.

Categories
React WordPress Plugins

React app embedded into WordPress page via short code

Goal: Create WordPress plugin which will inject React based web app\widget into normal WordPress page\post\sidebar using a shortcode.

Embedded react app useful when you need to create an complex fully interactive widget\app like a calculator for example, and you want it to be a part of WordPress page.

In this article I’ll describe one of the approaches to embedded react app into WordPress page. Although it may be not a perfect way, we’ll dig deeper into other build approaches in next articles.

Let’s split our big task into sub-tasks to better understand how we achieve it:

  1. Create WordPress plugin
    • it will enqueue our js\css and register shortcode to render root element of React app.
    • yes shortcodes are old school approach (compared to Gutenberg Blocks). But they work well for this use case and we keep it simpler for now.
    • it will also pass in App’s settings via data attribute of root element.
  2. Generate React app via npx create-react-app
    • the idea is to utilize a ready to use solution for scaffolding and Webpack configuration, so newbies like me .🙂 in react world could follow standard React tutorials to build his first React App.
    • also you can use approach explained in this article to simply inject your existing React App, generated via npx create-react-app into WP based site.
  3. Modify build\start npm scripts to work well with WordPress.
    • by default react build Webpack’s configuration will generate js files split in chunks – it makes it harder to link them via wp_enqueue_scripts as we used to in WordPress.
    • so we’ll write a code which will partially override config and Webpack will generate js\css which will be easy to use in WP.
  4. Write JSX\React code and build it.
  5. Insert shortcode [wp-react-app] and enjoy.

Result plugin can be fetched from github https://github.com/MuhammadFaizanHaidar/wp-react-app/

1. Create WordPress plugin

It will register a shortcode and enqueue public scripts and styles for our React App.

https://github.com/MuhammadFaizanHaidar/wp-react-app/blob/main/public/class-wp-react-app-public.php

NB: I use

define('ENV_DEV', true); // in wp-config.php

to load generated by yarn start css\js files while development, set it to false when you need to use css\js generated via yarn build.

In a shortcode I pass in json string of settings as data-default-settings attribute for our App’s root element.

https://github.com/MuhammadFaizanHaidar/wp-react-app/blob/main/includes/shortcodes/class-wp-react-app-short-codes.php

<?php

/**
 * Fired to add short codes
 *
 * @link       www.faizanhaidar.com
 * @since      1.0.0
 *
 * @package    Wp_React_App
 * @subpackage Wp_React_App/includes
 */

/**
 * Fired to add short codes.
 *
 * This class defines all code necessary functions to run during the short codes rendering.
 *
 * @since      1.0.0
 * @package    Wp_React_App
 * @subpackage Wp_React_App/includes
 * @author     Muhammad Faizan Haidar <me@faizanhaidar.com>
 */
class Wp_React_App_Short_Codes {
    /**
	 * The unique identifier of this plugin.
	 *
	 * @since    1.0.0
	 * @access   protected
	 * @var      string    $plugin_name    The string used to uniquely identify this plugin.
	 */
	protected $plugin_name;

	/**
	 * The current version of the plugin.
	 *
	 * @since    1.0.0
	 * @access   protected
	 * @var      string    $version    The current version of the plugin.
	 */
	protected $version;
    /**
     * Class constructor.
     */
    public function __construct( $version, $name ) {

        $this->version     = $version;
        $this->plugin_name = $name;
        add_shortcode(
            'wp-react-app',
            [ $this, 'wp_react_app_shortcode' ]
        );

    }

    /**
     * Shortcode which renders Root element for your React App.
     *
     * @return string
     */
    public function wp_react_app_shortcode() {

        /**
         * You can pass in here some data which if you need to have some settings\localization etc for your App,
         * so you'll be able for example generate initial state of your app for Redux, based on some settings provided by WordPress.
         */
        ob_start();
        $settings = array(
            'l18n'       => array(
                'main_title' => 'Hi this is your React app running in WordPress',
            ),
            'some_items' => array( 'lorem ipsum', 'dolor sit amet' ),
        );
        ?>
       /** 

        * data-default-settings passed as an attribute.

        */
        <div id="wp-react-app" data-default-settings="<?php esc_attr_e( wp_json_encode( $settings ) ); ?>">ecgosdhds</div>
        <?php
        $output = ob_get_contents();
        ob_end_clean();

        return $output;
    }
}

2. Generate React App

In your new plugin’s directory simply run npx create-react-app app and wait a bit.

We’ll use yarn add for the sake of brevity but you can use npm as well. Just pick one (anyway you can switch back any time if needed).

Let’s cleanup a bit via removing redundant files from src directory of app. These are:

  • logo.svg – because in WordPress we handle images URLs differently – you can use relative to plugin’s path links to images.
  • serviceWorker.js

As well as references to them in index.js and App.js

You can remove all files inside /app/public except index.html as we don’t need them.

Remove .git directory inside react app’s folder – as you’ll probably want to track changes via git but for a whole plugin and not just react part of it. And in .gitignore remove line

/build

So our main.js and main.css files which are result of build process will be tracked with git.

Next step is optional – we’ll install node-sass I just prefer to work with SCSS files rather then plain CSS, so in case you like it as well – just cd to your newly generated react app directory and then run yarn add node-sass as described here https://create-react-app.dev/docs/adding-a-sass-stylesheet/

Create scss folder under src and move css files into it, renaming them to .scss and change imports of these files in js to point to our new .scss files like:

import './scss/App.scss';

in App.js, and

import './scss/index.scss';

for index.js

3. Modify build\start npm scripts to work well with WordPress

In your React App’s directory, run yarn add rewire --dev – we use rewire to be able to redefine webpack.config provided by create-react-app boilerplate without a need to eject react app or modify config files which reside in node_modules

Now create new directory called scripts – here we’ll set our JS files which will do magic for us.

start-non-split.js – this file will change Webpack config on fly. So that it will not split JS code in chunks and will not inject hash into filename.

const externals = require( './externals' );
const rewire = require( 'rewire' );
const defaults = rewire( 'react-scripts/scripts/start.js' );
const configFactory = defaults.__get__( 'configFactory' );

defaults.__set__( 'configFactory', ( env ) => {
   const config = configFactory( env );

   config.externals = {
      ...config.externals,
      ...externals,
   };

   config.optimization.splitChunks = {
      cacheGroups: {
         default: false,
      },
   };
   config.optimization.runtimeChunk = false;
   config.output.filename = 'static/js/[name].js';
   config.output.chunkFilename = 'static/js/[name].js';
   return config;
} );

build-non-split.js – this is used for building production js\css files. It will again build them as single files making it easier to link in WP.

const externals = require( './externals' );
const rewire = require( 'rewire' );
const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' );
const defaults = rewire( 'react-scripts/scripts/build.js' );
const config = defaults.__get__( 'config' );

/* we inject our Externals to keep our bundles clean and slim */
config.externals = {
   ...config.externals,
   ...externals,
};

/*
 * we set jsonFunction of webpack to our custom one
 * so multiple js bundles built with webpack could be safely loaded,
 * as we are aware that our plugin isn't the only one which can be potentially built with webpack.
 */
config.output.jsonpFunction = 'YourReactApp_webpackJsonpjs';

/* we disable chunks optimization because we want single js\css file to be loaded by plugin. */
config.optimization.splitChunks = {
   cacheGroups: {
      default: false,
   },
};
config.optimization.runtimeChunk = false;
config.output.filename = 'static/js/[name].js';
config.output.chunkFilename = 'static/js/[name].js';

/*
* lets find `MiniCssExtractPlugin` type of object in plugins array and redefine it's options.
* And remove all unnecessary plugins.
*/
const disabledPlugins = [
   'GenerateSW',
   'ManifestPlugin',
   'InterpolateHtmlPlugin',
   'InlineChunkHtmlPlugin',
   'HtmlWebpackPlugin',
];
config.plugins = config.plugins.reduce( ( plugins, pluginItem ) => {

   if ( disabledPlugins.indexOf( pluginItem.constructor.name ) >= 0 ) {
      return plugins;
   }

   if ( pluginItem instanceof MiniCssExtractPlugin ) {
      plugins.push(
         new MiniCssExtractPlugin( {
            filename: 'static/css/[name].css',
            chunkFilename: 'static/css/[name].css',
         } )
      );
   } else {
      plugins.push( pluginItem );
   }

   return plugins;
}, [] );

externals.js – this file contains shared scripts which can be provided by WP Core. So we don’t need them to be bundled into our build.

module.exports = {
   react: 'React',
   'react-dom': 'ReactDOM',
};

In my case after I’ve marked React and ReactDOM as external ones JS bundle’s size decreased from 160kb to 56kb – those get’s loaded from wp-includes as a dependency any way, but imagine you have bunch of such Apps and each will load extra version of bundled React library. To overcome this we mark them as external – this way we keep our bundles clean and light, and at the same time we leverage WordPress scripts dependency manager to link necessary dependencies for us.

Then open package.json file and in scripts section update start command to

"start": "node ./scripts/start-non-split.js",

and build command to

"build": "node ./scripts/build-non-split.js"

So your package.json file will look like this:

{
  "name": "app",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^4.2.4",
    "@testing-library/react": "^9.3.2",
    "@testing-library/user-event": "^7.1.2",
    "react": "^16.13.1",
    "react-dom": "^16.13.1",
    "react-scripts": "3.4.1"
  },
  "scripts": {
    "start": "node ./scripts/start-non-split.js",
    "build": "node ./scripts/build-non-split.js",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": "react-app"
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "node-sass": "^4.14.0",
    "rewire": "^5.0.0"
  }
}

4. Write JSX\React code and build it.

Now we are almost ready, let’s update index.js file which initializes our React app on root element inserted via shortcode.

import React from "react";
import ReactDOM from "react-dom";
import "./scss/index.scss";
import App from "./App";

const rootEl = document.getElementById("wp-react-app");
if (rootEl) {
  const settings = JSON.parse( rootEl.getAttribute( 'data-default-settings' ) );
  ReactDOM.render(
    <React.StrictMode>
      <App settings={settings} />
    </React.StrictMode>,
    rootEl
  );
}

Here we also read initialization settings data provided by WP, and pass them into App as prop.

If you’ll use Redux you can use these data to generate initial state for App.

Let’s update our App.js file to utilize our settings from props.

import React from 'react';
import './scss/App.scss';

function App(props) {

  const items = props.settings.some_items || [];

  return (
    <div className="App">
      <header className="App-header">
        <h1>{ props.settings.l18n.main_title }</h1>
        <ul>
          {
            items.map((item, index)=>{
              return (
                  <li key={index}>{item}</li>
              )
            })
          }
        </ul>
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

Now we are ready to test everything together.

  • activate our plugin and place [wp-react-app] shortcode on page.
  • in terminal cd to plugin’s directory /app and run yarn build – it will build js\css then just open a page where you’ve placed a shortcode and app will be rendered there.

For development:

  • add define('ENV_DEV', true); to your wp-config.php
  • in plugin’s /app sub directory run yarn start it will build css\js and spin up a dev server to serve updated css\js whenever you make change in source files. (yarn doesn’t support live reloading yet but for quickstart it’s enough).
  • Yarn will also open a new tab in browser leading to localhost:3000 and showing error message that React is not defined just close and ignore it. It says React is not defined just because we’ve declared it as external. And we haven’t bundled it into our result main.js
  • It will work inside WordPress page because we’ve declared wp-element as dependency in our plugin, so WordPress will load React on it’s own.
  • So just refresh your WordPress page where you’ve placed our new shortcode and here’s your React App inside WordPress page.
  • NB: in ENV_DEV true mode you need to yarn start otherwise it will not be able to load css\js, set it to false or comment out for production.

Happy codding 🙂

Final view after short code insertion. Hurray ! You have successfully embedded react app into WordPress page.

react-app-embedded-into-wordpress-page

And if you have enjoyed this post, feel free to share it or subscribe to my newsletter below.