Bourboneat WordPress Theme

I have created a new WordPress starter theme for building custom themes designed for WordPress version 4.1 and later. The theme uses the Bourbon Sass library and it’s Neat semantic grid components for a lightweight and modular responsive design. The header and footer designs were taken from the Bourbon Refills collection. Also included are IcoMoon font icons which can be easily updated using the IcoMoon app. Gulp’s build system is used to compile and minify Sass and Javascript modules into optimized CSS and Javascript. Clone, fork or download this responsive starter theme at GitHub and modify it as you wish into the theme you want.

https://github.com/jimfrenette/bourboneat

Features

New functions and feature enhancements in WordPress version 4.1 include:

Menus

The theme contains four wp_nav_menu’s, the main menu supports nested drop downs. Below are desktop previews of these responsive menus which collapse as needed on mobile screen sizes.

Main Menu (header.php)
Main Menu preview (header.php)

The footer contains three of the four registered wp_nav menus. Social links and terms menus are shown below. Also shown here above the footer is the pagination nav courtesy of WordPress – Twenty Fifteen. This is a new feature available in WordPress 4.1 and later.

Social and Terms Menu (footer.php)
Social and Terms Menu preview (footer.php)

Populating the social links menu is easy. All that is needed is a menu that contains custom links to social networks. The href attribute of the link is selected to determine which icon is rendered. Here is a snippet of the Sass that shows how this works:

// snippet from _nav-social.scss

a[href*="codepen.io"]:before {
    @include icon-codepen;
}
a[href*="dribbble.com"]:before {
    @include icon-dribbble;
}
a[href*="dropbox.com"]:before {
    @include icon-dropbox;
}
a[href*="facebook.com"]:before {
    @include icon-facebook;
}
a[href*="plus.google.com"]:before {
    @include icon-google-plus;
}
a[href*="github.com"]:before {
    @include icon-github;
}
a[href*="instagram.com"]:before {
    @include icon-instagram;
}
a[href*="linkedin.com"]:before {
    @include icon-linkedin;
}

This figure shows the footer menu setup:

Footer menu edit screen
Footer menu edit screen

This figure shows the terms footer menu setup:

Terms footer menu edit screen
Terms footer menu edit screen

This figure shows the manage menu locations setup:

Terms footer menu edit screen
Manage menu locations screen
UPDATE – October 7, 2015

The bourboneat theme recently passed the WordPress.org code review and approval process and is now included in the WordPress.org Theme Directory at WordPress – bourboneat – Free WordPress Themes.

Visual Studio MVC Bourbon Web App

It is now 2015 and with it a new version of Visual Studio that includes tools for Bower front end package management, Node Package Manager (NPM) and the Grunt JavaScript Task Runner. Not surprisingly, Microsoft has its own way of implementing Grunt, Bower and Node Modules in their upcoming Visual Studio debut. You don’t have to wait for Visual Studio 2015. Grunt, Bower, Node Modules and Bourbon can easily be included in a Visual Studio 2012 MVC 4 web application.

1. Create a New Project

New ASP.NET MVC 4 Web Application – MvcAppBourbon
New ASP.NET MVC 4 Web Application – MvcAppBourbon

2. Select the Empty Project Template

New ASP.NET MVC 4 Project – Empty Project Template
New ASP.NET MVC 4 Project – Empty Project Template

3. Ruby and Sass 3.3+

To install or update Sass you will need to have Ruby installed. For Windows, you can use the RubyInstaller for Windows. See this post for more info, Compass on Windows. These next step are done using a CLI, Windows PowerShell is what I will be using here. Git for Windows provides BASH emulation which also works great.

Install Sass

Ruby uses Gems to manage its code packages, to install the Sass Ruby Gem, enter gem install sass in the CLI.

Windows PowerShell – Install Sass
Windows PowerShell – Install Sass

4. Node Package Manager (NPM)

Install Node.js

NPM is included with Node.js. The best way to install NPM is to install node. The easiest way to install Node.js for Windows is with the Windows Installer (.msi) avaialble here.

5. Bower

Use NPM to install Bower globally on your system.

Install Bower
# global bower install
npm install -g bower

Change to the directory where you app is located. For me this is:
cd ‘~\Documents\Visual Studio 2012\Projects\MvcAppBourbon\MvcAppBourbon’

Install Bourbon
# bourbon install
bower install bourbon

Installed packages are located in the bower_components directory. This is created in the folder which the bower program was executed.

Install Bourbon Neat

Neat is a lightweight semantic grid framework for Sass and Bourbon.

# bourbon neat install
bower install neat

6. Bitters

Install Bourbon Bitters

