Using React and Laravel Lumen to Build a Company Status Board

A few months ago I bought an Apple Cinema display to use with my Macbook Pro. My plan was to use both screens, my Cinema display as my primary screen for work and important apps and my MBP as a secondary screen for less important background apps like Spotify. It quickly became clear that I almost never used the secondary screen on my MBP as I had more than enough space on my Cinema display. At about the same time I decided that I’d quite like to dip my toes in the wonderful world of React and learn what all the hype was about.

So I came up with the idea of building a small status board web app that I could leave in my secondary display that would give me a quick overview of everything I needed for my work. As I wanted to learn React, it made sense to build a single page web app powered by React components and I decided that it would be simple enough to power the app using Lumen as a small backend API.

At Delicious Brains there are three apps we use that pretty much power everything we do: Slack for team communication, Help Scout for giving our customers support and GitHub for building our software. I didn’t want the dashboard to be crammed full of graphs and useless information, I just wanted to be able to see helpful information at a glance. So I decided the three elements of the board would be:

  1. A Slack “graph” showing who was online and what timezone they were in
  2. A list of our Help Scout mailboxes and their statuses
  3. A list of recent GitHub notifications

Before we get into the details I’ll just mention that this whole project is available on GitHub so feel free to browse through, borrow, and steal code as you wish.

Building the backend API with Lumen

The backend API has two important jobs to do. It has to authenticate our web app with the external services (using OAuth) and it has to query the services for the relevant data and cache the responses. One of the great things about working with open source projects is that, chances are someone has already done most of the leg work for you, and as this was a quick side project I relied heavily on third party libraries in the API.

Slack and GitHub both have OAuth authentication endpoints. That means you need to create an “app” on both of their services (Slack and GitHub) and then use OAuth to authenticate with your new apps. I decided to use The League of Extraordinary Packages OAuth 2 Client to handle all of the OAuth autentication code (see AuthController.php). Help Scout doesn’t have OAuth endpoints so I just had to use an API key.

It’s worth noting at this point that the place to put all of the OAuth app details and API keys is in the Lumen .env file and not in the actual code repository. This makes the code more secure, reusable and far easier to maintain.

Next I had to create some API endpoints that React could use to load the data into the components. These endpoints would query their respective services and cache the response as required. You can see how I did this in the ApiController.php. I decided to abstract out the process of actually querying the respective APIs by creating some Util classes that handle the API queries and also return a single OauthTokenError if there was an authentication issue when querying the service API. Again these Util classes made use of third party libraries: Frlnc/php-slack for Slack and KnpLabs/php-github-api for GitHub. For Help Scout I just used cURL to query their API.

That’s it for the backend API. If you’re wondering at this point how to add a service that I’ve not included, the process would look something like this:

  • Add a new route in routes.php
  • Add the corresponding method to ApiController.php
  • If the service uses OAuth for authentication you’ll need to add a method for it in AuthController.php (remebering to add the corresponding /auth route in routes.php)
  • Create a Util class to fetch the required data that can be used in your ApiController.php method.

Building the frontend with React

On to the “fun stuff”. If you haven’t heard of React yet it is a framework built by Facebook for building modern user interfaces. The idea is that while libraries like Backbone, Ember and Angular provide a framework for all aspects of a frontend Model-View-Controller application, React only provides functionality for the “View” part of a MVC application and it doesn’t care what you use to power the rest of your application. React has gained huge popularity and momentum recently as the main player in the “building UI’s in JS” space and I decided to use it to build the UI for our app.

There are another couple of libraries I needed to make use of to make our frontend work. I decided to use good old jQuery to query our API using AJAX, Moment.js to parse timestamps and output relative time strings, Normalize.css to… well… normalize our CSS and Font Awesome to provide our icons.

As this was going to be a single page application, first I needed to create the single page that would be output by Lumen. This meant creating a single view whose sole purpose is to load all of the JS and CSS dependancies. As this was going to be a small web app that I ran on my local machine, I wasn’t worried about optimisation, but in production a lot of the JS and CSS files would typically be concatenated and minified using a build tool.

The structure of the JS is as follows:

  • bootstrap.js – Creates the global App variable that we will use to hold our application objects, functions and React components. It also holds any “utility” functions we might need.
  • react/error.js – A global error component that handles our OauthTokenError that we spoke about above.
  • react/[slack|helpscout|github].js – The individual service components.
  • react/app.js – This is where the ReactDOM.render() method goes that ties our app together.

The composition of the React service components are as follows (using github.js as an example):

loadNotificationsFromServer: function() {
    this.setState({loading: true});
    $.ajax({
        url: this.props.url,
        dataType: 'json',
        cache: false,
        success: function(data) {
            if (typeof data.error !== 'undefined') {
                this.setState({error: data.error, loading: false});
            } else {
                this.setState({data: data, loading: false});
                setTimeout(this.loadNotificationsFromServer, this.props.pollInterval);
            }
        }.bind(this),
        error: function(xhr, status, err) {
            this.setState({loading: false});
            console.error(this.props.url, status, err.toString());
        }.bind(this)
    });
},

