Build your own Dashboard on the Trello API
Once upon a time someone created a Trello board and invited their team to it. Over time they added cards, moved old ones and archived those they'd finished. One day they started adding labels to their cards ('Bug', 'High priority', 'Blocked'). Their use of Trello grew as the team grew, their project grew and others started using Trello. As the team's use of Trello expanded, managers wanted to get updates on how the team was doing. Are we closing as many bugs as we opened? What's our velocity? How about a cumulative flow diagram? There was much scratching of heads and "well I suppose we could...". Until finally one intrepid developer took a look at the Trello API. You are that developer, and here is where you start building your first dashboard on the Trello API.
Wasn't that a nice story? :) It's not too far from what I've seen at a lot of the companies I've been talking to while building Corrello - Dashboards for agile teams using Trello. Today we're going to build a very simple dashboard which will show a count of cards with each label. The code is all available on Github but I'd encourage you to follow along as we build your dashboard here. It really is extremely simple, but it also shows the key concepts you need to learn about the Trello API to build anything you want on top of it.
First off - The Trello API
Trello have created a fantastic API. In fact, their own mobile apps are built against their API. They did this to show that they aren't holding anything back from their public API. You get full access to everything their own apps do. You can make 100 requests every 10 seconds which is pretty good. We'll be able to load the information we need for our dashboard without making people wait. If you were caching data locally obviously things would be even faster.
Trello have also published some very good Trello developer documentation which is worth bookmarking for future reference.
Our blank dashboard
If we're going to have an empty dashboard, it may as well be a good looking one! So let's get bootstrap. I'm using v3 but go with whatever you're happy with. You will need to host this html file somehow. Use whatever you're happiest with, we won't be writing any back end code so it really doesn't matter :)
Connecting to the API
Next we need to connect to the API and authenticate a user. The first thing to do is get your app key from here. We will need the key field in the next step where we add the client.js file from Trello to our dashboard, and authenticate our user.
If you look at where we are loading the client.js file from api.trello.com and you will see we pass in a parameter key=[AppKey]. Take [AppKey] and replace it with they key you got for your app.
If you reload your page you should be presented with this popup (if it doesn't appear check that your browser isn't blocking popups).
This shows we're asking for read permission only and that we want access forever. You can choose to get write permission as well when you call Trello.authorize(). Don't worry, due the the magic of local storage you will only need to authenticate once :)
Selecting the board to report on
Now we're authenticated we can access the Trello API as the user and start loading the data we want. We'll start by loading all of their boards and asking the user to choose one for us to create a dashboard for. This is where things get a little more interesting.
There is now a select element which we will put our boards in and a loadBoards() function which gets the boards for the current user from the Trello API.
All the loadBoards() function does is call Trello.get() with the path we want to load and tell it to call loadedBoards() when it's done. All resources in the Trello API are structured in the same way, so if you want to load a specific board you ask for '/boards/[id]' where [id] is the id of the board you wish to load. To get the lists for a board you request '/boards/[id]/lists'. What we're requesting here is all the boards the currently authenticated user can see '/members/me/boards'. Simple right?
Getting the counts for the labels
Not long to go now, but we've already connected to someone's Trello account and loaded some data for them. Now we want to let them select a board to report on and get the labels for that board along with the counts of cards with each label. You've probably already guessed that we need to call '/boards/[id]/labels' to get the labels we are interested in.
The JSON we get back from that request actually gives us all the information we need! Including the label name, how often it's used and the colour to use.
Get the full final version of the code here.
What next?
That's it. Your dashboard may not be anything too fancy (yet) but you now know how to get whatever data you want from the Trello API. If you want to check out the full documentation for the API head here, and if you want to see what is returned from any request checkout the sandbox. You could take your dashboard above and extend it to add the features you want, or move some of the code server side and start storing data in a database. It would be pretty simple to load the cards for a board and display the actual cards linked to each label if you wanted to.
Want a more advanced Dashboard?
If you're looking for something more comprehensive without all the coding (where's the fun in that?) do check out Corrello. It's got cumulative flow diagrams, burndown charts, counts of bugs etc. and lots more.