Bitters jump start projects with a predefined set of basic Sass variables, default element style and project structure. Bitters are not installed with bower since the styles and variables are intended to be customized as needed. Change to the root directory of the app if not already there from bourbon install above. For me this is:
cd ‘~\Documents\Visual Studio 2012\Projects\MvcAppBourbon\MvcAppBourbon’

# bourbon bitters install
gem install bitters

# create a directory for sass files and folders
# this is done from within the MvcAppBourbon app root

mkdir sass

# change to the new sass directory
cd sass

# install bitters into the sass folder
bitters install

# navigate back to the MvcAppBourbon app root
cd ../

# create a directory for css files
mkdir css

Bitters files are installed to base/base. In-depth instructions on GitHub.

7. Grunt

Install Grunt

Use NPM to install Grunt’s command line interface (CLI) globally on your system. Then use NPM init to create a package.json that stores node package data for the app. The third command to run, npm install grunt –save-dev installs the latest version of Grunt into the project and adds it to the package.json devDependencies. More info is avaialable here.

# grunt CLI install
npm install -g grunt-cli

# create package.json
npm init

# grunt install to app, updates package.json
npm install grunt --save-dev

Installed npm packages are located in the node_modules directory. This is created in the folder which the npm install program was executed.

Install Grunt Plugins

The Grunt task that handles sass compilation to css when a .scss file is updated and saved is accomplished with these two plugins, grunt-contrib-watch and grunt-contrib-compass.

# grunt-contrib-watch install
npm install grunt-contrib-watch --save-dev

# grunt-contrib-compass install
npm install grunt-contrib-compass --save-dev
Create Gruntfile.js

In Visual Studio > Solution Explorer;
Right click MvcAppBourbon;
Select: Add > New Item > JavaScript File;
Name: Gruntfile.js

Add this JavaScript to the Gruntfile.

Gruntfile.js
'use strict';

module.exports = function(grunt) {
	// Project configuration.
	grunt.initConfig({
	    pkg: grunt.file.readJSON('package.json'),
	    compass: {
	      dist: {
	        options: {  
	          cssDir: 'css/',
	          sassDir: 'sass/',
	          outputStyle: 'compressed'
	        }
	      }
	    },
	    watch: {
			css: {
				files: '**/*.scss',
				tasks: ['compass']
			}
	    }
	});

	// Load the plugins.
	grunt.loadNpmTasks('grunt-contrib-compass');
	grunt.loadNpmTasks('grunt-contrib-watch');

	// default task
	grunt.registerTask('default', ['watch']);
}

8. SassyStudio Extension

In Visual Studio 2012, select Tools > Extensions and Updates

Search for and install the SassyStudio extension. This free utility provides a small amount of support for .scss files in Visual Studio. More info

9. Sass

In Visual Studio Solution Explorer;
Select Show All Files;

Show All Files – MvcAppBourbon

Right click sass > Include In Project;

Include In Project – MvcAppBourbon

Open sass/base/_grid-settings.scss and change the import path: @import “neat-helpers” to @import “../../bower_components/neat/app/assets/stylesheets/neat-helpers”.

_grid-settings.scss
//not in Rails
@import "../../bower_components/neat/app/assets/stylesheets/neat-helpers";
Create main.scss

In Visual Studio > Solution Explorer;
Right click MvcAppBourbon > sass;
Select: Add > New Item > SASS File;
Name: main.scss

Add this Sass to the main.scss file to import Bitters (base/base) and Neat. Neat is imported after Bitters.

main.scss
@import "../bower_components/bourbon/app/assets/stylesheets/bourbon.scss";
@import "base/base";
@import '../bower_components/neat/app/assets/stylesheets/neat';

Prior to making anymore Sass edits, in the CLI, load grunt to watch and compile changes.

Windows PowerShell – Grunt
Windows PowerShell – Grunt

Since we are using Neat, uncomment the grid-settings import in sass/base/_base.scss:

_base.scss
// Neat Settings -- uncomment if using Neat -- must be imported before Neat
@import "grid-settings";

After saving sass/main.scss, the running grunt tasks should should indicate that css/main.css has been written in the CLI and css/main.css should be updated to contain all of the base styles from the bitters import. Refresh Solution Explorer to see the new css.

Windows PowerShell – Grunt Compass
Windows PowerShell – Grunt Compass

On the next page, controller, views and some Bourbon Refills added for demonstration.

Resources

Bourbon

This post is not about a barrel-aged distilled spirit made primarily from corn. Instead, it is about a Sass mixin library. To add Bourbon to your web project, visit the Bourbon GitHub repo and take a look at the requirements.

