Using COG & BLT with Drupal 8.4.0 (Pt. 1)

The Building a New Acquia.com series is a fascinating, and instructive, window into the eat-our-own-dogfood process that Acquia is going through on our way to a completely new redesign. Check out the series page to catch up with this multi-part epic. This post, by Acquia Senior Engineer Dave Myburgh, picks up from the previous, provocatively-titled entry by Kevin Colligan, Program Manager, Professional Services: Website Redesign: Everybody Has a Plan Until They Get Punched in the Mouth . Take it away, Dave. Hello everybody, and welcome to a new series of blog posts about using the Cog base theme with the brand new (as of this writing) Drupal 8.4.0. I thought this might be useful/interesting to many of you out there who are not familiar with Cog and are more used to frameworks like Bootstrap. I am one of you, so we'll be learning this new thing together. My intentions aren't 100 percent altruistic, because my team and I maintain www.acquia.com and when we switch that over to Drupal 8, we'll be using Cog as our theme. So these blog posts will be be a way for me to get ready for that as well as helping y'all. This first post will be relatively simple and will detail getting everything installed and ready to go for theme development. We'll get into the weeds more in future posts. I don't really know how many posts there will be in the series, but I figure there will be at least three in total. Cog can be installed as a standalone theme on any Drupal install, but it comes as part of BLT, so I'm going to be creating a new BLT project first, and then go through the Cog install steps. BLT comes with a bunch of tools that make working with your site much easier -- and it integrates with Acquia Cloud. Alright, let's get started.

Install BLT

Seeing as Drupal 8 is moving so heavily towards using Composer for everything, we'll be using it here too. It is yet another new thing I am learning, so you're not alone if it's new for you. You can install entire projects with it, as well as manage modules and themes (bye-bye drush dl). The first step is to create a new BLT project (change "cog-test" to whatever you want to call your project):

composer create-project --no-interaction acquia/blt-project cog-test

Then we ensure that the BLT alias is installed on your system:

composer run-script blt-alias

After all that has run, you can go into your project folder and you'll see a bunch of folders, along with the docroot folder where your actual Drupal install will be. In the blt folder, there is a project.yml file that tells BLT all about your project. You can edit some settings in there to customize your project as you like e.g. if you don't want to use the Lightning distro, switch the "profile" value to "standard" to get vanilla Drupal. You can also change the url for your local site, among other things. Once you're happy with all that, let's go ahead and enable our Drupal VM instance for this site. You might need to install things like vagrant beforehand, so check the DrupalVM documentation if you get errors trying to run the following command:

blt vm

This could take a while, so sit back and relax while it creates a new virtual machine based off Ubuntu 16.04. This will give you an environment for your site to run in, without needing to install things like Acquia Dev Desktop or MAMP or any other local LAMP stack. One thing to note is that Dev Desktop does not currently have Drush 9 or PHP 7.1 in it, both of which are recommended for Drupal 8.4. Once you're back at your command prompt, let's get the site installed and configured by telling BLT to run the setup:

blt setup

Now your site should be available in your browser at http://local.cog-test.com (replace cog-test with whatever your project name was). You can change that url in your blt/project.yml file if you want to. If you want to interact with your site via Drush, you can use the automatically-created Drush alias @local.cog-test, or you can SSH into the vagrant machine first (just like you're logging into the hosting server), by running vagrant ssh.

Create the Cog subtheme

Cog has a drush command that you can use to create the subtheme automatically, thereby avoiding editing and renaming a bunch of files. You can, of course, do it manually as well. I'll describe both methods here.

Drush method

vagrant ssh
cd docroot
drush en -y cog
drush cog 'mycog'
exit

Manual method

copy STARTERKIT folder from cog theme folder to docroot/themes/custom
rename it to mycog (or whatever you want to call your theme)
rename STARTERKIT.* files to mycog.* and also do that within the following files: theme-settings.php, mycog.info.yml, mycog.theme)

Once you've created your subtheme, you need to install the various tools necessary to work with it. Most notably gulp. Gulp can do a ton of stuff, but most importantly, it can compile SASS files into CSS for you. Yes, Cog uses SASS for managing CSS. Drupal seems to have adopted SASS as its language of choice, instead of LESS. The SASS files are structured in a SMACSS way, so if this is all new to you as well, you've got an extra bit of reading to do, I'm afraid. SASS is awesome and once you've understood the basics, it will make your life much easier. So the following steps will get Gulp installed so that you can compile the current SASS and have something to look at when you enable your custom theme a bit later (you will need things like nvm already installed, so get those in before you start these steps).

cd docroot/themes/custom/mycog
./install-node.sh 6.11.2
source ~/.bashrc
nvm use --delete-prefix 6.11.2
npm install
npm install -g gulp-cli
npm run build

That last command should result in a compiled CSS file for your site. You can now run gulp watch to monitor the SASS files and recompile the CSS file as soon as changes are detected. Let's go back to the website and enable the Cog theme (if you haven't already) and then set your new custom theme as the default. Note, if you can't login into the site, run drush @local.cog-test uli to get in. It might actually load up the site and log you in automatically, otherwise you'll have to copy the string it generates and paste it after your site url to get in. Take a look at the home page and you should have a rather blank black and white design with a bunch of blocks showing up. If not, double-check that you didn't miss any steps. You can also check BLT's and Cog's documentation.