Better

Better Brand Agency

Better Boilerplate Documentation

Introduction

This document should be used as a reference for using the Better Boilerplate. The standards document should be used as a reference for writing HTML and CSS/SCSS.

About the Better Boilerplate

The Better Boilerplate should be used for all frontend projects. The boilerplate is made up of many different modules and will manage much of the frontend build process but the main focus of the boilerplate is a CSS framework, over time I would like it to include a Javascript framework too.

The Better Boilerplate carries very little "style" and consists mainly of structure and some themeable objects, this allows us to create the styles needed based on each design individually.

The Better Boilerplate has already been rewritten a few times and will continue to be improved and redeveloped to meet future requirements.

Legacy websites using older versions of the Better Boilerplate have most of the same base code but maybe missing some optional modules or features.

Very early versions of the Better Boilerplate included the InuitCSS framework (documentation ) but that is no longer the case, some of the elements from Inuit have been taken and re-worked into the newer versions of the Better Boilerplate but Inuit in it's entirity was removed, in favour of custom, tailor made modules for our projects.

Table of Contents

Getting Started

Getting started with the Better Boilerplate has a few prerequisites, mainly programs which are required to be installed for the Better Boilerplate to run and compile.

The Better Boilerplate assumes a working knowledge of HTML, CSS, SCSS/SASS, BEM (Block, Element, Modifier) and Javascript.

Prerequisites

In order to run the Better Boilerplate you will need to install some software first;

NPM
NPM (Node Package Manager) is required to be able to run gulp tasks and compile the SCSS. Install: https://www.npmjs.com/ .
SASS/SCSS
The Better Boilerplate is written in SCSS which is part of SASS (Syntactically Awesome Style Sheets) - SASS gives us access to features which are not readily available in vanilla CSS. Install: http://sass-lang.com/install .
Gulp
The Better Boilerplate makes use of Gulp as a task runner to help streamline some of the build process. Install: https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md

Downloading

There are two variations of the Better Boilerplate;

Plain Better Boilerplate
The plain Better Boilerplate (CSS and Basic PHP files) is available for download from BitBucket .
Betterpress
The heavily modifed version of wordpress, complete with the Better Boilerplate is available for download from BitBucket . More documentation needs to be written around how to use and get up and running with BetterPress.

Installing

Once you have downloaded the Better Boilerplate and included it in your project files you will need to install the required npm modules, to do this; navigate to the root folder of you project and run the following command in terminal, the sudo command is to make sure you have admin rights to install the required node modules and will ask you to input your password;

$sudo npm install

You should also run;

$sudo npm update

Just to make sure the npm modules are up-to-date before getting started.

Gulp Tasks

The Better Boilerplate is making use of Gulp to automate much of the build process. You may wish to alter some of the settings in the gulpfile before beginning your project, such as the public or dist folder. To do this open the gulpfile.js found in the root folder of the Better Boilerplate and edit where necessary. The gulpfile is broken down into multiple tasks which can be run individually or all at once, all commands are run from the root folder of the Better Boilerplate in terminal:

gulp
Running the gulp command will run through all the tasks in the gulp file and will continually listen for changes in any of the source files and automatically compile them into the dist folder, this task can run in the background while you are working and will automatically recompile the code as you make changes.

All of the other gulp tasks will only run once and then stop.
gulp lint
Running the gulp lint command will analyse JS files in the project for potential errors.
gulp scripts
Running the gulp scripts command will compile the JS files from src/js/vendor and main.js to dist/js into a single minified and concatenated file main.min.js.
gulp other-scripts
Running the gulp other-scripts command will copy any files inside the src/scripts/other-scripts folder to dist/js. These files will be minified and moved but their filename will remain the same.
gulp styles
Running the gulp styles command will compile all of the css found in the src/styles folder into a single CSS file main.css found in dist/css. The gulp styles during compilation will also auto-vendor-prefix many CSS3 elements, adding automatic support without the need for prefixes within your theme code.
gulp styles-min
Running the gulp styles-min command will do the same as the gulp styles command but will also rename and minify the compiled file (main.min.css) into dist/css.
gulp clean
Running the gulp clean command will remove the contents of the css and js folders inside dist.
gulp images
Running the gulp images command will copy and optimise all image inside the src/images folder into the dist/images folder. The compression settings used for the images can be adjusted inside the gulpfile.js
gulp fonts
Running the gulp fonts command will copy any custom fonts placed inside the src/fonts folder to the dist/fonts folder.
gulp favicons
Running the gulp favicons command will copy any custom favicons placed inside the src/favicons folder to the dist/favicons folder.
gulp server
The Better Boilerplate, by default, includes a task to run a local dev server on your machine. Running the gulp server command will boot up a local server on localhost:8080 which means you don't require a server to get started.

Betterpress does not include this gulp task. Additionally, you may want to remove this task if you are working within a framework such as Laravel or a CMS such as Craft or WordPress.

File Structure

The Better Boilerplate in broken down into multiple files and folders but follows a familiar and simple structure. Starting from the outside working in;

The top level is two folders /src and /dist. Using gulp tasks the Better Boilerplate will compile CSS and Javascript from the /src folder into the /dist folder.

Src

The /src folder is where you will edit all of your CSS, Javascript, fonts, favicons and images. The folder structure inside the src folder is simple and fairly self explanatory;

Favicons
Favicons should be placed in the /src/favicons folder.
Fonts
Any custom fonts should be placed in the /src/fonts folder.
Images
Images should be placed in the /src/images folder. Images placed into this folder are automatically optimised for the web and are, therefore, reduced in size. The compression settings used for the images can be adjusted from the gulpfile.js found in the root folder of the Better Boilerplate.
PSDs
The PSDs folder contains any editable assets which are required for external modules such as chosen select menus.
Scripts
The scripts folder contains a main.js file and two folders. The files contained in the /vendor folder and, also, the main.js file will be minified and then compiled into /dist/js/main.min.js. The second folder /other-scripts will be moved in the same folder in dist (/dist/js) but as a seperate file, this folder should be used for scripts which will not be needed on all pages.
Styles
The styles folder is broken down into 3 folders;
  • better-boilerplate - This is the bulk of the CSS framework and SHOULD NOT BE EDITED DIRECTLY. Any code you wish to change should be overwritten using your own files in the theme folder.
  • settings - The settings folder contains overrides and settings for pretty much everything included in the CSS Framework. The settings folder is covered in detail below.
  • theme - The theme folder is where you should write your own CSS/SCSS. This folder is already broken down into multiple folders, containing files, most of which are empty, ready for you to start customising. If you need to add more theme files you can create them within the exisiting folder structure and then include them in the main.scss file found in the root of the styles folder.