The load{Data}FromServer function uses jQuery’s AJAX functionality to ping our backend API for the data it requires. We store any data and errors in the component’s state so we can use it later. Note that we also use setTimeout here to poll our backend API to refresh the data at a regular interval. The pollInterval is a component property that we define in app.js.

getInitialState: function() {
    return {
        loading: false,
        error: null,
        data: []
    };
},
componentDidMount: function() {
    this.loadNotificationsFromServer();
},

We make use of React’s getInitialState function to setup the initial state of the component and the componentDidMount function to kick off our initial call to the API.

render: function() {
    var loading;
    if (this.state.loading) {
        loading = <div className="box-loading"><i className="fa fa-spinner fa-spin"></i></div>
    }

    if (this.state.error) {
        return (
            <div className="github-status box box-has-error">
                {loading}
                <App.Views.Error type={this.state.error.type} data={this.state.error.data} />
            </div>
        );
    }

    var notifications = this.state.data.map(function(notification) {
        var typeIcon = <i className="fa fa-exclamation-circle"></i>
        if(notification.subject.type == 'PullRequest') {
            typeIcon = <i className="fa fa-code-fork"></i>
        }

        return (
            <tr key={notification.id}>
                <td className={'type type-' + notification.subject.type.toLowerCase()}>{typeIcon}</td>
                <td className="name"><a href={notification.repository.html_url} target="_blank">{notification.repository.full_name}</a></td>
                <td className="title">{notification.subject.title}</td>
                <td className="time">{moment(notification.updated_at).fromNow()}</td>
            </tr>
        );
    });
    return (
        <div className="github-status box">
            {loading}
            <table className="github-notifications">
                {notifications}
            </table>
        </div>
    );
}

Finally we use the render function to actually create the output for our component. If there is an error we simply return the App.Views.Error component which is a good example of how to make use of modular components. You’ll have noticed by now that components can contain multiple components that are either defined elsewhere, or are created at runtime, such as the {notifications} list above. As you can see I make use of the map function to create a list of table rows, in this case. The table row could easily be split out into it’s own component if necessary. Finally the render function returns the structure of the JSX that we will use for our component.

I’m not going to go into the intricacies of React here, suffice to say you should check out the documentation and learn it for yourself. I’ll just point out that one “gotcha” to look out for is that JSX uses className and not class.

Putting it all together

Now that we have both the backend and frontend in place, it’s time to set it up and run it. I personally use the status board on my secondary screen but there is nothing stopping you displaying a similar dashboard on a dedicated monitor on the wall of your office, but that’s entirely up to you.

As MAMP is already running on my machine it made sense to use it to run my status board. I simply set up a new virtual host running PHP >= 5.5.9 called statusboard.dev. If you are setting up the repo yourself you should follow the instructions in the readme. I recommend using Fluid to make it feel more like an “app” and add it to your dock. Point fluid to your web address (statusboard.dev) and add an icon if you want.

If you have any comments or suggestions I’d love to hear them in the comments. I’d especially love to hear if you make use of the status board anywhere and what customizations you make to it.

About the Author

Gilbert Pellegrom

Gilbert loves to build software. From jQuery scripts to WordPress plugins to full blown SaaS apps, Gilbert has been creating elegant software his whole career. Probably most famous for creating the Nivo Slider.

  • Jon

    Awesome. I’ve been wanting to play with Laravel _and_ React on something just like this, to expand my skills with both. Very cool.

  • Ulrik

    I had trouble getting oAuth working for slack. I had to manually add scope to the request url.
    Should it authenticate without me adding the scope ? just got an error message saying “OAuth error: blank_scope: Requested scopes cannot be blank”

    ps: Great writeup ! 🙂

    • I haven’t had that issue but Slack have maybe changed their API since I made the status board. Will check it out.

  • Varsha Jadhav

    As per the article here, I’ve Lumen as a backend that takes the input values from React as a frontend. Even the response from Lumen is in json format and it’s getting on the client.
    I’m getting the response on the URL defined in the form’s action which is the server’s route in json format as follows.

    {“name”:”Aniruddha”,”age”:”22″,”maths”:”100″,”science”:”100″,”english”:”100″}

    But how to get and display this data in my React. As the response is on the URL of Form’s action, and the URL is not defined by React.

    Is there any way to get the response from Lumen for display the response in React?

  • Thanks Gilbert for this nice tutorial. I am going to build an Android app. I had never use the github oAuth, Lumen and react. I am familiar with Laravel and created few apps and projects using this. So it is easy to use Lumen for me.

    It would be very help full if some one can provide me some good links, from where I can understand the working of oAuth and react.js. I need to start working on a project that have a small back-end (about three pages, need on react.js) and a small Android app for creating and displaying the stuff.

    Thanks in advance for any help.