Roy SivanThis Angular Admin Boilerplate gets you started building a plugin in the admin area that leverages Angular and the WordPress REST API.

Thanks to course advisor, Roy Sivan, for developing this boilerplate and 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.

Author Credit: Roy Sivan

An Overview of the Angular Plugin 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.

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 AngularJS boilerplate, currently written in Angular 1.x.

To work with the 2 boilerplates a good knowledge of both the REST API and JavaScript is going to be necessary. A fundamental or working knowledge of Angular will be necessary, however Angular has an easy learning curve.

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. 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 boilerplate. Both of these examples are plugins with a lot of functionality, primarily interacting with the REST API.

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.

The Angular Plugin 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 terminal or bash your favorite bash/command-line tool and run npm install and gulp. This will install all packages needed including Angular 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.

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 89 and 90:

 

add_action( 'init', array( $js_app, 'create_cpt' ) );
add_action( 'init', array( $js_app, 'create_book_content' ) );

 

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.

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 Angular Admin Boilerplate

This plugin is more a starting point, which is why I call it a boilerplate. It doesn’t have an easy to customize admin panel, because it is the admin panel(s). This is where knowledge of AngularJS comes into place.

Working with the JavaScript

Start by opening /assets/js/admin-app.js remember if you want to make changes you’ll have to have run gulp from your command line / terminal, so it will auto-build on update. This file is the main application file and I’ve tried to document via comments as much as I can so you know what does what.

Ui Router States

This is the routing for the app. It utilizes the ui-router project, which allows for a lot more functionality over the default AngularJS router. This is a single page application, but it has multiple views based on the URL. So while your browser isn’t refreshing, going to a new page, the view changes using AngularJS and ajax (to get the data). Notice the routes I have set up for book. Each individual view has a state like list or edit. The great thing about ui-router is you can use an anchor (a) tag to call on the state name, passing in any data, and get the desired page.

Filter to trust HTML

By default AngularJS won’t trust HTML and won’t render it. This will make things like your content show the <p>tag</p> even though you want it to render in browser. This is a filter for this, and it is easy to use. Any time you have content that will have HTML you want to render put into the container ng-bind-html=” your.content | to_trusted” the pipe ( | ) and to_trusted is an AngularJS filter, your content will run through it and spit out trusted HTML to be rendered by the browser.

AngularJS Factory

Factories or Services are a great way to reduce code by being efficient. I have created a Books factory which in turn will allow me to run functions like Books.query();which will run a basic query (GET) AJAX command to grab the latest posts. I have pre-configured all the default functions of the factory to pass through the nonce setup by a localized object for authorization. User authorization happens also within the API, but you may have a better API authorization solution. This is just a boilerplate to start from.

Controllers

Each controller in the boilerplate focuses on the specific functionality of a view. In reality multiple views can share a controller, which I do a lot when there is duplicate need with only minor changes. For example if you have multiple post types, you could still use the List controller, and determine by the $stateParamswhich cpt is currently being requested and set that as a controller default. For the back-end developers, that approach is similar to a PHP class with its own unique properties.Within each controller is the functions needed from getting the post or posts, to saving/editing. Notice in the Edit controller I have a few definitions for custom post meta, this data is returned from the API.

Working with the API

I have set up a lot of the basic framework for working with the API. Open the /includes/admin_custom_api.php file. Here you will fine how I have customized the api for specific needs. While in 99% of cases with a CPT you will not need to create custom routes, I wanted to show that it is very easy, and you may need to add custom functionality for your plugin. For example in my Stripe for WordPress a lot of the routes are customized since I need to communicate with the Stripe API using the Stripe PHP SDK, returning back a JSON object of the data received from Stripe. In Josh Pollock’s Ingot plugin maybe of the A/B testing data comes from calls to the API that aren’t posts, so the custom endpoints allow for custom database calls to gather and analyze the data in the database.

If you are using a CPT with some custom post meta for each post like my basic example, you do not need to create custom endpoints. Read the API docs and you can quickly learn how to customize the default responses, as well as make any CPT API ready.

Project Ideas Based on This Boilerplate

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.

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. Minification of these files will only help speed up the whole process.

Ultimately you can also give your users a better UI/UX feel that may seem more like the “sexy” SAAS tech companies than a blog website admin.

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!