123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
Locomotive's Front-end Boilerplate
|
||
==================================
|
||
|
||
Front-end boilerplate for projects by [Locomotive][locomtl].
|
||
|
||
## Installation
|
||
```sh
|
||
# install mbp and gulp
|
||
npm install mbp gulp@next -g
|
||
```
|
||
|
||
## Usage
|
||
```sh
|
||
# 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`
|
||
- `assets/scripts/utils/environment.js`
|
||
|
||
## CSS
|
||
|
||
- We use [Sass](http://sass-lang.com) for our CSS Preprocessor
|
||
- [itcss](http://itcss.io) CSS architecture
|
||
- More Minimal BEM like CSS Syntax: `.block_element -modifier`
|
||
- [More Transparent UI Code with Namespaces](http://csswizardry.com/2015/03/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](https://github.com/inuitcss/inuitcss/tree/6eb574fa604481ffa36272e6034e77467334ec50) 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][demo-form]*
|
||
|
||
## 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](https://jquery.com) is globally included
|
||
|
||
[locomtl]: https://locomotive.ca
|
||
[demo-grid]: https://codepen.io/AntoineBoulanger/pen/EaLNxe
|
||
[demo-form]: https://codepen.io/AntoineBoulanger/pen/uBJmi
|
||
|
||
## Page transitions
|
||
We use [Pjax](https://github.com/MoOx/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()
|