Skip to content

Commit

Permalink
Merge pull request #149 from pattern-lab/dev
Browse files Browse the repository at this point in the history
v0.12.0
  • Loading branch information
Brian Muenzenmeyer committed Sep 20, 2015
2 parents 7a0b0d9 + 1192071 commit 12a40e1
Show file tree
Hide file tree
Showing 26 changed files with 592 additions and 328 deletions.
11 changes: 11 additions & 0 deletions CHANGELOG
Original file line number Diff line number Diff line change
@@ -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
Expand Down
9 changes: 6 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
109 changes: 57 additions & 52 deletions Gruntfile.js
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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'
}
});

Expand All @@ -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']);

};
113 changes: 67 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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": {
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion builder/lineage_hunter.js
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion builder/list_item_hunter.js
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion builder/media_hunter.js
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion builder/object_factory.js
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
6 changes: 3 additions & 3 deletions builder/parameter_hunter.js
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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);
Expand Down
Loading

0 comments on commit 12a40e1

Please sign in to comment.