Merge pull request #96 from pattern-lab/dev

Merging changes for patternlab 0.8.0

CHANGELOG

@@ -1,5 +1,21 @@
 THIS CHANGELOG IS AN ATTEMPT TO DOCUMENT CHANGES TO THIS PROJECT.
 
+PL-node-v0.8.0
+ - CHG: note the change in versioning to proper semver. wanted to do ths to inch closer to a 1.0.0 release
+ - DEL: deleted most of the lingering PHP sync listener code
+ - FIX: support for displaying the HTML and Mustache in the code viewer
+ - ADD: pattern link support
+ - CHG: updated included mustache templates to reflect pattern links in navigation and compiling pages direct from templates
+ - THX: @getsetbro for finding and fixing a typo
+ - FIX: fixed a bug preventing pattern states from displaying on the flat template/pages
+ - ADD: support for basic pseudo-patterns
+
+PL-node-v0.1.7
+ - ADD: pattern export
+ - CHG: updated devDependencies
+ - FIX: fixed a type in the README and config
+ - THX: thanks @seanhussey for the pull request!
+
 PL-node-v0.1.6
  - ADD: media queries found in css added to ish controls
  - ADD: basic lineage support

Gruntfile.js

@@ -31,6 +31,10 @@ module.exports = function(grunt) {
 			patternlab_grunt: {
 				src: './builder/patternlab_grunt.js',
 				dest: './builder/patternlab_grunt.js'
+			},
+			pattern_exporter: {
+				src: './builder/pattern_exporter.js',
+				dest: './builder/pattern_exporter.js'
 			}
 		},
 		copy: {
@@ -59,6 +63,9 @@ module.exports = function(grunt) {
 		},
 		watch: {
 			// scss: { //scss can be watched if you like
+			//	options: {
+			//		livereload: true
+			//	},
 			// 	files: ['source/css/**/*.scss', 'public/styleguide/css/*.scss'],
 			// 	tasks: ['default']
 			// },
@@ -83,7 +90,8 @@ module.exports = function(grunt) {
 				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.css': './public/styleguide/css/styleguide.scss',
+					'./public/styleguide/css/styleguide-specific.css': './public/styleguide/css/styleguide-specific.scss'
 				}
 			}
 		},

README.md

@@ -6,7 +6,7 @@ The Node version of Pattern Lab is, at its core, a static site generator. It com
 
 ### Getting Started
 
-To run patternlab-node, just do the following from the command line at the root of patternlab-node: 
+To run patternlab-node, run the following from the command line at the root of whichever directory you want to initialize your project in: 
 
 1. `npm install`
 2. `npm install -g grunt-cli`
@@ -46,7 +46,7 @@ The current selection is as follows. It reflects support versus patternlab-php.
 	"m": true,
 	"l": true,
 	"full": true,
-	"ranndom": true,
+	"random": true,
 	"disco": true,
 	"hay": true,
 	"mqs": false,
@@ -62,10 +62,6 @@ The current selection is as follows. It reflects support versus patternlab-php.
 	"tools-docs": true
 }
 ```
-
-##### Verbose Mode
-`patternlab.json` is a file created for debugging purposes. Set `debug` to true in `.config.json` to see all the secrets.
-
 ##### Pattern States
 You can set the state of a pattern by including it in `config.json` too. The out of the box styles are in progress (orange), in review (yellow), and complete (green).
 Pattern states should be lowercase and use hyphens where spaces are present.
@@ -77,6 +73,85 @@ Pattern states should be lowercase and use hyphens where spaces are present.
 }
 ```
 
