Swill Boilerplate

This website is still in progress.

Features

Cleans the assets (build, images, CSS, JS) in the project to maintain the directory organization
Compresses Images
Generates Sprites with .png
Generates Sprites with .svg and a .png to fallback
Analyzes CSS with CSS Lint
Prefixes CSS with Autoprefixer
Compiles Sass or Stylus (Catch the Stylus error and direct shows on the page, as in Sass)
Concatenates And Minifies Scripts
Analyzes JavaScript with ESLint
Compiles ES2015
Notifies when tasks are complete
Monitors change in the files and reloads browser with BrowserSync
Uses Jasmine & Karma to test JavaScript
Builds the project compressing HTML, CSS and JS
Pushes the build folder to gh-pages branch

Technologies

This boilerplate uses the following technologies:

Includes

Functions and mixins - CSS preprocessors
Google Analytics
jQuery Logo Downloadtip - Only if jQuery is used
Normalize.css
Outdated Browser
Styles to Basic HTML elements - Only available with Stylus

Installation

First, install Yeoman and generator-swill-boilerplate using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-swill-boilerplate

Then generate your new project:

yo swill-boilerplate

Usage

Open the files .csslintrc, .editorconfig, and .eslintrc and set your configs to CSSLint, EditorConfig and ESLint respectively.
Open the file src/header-comments.txt and set your project header.
Open the terminal and go to the local folder.
On your first run, execute the task gulp with parameter compile and start the development
```
$ gulp --compile
```

Folder Structure

    ./
    ├──┐
    │  │
    │  ├─ app // Public files
    │  │  │
    │  │  ├─ css
    │  │  │  └─ // Public styles
    │  │  │
    │  │  ├─ fonts
    │  │  │  └─ // Web Fonts
    │  │  │
    │  │  ├─ img
    │  │  │  │
    │  │  │  ├─ copyright // Images with copyright metadata
    │  │  │  │
    │  │  │  ├─ logos // Logos of the projet
    │  │  │  │
    │  │  │  └─ // Public images
    │  │  │
    │  │  ├─ js
    │  │  │  └─ // Public scripts
    │  │  │
    │  │  ├─ apple-touch-icon.png // Icon for Safari on iOS
    │  │  │
    │  │  ├─ favicon.ico //Icon for address bar and bookmark
    │  │  │
    │  │  ├─ index.html
    │  │  │
    │  │  └─ // HTML, PHP, etc Files
    │  │
    │  ├─ spec // Scripts test
    │  │
    │  └─ src // Source files for the projects
    │       │
    │       ├─ handlebars
    │       │  │
    │       │  ├─ includes // Handlebars partials
    │       │  │
    │       │  └─ // Handlebars templates
    │       │
    │       ├─ images // Original images, don't compressed
    │       │  │
    │       │  ├─ sprite // Images to generate the sprite
    │       │  │
    │       │  ├─ touch // Icons
    │       │  │   │
    │       │  │   ├─ chrome-touch-icon-192x192.png // Icon for Chrome on Android
    │       │  │   │
    │       │  │   ├─ icon-128x128.png // Icon for Firefox on FirefoxOS
    │       │  │   │
    │       │  │   ├─ tile.png // Tile icon for Win8
    │       │  │   │
    │       │  │   └─ tile-wide.png // Wide tile icon for Win8
    │       │  │
    │       │  └─ // .jpg, .jpeg, .gif, .svg and .bmp to be compressed
    │       │
    │       ├─ scripts
    │       │  │
    │       │  ├─ settings
    │       │  │  │
    │       │  │  ├─ call_plugins.js // Call the plugins after page load
    │       │  │  │
    │       │  │  └─ google_analytics.js
    │       │  │
    │       │  └─ // Scripts
    │       │
    │       ├─ stylesheets
    │       │    │
    │       │    ├─ components
    │       │    │
    │       │    ├─ helpers
    │       │    │  │
    │       │    │  ├─ functions // All files here will be concatenated to ../functions.{scss, styl}
    │       │    │  │
    │       │    │  ├─ mixins // All files here will be concatenated to ../mixins.{scss, styl}
    │       │    │  │
    │       │    │  └─ _helpers.{scss, styl} // Helper tips to preprocessor syntax
    │       │    │
    │       │    ├─ partials // Styles to base tags
    │       │    │
    │       │    ├─ settings
    │       │    │  │
    │       │    │  ├─ _variables.{sass, styl}
    │       │    │  │
    │       │    │  └─ _web-fonts.{sass, styl}
    │       │    │
    │       │    ├─ _base.{sass, styl} // Main Styles
    │       │    │
    │       │    └─ styles.{sass, styl} // Base file with imports
    │       │
    │       ├─ vendors // Third-party code
    │       │
    │       └─ header-comments.txt // Header to styles and Scripts
    │
    ├─ .bowerrc // Bower configuration file
    ├─ .csslintrc // CSSLint configuration file
    ├─ .editorconfig // Editorconfig configuration file
    ├─ .eslintrc // ESLint configuration file
    ├─ bower.json // Bower dependencies
    ├─ config.json // Swill configuration file
    ├─ gulpfile.js // Gulp file
    ├─ LICENSE.md // Swill License
    ├─ karma.conf.js // Karma configuration file
    ├─ package.json // NPM dependencies
    └─ README.md // Documentation

