#generator-power

##Overview The goal of this yo generator is to create a consistent framework for front-end web and application development and to implement tools that facilitate best practices through the use of automation and templating.

Common front-end processes have been automated using grunt, but the configuration of those tasks has been streamlined and moved to a JSON settings file. The majority of projects can be configured via this JSON file without any changes to the underlying grunt task configurations. Additionally these settings files can be overridden in order to provide environment specific settings variations.

###features

• Capable of scaffolding multiple predefined or customized templates
• Dependency management
• Stylesheet compilation (less or sass), optimization, and minification
• Image asset export using Sketch/Sketchtool
• Image minification
• Web embeddable font generation
• Icon font generation from SVGs
• Script minification, concatenation
• RequireJS compilation; standard, or self-contained using AlmondJS

##Setup This project is intended to be forked and customized. Once forked, additional template types can be added and additional bower dependencies can be configured.

First install yo (requires node): npm install -g yo

If you want to use the generator as is, just install it: npm install -g generator-power

If you'd like to modify and customize template types and installation options, Fork this repository then from a cloned folder run npm link to make it available for development and local use.

To run the generator, cd to an empty/uninitialized project directory and run yo power. A series of prompts will allow you to select and customize the installation.

##Adding Templates todo

##Adding Dependencies todo

##Project Configuration To configure a project manually or modify settings beyond what can be done via the yo generator process one can use JSON Configuration files. Any file that matches **/*-settings.json will be recursively merged into the project settings. This can be used to provide environment specific or developer specific variations to the project's configuration.

Attributes marked as required must be present somewhere in the settings inheritance. Files with higher order attribute values will override files with lower values. Objects are merged recursively, Primitives and Arrays are overwritten.

JSON settings file

{
	"order": 0,
	"settings": {
		...
	}
}

###source References to location of coded assets. All paths are relative to the directory containing "Gruntfile.js".

        "source": {
            "root": "source",
            "scripts": "source/scripts",
            "less": "source/less",
            "sass": "source/sass"
        }

Attribute	Description	required	inheritable
root	path to source root	√	√
scripts	path to javascript source	√	√
less	path to less source	less or sass	√
sass	path to sass source	less or sass	√

###resource References to locations of binary, file and image assets. All paths are relative to the directory containing "Gruntfile.js".

        "resource": {
            "root": "resource",
            "fonts": "resource/fonts",
            "images": "resource/images",
            "icons": "resource/icons",
            "sketch": "resource/sketch"
        }

Attribute	Description	required	inheritable
root	path to resource root	√	√
fonts	path to fonts source	√	√
images	path to image source	√	√
icons	path to icons source	√	√
sketch	path to sketch source	√	√

###build References to output paths. All paths are relative to the directory containing "Gruntfile.js".

        "build": {
            "root": "public",
            "scripts": "public/assets/scripts",
            "css": "public/assets/css",
            "fonts": "public/assets/fonts",
            "images": "public/assets/images"
        }

Attribute	Description	required	inheritable
root	path to build root	√	√
scripts	path to build scripts	√	√
css	path to build css	√	√
fonts	path to build fonts	√	√
images	path to build images	√	√

###dependencies grunt-bower-map is used to pick and place external dependency assets installed via bower. There are five asset types that have been predefined for specifying options: js, less, sass, fonts, and images. Files can be copied, renamed and even modified using the following configuration options.

        "dependencies": {
        	"path": "vendor"
            "shim": {},
            "map": {},
            "extensions": {},
            "replace": {}
        }

Attribute	Description	required	inheritable
vendorPath	the directory into which dependencies are copied within each asset type destination (default "vendor")		√
shim	specify or override included files by package		√
extensions	define file types to include by asset type		√
map	remap destination paths for included assets by asset type		√
replace	define regex file content replacements by asset type by package		√

#####asset type destinations

Asset Type	Path
scripts	settings.source.scripts + "/" + settings.dependencies.path
less	settings.source.less + "/" + settings.dependencies.path
sass	settings.source.sass + "/" + settings.dependencies.path
fonts	settings.build.fonts + "/" + settings.dependencies.path
images	settings.build.images + "/" + settings.dependencies.path

#####extensions example The values in extensions determines which types of files to include in the mapping operation.

            "extensions": {
                "scripts": ["js"],
                "less": ["less","css"],
                "sass": ["sass","css"],
                "fonts": ["woff","eot","ttf","svg"],
                "images": ["png","jpg","svg","gif"]
            }

#####shim example Use shim to specify which files to include from each bower package if there is no bower.json file included or to override which files to include. Attributes of the shim property should reference bower package names. The attribute values can be an array of, or a single globbing pattern or string.

        "dependencies": {
            "shim": {
                "flexslider": [
                    "flexslider.less",
                    "jquery.flexslider.js",
                    "fonts/*"
                ]
            }
        },

#####map example

Use map to copy dependencies to a specific location other than the default destination; files can also be renamed using map. Mappings must be specified per asset type and may be individual files or entire directories. All mappings are relative to the asset type's default destination directory as defined in grunt/configuration/bower.js.