+##### Pseudo-Patterns
+Pseudo-patterns are meant to give developers the ability to build multiple and unique **rendered** patterns off of one base pattern and its mark-up while giving them control over the data that is injected into the base pattern. This feature is especially useful when developing template- and page-style patterns.
+
+Pseudo-patterns are, essentially, the pattern-specific JSON files that would accompany a pattern. Rather than require a Mustache pattern, though, pseudo-patterns are hinted so a developer can reference a shared pattern. The basic syntax:
+
+`patternName~pseudoPatternName.json`
+
+The tilde, `~`, and JSON extension denotes that this is a pseudo-pattern. `patternName` is the parent pattern that will be used when rendering the pseudo-pattern. `patternName` and `pseudoPatternName` are combined when adding the pseudo-pattern to the navigation.
+
+The JSON file itself works exactly like the [pattern-specific JSON file](http://patternlab.io/docs/data-pattern-specific.html). It has the added benefit that the pseudo-pattern will also import any values from the parent pattern's pattern-specific JSON file. Here is an example (which ships with the package) where we want to show an emergency notification on our homepage template. Our `03-templates/` directory looks like this:
+
+```
+00-homepage.mustache
+01-blog.mustache
+02-article.mustache
+```
+
+Our `00-homepage.mustache` template might look like this:
+
+```
+<div id="main-container">
+    {{# emergency }}
+        <div class="emergency">Oh Noes! Emergency!</div>
+    {{/ emergency }}
+    { ...a bunch of other content... }
+</div>
+```
+
+If our `_data.json` file doesn't give a value for `emergency` that section will never show up when `00-homepage.mustache` is rendered.
+
+We want to show both the regular and emergency states of the homepage but we don't want to duplicate the entire `00-homepage.mustache` template. That would be a maintenance nightmare. So let's add our pseudo-pattern:
+
+```
+00-homepage.mustache
+00-homepage~emergency.json
+01-blog.mustache
+02-article.mustache
+```
+
+In our pseudo-pattern, `00-homepage~emergency.json`, we add our `emergency` attribute:
+
+```
+{
+    "emergency": true
+}
+```
+
+Now when we generate our site we'll have our homepage template rendered twice. Once as the regular template and once as a pseudo-pattern showing the emergency section. Note that the pseudo-pattern will show up in our navigation as `Homepage Emergency`.
+
+##### Pattern Linking
+You can build patterns that link to one another to help simulate using a real website. This is especially useful when working with the Pages and Templates pattern types. The basic format is:
+
+`{{ link.pattern-name }}`
+
+For example, if you wanted to add a link to the `home page` template from your `blog` template you could write the following:
+
+`<a href="{{ link.templates-homepage }}">Home</a>`
+
+This would compile to:
+
+`<a href="/patterns/templates-homepage/templates-homepage.html">Home</a>`
+
+As you can see, it's a much easier way of linking patterns to one another.
+
+
+##### Pattern Export
+`config.json` also has two properties that work together to export completed patterns for use in a production environment. Provide an array of keys and an output directory. Pattern Lab doesn't ship with any pattern export keys, but the default directory is `"./pattern_exports/"` created inside the install directory. 
+
+```
+"patternExportKeys": ["molecules-primary-nav", "organisms-header", "organisms-header"],
+"patternExportDirectory": "./pattern_exports/"
+```
+
+Coupled with exported css (much easier to extract with existing tools like [grunt-contrib-copy](https://github.com/gruntjs/grunt-contrib-copy)), pattern export can help to maintain the relevancy of the design system by directly placing partials in a directory of your choosing.
+
+
+##### Verbose 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.
 

builder/lineage_hunter.js

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

builder/media_hunter.js

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

builder/object_factory.js

@@ -1,5 +1,5 @@
 /* 
- * patternlab-node - v0.1.6 - 2014 
+ * patternlab-node - v0.8.0 - 2015 
  * 
  * Brian Muenzenmeyer, and the web community.
  * Licensed under the MIT license. 
@@ -11,18 +11,19 @@
 (function () {
 	"use strict";
 
-	var oPattern = function(name, subdir, filename, data){
-		this.name = name; //this is the unique name with the subDir
+	var oPattern = function(subdir, filename, data){
+		this.fileName = filename.substring(0, filename.indexOf('.'));
 		this.subdir = subdir;
-		this.filename = filename;
-		this.data =  data;
-		this.template = '';
-		this.patternPartial = '';
-		this.patternName = ''; //this is the display name for the ui
-		this.patternLink = '';
-		this.patternGroup = name.substring(name.indexOf('-') + 1, name.indexOf('-', 4) + 1 - name.indexOf('-') + 1);
+		this.name = (subdir.replace(/[\/\\]/g, '-') + '-' + this.fileName).replace(/\\/g, '-'); //this is the unique name with the subDir
+		this.data =  data || null;
+		this.patternName = this.fileName.substring(this.fileName.indexOf('-') + 1); //this is the display name for the ui
+		this.patternLink = this.name + '/' + this.name + '.html';
+		this.patternGroup = this.name.substring(this.name.indexOf('-') + 1, this.name.indexOf('-', 4) + 1 - this.name.indexOf('-') + 1);
 		this.patternSubGroup = subdir.substring(subdir.indexOf('/') + 4);
 		this.flatPatternPath = subdir.replace(/\//g, '-');
+		this.key = this.patternGroup + '-' + this.patternName;
+		this.template = '';
+		this.patternPartial = '';
 		this.lineage = [];
 		this.lineageIndex = [];
 		this.lineageR = [];

builder/pattern_assembler.js

@@ -1,5 +1,35 @@
 (function () {
-	"use strict";
-
+  "use strict";
+
+  var fs = require('fs-extra'),
+      path = require('path');
+
+  var pattern_assembler = function(){
+
+    function setState(pattern, patternlab){
+      if(patternlab.config.patternStates[pattern.patternName]){
+        pattern.patternState = patternlab.config.patternStates[pattern.patternName];
+      } else{
+        pattern.patternState = "";
+      }
+    }
+
+    function addPattern(pattern, patternLab){
+      patternLab.data.link[pattern.patternGroup + '-' + pattern.patternName] = '/patterns/' + pattern.patternLink;
+      patternLab.patterns.push(pattern);
+    }
+
+    return {
+      setPatternState: function(pattern, patternlab){
+        setState(pattern, patternlab);
+      },
+      addPattern: function(pattern, patternLab){
+        addPattern(pattern, patternLab);
+      }
+    };
+
+  };
+
+  module.exports = pattern_assembler;
 
 }());

builder/pattern_exporter.js

@@ -0,0 +1,48 @@
+/* 
+ * patternlab-node - v0.8.0 - 2015 
+ * 
+ * Brian Muenzenmeyer, and the web community.
+ * Licensed under the MIT license. 
+ * 
+ * Many thanks to Brad Frost and Dave Olsen for inspiration, encouragement, and advice. 
+ *
+ */
+
+(function () {
+  "use strict";
+
+  var fs = require('fs-extra'),
+      path = require('path');
+
+  var pattern_exporter = function(){
+
+    function exportPatterns(patternlab){
+
+      //read the config export options
+      var exportKeys = patternlab.config.patternExportKeys;
+
+      //find the chosen patterns to export
+      for (var i = 0; i < exportKeys.length; i++){
+        for (var j = 0; j < patternlab.patterns.length; j++){
+          if(exportKeys[i] === patternlab.patterns[j].key){
+            //write matches to the desired location
+            fs.outputFileSync(patternlab.config.patternExportDirectory + patternlab.patterns[j].key + '.html', patternlab.patterns[j].patternPartial);
+          }
+        }
+      }
+
+
+
+    }
+
+    return {
+      export_patterns: function(patternlab){
+        exportPatterns(patternlab);
+      }
+    };
+
+  };
+
+  module.exports = pattern_exporter;
+
+}());