Merge pull request #149 from pattern-lab/dev

v0.12.0

CHANGELOG

@@ -1,5 +1,16 @@
 THIS CHANGELOG IS AN ATTEMPT TO DOCUMENT CHANGES TO THIS PROJECT.
 
+PL-node-v0.12.0
+ - ADD: Gulp support arrives with an optional configuration
+ - ADD: Instructions how to install and run with Gulp
+ - DEL: Deleted the sass modules from `package.json` files
+ - CHG: Commented out all sass tasks in Grunt and Gulp files
+ - CHG: Changed static web server provider to BrowserSync
+ - CHG: Replaced the Style Guide toolbar Auto-Reload and Page Follow with a link to the BrowserSync UI
+ - THX: Thanks @oscar-g for the initial work on the gulpfile!
+ - ADD: An alternative, more verbose syntax for pattern partial inclusion
+ - THX: Thanks @e2tha-e for the thoughtful addition with unit test coverage
+
 PL-node-v0.11.0
  - ADD: Ignore pattern directories that start with an underscore.
  - ADD: Support for lists with the listItems variable

CONTRIBUTING.md

@@ -4,6 +4,9 @@ If you'd like to contribute to patternlab - node, please do so! There is always
 No pull request is too small.
 
 ##Guidelines
-1. Please keep your pull requests concise
-2. _ALWAYS_ submit it against the [dev branch](https://github.com/pattern-lab/patternlab-node/tree/dev). If this does not occur, I will first, try to redirect you gently, second, port over your contribution manually if time allows, and/or third, close your pull request.
-3. If you can, add some unit tests using the existing patterns
+1. Please keep your pull requests concise and limited to **ONE** substantive change at a time.
+2. _ALWAYS_ submit pull requests against the [dev branch](https://github.com/pattern-lab/patternlab-node/tree/dev). If this does not occur, I will first, try to redirect you gently, second, port over your contribution manually if time allows, and/or third, close your pull request.
+3. If you can, add some unit tests using the existing patterns
+
+##Coding style
+Regarding code style like indentation and whitespace, follow the conventions you see used in the source already. Add enough source code comments to help the next person.

Gruntfile.js

@@ -3,10 +3,6 @@ module.exports = function(grunt) {
 	// Project configuration.
 	grunt.initConfig({
 		pkg: grunt.file.readJSON('package.json'),
-		clean: {
-			options: { force: true },
-			files: ['./public/patterns']
-		},
 		concat: {
 			options: {
 				stripBanners: true,
@@ -63,67 +59,72 @@ module.exports = function(grunt) {
 				{ expand: true, cwd: './source/fonts/', src: '*', dest: './public/fonts/'},
 				{ expand: true, cwd: './source/_data/', src: 'annotations.js', dest: './public/data/' }
 				]
-			}
-		},
-		jshint: {
-			options: {
-				"curly": true,
-				"eqnull": true,
-				"eqeqeq": true,
-				"undef": true,
-				"forin": true,
-				//"unused": true,
-				"node": true
 			},
-			patternlab: ['Gruntfile.js', './builder/lib/patternlab.js']
+			css: {
+				files: [
+				{ expand: true, cwd: './source/css/', src: '*.css', dest: './public/css/' }
+				]
+			}
 		},
 		watch: {
-			// scss: { //scss can be watched if you like
-			//	options: {
-			//		livereload: true
-			//	},
+			all: {
+				files: [
+					'source/css/**/*.css',
+					'public/styleguide/css/*.css',
+					'source/_patterns/**/*.mustache',
+					'source/_patterns/**/*.json',
+					'source/_data/*.json'
+				],
+				tasks: ['default']
+			},
+			// scss: {
 			// 	files: ['source/css/**/*.scss', 'public/styleguide/css/*.scss'],
-			// 	tasks: ['default']
+			// 	tasks: ['sass', 'copy:css','bsReload:css']
 			// },
-			all: {
-				options: {
-					livereload: true
-				},
+			patterns: {
 				files: [
-				'source/_patterns/**/*.mustache',
-				'source/_patterns/**/*.json',
-				'source/_data/*.json'
+					'source/_patterns/**/*.mustache',
+					'source/_patterns/**/*.json',
+					'source/_data/*.json'
 				],
 				tasks: ['default']
 			}
 		},
-		sass: {
-			build: {
-				options: {
-					style: 'expanded',
-					precision: 8
-				},
-				files: {
-					'./source/css/style.css': './source/css/style.scss',
-					'./public/styleguide/css/static.css': './public/styleguide/css/static.scss',
-					'./public/styleguide/css/styleguide.css': './public/styleguide/css/styleguide.scss',
-					'./public/styleguide/css/styleguide-specific.css': './public/styleguide/css/styleguide-specific.scss'
-				}
-			}
-		},
+		// sass: {
+		// 	build: {
+		// 		options: {
+		// 			style: 'expanded',
+		// 			precision: 8
+		// 		},
+		// 		files: {
+		// 			'./source/css/style.css': './source/css/style.scss',
+		// 			'./public/styleguide/css/static.css': './public/styleguide/css/static.scss',
+		// 			'./public/styleguide/css/styleguide.css': './public/styleguide/css/styleguide.scss',
+		// 			'./public/styleguide/css/styleguide-specific.css': './public/styleguide/css/styleguide-specific.scss'
+		// 		}
+		// 	}
+		// },
 		nodeunit: {
 			all: ['test/*_tests.js']
 		},
-		connect: {
-			app:{
+		browserSync: {
+			dev: {
 				options: {
-					port: 9001,
-					base: './public',
-					hostname: 'localhost',
-					open: true,
-					livereload: 35729
+					server:  './public',
+					watchTask: true,
+					plugins: [
+						{
+							module: 'bs-html-injector',
+							options: {
+								files: './public/index.html'
+							}
+						}
+					]
 				}
 			}
+		},
+		bsReload: {
+			css: './public/**/*.css'
 		}
 	});
 
@@ -134,11 +135,15 @@ module.exports = function(grunt) {
 	grunt.task.loadTasks('./builder/');
 
 	//if you choose to use scss, or any preprocessor, you can add it here
-	grunt.registerTask('default', ['clean', 'concat', 'patternlab', /*'sass',*/ 'copy']);
+	grunt.registerTask('default', ['patternlab', /*'sass',*/ 'copy:main']);
 
 	//travis CI task
-	grunt.registerTask('travis', ['nodeunit', 'clean', 'concat', 'patternlab', /*'sass',*/ 'copy']);
+	grunt.registerTask('travis', ['nodeunit', 'patternlab']);
+
+	//TODO: this line is more efficient, but you cannot run concurrent watch tasks without another dependency.
+	//grunt.registerTask('serve', ['patternlab', /*'sass',*/ 'copy:main', 'browserSync', 'watch:patterns', 'watch:scss']);
+	grunt.registerTask('serve', ['patternlab', /*'sass',*/ 'copy:main', 'browserSync', 'watch:all']);
 
-	grunt.registerTask('serve', ['clean', 'concat', 'patternlab', /*'sass',*/ 'copy', 'connect', 'watch']);
+	grunt.registerTask('build', ['nodeunit', 'concat']);
 
 };

README.md

@@ -2,21 +2,59 @@
 
 ## About the Node Version of Pattern Lab
 
-The Node version of Pattern Lab is, at its core, a static site generator. It combines platform-agnostic assets, like the [Mustache](http://mustache.github.io/)-based patterns and the JavaScript-based viewer, with a Node-based "builder" that transforms and dynamically builds the Pattern Lab site. By making it a static site generator, the Node version of Pattern Lab strongly separates patterns, data, and presentation from build logic. The Node version is a work in progress, the [PHP version](https://github.com/pattern-lab/patternlab-php) should be seen as a reference for other developers to improve upon as they build their own Pattern Lab Builders in their language of choice.
+The Node version of [Pattern Lab](http://patternlab.io/) is, at its core, a static site generator. It combines platform-agnostic assets, like the Mustache-based patterns, the JavaScript-based viewer, and the self-contained webserver, with a Node-based "builder" that transforms and dynamically builds the Pattern Lab site.
 
-### Getting Started
+This repository contains the vanilla builder logic, grunt and gulp configurations, and some sample template/css/data to illustrate the power and flexibility of the tool.
 
-To run patternlab-node, run the following from the command line at the root of whichever directory you want to initialize your project in:
+### Download
 
-1. `npm install`
-2. `npm install -g grunt-cli`
-3. `grunt`  
+* Download the [latest release of patternlab-node](https://github.com/pattern-lab/patternlab-node/releases/latest) from Github
+* Via npm, run `npm install patternlab-node` (Note this will auto install the grunt version currently. see below)
 
-This creates all patterns, the styleguide, and the pattern lab site.
+### Choose Your Adventure! Now Vanilla, Grunt & Gulp
+
+This repository ships with two `package.json` files, a `Gruntfile.js`, and a `gulpfile.js`. The default is grunt currently. The core builder is not dependent on either.
+
+**HELP WANTED** Please help me test both of the configurations by [reporting](https://github.com/pattern-lab/patternlab-node/blob/dev/CONTRIBUTING.md) any issues encountered.
+
+### Getting Started - Grunt
+
+To run patternlab-node using grunt, do the following in the directory you downloaded and extracted the zipped release:
+
+1. Run `npm install` from the command line
+2. Optionally, delete `package.gulp.json`, `gulpfile.js`, and `builder/patternlab_gulp.js` files if you are certain you don't need it.
+* Not deleting `builder/patternlab_gulp.js` may cause a harmless error when running grunt. Delete it.
+3. Run `grunt` or `grunt serve` from the command line
+
+This creates all patterns, the styleguide, and the pattern lab site. It's strongly recommended to run `grunt serve` to see have BrowserSync spin up and serve the files to you.
+
+### Getting Started - Gulp
+
+To run patternlab-node using gulp, you need to swap out the default grunt configuration. Do the following in the directory you downloaded and extracted the zipped release:
+
+1. Rename `package.json` to `package.grunt.json` or delete it if you don't intend on going back
+2. Rename `package.gulp.json` to `package.json`
+3. Run `npm install` from the command line
+4. Run `gulp` or `gulp serve` from the command line
+
+This creates all patterns, the styleguide, and the pattern lab site. It's strongly recommended to run `grunt serve` to see have BrowserSync spin up and serve the files to you.
+
+### There and Back Again, or Switching Between Grunt and Gulp
+
+It's not expected to toggle between the two build systems, but for those migrating between the two configs, here's some general guidelines:
+
+* Make sure your `package.json` files are correct per the Getting Started sections.
+* Run `npm cache clear` before installation
+* Delete the contents of `./node_modules` if you want a cleaner installation.
+* Regarding speed, Gulp is faster. BrowserSync takes a bit longer than the old static server to spin up, but its capabilities far outweigh the startup cost.
+
+### Upgrading
+
+You can find some simple upgrade documenation in it's current home here (unreleased but confirmed to work): [https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md](https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md)
 
 ### Command Line Interface
 
-The following are grunt task arguments you may execute:
+The following are grunt/gulp task arguments you may execute:
 
 ##### `patternlab`
 With no arguments, patternlab runs the full builder, compiling patterns, and constructing the front-end site.
@@ -30,15 +68,20 @@ Retrieve the version of patternlab-node you have installed
 ##### `patternlab:help`
 Get more information about patternlab-node, pattern lab in general, and where to report issues.
 
-### Config Options
+### Further Configuration
 
 ##### Watching Changes
-To have patternlab-node watch for changes to either a mustache template, data, or stylesheets, run `grunt watch`. The `Gruntfile` governs what is watched. It should be easy to add scss or whatever preprocessor you fancy.
+To have patternlab-node watch for changes to either a mustache template, data, or stylesheets, run `grunt|gulp watch` or `grunt|gulp serve`. The `Gruntfile|Gulpfile` governs what is watched. It should be easy to add scss or whatever preprocessor you fancy.
+
+##### Preprocessor Support
+The patternlab-node release package ships with some `.scss` files utilized in the creation of the style guide and sample templates, but these are not required. The compilation tasks are commented out in the `Gruntfiles|Gulpfiles` but can be uncommented or changed to meet your needs. Sass modules are not included in `package.json` files - the prevailing thought being if you are familiar enough with preprocessors, you can use the instructions for [grunt-contrib-sass](https://github.com/gruntjs/grunt-contrib-sass) / [gulp-sass](https://github.com/dlmanning/gulp-sass) / _preprocessor of choice_ to install them. Uncomment the preprocessor configuration to fully utilize the example templates, css and style guide.
+
+**NOTE:** You may run into issues installing gulp-sass if you don't have the latest Visual Studio on Windows. See [here](https://github.com/sass/node-sass/issues/469) for more information and [this query](https://github.com/sass/node-sass/issues?utf8=%E2%9C%93&q=is%3Aissue+install) for a slew of installation problems related to gulp-sass.
 
 ##### Nav Bar Controls
-If you don't have a need for some of the nav-bar tools in the patternlab frontend, you can turn them off in `config.json`.
+If you don't have a need for some of the nav-bar tools in the Pattern Lab frontend, you can turn them off in `config.json`.
 
-The current selection is as follows. It reflects support versus patternlab-php.
+The current selection is as follows.
 
 ```
 "ishControlsVisible": {
@@ -99,11 +142,20 @@ If you'd like to exclude an individual pattern you can do so by prepending the f
 
 You can also exclude complete directories by prepending the directory name with an underscore, like: `/_experiment/...`
 
-##### Verbose Mode
+##### Debug Mode
 `patternlab.json` is a file created for debugging purposes. Set `debug` to true in `.config.json` to see all the secrets.
 
-##### Server
-Running `grunt serve` will compile the patternlab front end and host it on <a href="http://localhost:9001">http://localhost:9001</a> by default. Page will reload on any saved source code change.
+##### Server &amp; BrowserSync
+Running `grunt serve` or `gulp serve` will compile the Pattern Lab frontend and host it by default on <a href="http://localhost:3000">http://localhost:3000</a> via [BrowserSync](http://www.browsersync.io/docs/). After it starts, templates, `data.json`, and scss/css changes in your source code will be automatically injected into the page.
+
+You'll notice that if you have this open across different browsers, we do our best to keep the frontend in sync, but there is a known issue with synced navigation using the main menu.
+
+### Roadmap
+
+
+A roadmap exists for Pattern Lab Node. Check it out [here](https://github.com/pattern-lab/patternlab-node/issues/134). The Node version of Pattern Lab is maintained by [@bmuenzenmeyer](https://twitter.com/bmuenzenmeyer) and contributors. Pull requests welcome, but please take a moment to read the [guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/CONTRIBUTING.md).
+
+Dave Olsen has also published the [specification](https://github.com/pattern-lab/the-spec/blob/draft/SPEC.md) for Pattern Lab ports. Development will be oriented toward compliance with this as the spec and the port mature together. Post v1 work will focus on other pattern engines and a plugin architecture.
 
 ### Advanced Pattern Library Features
 
@@ -190,37 +242,6 @@ This would compile to:
 
 As you can see, it's a much easier way of linking patterns to one another.
 
-
-===
-
-The Node version of Pattern Lab is maintained by [@bmuenzenmeyer](https://twitter.com/bmuenzenmeyer) and contributors. Pull requests welcome, but please take a moment to read the [guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/CONTRIBUTING.md).
-
-### Upgrading
-
-You can find some simple upgrade documenation in it's current home here (unreleased but confirmed to work): [https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md](https://github.com/pattern-lab/website/blob/dev/patternlabsite/docs/node/upgrading.md)
-
-### ROADMAP
-
-A roadmap exists for Pattern Lab Node. Check it out [here](https://github.com/pattern-lab/patternlab-node/issues/134)
-
-Dave Olsen has also published the [specification](https://github.com/pattern-lab/the-spec/blob/draft/SPEC.md) for Pattern Lab ports. Development will be oriented toward compliance with this as the spec and the port mature together.
-
-### Is Pattern Lab a Platform or a Build Tool?
-
-A lot of good conversation has revolved around whether Pattern Lab is a platform or a tool in the toolbox, part of a larger solution. It's my goal to #1) adhere to the specification and #2) meet the needs of both use cases.
-
-If you want to only build the patterns, alter your `Gruntfile.js` patternlab task to the following:
-
-```
-grunt.registerTask('default', ['clean', 'concat', 'patternlab:only_patterns', /*'sass',*/ 'copy']);
-```
-
-This will output compiled patterns to ./public/patterns/
-
-### Where is the Gulp Version?
-
-The core patternlab engine is free of any dependencies to grunt, allowing users to integrate with gulp if desired. Future efforts here will orient towards [this gulp implementation](https://github.com/oscar-g/patternlab-node/tree/dev-gulp) by [oscar-g](https://github.com/oscar-g).
-
 ===
 
 ## Working with Patterns

builder/lineage_hunter.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.11.0 - 2015 
+ * patternlab-node - v0.12.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 

builder/list_item_hunter.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.11.0 - 2015 
+ * patternlab-node - v0.12.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 

builder/media_hunter.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.11.0 - 2015 
+ * patternlab-node - v0.12.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 

builder/object_factory.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.11.0 - 2015 
+ * patternlab-node - v0.12.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 

builder/parameter_hunter.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.11.0 - 2015 
+ * patternlab-node - v0.12.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 
@@ -21,12 +21,12 @@
 		function findparameters(pattern, patternlab){
 
 			//find the {{> template-name(*) }} within patterns
-			var matches = pattern.template.match(/{{>([ ]+)?([A-Za-z0-9-]+)(\()(.+)(\))([ ]+)?}}/g);
+			var matches = pattern.template.match(/{{>([ ]+)?([\w\-\.\/~]+)(\()(.+)(\))([ ]+)?}}/g);
 			if(matches !== null){
 				//compile this partial immeadiately, essentially consuming it.
 				matches.forEach(function(pMatch, index, matches){
 					//find the partial's name
-					var partialName = pMatch.match(/([a-z-]+)/ig)[0];
+					var partialName = pMatch.match(/([\w\-\.\/~]+)/g)[0];
 
 					if(patternlab.config.debug){
 						console.log('found patternParameters for ' + partialName);