A Little Background on Pattern Lab
We touched on the reasoning for the use of Pattern Lab in the SiteFarm project in our article "An Introduction to Atomic Design and Pattern Lab in SiteFarm".
We began working with Pattern Lab as a means to quickly conceptualize and create the front-end of a website without the complexity of simultaneously building the back end. This allowed us to present a simple interactive version of a web project to a client for approval without having to complete the project. The framework is conceived around Atomic Design principles, devised by Brad Frost.
I think this pretty well sums up why we used Pattern Lab but we are going to discuss some of the details of why we organized the file structure the way we did, where to find important code, and how we develop within this environment. This is meant to be an overview of all the moving parts and we will go into more technical details in another post.
Resources and Task Managment
Our pattern lab uses two library management systems to manage and update the resources and tools needed for compiling pattern lab and providing external packages for development.
Node - We use Node Package Manager, or NPM, to get development dependencies like GULP, Auto Prefixer, and Bower.
Bower - We use Bower for both development and production library dependencies. Production libraries like jQuery, Photo Swipe, or Superfish.
Gulp - "gulp is a toolkit for automating painful or time-consuming tasks in your development workflow, so you can stop messing around and build something." - gulpjs.com. We use gulp to validate css and js, compile and watch pattern lab code, create mixin documentation, and sync code from the pattern lab into our Drupal theme.
Configuration
With all the complex tasks being managed by Gulp, we thought it best not to torture users with having to go into the /gulp_tasks directory and tweak code in order to manipulate things like paths for code to be compiled to, or turning things like theme sync on or off, so we added a .yml config file. The config file, gulp-config.yml, is a git controlled configuration file. Open it up to see all the settings available. To manipulate it locally one only needs to duplicate it, name it gulp-config--custom.yml and you now have a git ignored local configuration file that allows you to enable certain Gulp tasks to use or manipulate other available functionality. For example, if you are trying to debug why some JS isn't working on your project it probably isn't helpful that the .js is minified on the front end, so you can use your custom config file to turn off Gulp Uglify. Uglify is the action the minifies all the js code on compilation.
There are many other configurations available that will be discussed in another article.
Source Code
We strongly recommend reading the documentation for Pattern Lab. All the development in the SiteFarm pattern lab happens within the source/ directory. Within that directory you will find the following directories:
- _data: Any .json files in this directory prefixed with an underscore will provide data to the mustache template files.
- _patterns: This directory contains the .mustache templates organized in an atomic file structure(atoms, molecules, organisms, templates, pages). Notice that the page directory contains matching .json files for each page. These .json files contain the data overrides from the _data directory for page content.
- images: Add any images to this directory and feel free to organize into sub-directories.
- js: This directory contains .js files. Place vendor scripts that cannot be imported using node or bower into the /vendor folder.
- sass:
- 0_utility: The files in this directory provide mixins and classes for global things like spacing and alignment.
- 1_base_html: This contains styling for raw HTML elements like <html>, <body>, <p>, <a>, etc.
- 2_base_class: This contains styling applied to classes, not elements.
- 3_component: This contains styling specific to components like teaser, icons, facebook feed, etc.
- 4_region: This contains styling for entire regions like header and footer.
- 5_layout: This contains styling for layout options on the site.
- 6_skin: This is where you would find skins that retheme whole pages of the site.
- The rest of the files in this directory are sass variables, and files managing the compilation of all this code. This will be discussed further in another article.
Ease of Use
We have configured the SiteFarm pattern lab to be as developer friendly as possible. All the production and development dependencies are managed by NPM and Bower. This means that getting started should be as easy as cloning the Pattern Lab repository and running the NPM and Bower install commands.
After that you will have Gulp Tasks available to you. You can see the available tasks by opening the gulpfile.js in the root of the project, or some IDEs, like PHP Storm, have an interface for viewing and executing Gulp commands. Using Gulp you can now compile SASS, JS, Pattern Lab, sync theme to another destination, validate CSS and JS, and watch for changes with live reload.
One helpful package included in the build is Auto-Prefixer. When writing SASS you do not need to include vendor prefixes:
-webkit-(Chrome, Safari, newer versions of Opera, almost all iOS browsers (including Firefox for iOS); basically, any WebKit based browser)-moz-(Firefox)-o-(Old, pre-WebKit, versions of Opera)-ms-(Internet Explorer and Microsoft Edge)
Just write the property and upon compile the vendor prefixes will be created for you.
Another helpful addition is Breakpoint SASS which includes a breakpoint mixin that allows you to easily add styling based on screen size. You can dictate what styling gets applied from a specific screen width up, down, or between values, as well as dictate which rule is to be applied in browsers that do not support media queries.
The Wrap Up
So you can see there is a lot going on, but it is all for ease of development both for new and experienced developers. Once you get over the learning curve of developing in this environment you will find it an invaluable way to develop sub-themes for the SiteFarm CMS. You will find additional developer documentation within the README.md files located throughout the Pattern Lab repository.