Dependencies

Download and install the EditorConfig plugin for your text editor.
Download and install Node.js
- Select npm package manager
Install Gulp
- Open command line and executec
```
$ npm install -g gulp
```

Boilerplate

JavaScript files in src/scripts named with *_IGNORE.js will be ignored and won't be published, named with *_SEPARATE.js won't be concatenated and will be generated separately.

Example

myplugin_SEPARATE.js will be published as myplugin.js.

The folder public/img is cleaned when some tasks are executed, the images come from src/images, but if you work with copyrighted images you shouldn't use compression, because it removes the metadata from the files. You can place images directly in the public/img/copyright, they won't be deleted.

If for some other reason you want to use other folders, add the path in basePaths.clean.ignore on config.json, and it won't be deleted.

Tasks

Default Task - serve the project and watch (Alias to gulp serve)

$ gulp

Default Task (the default task accepts the parameter --compile) - clean assets, compile, watch and serve the project.

$ gulp --compile

Compile Task - clean assets and compile the project.

$ gulp compile

Build Task - build the project

$ gulp build

Build Task (the build task accepts the parameter --serve) - build the project and serve built project.

$ gulp build --serve

Gh-pages Task - build the project and push the output folder to gh-pages branch

$ gulp gh-pages

Test Task - run unit tests

$ gulp test

Config

Open the file config.json and setting as needed.

basePaths

Type: Object

Application paths.

components

Type: Boolean

Basic styles, only available with Stylus.

jQuery

Type: Boolean

lintCSS

Type: Boolean

lintJS

Type: Boolean

handlebars

Type: Boolean

inlineSVG

Type: Boolean

Enable SVG inline. Only available with handlebars.

jQuery svg to inline is an option to use without handlebars

autoprefixerBrowsers

Type: Array

Autoprefixer option, see the autoprefixer docs.

browserSync

Type: Object

BrowserSync options, see the browsersync docs.

If you use dynamic files, it's necessary to replace the server option by proxy.

Example

"browserSyncConfig": {
  "notify": false,
  "logPrefix": "BrowserSync",
  "server": {
      "baseDir": ["src/", "public/"]
  }
}

"browserSyncConfig": {
  "notify": false,
  "logPrefix": "BrowserSync",
  "proxy": "localhost/swill-boilerplate/public/"
}

browserSyncBuild

Type: Object

BrowserSync options for the built project, see the browsersync docs.

Bitmap Sprite

This boilerplate uses gulp.spritesmith to generate bitmap sprites.

When the sprite is generated, a file _bitmap-sprite.{styl,scss} is created with four mixins and the variables of the parameters of the images, like height and width (the names of the variables are the same as the original filename before the compilation).

Just use the mixins with the variables as parameters.

Example

#arrow
sprite($left_arrow)

&:hover
  spritePosition($right_arrow)

Output

#arrow {
  background-image: url(../images/sprite.png);
  background-position: 0px 0px;
  width: 32px;
  height: 32px;
}
#arrow:hover {
  background-position: 0px -34px;
}

Vector Sprite

SVG sprites are generated with gulp-svg-sprite, and as a fallback, all the SVG sprites are converted to .png with gulp-svg2png.

Put the icon in src/images/sprite.

In HTML put the class in elements

<i class="icon-star-dims icon-star"><i>

The class -dims gets the dimensions and the other the position of the icon in sprite.

The classname is defined by the .svg filename, example:

moon.svg the classname uses the prefix icon- and the filename of the svg moon.

If you want to use a hover, just name the file moon~hover.svg and use the class sgv-moon.