mirror of
https://github.com/locomotivemtl/locomotive-boilerplate.git
synced 2026-01-15 00:55:08 +08:00
Complete rewrite of readme for v2, change styles base folder name for elements
This commit is contained in:
Antoine Boulanger
253
README.md
253
README.md
@@ -21,138 +21,177 @@ gulp
|
||||
```
|
||||
|
||||
## Configuration
|
||||
Change the mentions of `boilerplate` for your project's name in `mconfig.json`.
|
||||
Change the mentions of `boilerplate` for your project's name in `mconfig.json`. It is based on [modularBP](https://github.com/modularorg/modularbp).
|
||||
|
||||
## CSS
|
||||
[Learn more](https://github.com/modularorg/modularbp)
|
||||
|
||||
- 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)
|
||||
## Build
|
||||
[gulp](https://github.com/gulpjs/gulp) is our build system. It compiles our styles and scripts, generate svg sprites, live reload the browser and minify everything.
|
||||
|
||||
### Sass import order
|
||||
#### Tasks
|
||||
```sh
|
||||
# watch
|
||||
gulp
|
||||
|
||||
* **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 {}`).
|
||||
# compile
|
||||
gulp compile
|
||||
|
||||
### 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**
|
||||
# minify
|
||||
gulp build
|
||||
```
|
||||
<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>
|
||||
|
||||
[Learn more](https://github.com/modularorg/modularbp-gulp)
|
||||
|
||||
## Styles
|
||||
[Sass](https://github.com/sass/node-sass) is our CSS preprocessor. [Autoprefixer](https://github.com/postcss/autoprefixer) is also included.
|
||||
|
||||
#### Architecture
|
||||
[ITCSS](https://github.com/itcss) is our CSS architecture.
|
||||
|
||||
* `settings`: Global variables, site-wide settings, config switches, etc.
|
||||
* `tools`: Site-wide mixins and functions.
|
||||
* `generic`: Low-specificity, far-reaching rulesets (e.g. resets).
|
||||
* `elements`: Unclassed HTML elements (e.g. `a {}`, `blockquote {}`, `address {}`).
|
||||
* `objects`: Objects, abstractions, and design patterns (e.g. `.o-layout {}`).
|
||||
* `components`: Discrete, complete chunks of UI (e.g. `.c-carousel {}`).
|
||||
* `utilities`: High-specificity, very explicit selectors. Overrides and helper
|
||||
classes (e.g. `.u-hidden {}`)
|
||||
|
||||
[_source_](https://github.com/inuitcss/inuitcss#css-directory-structure)
|
||||
|
||||
#### Naming
|
||||
We use a simplified [BEM](https://github.com/bem) syntax.
|
||||
|
||||
`.block .block_element -modifier`
|
||||
|
||||
#### Namespaces
|
||||
We namespace our classes for more [transparency](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/).
|
||||
|
||||
* `o-`: Object that it may be used in any number of unrelated contexts to the one you can currently see it in. Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places.
|
||||
* `c-`: Component is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you’re currently looking at. Modifying these styles should be safe and have no side effects.
|
||||
* `u-`: Utility has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI.
|
||||
* `s-`: Scope creates a new styling context. Similar to a Theme, but not necessarily cosmetic, these should be used sparingly—they can be open to abuse and lead to poor CSS if not used wisely.
|
||||
* `is-`, `has-`: Is currently styled a certain way because of a state or condition. It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked.
|
||||
|
||||
[_source_](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/#the-namespaces)
|
||||
|
||||
#### Example
|
||||
```html
|
||||
<div class="c-block -large">
|
||||
<div class="c-block_layout o-layout">
|
||||
<div class="o-layout_item u-1/2@from-medium">
|
||||
<div class="c-block_heading o-h -medium">Heading</div>
|
||||
</div>
|
||||
<div class="o-layout_item u-1/2@from-medium">
|
||||
<a class="c-block_button o-button -outline" href="#">Button</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
```scss
|
||||
.c-block {
|
||||
&.-large {
|
||||
padding: rem(60px);
|
||||
}
|
||||
}
|
||||
|
||||
**CSS** (`/tools/_widths.scss`)
|
||||
```
|
||||
.u-1\/2\@from-medium {
|
||||
@media (min-width: $from-medium) {
|
||||
width: span(1/2);
|
||||
.c-block_heading {
|
||||
@media (max-width: $to-medium) {
|
||||
.c-block.-large & {
|
||||
margin-bottom: rem(40px);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Scripts
|
||||
[modularJS](https://github.com/modularorg/modularjs) is a small framework we use on top of ES modules. It compiles with [Rollup](https://github.com/rollup/rollup) and [Babel](https://github.com/babel/babel).
|
||||
|
||||
### Form
|
||||
#### Why
|
||||
- Automatically init visible modules.
|
||||
- Easily call other modules methods.
|
||||
- Quickly set scoped events with delegation.
|
||||
- Simply select DOM elements scoped in their module.
|
||||
|
||||
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.
|
||||
[_source_](https://github.com/modularorg/modularjs#why)
|
||||
|
||||
*[Demo][demo-form]*
|
||||
#### Example
|
||||
```html
|
||||
<div data-module-example>
|
||||
<div data-example="main">
|
||||
<h2>Example</h2>
|
||||
</div>
|
||||
<button data-example="load">More</button>
|
||||
</div>
|
||||
```
|
||||
```js
|
||||
import { module } from 'modujs';
|
||||
|
||||
## JavaScript
|
||||
export default class extends module {
|
||||
constructor(m) {
|
||||
super(m);
|
||||
|
||||
- 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
|
||||
this.events = {
|
||||
click: {
|
||||
load: 'loadMore'
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[locomtl]: https://locomotive.ca
|
||||
[demo-grid]: https://codepen.io/AntoineBoulanger/pen/EaLNxe
|
||||
[demo-form]: https://codepen.io/AntoineBoulanger/pen/uBJmi
|
||||
loadMore() {
|
||||
this.$('main').classList.add('is-loading');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[Learn more](https://github.com/modularorg/modularjs)
|
||||
|
||||
## Page transitions
|
||||
We use [Pjax](https://github.com/MoOx/pjax) by MoOx.
|
||||
[modularLoad](https://github.com/modularorg/modularload) is used for page transitions and lazy loading.
|
||||
|
||||
### 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.
|
||||
#### Example
|
||||
```html
|
||||
<nav>
|
||||
<a href="/">Home</a>
|
||||
<a href="/page" data-load="transitionName">Page</a>
|
||||
</nav>
|
||||
<div data-load-container>
|
||||
<img data-load-src="assets/images/hello.jpg">
|
||||
</div>
|
||||
```
|
||||
```js
|
||||
import modularLoad from 'modularload';
|
||||
|
||||
2. Main settings are set inside `assets/scripts/transitions/TransitionManager.js`
|
||||
this.load = new modularLoad({
|
||||
enterDelay: 300,
|
||||
transitions: {
|
||||
transitionName: {
|
||||
enterDelay: 450
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
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
|
||||
[Learn more](https://github.com/modularorg/modularload)
|
||||
|
||||
### Schema
|
||||
## Scroll detection
|
||||
[Locomotive Scroll](https://github.com/locomotivemtl/locomotive-scroll) is used for elements in viewport detection and smooth scrolling with parallax.
|
||||
|
||||
Legend
|
||||
- `[ ]` : listener
|
||||
- `*` : trigger event
|
||||
#### Example
|
||||
```html
|
||||
<div class="o-scroll" data-module-scroll>
|
||||
<div class="js-animate">Trigger</div>
|
||||
<div class="js-animate" data-speed="1">Parallax</div>
|
||||
</div>
|
||||
```
|
||||
```js
|
||||
import ScrollManager from '../scroll/vendors/ScrollManager';
|
||||
|
||||
`[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](https://github.com/locomotivemtl/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)
|
||||
this.scrollManager = new ScrollManager({
|
||||
container: $(this.el),
|
||||
selector: '.js-animate',
|
||||
smooth: true
|
||||
});
|
||||
````
|
||||
|
||||
[Learn more](https://github.com/locomotivemtl/locomotive-scroll)
|
||||
|
||||
@@ -26,11 +26,11 @@
|
||||
@import "generic/form";
|
||||
@import "generic/button";
|
||||
|
||||
// Base
|
||||
// Elements
|
||||
// ==========================================================================
|
||||
@import "base/fonts";
|
||||
@import "base/page";
|
||||
@import "base/headings";
|
||||
@import "elements/fonts";
|
||||
@import "elements/page";
|
||||
@import "elements/headings";
|
||||
|
||||
// Objects
|
||||
// ==========================================================================
|
||||
|
||||
Reference in New Issue
Block a user