Streamlined Drupal Project Setup and Theming

by Aaron Froehlich and Jeff Amaral

Building upon Alexandra’s great post, Maintaining your Sanity while Theming in Drupal, we decided that it was time to standardize the process of creating new Drupal projects so that we could be up and running in minutes with a new site that is organized the way we like it, includes useful profile and theming conveniences, and leverages Sass and LiveReload right out of the box. Meet Drupal Streamline, a convenient, hassle-free starting point for new Drupal projects.

Here's a quick demo:

Initializing a new project

  1. Download a copy of Drupal Streamline to your system and expand the zip file
  2. Visit the project root in your terminal and run $ bin/init.

The init script will download the latest copy of Drupal 7 and some commonly used modules, ask a few questions, and then create a starter install profile and theme ready for installation on your dev machine. It’ll even initialize a new git repo if you want.

Install your dev site

You can now install Drupal however you normally would. For example, you might create an Apache <virtualhost> pointing to the docroot/ directory and visit /install.php. When you do, you’ll notice a new install profile alongside the familiar Standard and Minimal. It was created by the init script and is intended to function as a ‘custom module’ where you can add miscellaneous bits of custom code to the .profile file and ‘migrations’, or update scripts, to the .install file.

Pro tip: Check out some of the many, fine, articles that show how to combine <VirtualDocumentRoot> and various clever DNS tricks to allow automagic development website creation just by creating a new directory in a specific location.

Ready to “themify”!

Now for the best part of Drupal Streamline (in our opinion, of course!) – rapid theming with instant in-browser preview!

First, ensure that you have Bundler installed and run:

$ bundle install

You only need to do this once per project.

From now on, streamlined theming nirvana is yours by running:

$ bin/themify

Refresh your browser so that you see a Browser connected message in your terminal, open the scss/base/_variables.scss file, edit the $brand color, and voila, you should see your site’s color refresh ‘automagically’.

We generally keep a text editor in one monitor and the browser in another and just hack away on our .scss files, peeking over to look at the nearly instant changes in the browser as we go.

To stop the themify script, just hit control + c in the terminal.

If your experience with LiveReload at this point is limited to the LiveReload app or browser extension, it may surprise you that neither of those are needed to get this setup working. Let’s dig in a little and see what’s happening here.

Sass, LiveReload, and Guard

If you aren’t familiar with any of these projects, that’s OK. Drupal Streamline is configured to get them all working automatically, but you should really read more about them if you’re interested.

The starting point for our setup is Guard, which simply watches for changes to files and can be configured to do something when they occur. It’s configured via the Guardfile in the root of the project.

The first ‘guard’ configures Sass (which extends CSS in nifty ways), and begins watching for changes to .scss files in the theme directory. When the .scss files are modified, they are compiled into a single, compressed .css file in the css/ directory of the theme.

The second ‘guard’ tells LiveReload to watch for changes to any .js and .css files and reload them in the browser if needed. Note that we use a non-standard LiveReload port to avoid conflicts with the LiveReload app.

Guard & LiveReload

Here’s how we can use LiveReload without the app or browser extensions:

There is a hook_init() implementation in the drupal_streamline_dev module which adds the livereload.js script (from guard-livereload) to every page if it is available.

bin/themify takes care of a few things for us:

  • It uses drush to enable the drupal_streamline_dev module (so that livereload.js is available)
  • It starts Guard
  • It stops Guard when quit (via control + c)

The Client_theme

Both the structure and content of our Sass files are still in flux, as we work to find the best balance between convenience, efficiency and usability. Out of the box, the site is responsive and the theme template supports first and second sidebars (based on the Stark theme). There are also some useful mixins in both the base/_grid.scss and base/_responsive-mixins.scss files, which allow you to target specific screen resolutions simply and understandably.

If you already have your own preferred grid system/starter theme, swapping it out should be relatively painless. Just be sure to update the theme name (if you change it) in both the Guardfile and profile’s .install file.

Forks and Pull Requests Welcome!

After years of cobbling together the bits and scraps of reusable code for each new project, we hope to finally have a solid starting point. Drupal Streamline is meant to be a foundation from which to build, and if you find it useful, please leave a comment, file an issue, or submit a pull request for additional features that you find yourself using in each new project. Thanks for reading!