OfficialSite/README.md

Locomotive's Front-end Boilerplate

Front-end boilerplate for projects by Locomotive.

Requirements

Prerequisite	How to check	How to install
Node.js 4.1.1	node -v	nodejs.org
Grunt >= 0.1.13	grunt -v	npm install -g grunt-cli

Getting started

1. Get the latest node modules
   • npm install -g npm-check-updates
   • npm-check-updates -u
   • npm install

BrowserSync will automatically inject, refresh and sync all your browsers.

2. Set your project

   • build/browserSync.js update proxy
   • assets/scripts/utils/environment.js update APP_NAME

3. Run grunt, BrowserSync and start coding

   • grunt sync

Grunt

Each Grunt task has it's own file in the grunt_tasks folder.

CSS

• We use Sass for our CSS Preprocessor
• itcss CSS architecture
• More Minimal BEM like CSS Syntax: .block_element -modifier
• More Transparent UI Code with Namespaces

Sass import order

• Settings: Global variables, site-wide settings, config switches, etc.
• Tools: Site-wide mixins and functions.
• Generic: Low-specificity, far-reaching rulesets (e.g. resets).
• Base: Unclassed HTML elements (e.g. a {}, blockquote {}, address {}).
• Objects: Objects, abstractions, and design patterns (e.g. .o-media {}).
• Components: Discrete, complete chunks of UI (e.g. .c-carousel {}).
• Utilities: High-specificity, very explicit selectors. Overrides and helper classes (e.g. .u-hidden {}).

Grid

We use inuitcss layout and width system. We are using a inline-block grid system.

Insert a .o-layout block and add .o-layout_item elements inside it. By default o-layout_item made 100%. You can define different fractions in /tools/_widths.scss ($widths-fractions)

If you want a 2 columns grid, just add .u-1/2 on your 2 .o-layout_item

If you want to adapt columns by media queries, by example a 2 columns grid for 1000px + resolutions, and one columns in block under 1000px :

HTML

<div class="o-layout">
	<div class="o-layout_item u-1/2@from-medium">
		first colum
	</div>
	<div class="o-layout_item u-1/2@from-medium">
		second colum
	</div>
</div>

CSS (/tools/_widths.scss)

.u-1\/2\@from-medium {
	@media (min-width: $from-medium) {
    	width: span(1/2);
    }
}

Form

We included some basic CSS styles and resets to the form elements so we can easily have custom style form elements that work on every browsers.

Demo

JavaScript

• We use HTML data attributes to init our JavaScript modules: data-module
• All DOM related JavaScript is hooked to js- prefixed HTML classes
• jQuery is globally included

Page transitions

We use Pjax by MoOx.

Setup

1. Create a wrapper : .js-pjax-wrapper and a container .js-pjax-container inside. When a transition is launched, the new container is put inside the wrapper, and the old one is remove.

2. Main settings are set inside assets/scripts/transitions/TransitionManager.js

3. BaseTransition is launched by default, to set a new transition (like CustomTransition) :

   • create a new class TestTransition.js witch extends BaseTransition in assets/scripts/transitions/
   • add a line in assets/scripts/transitions/transitions.js to add your transition
   • use it like : <a href="/yourUrl" data-transition="TestTransition">My page</a>
   • Enjoy and made everything you want in your transition, check BaseTransition.js or CustomTransition.js like example

Schema

Legend

• [ ] : listener
• * : trigger event

[pjax:send] -> (transition) launch()

[pjax:switch] (= new view is loaded) -> (BaseTransition) hideView() -> hide animations & *readyToRemove

[readyToRemove] -> remove() -> delete modules, remove oldView from the DOM, innerHTML newView, init modules, display()

display() -> (BaseTransition) displayView() -> display animations & *readyToDestroy -> init new modules

[readyToRemove] -> reinit()