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

There are many ways to use the power of JavaScript with WordPress.  When the REST API first came out into the community as a plugin one of the first things people thought about was creating new admin interfaces for WordPress. I think there is a big idea here, a fundamental shift that could happen for the whole WordPress dashboard.

Re-Imagining Admin Dashboards

I wrote about this idea in my article, “The case for a new WordPress dashboard”, however what if you could just re-imagine the dashboard for 1 plugin or theme settings page? This is what the WordPress Admin JavaScript Boilerplate is for.

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

To work with the boilerplate, a good knowledge of both the REST API and JavaScript is going to be necessary. A fundamental or working knowledge of React will be helpful, hover I learned React mostly while just writing this boilerplate, so the learning curve will be minimal.

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

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.

The gulp command will by default also run the watch command which will automatically build JavaScript and compile scss files when you modify and save.

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

Getting Started

One thing you need to know about React, is that while something like AngularJS uses HTML templates, React has HTML inside of jsx files which compile into JavaScript. This may sound confusing, and at first it will be. However I have created the gulp commands to build out the JSX properly so that modification to the JSX files should automatically build and run as needed.

Customizing Components

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.

 

Project Ideas

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.

It also allows for a lot more speed, as the JavaScript files and HTML files are quick to be cache’d and loaded.

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!