Building Quartz – Now With Full Transcript

Josh Kadis is the web applications technologist at Quartz. At our August Big Media Meetup, he gave a short “flash talk” on building qz.com on WordPress, which we’ve shared here and republished now with the full transcript below. Quartz just celebrated its one-year anniversary, and you can learn more about it by reading our case study here.

See Josh’s slides here.

 

My name is Josh Kadis, I work for Quartz, which is a business and economics site from Atlantic Media, which is the publisher of The Atlantic. We launched in September last year, and our most recent numbers for July were about 5 million uniques (views). My role at Quartz is I do the bulk of the WordPress work and then I’ve also been heavily involved in building the Backbone application that runs the front-end of the site.

If you haven’t seen Quartz, it looks like this. It’s a responsive web app, WordPress backend, publishes on JSON API, that gets picked up by the backbone front-end and the bar across the top under the word Quartz – that expands and that’s how you navigate between different sections and within a section you can navigate by scrolling up and down in the column on the left which we call the queue, or in the “item well”, which is the main content area on the right.

So the basic architecture is that Automattic and the VIP team host our WordPress installation, the Backbone files and our CSS and some other Javascript kind of stuff are hosted on the same CDN that’s used by the rest of Atlantic Media, which is like theatlantic.com, theatlanticwire.com and other non-WordPress sites.

WordPress publishes the JSON API, and we get all the backend post authoring and media and we have some custom backend stuff, like a post type that allows us to publish the newsletter through the MailChimp API from within WordPress.

We have a self-hosted system for reader accounts, which is what you would use for the commenting feature that we recently rolled out which is more for annotating individual paragraphs within a post, and then managing your subscription to the newsletter The Daily Brief and that kind of stuff, so that’s also WordPress.

We’ve actually found that the comments that come back are less awful because people get to the specifics of what they want to say about this specific paragraph instead of a general “you suck”. That’s kind of nice.

We have this division of labour between WordPress and backbone where WordPress handles what you would expect: generating the basic HTML markup which kind of gives the page the basic structure and is useful for search engines. WordPress publishes the JSON API, and we get all the backend post authoring and media and we have some custom backend stuff, like a post type that allows us to publish the newsletter through the MailChimp API from within WordPress.

The order of the posts you see on the homepage is not initially chronological, it’s manually ordered by the editorial staff, that’s the ‘Top’ post. So there’s a plugin that allows them to do that with a drag and drop interface from among the recent posts. Backbone also handles what you’d expect on the client side: fetching data from the API, deciding where and when to render it on the page, reflowing based on the device and on the screen size. We’re doing some offline reading with local storage and all of the annotation’s functionality is contained within the Backbone app and the entire thing can be turned on and off without even touching WordPress.

The URL and getting Backbone and WordPress to interpret the URL in the same way is really where the two things come together. The whole site relies on that or else the front-end and back-end are out of sync.

So we have these two things and where do they really intersect? It’s here: The URL and getting Backbone and WordPress to interpret the URL in the same way is really where the two things come together. The whole site relies on that or else the front-end and back-end are out of sync. So just to kind of quickly walk through it, if you haven’t written a Backbone app before, the router is the foundation of it, it essentially determines how the URL is parsed and then triggers a series of events that come one after another and ultimately result in stuff showing up on the page.

Good URL design is really a key to what we’re doing.

To work, the router reads the permalinks, and Backbone has some kind of build in syntax for how you read a permalink and decide what’s a variable within that and what’s a key. The permalinks come back to WordPress to run off the rewrite rules, and the rewrite rules run Quartz.

Good URL design is really a key to what we’re doing. So something like this: http://qz.com/107970 is the URL of the most viewed post of the history of Atlantic Media, it’s about bees. This is something that doesn’t have to run through a URL shortener, doesn’t get redirected, both Backbone and WordPress will understand this URL and parse out that single ID in the exact same way. Here is a little bit of code from the router, grossly over simplified.

Basically the router initializes, you give it this regex, it looks for these core sections: ‘Top’ – which is, I explained, is the manually ordered, “here’s what’s important right now” segment of posts. ‘Most recent’ is the latest one, ‘Popular’ we kind of calculated near real time using Chartbeat, ‘About’ is some static pages.