The first requirement is obviously Sass, since this is a mixin library for it. As of this post, the latest Bourbon requires Sass 3.3+. To install or update Sass you will need to have Ruby installed. Ruby comes pre-installed on OS X. For Windows, you can use the RubyInstaller for Windows. When I set this up last year, I used the Ruby 1.9.3 installers. These next step are performed using a CLI. Git for Windows provides a BASH emulation that you can use instead of the Command Prompt.

Sass check / update

# version check
$ sass --v
Sass 3.2.12 (Media Mark)

# update
$ gem update sass
Updating installed gems
Updating sass
Fetching: sass-3.4.5.gem (100%)
Successfully installed sass-3.4.5
Gems updated: sass
Installing ri documentation for sass-3.4.5...
Installing RDoc documentation for sass-3.4.5...

Install Bourbon

Option 1

The installation as documented at the bourbon repo is pretty straight forward.

# Bourbon gem install
$ gem install bourbon
Fetching: thor-0.19.1.gem (100%)
Fetching: bourbon-4.0.2.gem (100%)
Successfully installed thor-0.19.1
Successfully installed bourbon-4.0.2
2 gems installed
Installing ri documentation for thor-0.19.1...
Installing ri documentation for bourbon-4.0.2...
Installing RDoc documentation for thor-0.19.1...
Installing RDoc documentation for bourbon-4.0.2...

# change to your project directory
# e.g., cd ~/mywebsite
# install Bourbon into your project
$ bourbon install
Bourbon files installed to bourbon/
Option 2

A good alternative is to use Bower to install Bourbon and manage packages for your project. You will need to have the Node Package Manger (NPM) which is bundled with Node.js. If you have not done so already, install Node.js. Then, use the NPM to install Bower

# global bower install
$ npm install -g bower

Next, using bower init, generate a bower.json file for your project. You will be prompted for answers to generate the file. Answering each is up to you, accept the defaults by selecting enter. After the bower.json file is created in your project, install Bourbon using bower install –save bourbon:

# change to your project directory
# e.g., cd ~/mywebsite
$ bower init
? name: BourbonTutorial
? version: 0.0.1
? description:
? main file:
? what types of modules does this package expose?:
? keywords:
? authors: jimfrenette <jim@jimfrenette.com>
? license: MIT
? homepage:
? set currently installed components as dependencies?: Yes
? add commonly ignored files to ignore list?: Yes
? would you like to mark this package as private which prevents it from being accidentally published to the registry?: No

{
  name: 'BourbonTutorial',
  version: '0.0.1',
  authors: [
    'jimfrenette '
  ],
  license: 'MIT',
  ignore: [
    '**/.*',
    'node_modules',
    'bower_components',
    'test',
    'tests'
  ]
}

? Looks good?: Yes

# install Bourbon into your project using Bower,
# this command installs the package and the --save option
# adds the dependency to the bower.json file

$ bower install --save bourbon
bower cached        git://github.com/thoughtbot/bourbon.git#4.0.2
bower validate      4.0.2 against git://github.com/thoughtbot/bourbon.git#*
bower install       bourbon#4.0.2

bourbon#4.0.2 bower_components\bourbon

Using Bourbon

Now we can create a Sass file and test drive some Bourbon mixins. Create a folder named sass in your web project root. And in that folder create a main.scss file with the code/text editor of your choice. Add the following Sass code to your new main.scss file and save it. NOTE: if you used option 1 to install Bourbon, adjust your import path as needed since /bower_components unavailable.

main.scss
@import "../bower_components/bourbon/dist/_bourbon.scss";

