React WordPress Plugin Boilerplate from Roy Sivan
This React Admin Boilerplate gets you started building a plugin in the admin area that leverages React and the WordPress REST API.
Thanks to course advisor, Roy Sivan, for developing this boilerplate and for writing this project for us.
Now, let’s jump into what this boilerplate looks like out of the box, how we can customize it, and even some ideas for taking it further.
An Overview of the React Admin Boilerplate
Re-Imagining Admin Dashboards
It is created for plugin or theme developers who have unique functionality or want to offer a unique UX for their users. The boilerplates available are quick ways to start, written in AngularJS and ReactJS, both are a work in progress. This article is going to focus on the ReactJS boilerplate
Recommended Background Knowledge
What This Project is Ideal For
In a nutshell this boilerplate is ideal for those plugin developers or theme developers who want to give their users a unique experience that is not WordPress.
This comes in really handy when you have a plugin with advanced functionality that goes beyond maybe what WordPress can give you admin-wise out of the box.
Examples of Boilerplate in Action
The best examples of using a custom app for the admin interface include Ingot A/B testing plugin written primarily by Josh Pollock and my Stripe for WordPress dashboard, which was directly built from the AngularJS version of the boilerplate.
Both of these examples are plugins with a lot of functionality, primarily interacting with the REST API.
The Boilerplate is Also a Plugin
While the boilerplate is meant to be used by plugin or theme authors, it is in itself a plugin, and you will be able to activate it, this is so a plugin can be built around the boilerplate, or just added into an existing plugin easily.
A Note From the Boilerplate Author
As a warning, I did re-learn ReactJS while building this boilerplate. While I don’t use React on a day to day and they have a lot of changes per release, I had to re-learn it, but I kept it very basic.
This should make it easy for anyone to pick up, however may miss some of the more advanced functionality of React.
This also may mean something that I did not know about that could have made development easier, is not included.
Get Involved with This Open Source Project
This is why I keep them open source, so developers can work with them, and if they find a better way to do something, submit a PR so I can learn from others as well.
The Boilerplate Out of the Box
Installing the boilerplate is easy but you will need to make sure to have npm installed globally.
Clone the repo into your /wp-content/plugins directory or download the zip and unzip into the same directory.
Once the files are there open your favorite command-line tool and run npm install and gulp. This will install all packages needed including React with it’s dependences, Bootstrap, and Gulp with it’s dependencies.
As mentioned before, this boilerplate is meant for developers to add their own functionality of their plugins or themes. It will however run fine out of the box and activate as a standalone plugin.
Adding Demo Custom Post Types and Content
The plugin will by default also create a books custom post type with some dummy post data, if you do not want this to happen go to the admin-js-app.php file remove or comment out lines 40 and 41:
add_action('init', array($this, 'create_cpt')); add_action('init', array($this, 'create_book_content'));
Checking Out the Boilerplate in the Admin Area
Once activated, you will see a new menu item “JS App” which will be the main page for the single page application.
If you had the plugin install the custom post type and content, you’ll see “books” in the menu next to “Main”, clicking on this will take you to a list page for all the posts in the book CPT.
Built into the plugin is an edit page and detail (view) page for the book post type. You can uses these pages as a template for other custom post types since it includes basic functionality like update/save as well as delete.
New Page Feature
There is no “new” page or creation form yet, however this would depend on the application or use case. When I first built this and used it for my Stripe for WordPress plugin, there wasn’t much needed to be created, only read and edited.
Customizing the React Admin Boilerplate
Many people love React for one of its main design features, and that is everything is component based. That is how I set up this boilerplate. When you open up assets/js/components you will see the js files which have the templates.
Each component is a React function (createClass) which has methods for anything you may need, ultimately rendering the template for that component. These components can be nested within each other to make life easier and to modularize your view.
As an example open assets/js/components/list-posts.js you will see all the components needed for the list page. We start with getting all the books from the API, I tried this into the componentDidMount method because you want to make sure the component loads before calling the API. In the render method of AllBooks you will see it returns a <Books> element.
The Books element is a component and is defined next. For every book the books component returns a BookRow which is another component, and that has the actual html.
As commented in BookRow I was unable to find an easy way to bring data into the HTML as I needed it, so I had to use the React createElement function and create each element of the page individually, then use 1 createElement to create an article which wraps them all, and have the component render the article.
Taking it Further
Once you understand how everything works by looking through the components, and the main admin-app.js you are ready to customize.
Start by customizing what a single component renders, from there see if you can modify the every page.
Once you have figured that out, move on to whatever you may think of next for customizing to fit your needs.
Making It Better
React is still an emerging technology/framework. While I haven’t been able to keep up, new things are being released regularly, and it is very fast.
See what is new since I wrote the boilerplate, and please send me a PR if you find better ways to do things with newer versions of React.
Create a New Admin UX
As I said before, this is primarily focused on plugin and theme developers who have a desire to create a truly unique UX for their users.
You can take this project and customize just the styles to create something custom that still integrates well into the WordPress Admin.
Ingot Plugins Using the Boilerplate
Ingot for example has a whole multi-step creation flow which looks and feels a lot better than if it had been built using default WordPress admin pages.
Building Out the Build Process
Minification of these files will only help speed up the whole process. You can also do further customizations to the Gulp build process or switch to use another build tool.
Integrate with a 3rd Part API
Lastly, if your plugin works with other API’s this might be a good starting point to make 1 seamless flow for all data both on the site and coming in from the API(s) that your plugin communicates with.
Share Your Work!
Have an example project you have built based on this?
Let Zac know and we will feature it here!
Previous SectionNext Section