map entire directory

        "dependencies": {
            "map": {
                "scripts":{
                    "package-name/": "/another-name",
                }
            }
        }

rename single file

        "dependencies": {
            "map": {
                "less":{
                    "normalize-css/normalize.css": "/normalize.less",
                }
            }
        }

#####replace example Use replace to change values within external assets. Replacements should be specifed per asset type per package name. The values should take the form RegEx Pattern (String) : replacement string

        "dependencies": {
            "replace": {
                "less":{
                    "flexslider": {
                        "url\\('fonts/": "url('/assets/fonts/vendor/flexslider/"
                    },
                }
            }
        }

###style The style attribute can be used to determine how source styles get compiled.

        "style": {
            "language": "<%= styleLanguage %>",
            "combine-media-queries": true,
            "optimize": true,
            "browsers": [
                "ie > 7",
                "Firefox > 3.5",
                "chrome > 9",
                "safari > 5"
            ],
            "files": [
            	"main"
            ]
        }

Attribute	Description	required	inheritable
language	"less" or "sass"	√	√
combine-media-queries	Boolean flag indicating whether to combine media queries (mobile first ordering) using cmq.	√	√
optimize	Boolean flag indicating whether to compress and optimize css. If set to true, css output will be optimized with cssmin	√	√
browsers	a browserlist style (https://github.com/ai/browserslist) array of browsers to autoprefix	√	√
files	an array of style source files to compile (extension omitted)	√	√

###images The images attribute can be used to determine the types of images to optimize and copy from the resource folder to the build folder.

        "images": {
            "types": "png,jpg,jpeg,gif,svg,ico"
        }

Attribute	Description	required	inheritable
types	array of image extensions to compress	√	√

###fonts The fonts attribute can be used to generate web embeddable fonts and icon fonts. All font paths are relative to the resource.fonts path.

        "fonts": {
            "engine": "node",
            "iconFontName": "IconFont",
            "families": {
                "FontFamilyOne": {
                    "normal": {
                        "200": "FontOne-Light.ttf",
                        "400": "FontOne-Regular.ttf",
                        "700": "FontOne-Bold.ttf"
                    },
                    "italic": {
                        "200": "FontOne-LightItalic.ttf",
                        "400": "FontOne-RegularItalic.ttf",
                        "700": "FontOne-BoldItalic.ttf"
                    }
                },
                "FontFamilyTwo": {
                    "normal": {
                        "400": "font-src/FontTwo-Regular.ttf"
                    }
                }
            }
        }

Attribute	Description	required	inheritable
engine	"fontforge" or "node"	√	√
iconFontName	Font name to use for generated icons	√	√
families	map source ttfs to font-family names, styles, and weights. The families attribute is required, but it can be left empty.	√	√

font family definition structure

See https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight for weight mapping suggestions.

            "families": {
            	// 0-n occurances (unique names).  
            	//Any valid css font name, PascalCase is recomended
                "FontFamilyName": {  
                	//css font-weights               
                	"normal": {
                		"100": "path/to/font.ttf",
                		"200": "path/to/font.ttf",
                		"300": "path/to/font.ttf",
                		"400": "path/to/font.ttf", //normal
                		"500": "path/to/font.ttf",
                		"600": "path/to/font.ttf",
                		"700": "path/to/font.ttf", //bold
                		"800": "path/to/font.ttf",
                		"900": "path/to/font.ttf"
                    },
                    "italic": {
						...
                    }
                    "oblique": {
                        ...
                    }
                }
                
				...
				
            }

###scripts The scripts attribute can be used to specify scripts to copy, concatenate, or compile using requireJS with or without AlmondJS.

    "scripts": {
      "jshint": true,
      "log": false,
      "comments": "some",
      "compress": true,
      "copy": [
        "**/*.js"
      ],
      "concat": [],
      "require": false,
      "almond": false
    }

Attribute	Description	required	inheritable
jshint	Boolean flag to enable or disable jshinting	√	√
log	Boolean flag to enable or disable calls to console.log	√	√
comments	String that indicates how to deal with comments when compress is true; 'some','all','none'	√	√
compress	Boolean flag to enable or disable script compression/uglification	√	√
copy	Array of file globbing patterns or file mapping objects to optimize and copy to the build folder	√	√
concat	Array of file mapping objects to concatenate, optimize and copy to the build folder	√	√
require	require configuration object or false if not using requirejs	√	√
almond	almond configuration object or false if not using almond	√	√

####scripts.require

            "require": {
                "config": "config.js",
                "modules": [
                    { "name": "main" }
                ]
            }

Attribute	Description	required	inheritable
config	Path (relative to script source) to require config	√	√
modules	Require module list (see https://github.com/jrburke/r.js/blob/master/build/example.build.js line 351 for additional deatails )	√	√

####scripts.almond

            "almond": {
                "config": "config.js",
                "main": "main",
                "out": "main.js"
            }

Attribute	Description	required	inheritable
config	Path (relative to script source) to require config	√	√
main	The main require module to include	√	√
out	The output path for the almond build	√	√