When the router recognizes one of these keywords from the regex and the URL, it triggers the core function which passes the particular one to this event which then gets triggered and a whole bunch of other stuff happens that results in a bunch of posts as you scroll through.

When you look at the WordPress theme, if you see rewrite rules, you would kind of recognize the regular expression: Top, Latest, Popular, About, and for both the front-end query, which is this first set of rewrite rules and then the API they both resolve to pass these two parameters, these two query variables to WordPress. API = true or false and then request = one of these things in this array.

For handling those two variables, we add_rewrite_tag request, we hook into query_vars and add API and then WordPress knows to look for those two things so that when the parse_request action comes around, we are able to, and in my oversimplification, I left out an if statement here, then we can fire up this qz API class and kind of pre-empt the main WordPress loops and that’s how we get JSON back without really needing to run through anything else that WordPress would do.

So this kind of enables us to go from a regular URL with a parameter like JSON tacked onto the end which is how in a lot of situations if you were building a JSON API on top of WordPress, you might do something like this and get back basically the same data structure that’s in the WordPress post object.

For us, we haven’t done that for a couple of reasons. We’ve gone with a custom API for clarity’s sake, being able to put all our endpoints inside API and then on the server side, we want to do all our processing of the meta data before we return it through JSON or else all that work needs to be done and that slows things down.

So for example, we’re able to return the URL to multiple sizes of the same image which we’ll ultimately be able to serve differently using this new SRC set attribute for different screen resolutions, stuff like that that is not necessarily apparent if you’re just reading the meta data straight out of the database.

So the Backbone side touches WordPress in a couple of other places. One is we need a way to keep track of version numbers, because they really are so separate. When we load the current Backbone version, it’s a different actual number than the WordPress version, so WordPress needs to know what’s what and keep one step ahead of the VIP team, really, because we put in a deploy to them, and we’re not sure when it’s going to come back so we want to know that as soon as it does, we’re ready and we’ll load the correct version of the application.

We’re also sort of separate from WordPress but still in Automattic, we’re using an Akismet API for kind of like profanity and spam filtering when annotations come in.

So in a second I’ll show you a quick shot of a plugin that enables us to do that. We’re also sort of separate from WordPress but still in Automattic, we’re using an Akismet API for kind of like profanity and spam filtering when annotations come in. Previews get pretty complicated in fact, with the Backbone app because it doesn’t know if the person is logged in to WordPress or not, it doesn’t know what permissions they have, so we need to sort of render some special Javascript in the markup that comes back initially from WordPress in order for Backbone to pick up that preview.

And then finally, there’s something that we’re working on that David in the third row in the red shirt is going to be working on soon, which is kind of figuring out how to keep the WordPress post templates and the underscore templates that Backbone uses, keep those in sync. It’s kind of hard right now, and ultimately doing a better job of that will allow us to load more of the application initially from WordPress, instead of having to process it within the browser in the Backbone app and then put it on the page.

So, this is a quick look at the plugin that manages the version number, essentially it allows you to stay on this auto-pilot mode that kicks whichever version is higher between the constant that’s set in the theme that can get committed to VIP or a setting that’s saved in the options table that you can set here so if for example you have a new version in the Javascript application that’s not making any adjustments to WordPress, we can just update the setting here in the plugin as soon as we put it on the CDN and we’re ready to push it.

But if we have stuff that’s sort of related to some changes in the WordPress theme and some stuff in the Backbone app, we put the Backbone app up first change the constant in the WordPress theme to sort of point to that new version of the Backbone application and as long as we’re sort of incrementing the number, the plug in will kick the higher number as soon as the new code with the constant is live on VIP.

This is just a quick look at annotations. You should all check it out, it’s really really nice. The responsive aspects of it are really cool and it’s just an interesting way of diving into the content. We’ve actually found that the comments that come back are less awful because people get to the specifics of what they want to say about this specific paragraph instead of a general “you suck”. That’s kind of nice.