SVGs
I am using a simple command-line tool to compile all SVG files into one SVG (svgs.svg). This tool can be downloaded and installed from https://github.com/jgarber623/svgeez . You can then use the following command from the root of your project to listen for changes to the folder. For more information on using SVGs please see the 'Using SVG' section below. 
$svgeez watch --source src/svgs --destination dist/images/

Dist

The dist folder is automatically compiled using gulp tasks, CSS, Javascript, fonts, favicons and images SHOULD NOT BE EDITED from the /dist folder.

File Referencing

Files referenced inside CSS and Javascript should be done so using a relative file path, this is where gulp will compile the files;

src: url('../fonts/font-name.eot');

Where to Start

The best place to start with the Better Boilerplate is the settings folder and files, from there you can begin the setup based on the requirements of the project. This includes colours, optional modules, grid settings and more.

After the initial settings setup you can start writing you own theme code inside the src/styles/theme/ folder, including any overrides to the Better Boilerplate. You should NEVER EDIT any of the files inside the better-boilerplate folder.

Settings

All of the editable settings can be found in the styles/settings folder broken down into multiple files. In older versions of the boilerplate all settings are stored in a single file; _settings.scss found in the src/styles/ folder.

Base Options

The base options includes a number of boolean variables all of which control which parts of the CSS Framework are compiled into the main.css and main.min.css allowing you to control the requirements and size of the outputted code. The following options are available in the file, all variables are either true or false;

