Choosing a stack

With this set of tools we could focus on choosing a modern stack and creating an agile workflow to release small and frequent iterations of the website code.

Creating the theme

The site is basically a Wordpress theme based in Sage 9. We picked Laravel + Blade templates to build the controllers and the views and ES6 + Webpack + Vue.js to build the frontend components.

Sage comes with very good defaults, and the provided controllers and views are flexible enough to implement a basic theme and to be extended very easily. Controllers defined remember to the default pages in a common Wordpress theme: home, page, single, single article, single post…

For each controller class exists an associated template. Templates are divided also in layouts, views and partials:

• the layout of the application contains the common skeleton and structure of the pages. By default there’s just a single layout which just includes partials and calls the yield method, but new layouts can be defined to fit your application requirements
• the views are just blade templates that will be inserted
  in the layout. Each controller exposes instance variables that are available in the template.
• partials are snippets of templates that can be inserted and reused across the whole site. They accept local variables as arguments.

functions.php

This file deserves special attention. Those who already known Wordpress will be familiar with this file. functions.php is a special file in Wordpress where themes can interact with Wordpress internals, such as the The Loop, filters or rendering callbacks.

Once we have finished the project we can see that this file contains a few customizations that can’t be added in other parts of the project, Wordpress is not yet designed to implement customizations in a different way than this.

Good thing is that any special behaviour can be located in that file. Bad thing is that the file is more than 600 lines, and despite well structured code and comments, things can be a bit confusing.

Introducing projects entity

Just to demonstrate how flexible Sage is, we are going to describe how we introduced the entity projects in the theme.

In the ICIJ, every article is writen as part of an investigation. We named the investigations projects. Projects are a custom post type with special attributes created with Advanced Custom Fields.

In functions.php we had to:

• rewrite the URLs to the new structure /investigations/{investigation name}/(pages|articles)/{slug}
• add a filter to fetch the investigation from the URL parameter and search the article inside that investigation pool
• implement a new project controller to implement the home of an investigation together with a Blad template
• amend posts controller to obtain more articles from the current investigation in a new method

Project deployment

To start building the theme we had to setup a development environment. The idea behind Trellis and Ansible is to use the same roles for development, staging and production, so it comes with these three environments defined.

When you run development environment in your computer, you’ll be creating a Vagrant instance running Ubuntu. Internally it will install php, nginx, node.js, postgres or mysql and the rest of dependencies automatically. It won’t be any different with the staging or production environment except the domains, and the SSL certificates.

A good thing from Trellis is that roles will be part of the project code, and although they will work with the defaults you’ll be able to define and re-define small pieces, such as variables and settings.

We had also to define how the inventory of remote servers was obtained, due to the elastic nature of the production environment. Thankfully Ansible is very flexible and it can obtain the servers even from a remote JSON API.

Together with the provisioning roles there’s a deployment role implemented using Ansistrano that can be executed in any environment and will run dependencies and update the code. It also offers rollback capabilities.

Conclusion

This post is a quick overview of Roots tools to build Wordpress sites in a modern way. Many concepts and good practices from other frameworks have been applied to make the development experience nice and robust:

• Bedrock organizes Wordpress code in a way that developers deal with Wordpress as an external dependency that can be updated without affecting your themes.
• Sage changes Wordpress theme development process, and provides MVC code organization, with Laravel and Blade, and introduces a modern frontend stack with ES6 and Webpack.
• Trellis simplifies the creation, configuration and deployment of the different environments of the site, using Ansible and Ansistrano roles