#grunt-build

Getting Started

This configuration requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install the required configuration's plugins with this command:

npm install

Once the plugins have been installed, you can use the following commands from within the root directory

Build Targets:

default The source code. Generally this coinsides with the src/ directory. Code here is in it's least modified usable form. Transpiling should be done here, but no concatenation or minification. Most general development will be done for this build target as the location of code in source styling and logic files should be direct.

release The production code. Generally this is in the bin/ directory. Code here should be a flat and small as possible.

debug The pre-production code. Though this is built to the bin/ directory, this code should never be deployed. The primary purpose of this build target is to troubleshoot concatenation related errors obscured by minification that can't be reproduced in default.

Commands (overview):

grunt [build-target] creates a build based on the build-target:

default triggers spriting, includes and linting all within the src/ directory. The purpose of this command is for local development where optimization would slow down round-trips and concatenation would slow down debugging. Linting is included in this build-target. Before pushing code from a debug or release build, use this process to verify that all code is error-free and conforms to coding standards. For linting/validation configuration options, see: jshint, cssLint, HTML Validator.
debug triggers a build to the /bin directory without minification, but with image optimization. Use these builds to troubleshoot broken release builds.
release triggers a build to the /bin directory with minification. Use these builds for stage/test/QA/production releases where the final output of the files is expected/desired.

grunt watch:[build-target] triggers grunt [build-target] when .ghtml, .inc, .js, .css, or sprite files located in the appropriate folders are modified. The watchfiles are specified in a variable at the top of the gruntfile.

Basically grunt watches for changes to .ghtml files anywhere in src/ and .inc inside of src/inc/ or any subfolder therein. .css and .js files are watched when located below their respective src/ui/css/ or src/ui/js/ directories. Sprite images can trigger a buid if added or changed within the sprite directory (src/ui/img/sprites/)

See the gruntfile for more specifics or to modify these filenames etc.

grunt server[build-target] Runs a webserver and watch simultaneously with slight differences based on the build-target

default runs the default watch and creates an http server on localhost:3000 with it's root in the src directory. The intention of this process is for development providing linting, spriting and serving without the overhead of image optimization and the translation of concatenation or obfuscation
debug runs the debug watch alongside default watch and creates http servers: one for the debug build on localhost:3030 with it's root in ../bin directory and one for the default build on port 3000 as above.
release runs the release watch alongside default watch and creates http servers: one for the release build on localhost:3030 with it's root in ../bin directory and one for the default build on port 3000 as above.

for additional commands (copy, concat, processhtml, sprite etc.) see the gruntfile

File Structure:

==================

The purpose of this project has been to provide a build process within VML's SVN structure. Due to the disclusion of the htdocs folder the build process is conflated and confusing to newcomers. Therefore, builds are made to a bin folder that is then able to be copied into the ../htdocs folder via grunt copy:to_htdocs or by uncommenting this line in the release task.

When using this code, create a trunk/frontend directory in your SVN checkout and put the contents of this project clone there. The process will then build the deployment code to the trunk/frontend/bin folder and will then copy to the trunk/htdocs folder through the use of the code above.

The paths described below are constructed from the base and paths variables defined at the top of the gruntfile. Changes to the paths or base folder names can be made globally within these variables.

.
├─ frontend (grunt-build root folder)
│    ├─ src
│    │    ├─ inc
│    │    └─ ui
│    │       ├─ css
│    │       ├─ img
│    │       │   └─ sprites
│    │       └─ js
│    │           ├─ v
│    │           └─ plugins
│    ├─ bin (output files mirror of `front-end/src` with concatenated js & css)
│    │
│    ├─ Gruntfile.js
│    └─ package.json
│
└─ htdocs (`grunt copy:to_htdocs` will produce a copy of `frontend/bin` here)

frontend/src/inc Includes are expected to be stored here. These are added statically via processHTML to files that require them. In the interest of simplicity, files that require includes should be named with the extension .ghtml. For example: index.ghtml. The .ghtml extension (for grunt parsed HTML) was invented to follow the precident of .shtml (or server-parsed HTML). Without this extension, include deendencies are not processed by default configuration.

Includes can have whatever extension you desire, however, the convention has been to call name them with the .inc extension. If you wish to use a different extension remember to change the extension in the watchfiles variable to get watch to register the files.