$use-breakpoint-identifier
The breakpoint identifier will, when set to true, display a small tag towards the bottom right of the screen showing which media breakpoint is currently active. This is a really useful tool for responsive design, allowing you to quickly and easily indentify which breakpoint is currently active. This requires a single line of code to be placed in the website; 
<div class="breakpoint-identifier"></div>
$use-grids
The use grids variable controls whether the CSS for the grid is outputted into the compiled code.
$using-match-heights
The match heights variable is used to fix a known bug with match heights. With this variable turned off grid items will animate when the grid size changes at a certain breakpoint, this however causes a problem with the jQuery plugin match heights (http://brm.io/jquery-match-height/ ) which we frequently use.
$use-flex-widths
The use flex widths variable will output flexbox width properties (flex-basis) along with the normal width based properties for grid items.
$use-responsive-grid-classes
The use responsive grid classes variable will out the width classes with a responsive indentifier as the class prefix (lap-and-up-one-half). The variable will output classes for mobile, laptop and desktop. More information about this can be found in the media queries and grid sections of the documentation.
$use-responsive-helper-classes
The use responsive helper classes variable will, much like the responsive grid classes variable, out the helper classes with a responsive prefix (lap-and-up-is--hidden).
$use-responsive-tablet-classes
The use responsive tablet classes variable will output extra media query based classes for the tablet screen size (tablet-and-up-one-half and tablet-and-up--is-hidden).
$use-responsive-lap-wide-classes
The use responsive lap-wide classes variable will output extra media query based classes for the lap-wide screen size (lap-wide-and-up-one-half and lap-wide-and-up--is-hidden).
$use-responsive-desk-wide-classes
The use responsive desk-wide classes variable will output extra media query based classes for the desk-wide screen size (desk-wide-and-up-one-half and desk-wide-and-up--is-hidden).
$use-font-smoothing
The use font smoothing variable will output CSS used font smoothing. Some custom fonts will look better with this variable set to false.
$global-border-box
The global border box variable will set all elements in CSS to use border-box for box-sizing in CSS (http://www.w3schools.com/cssref/css3_pr_box-sizing.asp ).
$use-responsive-boxmodel-classes
The use responsive boxmodel classes variable will output all of the boxmodel classes with a responsive prefix (lap-wide-and-up-padding--left). This variable should be USED WITH CAUTION as the amount of CSS outputted by these variables is around an extra 50kb. These classes should only be output for PROTOTYPING or if the CSS is bundled with the application, such as an Android or iOS app.
$use-responsive-tablet-boxmodel-classes
The use responsive tablet boxmodel classes will output the same as the use responsive boxmodel classes but for the tablet media query (tablet-and-up-padding--left).
$use-responsive-lap-wide-boxmodel-classes
The use responsive lap-wide boxmodel classes will output the same as the use responsive boxmodel classes but for the lap-wide media query (lap-wide-and-up-padding--left).
$use-responsive-desk-wide-boxmodel-classes
The use responsive desk-wide boxmodel classes will output the same as the use responsive boxmodel classes but for the desk-wide media query (desk-wide-and-up-padding--left).

Colours

There are a number of colour based variables found in the _colours.scss settings file which can be edited and added to where appropriate.

Phonetic

By default we're setting a $color-alpha and $color-bravo, these are the brands main colours. Using the phonetic alphabet avoids naming a colour such as color--pink as this could change as a website or app develops (or clients change their minds).

Common

The common colours section includes a few variables which are often used such as; $color--warning (yellow), $color--error (red), $color--success (green) and (sky-blue).

Reference/Element

The reference/element colours have a few basics set, these can be changed to fit the current project;

$color-base-text
This is the default font colour used thoughout the webiste or application.
$color-border
This is the default border colour used thoughout the website or application.
$color-base-background
This is the background colour for the website or application.
$color-form-border
This is the default colour for borders on form elements.
$color-form-highlight
This is the default colour for form elements which are currently in focus.

Adding Colours

All of these colours can be added to, any other colours needed for the website by adding to the lists;

$color-charlie: blue;

Classes

All of the phonetic colours and common colours by default have a corresponding class for setting that variable as the text color and as a background;

<div class="color--alpha">This text will be the colour set by the $color-alpha variable</div>
    
<div class="background--alpha">The background colour of this element is set by the $color-alpha variable</div>

To add new colours which can be used as classes for text colour and background colour you need to edit the _colours.scss file found in styles/theme/base/_colours.scss. Unfortuntely there is a limitation with SASS which means these cannot be gererated from the variables directly. In this file there is an array which is used to generate the required classes. You need to add the name and the variable to the list;

$color-list: (
    alpha $color-alpha,
    bravo $color-bravo,
    twitter $color-twitter,
    error $color-error,
    warning $color-warning,
    success $color-success,
    charlie $color-charlie
);

Upon compilation the new classes, using $color-charlie: blue; will be available and compile to the following;

.color--charlie {
    color: blue;
}

.background--charlie {
    background-color: blue;
}

Content Widths

$content-width:				1080px;
$content-width-small:			900px;
$content-width-smallest:		600px;

The above variables relate to the below classes and are used for centering the main content when the browser window is large enough.

<div class="container--width"></div>
<div class="container--width-small"></div>
<div class="container--width-smallest"></div>

Fonts and Text

The Fonts and Text settings file contains all varialbes relating to font size, spacing and face.

$base-font-size
The base font-size is used as the default font size on the body and is used to calculate other values used in the site.
$base-line-height
The base line-height is used as the default line-height thoughout the site but it is also used to calculate other variables such as $base-spacing-unit and $half-spacing-unit, both of which are used for margin and padding values.
$font-family-alpha
The font-family alpha variable is used to set the main font-family for the website and accepts a full font stack as a value; 
$font-family-alpha:		"lato",sans-serif;
$font-family-bravo
The font-family bravo variable is used to set the secondary font-family for the website and accepts a full font stack as a value; 
$font-family-bravo:		"aktiv-grotesk-std",sans-serif;
$font-icon-family
The font icon family variable is used to set the icon family (if required), used in the site. 
$font-icon-family:		"fontAwesome";

The other variables in this file ($base-spacing-unit, $half-spacing-unit and $line-height-ratio) are all calculated by the other variables inside the fonts-and-text settings file

Global Properties

The global properties settings file allows you to set some global options for certain elements allowing you to maintain uniformity thoughout the website or application;

$text-shadow
0 1px 1px rgba(0,0,0,.3)
$border-radius
5px
$box-shadow
0 1px 1px rgba(0,0,0,.3)

Media Query Breakpoints

These variables are used to create the Responsive Grids.

$tablet-start:				450px;
$lap-start:				650px;
$lap-wide-start:			900px;
$desk-start:				1200px;
$desk-wide-start:			1400px;

Optional Modules

Optional modules can be turned on and off using the included variables, for more information about how to use these moudles see the optional modules documentation below.

$use-media-object: true;
$use-chosen-select-menus: false;
$use-respsonsive-video: false;
$use-respsonsive-maps: false;
$use-flexnav: false;
$use-owl-carousel: false;
$use-custom-radio-and-checkboxes: false;

Grids

The grid system used in the Better Boilerplate uses a modified version of the inuitCSS Grid system, the class names are simple and are written in plain english. The newer versions of the Better Boilerplate include a number of variables in the styles/settings/_base-options.scss to allow for certain elements to be included or not included, this helps to keep the file size of the complied CSS down to a minimum by only including what is being using on a project to project basis.

Basic Structure

The basic html for using grids

<div class="grid">

	<div class="grid__item">

	</div>

	<div class="grid__item">

	</div>

</div>

Width Classes

There are a number of differet widths you can use with the grid layout;

one-whole
one-half
one-third
one-quarter
one-fifth
one-sixth
one-seventh
one-eighth
one-tenth
one-twelfth

above is a list of the item which spans a single column, the prefix is pluralised when required;

three-quarters

Can be used with the responsive classes but must be turned on in the settings using the $use-responsive-grid-classes variable.

Code Example

<div class="grid">

	<div class="grid__item two-thirds">

	</div>

	<div class="grid__item one-third">

	</div>

</div>

Rendered Example

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Animi, suscipit facere unde, laboriosam distinctio tempora, saepe sapiente doloribus quasi inventore maxime soluta quas? Molestiae quis, velit numquam, mollitia a neque! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Fugit soluta ab omnis officiis nostrum assumenda quas, quaerat expedita. Ex alias possimus aut delectus, tempora porro velit placeat ab quibusdam pariatur.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nihil pariatur id dolorum officiis voluptatem dicta doloribus rerum omnis excepturi voluptas, laboriosam debitis molestiae necessitatibus, ipsum facere velit cumque cupiditate ea.

Responsive Grids

All grid widths can be used with the defualt media queries. Classes should be written in mobile first order. The following example is a fully responsive grid and an extreme example.

Code Example

<div class="grid">

	<div class="grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth">

	</div>

	<div class="grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth">

	</div>

	<div class="grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth">

	</div>

	<div class="grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth">

	</div>

	<div class="grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth">

	</div>

</div>

Rendered Example

Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item

Responsive Grid Classes

The responsive grid prefix classes are combined with the width classes listed above. Older versions of the Better Boilerplate include a number of additional respsonive calsses for "and-down" but these were removed in favour of working in a mobile first manner.

mobile-				: Mobile Only
tablet-				: Tablet Only
tablet-and-up-			: Tablet and Up
lap-				: Laptop Only
lap-and-up-			: Laptop and Up
lap-wide-			: Laptop Wide Only
lap-wide-and-up-		: Laptop Wide and Up
desk-				: Desktop and Up
desk-wide-			: Desktop Wide and Up

Nesting Grids

Nesting grids is simple and just requires you to write the html again nested inside a grid item

Code Example

<div class="grid">

	<div class="grid__item two-thirds">

		<div class="grid">

			<div class="grid__item three-fifths">

			</div>

			<div class="grid__item two-fifths">

			</div>

		</div>

	</div>

	<div class="grid__item one-third">

	</div>

</div>

Rendered Example

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Repellat ea inventore accusantium dolore, sunt, soluta accusamus placeat similique quaerat, autem reiciendis aspernatur fugit. Ratione tempora, laboriosam. Neque natus ea consequuntur!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Enim saepe explicabo, ullam iste recusandae praesentium eius, reprehenderit provident fugiat, doloribus culpa delectus velit commodi placeat sequi. Eaque voluptatum, neque voluptates.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dolorem commodi officiis, quam pariatur vero a? Laudantium optio odit ab! Rerum porro, blanditiis possimus expedita illum laudantium! Minima consectetur nihil dolor.

Centered Grids

Code Example

<div class="grid grid--center">

	<div class="grid__item one-half">

	</div>

	<div class="grid__item one-half">

	</div>

	<div class="grid__item one-half">

	</div>

</div>

Rendered Example

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Animi, suscipit facere unde, laboriosam distinctio tempora, saepe sapiente doloribus quasi inventore maxime soluta quas? Molestiae quis, velit numquam, mollitia a neque!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nihil pariatur id dolorum officiis voluptatem dicta doloribus rerum omnis excepturi voluptas, laboriosam debitis molestiae necessitatibus, ipsum facere velit cumque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptas reprehenderit, sequi beatae molestias fuga repellat ipsa, enim nesciunt blanditiis totam. Numquam cum, perferendis optio voluptatem explicabo voluptatibus.

Full Width Grids

The full modifer will stop the grid carrying the default padding.

Code Example

<div class="grid grid--full">

	<div class="grid__item one-half">

	</div>

	<div class="grid__item one-half">

	</div>

</div>

Rendered Example

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Animi, suscipit facere unde, laboriosam distinctio tempora, saepe sapiente doloribus quasi inventore maxime soluta quas? Molestiae quis, velit numquam, mollitia a neque!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nihil pariatur id dolorum officiis voluptatem dicta doloribus rerum omnis excepturi voluptas, laboriosam debitis molestiae necessitatibus, ipsum facere velit cumque.

Best Practice

When using grids it's best to use another nested div inside to apply other styling such as borders and backgrounds.

Code Example

<div class="grid grid--center">

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>
	
	<div class="[ grid__item one-whole tablet-one-half lap-one-third lap-wide-one-quarter desk-one-fifth ] margin--bottom">
		<div class="padding bordered">
			Grid Item
		</div>
	</div>

</div>

Rendered Example

Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item

The above example shows how to use the responsive grid by applying all of the relevant classes straight onto the grid__item, this can also be achieved using a single class and extending the responsive classes within that class.

Code Example

<div class="grid grid--center">

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>
	
	<div class="custom-class">
		<div class="custom-class__container">
			Grid Item
		</div>
	</div>

</div>
.custom-class {
	@extend .grid__item;
	@extend .tablet-one-half;
	@extend .lap-one-third;
	@extend .lap-wide-one-quarter;
	@extend .desk-one-fifth;
	@extend .margin--bottom;
}

.custom-class__container {
	@extend .padding;
	@extend .bordered;
}

Rendered Example

Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item
Grid Item

Known Problems

Known problems and warnings for using the grid;

Disappearing Items, Code not Rendering

To avoid having to put comments between all grid items I have had to use a font-size hack, in which I set the font-size of the grid to 0, to get around the white space and display:inline-block issue with CSS, and then set the font-size back to normal on the grid__item. This causes problems if you put elements inside a grid without a grid__item class.

Code Example

<div class="grid grid--center">

	This will not be displayed because of the font-size 0

	<div class="grid__item one-half">
		Will be displayed
	</div>

	<div class="grid__item one-half">
		Will be displayed
	</div>

</div>

Rendered Example

This will not be displayed because of the font-size 0
Will be displayed
Will be displayed

Media Queries

The media queries listed in this section can be combined with other elements such as the Grid.

Using Media Queries in SCSS

The media queries use a mixin to compile the CSS this allows us to create dynamic media queries which are easily editable using a few variables.

Code Example

@include media-query(lap-wide-and-up) {

	.content {
		font-weight: bold;
	}

}

Compiled Example

@media only screen and (min-width: 900px) {
    
    .content {
        font-weight: bold;
    }
            
}

The following list is all of the pre-defined media queries and an explaination of each.

mobile	        		: Mobile Only
tablet				: Tablet Only
tablet-and-up			: Tablet and Up
lap				: Laptop Only
lap-and-up			: Laptop and Up
lap-wide			: Laptop Wide Only
lap-wide-and-up			: Laptop Wide and Up
desk				: Desktop and Up
desk-wide			: Desktop Wide and Up

Using Media Queries in HTML

There are a number of classes which are prefixable with the media-query name listed above with a - (dash);

tablet-and-up-one-third
lap-wide-and-up-one-half
desk-three-fifths
<div class="tablet-and-up-one-half">

Variables

All of the pre-defined media queries can be chagned in the styles/settings/_mediaquery-breakpoints.scss file. using the following variables;

$tablet-start:				450px;
$lap-start:				650px;
$lap-wide-start:			900px;
$desk-start:				1200px;
$desk-wide-start:			1400px;

Box Model Classes

There are a number of box-model classes which can be extended within the SCSS or can be used directly in the HTML as a CSS class;

Display Classes

The following display classes can be used for prototyping or for single use/random elements.

<div class="display--none"></div>
<div class="display--block"></div>
<div class="display--inline-block"></div>
<div class="display--inline"></div>
<div class="display--table"></div>
<div class="display--table-cell"></div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

Margins and Padding

All of the margin and padding helper classes are based on the $base-spacing-unit variable found in the styles/settings/_base-options.scss file.

$base-spacing-unit: 	24px;

The following classes can be used to add margins and padding to any block level element.

Padding Classes

<div class="padding">Will have 24px padding</div>
<div class="padding--top">Will have 24px padding top</div>
<div class="padding--right">Will have 24px padding right</div>
<div class="padding--bottom">Will have 24px padding bottom</div>
<div class="padding--left">Will have 24px padding left</div>
<div class="padding--ends">Will have 24px padding top and bottom</div>
<div class="padding--sides">Will have 24px padding left and right</div>

<div class="padding-half">Will have 12px padding</div>
// All padding-half classes can carry all of the above modifiers.
<div class="padding-half--top">Will have 12px padding top</div>

<div class="padding-quarter">Will have 6px padding</div>
// All padding-quarter classes can carry all of the above modifiers.
<div class="padding-quarter--top">Will have 6px padding top</div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

Margin Classes

<div class="margin">Will have a 24px margin</div>
<div class="margin--top">Will have a 24px margin top</div>
<div class="margin--right">Will have a 24px margin right</div>
<div class="margin--bottom">Will have a 24px margin bottom</div>
<div class="margin--left">Will have a 24px margin left</div>
<div class="margin--ends">Will have a 24px margin top and bottom</div>
<div class="margin--sides">Will have a 24px margin left and right</div>

<div class="margin-half">Will have a 12px margin</div>
// All margin-half classes can carry all of the above modifiers.
<div class="margin-half--top">Will have a 12px margin top</div>

<div class="margin-quarter">Will have 6px margin</div>
// All margin-quarter classes can carry all of the above modifiers.
<div class="margin-quarter--top">Will have 6px margin top</div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

Margin and Padding Best Practice

The following shows a best practice for using margins and padding throughout the website. Padding and margins should be added using multiples (or divisions) of the base-spacing-unit this allows the webpage/document to carry a consistant vertical and horizontal rhythm. See the example below (the base-spacing-unit variable in the example below is set to 24px);

.item {
	padding: ($half-spacing-unit / 2) ($half-spacing-unit / 2); // 6px 6px

	@include media-query(tablet) {
		padding: $half-spacing-unit ($half-spacing-unit / 2); // 12px 6px
	}

	@include media-query(lap) {
		padding: $half-spacing-unit $half-spacing-unit; // 12px 12px
	}

	@include media-query(lap-wide) {
		padding: $base-spacing-unit $half-spacing-unit; // 24px 12px
	}

	@include media-query(desk) {
		padding: $base-spacing-unit $base-spacing-unit; // 24px 24px
	}

	@include media-query(wide) {
		padding: ($base-spacing-unit * 1.5) ($base-spacing-unit * 1.5); // 36px 36px
	}

}

Responsive Prefixing

All of the box-model classes can be prefixed however prefixing the following classes should only be used for prototyping as generating the required classes will create around 50kb of extra CSS (To view exactly how much code these variables compile I've made a simple pen on codepen which demonstrates this, simply click on the 'view compiled' button in the CSS section of the pen to see the generated code - all 3199 lines of it) in the complied code. This must be turned on using the $use-responsive-boxmodel-classes variable in the styles/settings/_base-options.scss file. Box-model classes without the respsonsive prefix are always available but the prefixes must be 'turned on'.

<div class="text--center lap-wide-and-up-text--left">

The above example would align text centrally until the browser window is at the width of 'lap-wide' and then it will be aligned left

Helper Classes

In addition to the box-model classes there are a number of helper classes which again can be extended within the SCSS or can be used directly in the HTML as a CSS class;

Float Classes

The following display classes can be used.

<div class="float--left"></div>
<div class="float--right"></div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

State Classes

The following state classes can be used.

<div class="is-hidden"></div>
<div class="is-visuallyhidden"></div> //Hidden visually but not from screen readers
<div class="is-visible"></div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

Text and Font Classes

The following text classes can be used.

Alignment

<div class="text--center"></div>
<div class="text--left"></div>
<div class="text--right"></div>

Transform

<div class="text--uppercase"></div>
<div class="text--capitalized"></div>

Weight

<div class="text--regular"></div>
<div class="text--semi-bold"></div>
<div class="text--bold"></div>

Can be used with the responsive classes for prototyping purposes only and must be turned on in the settings.

Position Classes

The following position classes can be used.

<div class="position--relative"></div>
<div class="position--absolute"></div>
<div class="position--static"></div>
<div class="position--fixed"></div>

Mixins

The Better Boilerplate has a number of useful mixins included;

Background Opacity

Create a semi-trasparent version of any colour, including varliables with a fallback to browsers which do not support transparency.

Usage

@include background-opacity(, );
    
.class-name {
    @include background-opactiy($color-alpha, 0.8);
}

Output

.class-name {
    background: #E2007C;
    background: rgba(226, 0, 124, 0.8);
}

Font Size

Output font-size in rems based on a pixel size.

Usage

@include font-size(, , );
    
.class-name {
    @include font-size(16px, true, true);
}

Output

.class-name {
    font-size: 16px !important;
    font-size: 1rem !important;
    line-height: 1.5 !important;
}

Headings

Style all headings in one fell swoop;

Usage

@include headings(, ) {}
    
@include headings(1,6) {
    font-weight: bold;
    color: $color-alpha;
}

Output

h1, h2, h3, h4, h5, h6 {
    font-weight: bold;
    color: #E2007C;
}

Opacity

Cross Browser Opacity (all the way back to IE5)

Usage

@include opacity();
    
.class-name {    
    @include opacity(0.8);
}

Output

.class-name {    
    opacity: 0.8;
    filter: alpha(opacity=80);
}

Clearfix

A great way to automatically clear floats on child elements is to use the 'clearfix' placeholder. This is generally used in layouts where elements are floated and meant to be stacked horizontally.

Usage

.class-name {    
    @extend %clearfix;
}

Output

.class-name {
    *zoom: 1;
}
   
.class-name:before, .class-name:after {
    content: " ";
    display: table;
}

.class-name:after {
    clear: both;
}

Word-wrap

Allow long words to be able to break and wrap onto the next line, this is especially useful for email addresses and links.

Usage

.class-name {
    @extend %word-wrap;
}

Output

.class-name {
    overflow-wrap: break-word;
    word-wrap: break-word;
    -ms-word-break: break-all;
    word-break: break-word;
    -ms-hyphens: auto;
    -moz-hyphens: auto;
    -webkit-hyphens: auto;
    hyphens: auto;
}

Default Styles

The Better Boilerplate carries some default styling for basic elements. This code can be found in the styles/theme/base/_global.scss file. The code is placed in the theme folder as these are style you may wish to change on a project to project basis.

Blockquote

The following example shows the default blockquote and cite styling;

Usage

<blockquote>Two things are infinite: the universe and human stupidity; and I'm not sure about the universe.</blockquote>
<cite>Albert Einstein</cite>

Rendered Example

Two things are infinite: the universe and human stupidity; and I'm not sure about the universe.
Albert Einstein

Description List

The following example shows the default description/definition list styling;

Usage

<dl>

    <dt>Description Title</dt>
    <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?</dd>

    <dt>Description Title</dt>
    <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?</dd>

    <dt>Description Title</dt>
    <dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?</dd>

</dl>

Rendered Example

Description Title
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?
Description Title
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?
Description Title
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Amet doloremque voluptatem aspernatur, unde eveniet esse dignissimos est eaque eius, soluta, quidem fuga. Consectetur cumque eveniet saepe, quas necessitatibus quibusdam aliquid?

Forms

The following example shows the default form element styling;

Usage Example

<form>

    <input class="margin--bottom" type="text" placeholder="Basic Text Input">

    <textarea class="margin--bottom" placeholder="Basic Textarea" rows="10"></textarea>

    <select class="margin--bottom">
        <option value="" disabled selected>Please Select</option>
        <option value="one">Option One</option>
        <option value="two">Option Two</option>
        <option value="three">Options Three</option>
    </select>

    <p class="margin-half--bottom">Checkbox Question:</p>

    <label class="margin-half--bottom margin--right" for="checkbox-one"><input id="checkbox-one" type="checkbox" name="checkboxes" value="One">Checkbox One</label>

    <label class="margin--bottom margin--right" for="checkbox-two"><input id="checkbox-two" type="checkbox" name="checkboxes" value="Two">Checkbox Two</label>

    <br>

    <p class="margin-half--bottom">Radio Question:</p>

    <label class="margin-half--bottom margin--right" for="radio-one"><input id="radio-one" type="radio" name="radio" value="One">Radio One</label>

    <label class="margin-half--bottom margin--right" for="radio-two"><input id="radio-two" type="radio" name="radio" value="Two">Radio Two</label>

    <label class="margin--right" for="radio-three"><input id="radio-three" type="radio" name="radio" value="Three">Radio Three</label>

    <input class="margin--top" type="submit">

</form>

Rendered Example

Checkbox Question:


Radio Question:

Icon Fonts

Using icon fonts with the Better Boilerplate is really simple and requires you to only edit a simple loop found in styles/theme/components/_icons.scss to add the icons you need from a given icon font.

Icon Loop

The loop found at the top of the SCSS partial will look something like the following;

$icon-list: (
    heart "\f004",
    arrow-up "\f106",
    menu "\f0c9"
);

To add more icons simply add them to the list, the first part of the list is the reference name that will be used in the HTML to reference the icon. The second part of the list inside quotes is the unicode value of the icon;

$icon-list: (
    heart "\f004",
    arrow-up "\f106",
    menu "\f0c9",
    diamond "\f219"
);

By default we are using font awesome (https://fortawesome.github.io/Font-Awesome/ ) as the default icon font but this can be changed using the $font-icon-family variable found in the settings/_fonts-and-text.scss file.

Usage Example

<i class="icon icon--diamond"></i>

Rendered Example

Tables

The following example shows the default table styling;

Usage Example

<table>
    <tr>
        <th>Firstname</th>
        <th>Lastname</th>
        <th>Points</th>
    </tr>
    <tr>
        <td>Steven</td>
        <td>Roberts</td>
        <td>94</td>
    </tr>
</table>

Rendered Example

Firstname Lastname Points
Steven Roberts 94

Tables - Horizontal Border Only

The following example shows the table styling when using the class table__horizontal-border-only;

Usage Example

<table class="table__horizontal-border-only">
    <tr>
        <th>Firstname</th>
        <th>Lastname</th>
        <th>Points</th>
    </tr>
    <tr>
        <td>Steven</td>
        <td>Roberts</td>
        <td>94</td>
    </tr>
</table>

Rendered Example

Firstname Lastname Points
Steven Roberts 94

Images

The Better Boilerplate has a number of different options for displaying images, as well as the optimisation settings (in gulp) covered above

Responsive Images

Images in the Better Boilerplate are responsive by default when you are using the standard HTML image markup. Images will, also, never scale above their original dimensions, this is to prevent the image stretching and appearing pixelated. For example, if an image's raw dimensions are 800x600px then it will never be scaled above that;

Usage

<img src="/dist/images/landscape.jpg" alt="Sunset Landscape">

Rendered Example

Sunset Landscape

Non Responsive Images

To output an image which is not responsive you will need to specify the width and height attributes within the HTML image markup;

Usage

<img src="/dist/images/landscape.jpg" alt="Sunset Landscape" width="250">

Rendered Example

Sunset Landscape

Image Positioning

There are a number of image position clases which can be used to quickly position an image in the page;

Right Alignment

Images positioned using the image--right class are floated to the right with content flowing around it to the left.

Example
<img class="image--right" src="/dist/images/landscape.jpg" alt="Sunset Landscape" width="35%">
Sunset Landscape

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Velit esse natus quis voluptas molestiae quaerat a modi, aspernatur nemo omnis voluptatum, obcaecati iusto voluptatem facilis ut neque similique nobis doloribus! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iste alias, culpa obcaecati, nisi est numquam debitis possimus laborum rerum, suscipit pariatur illum reprehenderit quibusdam sunt neque beatae. Est, omnis, ut? Lorem ipsum dolor sit amet, consectetur adipisicing elit. Beatae accusantium et expedita, a nulla! Quaerat magni, voluptates nostrum maxime dolore odit veniam, ipsum quo praesentium iusto asperiores dolores, corporis ad.

Left Alignment

Images positioned using the image--left class are floated to the left with content flowing around it to the right.

Example
<img class="image--right" src="/dist/images/landscape.jpg" alt="Sunset Landscape" width="35%">
Sunset Landscape

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Velit esse natus quis voluptas molestiae quaerat a modi, aspernatur nemo omnis voluptatum, obcaecati iusto voluptatem facilis ut neque similique nobis doloribus! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iste alias, culpa obcaecati, nisi est numquam debitis possimus laborum rerum, suscipit pariatur illum reprehenderit quibusdam sunt neque beatae. Est, omnis, ut? Lorem ipsum dolor sit amet, consectetur adipisicing elit. Beatae accusantium et expedita, a nulla! Quaerat magni, voluptates nostrum maxime dolore odit veniam, ipsum quo praesentium iusto asperiores dolores, corporis ad.

Center Alignment

Images positioned using the image--center class unlike the other position classes is not floated but instead made a block level element which will span a full column, wrapping any content underneath.

Example
<img class="image--right" src="/dist/images/landscape.jpg" alt="Sunset Landscape" width="35%">
Sunset Landscape

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Velit esse natus quis voluptas molestiae quaerat a modi, aspernatur nemo omnis voluptatum, obcaecati iusto voluptatem facilis ut neque similique nobis doloribus! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iste alias, culpa obcaecati, nisi est numquam debitis possimus laborum rerum, suscipit pariatur illum reprehenderit quibusdam sunt neque beatae. Est, omnis, ut? Lorem ipsum dolor sit amet, consectetur adipisicing elit. Beatae accusantium et expedita, a nulla! Quaerat magni, voluptates nostrum maxime dolore odit veniam, ipsum quo praesentium iusto asperiores dolores, corporis ad.

Circular Images

Using circular images requires the image itself to already be square, this can be done manually or using an image generator like the one built into wordpress.

Usage

<img class="image--circular" src="/dist/images/profile.jpg" alt="Steven Roberts" width="250">

Rendered Example

Using SVG

To use SVGs in the page we use the following code or something similar in Wordpress or another PHP Framework; This code includes the compiled single SVG in the page, usually placed in the header or page template.

<?php include_once('images/svgs.svg'); ?>

Then to reference an SVG within the file you use the following code;

<svg class="svg svg--header-logo">
    <use xlink:href="#svgs-better-logo"></use>
</svg>

The xlink:href value is the file name of the SVG from the src folder with #svgs- preceding it and the file suffix removed. For example; if the filename was better-logo.svg the xlink:href will be #svgs-better-logo.

By giving the SVG a class of svg it will inherit the Better Boilerplate default settings for an SVG image. Then with a modified class such as svg--header-logo we can then target the svg and change attributes such as color, size and positioning.

Optional Modules

All of the optional modules can be turned on or off using the variables found in the styles/settings/_modules file. In older versions of the Better Boilerplate they are in the _settings.scss file found in the src/styles/ folder.

Custom Radio Buttons and Checkboxes

In order to use the pre-styled custom radio buttons and checkboxes you will need to use the classes .radio or .checkbox on the input itself and .radio__label or .checkbox__label on the label. Radio buttons generated by the module are round and checkboxes are square. The module requires the HTML to be written with the input followed by the label, this is due to the CSS Selectors being used. The colour is set using the variable $color-form-highlight in the styles/settings/_colours.scss file.

Code Example

<form>

    <p class="margin-half--bottom">Radio Buttons;</p>
    <input class="radio" id="custom-radio-button-one" type="radio" name="radio" value="one" />
    <label class="radio__label" for="custom-radio-button-one">Radio Button One</label>

    <input class="radio" id="custom-radio-button-two" type="radio" name="radio" value="two" />
    <label class="radio__label" for="custom-radio-button-two">Radio Button Two</label>

    <p class="margin-half--bottom margin--top">Checkboxes;</p>
    <input class="checkbox" id="custom-checkbox-one" type="checkbox" name="checkbox" value="one" />
    <label class="checkbox__label" for="custom-checkbox-one">Checkbox One</label>

    <input class="checkbox" id="custom-checkbox-two" type="checkbox" name="checkbox" value="two" />
    <label class="checkbox__label" for="custom-checkbox-two">Checkbox Two</label>

</form>

Rendered Example

Radio Buttons;

Checkboxes;

Media Object

The media object (popularised by Nicola Sullivan ) is available in the Better Boilerplate once actived using the $use-media-object variable found in the styles/settings/_modules.scss file.

Code Example

<div class="media">
	<div class="media__img"></div>
	<div class="media__body"></div>
</div>

Rendered Example

Steven Roberts
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsa dicta eius id officia. Temporibus pariatur deleniti culpa, aliquid dolorum fugit itaque dolore. Eligendi magnam obcaecati, eum dolor ipsa neque in! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsa dicta eius id officia. Temporibus pariatur deleniti culpa, aliquid dolorum fugit itaque dolore.

Media Object (Reverse)

The media object also carries a reverse option which will put the image/secondary content on the right.

Code Example

<div class="media">
	<div class="media__img--rev"></div>
	<div class="media__body"></div>
</div>

Rendered Example

Steven Roberts
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsa dicta eius id officia. Temporibus pariatur deleniti culpa, aliquid dolorum fugit itaque dolore. Eligendi magnam obcaecati, eum dolor ipsa neque in! Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsa dicta eius id officia. Temporibus pariatur deleniti culpa, aliquid dolorum fugit itaque dolore.

Responsive Video

The only requirement for the responsive video module is to wrap a video-container.

Code Example

<div class="video-container">
    <iframe src="https://www.youtube.com/embed/L3VMCHKwnH0?rel=0" width="560" height="315" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
</div>

Rendered Example

Responsive Maps

The only requirement for the responsive maps module is to wrap a map-container.

Code Example

<div class="map-container">
	<iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d74003.13484064981!2d-1.3012035975264002!3d54.575837003124185!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x487eea3088fa14b1%3A0xb6bfed71513693b8!2sBetter!5e0!3m2!1sen!2suk!4v1450802036329" frameborder="1" allowfullscreen></iframe>
</div>

Rendered Example

Chosen (Select Menus)

The Better Boilerplate includes a heavily modified version of Chosen (http://harvesthq.github.io/chosen/ ). Chosen is used to style select menus in order for them to be consistent in design across all browsers. The JS file for this module and all the others can be found in the scripts/vendor folder. The jQuery Plugin has a number of options available, for a list of these options please see the options documentation for chosen.

Usage

The module requires a small amount of JS to be run on page load ((document).ready);

$('select').chosen({
    disable_search: true,
});

This code is already included in the src/scripts/main.js file and should be removed as well as turning off the $use-chosen-select-menus variable found in the styles/settings/_modules.scss file, should you not want to use it.

Styling/Customisation

The chosen module is completely re-stylable using the variables found in the styles/theme/widgets/_chosen-theme.scss file. Changing the values of these variables and recompiling the CSS will render your new styling.

Code Example

<select>
    <option value="" disabled selected>Please Select</option>
    <option value="one">Option One</option>
    <option value="two">Option Two</option>
    <option value="three">Options Three</option>
</select>

Rendered Example

Flexnav (Responsive Navigation)

The Better Boilerplate includes a stripped back (function only) version of Flexnav . Flexnav allows us to tuck away the navigation into an expandable menu when you reach a certain breakpoint (browser width). The JS file for this module and all the others can be found in the scripts/vendor folder.

Usage

The module requires a small amount of JS to be run on page load ((document).ready);

$(".flexnav").flexNav({
    'hoverIntent': true,
});

In addtion to the JS you will need to modify the HTML of the menu (<ul>) by adding a class (.flexnav) and a custom data attribute (data-breakpoint). The custom data attribute is used to determine where the breakpoint is for the menu to tuck away into the expandable menu. The example shown below will show the 'mobile menu' on screen sizes under 1000px in width. It is usually best to set this value to be the same as one of the breakpoints in the media query breakpoints settings file, this will make styling much easier.

<ul class="flexnav" data-breakpoint="1000">

Styling/Customisation

The module itself carries very little style so you will need to write the style yourself, its usually best to do this inside the styles/theme/sections/_navbar.scss file or somewhere inside the theme folder.

Owl Carousel (Responsive Slider)

The Better Boilerplate inclues a modifed version of Owl Slider 2 (http://www.owlcarousel.owlgraphic.com/ ).

Usage

This modules requires jQuery and the following code to be put inside the page load ((document).ready). The following code is included in the src/scripts/main.js file and should be removed if not being used.

$('.js-default-carousel').owlCarousel({
    items: 1, // Number of items to show at once
    loop: true, // Loop back to the start when end is reached
    nav: true, // Show left and right arrows
    dots: true, // Show pagination style dots
    navText: ["",""], //remove text from next and previous buttons to show arrows in CSS instead
});

In addition to the js above you will also need to write the HTML in a specific way. The parent container needs the class owl-carousel for the js to find the element and render the slider. The elements inside of the container can be a single image or contain divs with images and an overlay with text in.

Simple Example
<div class="owl-carousel js-default-carousel">
       
    <img class="carousel__image" src="/dist/images/landscape.jpg">
    <img class="carousel__image" src="/dist/images/landscape2.jpg">
    <img class="carousel__image" src="/dist/images/landscape3.jpg">
    <img class="carousel__image" src="/dist/images/landscape4.jpg">

</div>
With Overlay Example
<div class="owl-carousel js-default-carousel">
       
    <div class="carousel__item">
        <div class="carousel__overlay">
            <p>Carousel Item One</p>
        </div>
        <img class="carousel__image" src="/dist/images/landscape.jpg">
    </div>
    
    <div class="carousel__item">
        <div class="carousel__overlay">
            <p>Carousel Item Two</p>
        </div>
        <img class="carousel__image" src="/dist/images/landscape2.jpg">
    </div>
    
    <div class="carousel__item">
        <div class="carousel__overlay">
            <p>Carousel Item Three</p>
        </div>
        <img class="carousel__image" src="/dist/images/landscape3.jpg">
    </div>
    
    <div class="carousel__item">
        <div class="carousel__overlay">
            <p>Carousel Item Four</p>
        </div>
        <img class="carousel__image" src="/dist/images/landscape4.jpg">
    </div>

</div>

The Overlay example will need you to style and position the overlay yourself, as this will likely change from project to project, the styles for this are not inclued in the theme.

Rendered Example

Match Heights

The Better Boilerplate includes the jQuery Plugin Match Heights (http://brm.io/jquery-match-height/ ). This plugin is really useful for matching the height of two or more elements which sit in the same column.

Usage

This module requires jQuery and is already bundled with the JS included in the Better Boilerplate. Using this module is really simple and requires just a simple data tag adding to an existing html element

<div class="grid">
    
    <div class="grid__item one-third">
        <div class="padding background--alpha color--white" data-match-height="grid-columns">
            <h5 class="color--white">Column Title</h5>
            <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptas suscipit amet deleniti sapiente quo, iste at impedit cum, facere perspiciatis maiores explicabo nobis, reprehenderit ex commodi nam harum quaerat! Maiores!</p>
        </div>        
    </div>

    <div class="grid__item one-third">
        <div class="padding background--alpha color--white" data-match-height="grid-columns">
            <h5 class="color--white">Column Title</h5>
            <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Alias perspiciatis quibusdam culpa qui quis, iste voluptatem laborum labore fugit ad ullam sint.</p>
        </div>
    </div>

    <div class="grid__item one-third">
        <div class="padding background--alpha color--white" data-match-height="grid-columns">
            <h5 class="color--white">Column Title</h5>
            <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
        </div>
    </div>

</div>

Rendered Example

Not Matched
Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptas suscipit amet deleniti sapiente quo, iste at impedit cum, facere perspiciatis maiores explicabo nobis, reprehenderit ex commodi nam harum quaerat! Maiores!

Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Alias perspiciatis quibusdam culpa qui quis, iste voluptatem laborum labore fugit ad ullam sint.

Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Matched
Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptas suscipit amet deleniti sapiente quo, iste at impedit cum, facere perspiciatis maiores explicabo nobis, reprehenderit ex commodi nam harum quaerat! Maiores!

Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Alias perspiciatis quibusdam culpa qui quis, iste voluptatem laborum labore fugit ad ullam sint.

Column Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Polyfills

The Better Boilerplate makes use of HTML5 elements and some of the newer CSS3 elements available to designers and developers, to offer the best support we can for older browsers. The following files are included in the src/scripts/other-script/ folder and will need including in the header of your website.

html5-shiv

The html5 shiv allows older versions of IE to support html5 elements (<article>, <nav>, <header> etc.). As these are only not supported by IE8 and earlier the following code is required to only use the polyfill when needed.

<!--[if lte IE 8]>
    <script src="/dist/js/html5-shiv.js"></script>
<![endif]-->

media-polyfill

The media-polyfill is used to allow older browsers (IE8 and earlier) to have support for media queries, this is particularly useful when you need to support older browsers since we are building in a mobile first manner.

<!--[if lte IE 8]>
    <script src="/dist/js/media-polyfill.js"></script>
<![endif]-->

placeholder-polyfill

The placeholder-polyfill will be used to add support for placeholders in IE9 and before;

<!--[if lte IE 9]>
    <script src="/dist/js/placeholder-polyfill.js"></script>
<![endif]-->