Documentation

Installation

  1. Get the Files - Download or clone the repository into Drupal's sites/all/themes directory.
  2. Install Grunt Requirements - cd to the theme root and run npm install. This will install all the npm packages that Grunt needs to properly run.
  3. Enable and Set Default - There are a couple ways to enable themes in Drupal:
    1. Drush If you have Drush installed:
      1. Run drush pm-enable BaseBuildingBlocks
      2. … And then drush vset theme_default BaseBuildingBlocks
    2. Administraion UI - Navigate to admin/appearance/list and click "Enable and set default"

For more information on installing themes in Drupal, please visit the official Theme Installation documentation on drupal.org.

Theme Assets

less/css

BBB makes use of less, includes a Grunt script that compiles everything into one minified css file: style.min.css.

All css/less files are located in assets/css/, and there are a number of .less and/or .css files located in that directory:

  • /bootstrap/ - This directory contains all of the Bootstrap less files.
  • /fonts/ - Place all font files in this directory. By default, contains Ico Moon files.
  • /app.less - This contains all the custom styles for your app. You'll write most of your theme less into this file. At the top, you'll find a number of @imports, which allow you to use Bootstrap mixins and utilities within your less.
  • /drupal.less - Adds some default styling for Drupal elements (like forms, autocompletes, lists, etc).
  • /icons.css - Icon classes from Ico Moon. See the section on custom icons for more information.
  • /style.min.css - This is the file that everything compiles too.

Javascript

All Javascript in BBB is located in assets/js/ and organized as follows:

  • /plugins/ - All jQuery plugins should be placed in this folder. They will get picked up by Grunt and compiled into scripts.min.js
  • /plugins/bootstrap/ - Bootstrap javascript files are located in this folder.
  • /vendor/ - Includes non-plugin vendor javscript files, such as Modernizr.
  • /main.js - Put all of your custom theme js in here. By default, this includes an iOS orientation fix, but that's it.
  • /scripts.min.js - All javascript (excepting the js in the /vendor/ direcotry) is compiled/minified into this file.

Images

All images related to your theme should be placed in the /assets/img/ directory. The image folder contains an /hd/ directory for larger versions of your image files that can be loaded conditionally (media queries) for hi-res devices. All icon image files should be placed in the /icons directory.

Grunt

BBB ships with Gruntfile.js and grunt.js files, which allow theme developers to easily use less/js in their themes.

  • Installation - cd to the theme root and run npm install. This will install all the npm packages that Grunt needs to properly run.
  • Use - You can keep Grunt running while you are editing your theme so that every time you save a .less or .js file, Grunt will recompile/minify everything. To do so, cd to the theme root and run grunt watch. I often keep Grunt watching my code in a terminal tab seperate from the one I'm currently working in. You can alternativly run grunt every time you make changes that you want to compile/minify.

Templating

All of the template files within BBB are located in the /templates directory. Additional subfolders exist within the templates directory to help further organize template files. Below each template type in BBB by default is outlined. If you are adding new template files, please remember to clear your cache before expecting to observe changes (drush cc theme).

Content Type Page Temlates

BBB Adds support for content-type page templates. page--contentTypeName.tpl.php files can be used to customize layouts for specific content types.

404 Error Page Template

Do something fun with your 404 error page! :)

Include Files

Code that might be used in multiple template file should be placed in appropriate files within the /templates/includes/ directory. Especially keep this in mind if you have multiple content type page templates in use.

Block Templates

All block templates should be placed in /templates/blocks/. For more information about theming blocks, see the Drupal documention for writing block.tpl.php files.

Field Templates

Field templates should be placed in /templates/fields/. For more information about theming fields, see the Drupal documentation for writing field.tpl.php files.

Node Templates

Node tempaltes should be placed in /templates/nodes. For more information about theming nodes, see the Drupal documentation for writing node.tpl.php files.

Region Templates

Region templates should be placed in /templates/regions. For more information about theming regions, see the Drupal documentation for writing region.tpl.php files. A number of region templates exist by default in BBB.