battlestar-digital / bsd-plugin-boilerplate

A modern WordPress plugin boilerplate using namespaces for PHP and React for plugin settings.

Battlestar Digital Plugin Boilerplate

This modern boilerplate template uses namespaces for PHP and React for plugin settings.

Initial Setup

Prerequisites

Before you begin, ensure you have met the following requirements:

• You have installed the latest version of Node.js
• You have installed the latest version of NPM (included with Node.js)

Installation

Copy the contents of the bsd-plugin-boilerplate folder into your \wp-content\plugins folder. The steps below will walk you through customizing these files for your new plugin.

First, we need to replace our generic plugin name and slug with your plugin name and slug.

1. Rename the root folder to your plugin's slug.
2. Rename bsd-plugin-boilerplate.php to your-plugin-slug.php
3. Rename includes\class-bsd-plugin-boilerplate.php to includes\class-your-plugin-slug.php
4. Find and replace all instances of bsd-plugin-boilerplate with your-plugin-slug
5. Find and replace all instances of bsd_plugin_boilerplate_admin with your_plugin_slug_admin
6. Find and replace all instances of BSD_Plugin_Boilerplate_Main_Plugin with Your_Plugin_Slug_Main_Plugin
7. Find and replace all instances of BSD_PLUGIN_BOILERPLATE_URL with YOUR_PLUGIN_SLUG_URL
8. Find and replace all instances of BSD_Plugin_Boilerplate with Your_Plugin_Slug
9. Find and replace all instances of BSD Plugin Boilerplate with Your Plugin Name

Next, install the required Node modules and create a dist file:

1. Navigate to your-plugin-slug\blocks and run npm install
2. Run npm run build. This command creates the dist folder which contains the JS and CSS files enqueued by your plugin.

Finally, open your WordPress admin dashboard and activate the plugin.

Congratulations! You now have a fully-functional -- if somewhat barebones -- plugin.

Screenshots

Out of the box, you'll have a settings icon in the Admin dashboard:

You can, and probably should, replace the embedded SVG icon in \includes\admins\menu.php. SVG Repo has a great selection of SVG icons.

To start, you'll have a single sample setting available in the settings page:

Obviously, you'll want to replace this with your own plugin option.

Customization

Plugin Options

Creating your plugin settings requires two steps, and an optional third:

1. Register your setting by adding a new call to the register_setting function. Add this call in \includes\init.php, modeling (or updating) the example provided in lines 11-18.
2. Update \blocks\app\admin-settings\index.js. Okay, this isn't really a single-step process. Using the boilerplates sample setting as a guide, add your setting as follows:
   1. Create a new constant in componentDidMount (sample: productVariations).
   2. Add your setting to the settings array inside setState (sample: BSD_Plugin_Boilerplate_sample_setting: productVariations).
   3. Add a new function to run when your setting is updated. You can copy sampleSettingsChange(newVal).
   4. Bind your new function (sample: this.sampleSettingChange = this.sampleSettingChange.bind(this); in the constructor).
   5. Add a new Panel Row in the render function. See the existing <TextControl> for an example.
      1. Refer to the Block Editor Handbook for components you can use, such as the CheckboxControl, SelectControl, and TextareaControl
3. Optionally, but highly recommended, is to clean up after yourself. Add your setting to the array in uninstall.php

Deployment

This boilerplate includes scripts that will allow you to package it for deployment. While these are optional -- you can certainly package it by hand -- we highly recommend their use to streamline your plugin process.

Setup

1. Install gulp globally: npm install --global gulp-cli

Backlog

1. Add a Gulp script to ZIP only the files necessary for plugin distribution (e.g., ignore node-modules, blocks\app)
2. Add a Gulp script to rename files, variables, and constants with your plugin name and slug
3. Add PHPUnit for PHP unit tests
4. Add React Testing Library for React component testing