locomotive-boilerplate/README.md

Locomotive Boilerplate

Front-end boilerplate for projects by Locomotive.

Installation

npm install mbp gulp -g

Usage

# init your project
mbp init locomotivemtl/locomotive-boilerplate <directory>

# run default watch task
gulp

Configuration

Change the mentions of boilerplate for your project's name in mconfig.json.

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()

Locomotive Scroll

• locomotive-scroll

Configuration

• Create a .o-scroll container with data-module="Scroll"
• in the module Scroll.js you have a basic initialisation

Options

Options	Type	Description
container	$element	Scroll container (with the smooth scroll, this container will be transform)
selector	String	Every elements will be check by the scroll, can be affect by a followed data attributes
smooth	Boolean	If you want a smooth scroll
smoothMobile	Boolean	If you want a smooth scroll on mobile
mobileContainer	$element	Scroll container on mobile, document by default
getWay	Boolean	if true, the animate will determine if you scroll down or scroll up
getSpeed	Boolean	if true, the animate will calcul the velocity of your scroll. Access with this.scroll.y

Data attributes

Data	Value	Description
data-speed	number	Speed of transform for parallax elements
data-repeat	false	Determine if the "In View" class is added one or each times
data-inview-class	is-show	CSS Class when the element is in view.
data-position	top/bottom	Trigger from top/bottom of the window instead of the default from bottom to top
data-target	#id, .class	Trigger from another element
data-horizontal	false	Use transformX instead of transformY
data-sticky	false	Set $element sticky when it's in viewport
data-sticky-target	#id	Stop the element stick when the target is in viewport
data-callback	test.Scroll(test:0)	trigger event, with options way wich return "leave" or "enter" when $element is in viewport
data-viewport-offset	i,j	value between 0 to 1 (0.3 to start at 30% of the bottom of the viewport), useful to trigger a sequence of callbacks. (i : value wich start at the bottom, j : start at the top, j is optional)