button {
    @include button(shiny, #ff0000);
}

Next, create a folder name css for you compiled sass output. Your directory structure should now look something like this depending on which Bourbon install option you used.

option 1
# | bourbon/
# | css/
# | sass/
#     | -- main.scss
 
option 2
# | bower_components/
#     | -- bourbon/
# | css/
# | sass/
#     | -- main.scss
# | bower.json
Setup sass to compile main.scss automatically

From within your projects sass folder, execute the sass watch command. Whenever your main.scss file is saved, the respective main.css will be written with all of the applicable browser extensions, reusable properties, etc..

# change to your sass folder in your project directory
# e.g., cd ~/mywebsite/sass

$ sass --watch  main.scss:../css/main.css
>>> Sass is watching for changes. Press Ctrl-C to stop.
←[32m      write ../css/main.css
←[0m←[32m      write ../css/main.css.map
←[0m

Here is what your /css/main.css file should look like after the Sass compile.

button {
  border: 1px solid #8a0000;
  border-bottom: 1px solid #810000;
  border-radius: 5px;
  box-shadow: inset 0 1px 0 0 #ff1d0c;
  color: white;
  display: inline-block;
  font-size: inherit;
  font-weight: bold;
  background-color: #ff0000;
  background-image: -webkit-linear-gradient(top, #ff0000 0%, #c70000 50%, #a90000 50%, #b00000 100%);
  background-image: linear-gradient(to bottom,#ff0000 0%, #c70000 50%, #a90000 50%, #b00000 100%);
  padding: 7px 18px;
  text-align: center;
  text-decoration: none;
  text-shadow: 0 -1px 1px #730000; }
  button:hover:not(:disabled) {
    cursor: pointer;
    background-color: #f20000;
    background-image: -webkit-linear-gradient(top, #f20000 0%, #bd0000 50%, #a20000 50%, #a90000 100%);
    background-image: linear-gradient(to bottom,#f20000 0%, #bd0000 50%, #a20000 50%, #a90000 100%); }
  button:active:not(:disabled), button:focus:not(:disabled) {
    box-shadow: inset 0 0 20px 0 #900000; }
  button:disabled {
    opacity: 0.5;
    cursor: not-allowed; }

/*# sourceMappingURL=main.css.map */

This is just the tip of the iceberg. With Sass, you can develop modular, reusable styles in small chunks to help make your CSS DRY and organized.

Bourbon Neat with Bitters

Neat is a lightweight semantic grid framework for Sass and Bourbon. Bitters is a set of Sass styles, variables and structure for Bourbon projects.

Going to change gears a little here and use Grunt to handle the watch & compile task for the Sass (.scss) files. Therefore, create this package.json file for NPM in the project root.

package.json
{
  "name": "bourbon-tutorial",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.5",
    "grunt-contrib-compass": "~1.0.1",
    "grunt-contrib-watch": "~0.6.1"
  }
}

Using Bower install Option 2, your file structure should look like this:

# option 2
# | bower_components/
#     | -- bourbon/
# | css/
# | sass/
#     | -- main.scss
# | bower.json
# | package.json

From the project root directory, run the NPM install which will add the grunt node modules to the project specified in package.json

# install node modules 
$ npm install

Install Neat and Bitters

# install neat using Bower,
# this command installs the package and the --save option
# adds the dependency to the bower.json file

$ bower install --save neat

# install bitters
$ gem install bitters

# add the library to the project,
# change to the sass directory,
# e.g., cd sass
$ bitters install

A base directory will be created in /sass containing the Bitters library. Detailed instructions are available here.

Create Grunt config

A Grunt configuration file is needed to run the watch and compile tasks. Create this gruntfile.js in the project root.

gruntfile.js
module.exports = function(grunt) {
  'use strict';
  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    compass: {
      dist: {
        // these options will override (or extend) config.rb settings.
        options: {  
          cssDir: 'css/',
          sassDir: 'sass/',
          outputStyle: 'compressed'
        }
      }
    },
    watch: {
      css: {
        files: '**/*.scss',
        tasks: ['compass']
      }
    }
  });
  // Load the plugins.
  grunt.loadNpmTasks('grunt-contrib-compass');
  grunt.loadNpmTasks('grunt-contrib-watch');
  // Default task(s).
  grunt.registerTask('default', ['watch']);
};

Run grunt

$ grunt
Running "watch" task
Waiting...

Step 2

This tutorial is not using Ruby on Rails, so edit sass/base/_grid-settings.scss changing the import path as needed for neat-helpers.

_grid-settings.scss
//not in Rails
@import "../../bower_components/neat/app/assets/stylesheets/neat-helpers";

Edit sass/main.scss to import Bitters (base/base) and Neat. Neat is imported after Bitters.

main.scss
@import "../bower_components/bourbon/dist/_bourbon.scss";
@import "base/base";
@import "../bower_components/neat/app/assets/stylesheets/neat";

button {
    @include button(shiny, #ff0000);
}

UPDATE – Bourbon 4.1 path changes **

main.scss
// note changes to path in Bourbon 4.1
@import "../bower_components/bourbon/app/assets/stylesheets/_bourbon.scss";

** Bourbon 4.1.0 released on December 30, 2014
For Bower users, the Bourbon’s directory structure has been changed. Instead of a dist directory, which was just a duplicate of the entire Bourbon library for Bower to use, now point Bower to app/assets/stylesheets.

Bitters is a scaffold of scss files to get you started, add to or edit them as needed. Since we are using Neat, uncomment the grid-settings import in base/_base.scss:

_base.scss
// Neat Settings -- uncomment if using Neat -- must be imported before Neat
@import "grid-settings";

After saving sass/main.scss, per the running grunt tasks the terminal output should indicate that css/main.css has been written. css/main.css should be updated to contain all of the base styles from the bitters import.

>> File "sass\main.scss" changed.
Running "compass:dist" (compass) task
    write css/main.css (0.875s)

Done, without errors.
Source Code

Resources