Bowst Team
Show and Tell is Over
Welcome to the Drupal 8 Theming series finale! Over the past few months I’ve written four posts outlining the ins, outs and what-have-yous on theming in the latest release of Drupal. If you’ve been following along, then you know we’ve covered a lot of ground together. We began with the basics of defining a theme, moved on to how to structure your styling with SMACSS, and then I gave you a little insight into the Twig tempting language; finally, we got some action in the most recent post about JavaScript integration in D8.
Up until now there’s been a whole lot of show and tell — that’s fine, but at Bōwst we know that the best way to learn is by doing. With that tenet in mind, our very own Heather set about creating a boilerplate that you can download and customize to make it your own. We’ll delve into that momentarily, but first please allow me to show Heather the same courtesy I gave our pal Fluffy and introduce her.
Meet Heather
Heather is many things: a great friend, a team player, a cat-lover, a gardener, a cupcake aficionado and, here at Bōwst, our lead front-end developer. It’s Heather’s job to collaborate with designers and act as a bridge between our clients and development team to ensure that the sites we create match the design pixel for pixel and exceed expectations.
If we had to choose a spirit animal for Heather, it would be a hawk (albeit a friendly, thoughtful hawk that would never hurt a kitten) because she can spot a discrepancy in design and development from a mile away. In short, Heather is meticulous and her battle-tested process has delivered impeccable results time and time again. In addition to sharing the boilerplate theme she’s developed, she’s also outlined her process, and that’s what I’ll be relating to you in today’s post.
Bōwst Boilerpl8
Now that you know a little more about Heather, let’s discuss her theme. Bowst Boilerpl8 (BBpl8), which we desperately would like to call BB8 but can’t due to copyright law/infringement, has a lot going on. It uses the Drupal Bootstrap subtheme and comes loaded with styles, JavaScript, Twig templates, the necessary Drupal modules, and a gulp build system complete with the necessary node modules for compiling CSS and JS.
Get Ready
Download
The first thing we’ll need to do is download the theme to the appropriate directories in your Drupal 8 project. So the modules will go in the “themes/custom/bowst8/node_modules” directory, the Drupal Bootstrap subtheme will hang in the “themes/contrib” directory, and “bowst8” (which is the theme itself) belongs in “themes/custom”. All of the directories in bowst8 are already organized properly, so no worries there.
Settings
Settings.local.php
The next thing we need to do is configure our local site for development. For this bit, I’ll defer to an incredibly well organized and informative presentation, Thoughtful Theming, by The Great and Powerful JP McNeal. If you’re following along in the slideshow, we’ll skip ahead to slide 11 and go from there.
First, set up the “settings.local.php” file. To get there, from your main project directory to “docroot/sites” and open the “example.settings.local.php”. Copy that file, rename it “settings.local.php”, and deposit it in “sites/default”.
Second, in the “sites/default” directory, open the file “settings.php” and uncomment lines 689-691 to ensure the local settings file is included as part of Drupal’s settings file.
Drupal Caches
To configure Drupal’s caches, back in “settings.local.php” uncomment line 39 to enable the null cache service.
Next, disable CSS and JS aggregation by making certain that the values on lines 52 and 53 are set to “false”.
The last part of Drupal cache configuration is to disable the render and dynamic page caches by uncommenting lines 67 and 76 in “settings.local.php”.
Twig Cache
With the Drupal caches successfully configured, we’ll move on to disabling the Twig cache. Go to the “sites” folder and find the “development.services.yml” file. Then add or configure the following code block to disable the cache.
Rebuild
With the setup complete, in the terminal run “drush cr” to rebuild caches and we’re good to go.
Rename & Replace
In the yml, config, and system files, find all instances of “bowst8” in the “themes/custom” directory and change them to the name of your theme, including the bowst8 directory itself. Then override the “logo.svg”, “screenshot.png” and “favicon.ico” files with images for your theme.
Install
In the Drupal admin area navigate to the “Appearance” tab and install your new theme. Then, from the “Extend” tab, install the contrib modules that came with the theme. Please note that you may not need all of the modules that are included. We advise learning a little about each one and only installing those that you intend to use. Node packages can be installed from the terminal in your theme’s directory using the “npm install” command.
Get Set
With our theme files successfully downloaded and installed, it’s time to go back to Heather’s expertise and begin thinking about the styling process. In her Git repo for this project, she’s provided a number of helpful tips; I’ll be expanding on them and provide examples.
Plan
As I mentioned earlier, Heather is meticulous. She’s a planner and an organizer and as such the single most important piece of information she offers in her Git repo comments is PLAN AHEAD.
Map out the components and pieces of your Drupal site BEFORE you begin building (blocks, views, nodes, etc). Having a solid plan will ensure that your site build is mostly correct the first time and that you won’t need to make any major changes to structure or functionality after the initial build is complete.
While conceptualizing, do whatever you have to do to make sure that your plan is clear in your mind and effectively communicated to your team. Sometimes, if a site is large or particularly complex, we’ll even print out our designs page-by-page, pin them up and annotate them by hand, just to make absolutely certain that everyone is on the same page and, most importantly, that we like what we see. I know what you’re thinking…Relax, we recycle.
Style
SMACSS
In terms of organization, we are inspired by the SMACSS methodology and have used it as a base while forming a similar methodology and folder structure that we feel works best for Drupal 8 projects. If you’re unfamiliar with SMACSS, check out our blog post on that very topic.
Variables
This child theme is built with the Bootstrap framework (version 3.3.7), which contains variables that affect the global styling of your site. Once you have approved designs in place, the next thing Heather recommends is going through those designs and identifying consistencies. Look at headings, colors, paddings, font styles, etc. and apply those values to the appropriate variable already in place. You should always strive to achieve your desired styles by overriding an existing Bootstrap variable, rather than creating new variables and selectors, especially where global/default elements or Bootstrap components are concerned.
Responsive Design
Bootstrap is based on a mobile-first approach. Your default styles should be for mobile devices and all styles for tablet and desktop devices should be encapsulated within media queries. Those media queries should be placed directly below the main sections they pertain to, not jumbled together in a separate file.
Component-Styles vs Components-Drupal Folder
The component-styles folder is where your global reusable styles live. These are styles that can easily be used throughout the site by simply adding their class name to an element and are not hinged to any drupal components. Examples of these are backgrounds, forms, and button styles. The components-drupal folder is for styles that are just the opposite. These styles are fully bound to particular Drupal components, such as views and blocks.
Partials
Partials are sass files that contain styling particular to a certain area of the site or that contain global styles; these styles are then aggregated into a minified CSS file. For example, I might have a sass partial for the particular page or section of a page.
The child theme comes with several sass partials already in place, all with helpful at the top of each page describing the purpose and usage of each file. We strongly recommend reviewing each partial so that you can get a good idea of what goes into each and how you should organize any additional partials.
Go
Regions
With your base styles in place, it’s time to start building. Drupal regions are declared in your info.yml file. Your theme includes all of Drupal’s most used regions out-of-the-box, but you can choose to add or delete regions as you see fit. Just keep in mind that any regions you change, add or remove in your info.yml file also need to be reflected in your “page.html.twig” template, which can be found in the “templates/system” directory.
Header & Footer
Next come the header and footer. Alter the page.html.twig HTML as necessary to suit your needs. The main navigation is based on Bootstrap’s “Navbar” component and augmented with a Drupal menu. The styles pertaining to these items are in the appropriate sass partial files in the “sass/layout” directory. In the footer, double check that the copyright “original_year” variable is correct.
Keep Going
The rest is up to you. Keep building out your site with blocks, views, paragraphs, additional content types–whatever your heart desires, let your conscience be your guide, and I can’t think of a third Disney-themed motivational statement, but you get the idea.
With our next iteration of our boilerplate we hope to utilize Yeoman and Drupal Profiles to rapidly kickstart new sites. Yeoman will speed up the installation process by getting our folder structure in order (making many of the primary steps above obsolete) and Drupal Profiles will inject the proper base configuration settings in our D8 project. Stay tuned!