All includes that are referenced regardless of where they are located are referenced from the src/ directory. So, inc/scripts.inc not src/inc/scripts.inc or ../../scripts.inc. Output files have .html as an extension. WARNING for this reason, be sure not to name custom unparsed HTML files with the same name as files using the .ghtml extension. For example landing_page.ghtml and landing_page.html. Grunt in this case will overwrite landing_page.html. All non-.ghtml.html files are copied to bin in release builds either by copy or by htmlmin.

frontend/src/ui theming assets (css, images, fonts) and application javascript are stored here. In the interest of separation of theme and content, it is suggested that images as content and multi-media be stored elsewhere. Modify imagemin configuration in the gruntfile if needed.

frontend/src/ui/img images consumend by the css as "themeing elements" should live here. Images found here will be optimized in debug and release builds.

frontend/src/ui/img/sprites sprite images housed here are compiled into src/ui/img/spritesheet.png. This folder is not included in debug and release builds.

frontend/src/ui/css self explanitory. A simple CSS reset is included here for testing. Feel free to replace it if you feel strongly about it. By default all css files here are concatenated and minified. To specify the order these are added to the concatenated file, edit the "Concat" portion of the gruntfile. Also, for media specific or "one-off" files, exclude them from the "Concat" section and add them to the "Copy" or "Minification" sections.

frontend/src/ui/js javascript directory. Feel free to create additional organization here -- may require some configuration in the gruntfile. By default all js files here are concatenated and uglified. To specify the order these are added to the concatenated file, edit the "Concat" portion of the gruntfile. Also, for polyfills or platform/page specific "one-offs", the files will need to be excluded in the "Concat" section and added to the "Copy" or "Uglification".

frontend/src/ui/js/v javascript 3rd party libraries and frameworks go here. See above for caveats.

frontend/src/ui/js/plugins javascript plugins for libraries 3rd or 1st party should be here. See above for caveats. For convenience there is a commented suggestion in the gruntfile to ignore concating the src/ui/js/plugins directory when using require for instance.

Spriting:

Name the image files the same as the selectors they will be used for. the grunt spritesmith task will use this to generate the CSS selector for each sprite. for instance a.nav-item.png will become

a.nav-item{
    background-image:...
}

To avoid file-system restrictions, in order to start a selector with a class name, use an underscore _ instead of a dot . ONLY IN THE BEGINNING i.e. for the selector: .class1 .class2 name your .png: _class1 .class2.png.

Likewise, for pseudo classes, use a carat ^ in the filename instead of a colon :. For the selector: a:hover use: a^hover.png. In *nix environments colons are permitted in filenames, however this is forbidden in Windows and is generally confusing when using a network protocol (SSH/FTP etc.).

UPDATES

==========

Many things have changed in this build.

A server running on port 3000 or 3030 has been added in coordination with the watch so a single process can allow watch and serve files.
HTML minification has been added as an option
CSS Liniting has been laxed to break builds almost only on syntax errors
Builds happen within the project filesystem to allow for more flexibility project-to-project

Several breaking changes have occurred in this version due to a reorganization of the folder structure for a clearer build path. Additionally the naming of include-bearing html files has changed as well. See below:

Renamed the folders so there is a src/ and bin/. release will include a copy to the ../htdocs/ directory if desired, but the server will run from the bin to keep the build process independent of SysOps/WebOps SVN structure and allowing us to experiment with changes locally without affecting the ../htdocs directory.
CSS Minification allows a "backdoor" to creating multiple HTTP requests and the copy is placing unminified css in the release package -- worth considering changing. I applaud the flexibility in file naming, but the postfix ("_min.css") is still appended to the name, making flexibility slightly less helpful. Additionally the debug and release comments in the default code has the old hard-coded names ('all.css' and 'all_min.css'). So, this could change in the future.
Need to revisit the need to have a debug watch. The purpose of debug (and it's subsequent demand) should not require more than an occasional one-off build. The server entry does make sense as the files will need to be served to be viewed without configuring Apache/IIS/nginx.
ProcessHTML modified so all tasks build from .ghtml (not .inc.html -- who wants to type all that???)
debug builds HTML to the bin folder and release and dev both build HTML to the src folder so that HTMLminification can produce the html files in the bin.
Fixed inconsistent quotes
Added additional laxing in CSS Linter
Provided a COPY related booby hatch for production code in the event Wes needs to be able to read the code.
Removed "Chrome=1" from X-UA-Compatible meta since support for chromeframe is not often requested and the longer form of the content value fails W3C Validation. The project should pass validation out-of-the-box and features like chromeframe shuld be on a per-project basis