The Node version of Pattern Lab is, at its core, a static site generator. It combines platform-agnostic assets, like the Mustache-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 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.
To run patternlab-node, just do the following from the command line at the root of patternlab-node:
npm installnpm install -g grunt-cligrunt
This creates all patterns, the styleguide, and the pattern lab site.
The following are grunt task arguments you may execute:
With no arguments, patternlab runs the full builder, compiling patterns, and constructing the front-end site.
Compile the patterns only, outputting to ./public/patterns
Retrieve the version of patternlab-node you have installed
Get more information about patternlab-node, pattern lab in general, and where to report issues.
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.
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.
The current selection is as follows. It reflects support versus patternlab-php.
"ishControlsVisible": {
"s": true,
"m": true,
"l": true,
"full": true,
"ranndom": true,
"disco": true,
"hay": true,
"mqs": false,
"find": false,
"views-all": true,
"views-annotations": true,
"views-code": true,
"views-new": true,
"tools-all": true,
"tools-follow": false,
"tools-reload": false,
"tools-shortcuts": false,
"tools-docs": true
}
patternlab.json is a file created for debugging purposes. Set debug to true in .config.json to see all the secrets.
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.
"patternStates": {
"colors" : "inprogress",
"fonts" : "inreview",
"three-up" : "complete"
}
Running grunt serve will compile the patternlab front end and host it on http://localhost:9001 by default. Page will reload on any saved source code change.
===
The Node version of Pattern Lab is maintained by @bmuenzenmeyer and contributors. Pull requests welcome, but please take a moment to read the guidelines.
Dave Olsen has published the specification for Pattern Lab ports. Development will be oriented toward compliance with this as the spec and the port mature together.
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/
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 by oscar-g.
===
(The following documentation is built for the PHP version of Pattern Lab, but most applies to the node version too. If you find omissions or mistakes please open an issue.)
Patterns are the core element of Pattern Lab. Understanding how they work is the key to getting the most out of the system. Patterns use Mustache so please read Mustache's docs as well.
- How Patterns Are Organized
- Adding New Patterns
- Reorganizing Patterns
- Including One Pattern Within Another via Partials
- Managing Assets for a Pattern: JavaScript, images, CSS, etc.
- Modifying the Pattern Header and Footer
- Using Pattern Parameters
- Using Pattern State
- "Hiding" Patterns in the Navigation
- Adding Annotations
- Viewing Patterns on a Mobile Device
The Node version of Pattern Lab utilizes Mustache as the template language for patterns. In addition to allowing for the inclusion of one pattern within another it also gives pattern developers the ability to include variables. This means that attributes like image sources can be centralized in one file for easy modification across one or more patterns. The Node version of Pattern Lab uses a JSON file, source/_data/data.json, to centralize many of these attributes.
- Introduction to JSON & Mustache Variables
- Overriding the Central
data.jsonValues with Pattern-specific Values - Linking to Patterns with Pattern Lab's Default
linkVariable - Creating Lists with Pattern Lab's Default
listItemsVariable
By default, the Pattern Lab assets can be manually generated and the Pattern Lab site manually refreshed but who wants to waste time doing that? Here are some ways that Pattern Lab can make your development workflow a little smoother:
- Watching for Changes and Auto-Regenerating Patterns - Node version coming soon
- Auto-Reloading the Browser Window When Changes Are Made - Node version coming soon
- Multi-browser & Multi-device Testing with Page Follow
- Keyboard Shortcuts
- Special Pattern Lab-specific Query String Variables
- Preventing the Cleaning of public/ - Node version coming soon
- Modifying the Pattern Lab Nav - Node version coming soon
- Editing the config.ini Options - Node version coming soon