SiteFarm Pattern Lab: The Technical Stuff

Pattern Lab Technical Stuff

Cloning From BitBucket

Clone the most recent version of the SiteFarm Pattern lab from the BitBucket code repository. Cloning with git is recommended, but you can do a simple download if you are not ready for that next level dev awesomeness.

Clone Now!

System Dependencies

Installation of Node.js is required in order to begin installing SiteFarm Pattern Lab Dependencies.

Download Node.js

Either the latest or recommended version is fine.

Now you need install Gulp and Bower globally. Open a command line interface and change directories to the root of the project and run.

$ sudo npm install --global gulp bower

Installing Pattern Lab Dependencies

Installing the development and production dependencies for using pattern lab requires NPM (Node Package Manager). In order to use NPM you will need to install Node.js. After installing Node.js globally you will have access to NPM within the Pattern Lab root directory. After running npm install from the root of the Pattern Lab you will have a new directory named node_modules which contains all the dependencies installed by NPM. One of those dependencies is Bower. Now that you have Bower installed you can run the bower install command and it will create another directory named bower_components and install another set of dependencies.

Run:

$ npm install

$ bower install

If you choose, you may install additional dependencies using either Bower or NPM.

$ bower install {thing} --save

$ bower install {thing} --save-dev

or

$ npm install {thing} --save

$ npm install {thing} --save-dev

Using the --save-dev will exclude it from being compiled for production.

More Info

Gulp Configuration

In the root of the Pattern Lab repo you will find a gulp-config.yml. This file contains all the paths and settings for gulp to carry out all of its tasks, like validating, compiling, and serving code. Do not make edits to this file unless you intend make those changes for everyone. If you need to change any of these settings locally for your own development, create a file in the same directory named gulp-config--custom.yml. In this file you can copy any of the YAML key/value pairs from the gulp-config.yml and paste them into your new custom config file.

Lets take a look at the css config:

  • css
    • enabled - Boolean value that will enable or disable css related Gulp tasks.
    • src - The location of all files to compile from SCSS to CSS. Notice the use of asterisks in the source path, source/sass/**/*.scss. This path is using gulp-sass-glob to get all files ending in .scss from all folders in source/sass.
    • vendor - List of vendor CSS files to include in compilation.
    • dest - The location to place the compiled CSS.
    • flattenDestOutput - Boolean value for minification of compiled CSS.
    • lint
      • enabled - Boolean to turn CSS code validation on or off.
      • failOnError - Boolean to stop code from compiling if it does not validate.
      • extraSrc - Add paths to files that you would like to be included in CSS validation. You may exclude files from this process by placing them here, but prefixing the path with an exclamation point. This is the boolean NOT operator also called negation.
    • sourceComments - Boolean to leave or strip comments from the compiled CSS code.
    • sourceMapEmbed - Boolean for adding CSS source maps for in browser SASS debugging.
    • outputStyle: Tell the compiler whether you want "expanded" or "compressed" output code.
    • autoPrefixerBrowsers: List browsers you would like vendor prefixes generated for. https://github.com/ai/browserslist#queries
    • sassdoc: Settings for generated SASS documentation. http://sassdoc.com
      • enabled: Boolean to generate SASS Docs.
      • dest: Destination for SASS Documentation code.
      • verbose: Boolean value to enable or disable verbose mode
      • basePath: The SASS base path from the public repository. Notice in the config file this has a child element of "exclude" that you can use to exclude files from this base path.
      • theme: Set the theme to be used to display the SASS Docs. We are using "default".
      • sort: Set the sort order of the documentation. http://sassdoc.com/customising-the-view/#sort

Now lets take a look at the JavaScript config.

  • js
    • enabled: Boolean value enabling or disabling js Gulp tasks
    • src: A list of locations to find JS files. Notice the use of the file globbing technique here.
    • dest: The destination for compiled JS file.
    • destName: The file name you would like used for the compiled JS file.
    • sourceMapEmbed: Boolean value to enable JS source maps.
    • uglify: Boolean value to minify destination JS file.
    • eslint: Settings related to JS validation.
      • enabled: Boolean value to enable JS validation.
      • failAfterError: Boolean value to allow js to compile if it doesn't validate.
      • extraSrc: List of files to include or exclude from validation. This is useful for excluding code you didn't write, therefore have no authority to change to meet validation criteria.

Moving onto the image configuration.

  • images:
    • src: File path to where to find images.
    • dest: File path to where to place images.

Now lets look at the settings for the Bower Files.

  • bowerFiles:
    • enabled: Boolean value for compiling Bower files.
    • dir: Path to Bower file directory.
    • includePaths: List of bower directory paths to look for .scss files.

Browser Sync allows you to watch your changes happen in the browser as you develop. It also allows you to share your browser with others via a network.

  • browserSync:
    • enabled: Boolean value to turn on Browser Sync as part of the "watch" Gulp task.
    • port: The port on which to serve the the site locally.
    • watchFiles: Define specific files to watch.
    • domain: Specify a domain at which serve the files in the browser.
    • baseDir: Specify the base directory.
    • startPath: The path at which to open the browser. This path gets appended to the "domain".
    • openBrowserAtStart: Boolean value to allow browser to be automatically opened when "watch" task is initiated.
    • browser: List the browser you would like to be used when a browser is opened automatically.
    • reloadDelay: Time, in milliseconds, to wait before instructing the browser to reload/inject following a file change event
    • reloadDebounce: Wait, in milliseconds, for a specified window of event-silence before sending any reload events.

The Theme Sync configuration for migrating source files to another project. Once migrated they need to be compiled into dev or production code for that project.

  • themeSync:
    • enabled: Boolean value to turn enable "themesync" Gulp task.
    • newsite: Boolean value. If set to true when the "themesync" task is run it will not only move over the source files, but it will build the system for compiling code in your new project.
    • src: False if exporting, or a file path to the source if importing.
    • dest: Path to the theme directory or new site. Make sure the path ends in a /.
    • sassSrc: Path to find the SASS.
    • sassDest: Path to place the SASS in destination.
    • imagesSrc: Path to find the images.
    • imagesDest: Path to place the images in destination.

And finally configuration to allow Gulp to build the public pattern lab files from source.

  • patternLab:
    • enabled: Boolean value to allow Gulp to build the pattern lab.

View Config File

Also see the Local Gulp Configuration section of the README.md.

Gulp Tasks

PHP Storm Gulp Task Interface
PHP Storm - Gulp Task Interface

Depending on how you configured the gulp-config.yml you will have a number of tasks available to you. If you have an IDE(Integrated Development Environment) with a Gulp task interface you can use that, otherwise you will need to run your gulp tasks from a command line. When running Gulp commands from the command line, type "gulp" and the name of the task you wish to run. e.g. $ gulp defualt. If you are using PHP storm you can right click on the gulpfile.js and choose "Show Gulp Tasks" and it will open a handy little interface.

If you have all of the Gulp tasks enabled then you will have the follow available to you from the command line.

  • help - Running $ gulp help in your command line will show you a list of available Gulp tasks and their descriptions, much like this list you are reading.
  • default - Generate the entire site and start watching for changes [compile, serve, watch].
  • patternlab - Compile Patternlab patterns into html.
  • watch:markup - Watch changes to markup only.
  • newsite - Start a new site with gulp and config wired up.
  • themesync - Export Patternlab source files to a website theme.
  • serve - Create a local server using BrowserSync
  • js - Compile javascript (including Bower libraries), concat and uglify into a single scripts.js file.
  • validate:js - Lint JS using ESlint
  • watch:js - Watch changes to js only.
  • sass - Compile Sass to CSS using Libsass with Autoprefixer and SourceMaps.
  • css:vendor - Compile all vendor css (including Bower) into a single vendor.css file.
  • validate:css - Lint Sass files with Sass-lint.
  • docs:css - Build CSS docs using SassDoc.
  • watch:css - Watch changes to css only.
  • compile - Generate the entire site [patternlab, js, sass, css:vendor, docs:css].
  • validate - Validate CSS and JS by linting [validate:js, validate:css].
  • watch - Watch for changes to files [watch:markup, watch:js, watch:css].

The important tasks to note here are the ones that run multiple sub-tasks as they are designed to me development easier.

  • default - This will run [compile, serve, watch] and will likely be your go to task when developing locally.
  • validate - You can use this to do a quick validation of you code and make sure you are using best practices and matching your code style to the rest of the standards for this pattern lab.
  • compile - This is useful when you don't need to do anymore development and you just want to compile all the code for production. Often used after changing your local config file to uglify CSS and JS, but before sync'n to its final destination [patternlab, js, sass, css:vendor, docs:css].

Best Practices

SiteFarm Pattern Lab consists of data, dependencies, elements, patterns, JS, and CSS. Let's take a look at building in pattern lab using these pieces.

Javascript

Javascript libraries should be added via Bower or NPM. Some vendor files, such as the customized Modernizr.js file gets put into the vendor directory at /source/js/vendor/. The rest of your JS will go into /source/js/ and likely coincide with an html pattern. Name your JS files to match the pattern it goes to. For example say you have a pattern called primary-nav. Your assets for this component might look like this:

  • Pattern: /source/_patterns/01-molecules/05-navigation/00-primary-nav@complete.mustache
  • JS: /source/js/primary-nav.js
  • SASS: /source/sass/3_component/_nav-primary.scss *

* Note that in this example the Primary Navigation SASS file is called "nav-primary" instead of "primary-nav". Normally it would be preferable to keep the naming consistent, but an exception was made here in order to keep all the navigation together in the file structure by prefixing it with "nav-".

If adding additional JS files you will want to use the following as a template:

(function ($) {
  'use strict';

  $(document).ready(function () {

    // Write JS here.

  });

})(jQuery); // end jquery enclosure

As mentioned in the section on Gulp, you can run $ gulp validate:js to validate your code. Also, please read:

Read the README.md

Syntactically Awesome Style Sheets!

Also known as SASS.

Sass is the most mature, stable, and powerful professional grade CSS extension language in the world.

We use SASS as the language to write our front end css because it allows us to organize and write our styling using more advanced programming concepts. SASS allows the use of variables, nesting, loops, and functions known as mixins.

The SASS found in the SiteFarm Pattern Lab is as follows:

  • source/sass/
    • 0_utility/ The files in this directory provide mixins and classes for 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 put skins that re-theme whole pages of the site.
    • _hacks.scss This is really meant to be a temporary file for styling which needs to be added quickly or whose final destination is undecided. Clean out this file regularly.
    • _variable.scss A list of global variables defining colors, breakpoints, spacing, and more.
    • no-query.scss A list of SASS file imports gathering the above assets but excluding media queries for legacy browsers.
    • style.scss A list of SASS file imports gathering the above assets. This and no-query.scss are the only style files that get processed by Gulp from the source/sass/ directory.

When writing SASS try to adhere to BEM(Block, Element, Modifier) syntax. It lends itself to the nested nature of SASS and helps keep components modular. See the section "An Important Concept" in the An Introduction to Atomic Design and Pattern Lab in SiteFarm article for an example of how to develop a component using BEM Syntax.

IMPORTANT: When writing styles that are not in the source/sass/1_base_html/ directory try not to target HTML elements directly. So if a teasers body text is wrapped in a <p>, don't target .teaser p, give the paragraph a class, like teaser__body and target the class. This will maintain the integrity of the order of specificity we have worked hard to create here allowing the system to grow.

README.md

Patterns

This Pattern Lab uses Mustache templates to create patterns. Patterns are located in source/patterns/, and are organized using atomic design principals then further organized by type. Mustache uses .json files to incorporated data into its templates. The main data file for SiteFarm Pattern Lab is /source/_data/_data.json and any additional .json file added to the /source/_data/ directory that begins with an underscore will added to the data available to templates. The data can be simple variable assignments to be called in a template or it can be a nested array of data to be looped through in the template files.

Looking at the /source/_patterns/01-molecules/03-media/00-figure-with-caption@complete.mustache pattern as an example you can see that {{ figcaption }} is a simple variable pulled from the data.json file. Also note the mustache element {{> atoms-landscape-4x3 }} as this is the syntax for including another pattern within your pattern.

<figure> {{> atoms-landscape-4x3 }} <figcaption>{{ figcaption }}</figcaption> </figure>

Now lets look at the /source/_patterns/02-organisms/03-sections/00-latest-news@complete.mustache pattern. It uses a JSON data structure to create a pattern that is able to loop trough an array to create the output.

<section class="latest-news">

  {{# latest-news }}

     {{> molecules-teaser(teaser-byline: true, teaser-categorized: true) }}

  {{/ latest-news }}

  {{> molecules-pagination }}

</section>

This mustache syntax {{# latest-news }} denotes the start of a loop and {{/ latest-news }} ends it. Now lets look at the data for latest-news found in the _data.json file. You will see that latest news is an array of 6 empty items except for an additional boolean is being set for two of those items to flag it as featured. The featured data gets passed into those patterns as they are output.

"latest-news": [

{},

{ "featured": true },

{},

{},

{},

{ "featured": true }

]

Looking at the teaser pattern you can see that the featured data is being used to add or exclude the class vm-teaser--featured.

<article class="o-media vm-teaser {{# featured }}vm-teaser--featured{{/ featured }} {{ brand-class }} {{ styleModifier }}">

There are many more details to know when creating patterns. For more information about how patterns work please read the Pattern Lab documentation where you can find more info on important features such as Style Modifiers, Pattern States, Annotations, and Pattern Parameters.

Pattern Lab Docs

    Images

    What website isn't complete without images. You may place images in /source/images/ or any sub-directory of. Upon completion of the $ gulp images task, all images are duplicated into the /public/images/ directory.

    In Summary

    The SiteFarm Pattern Lab contains SiteFarm's front end code along with a system for managing it's dependencies and development. The dependencies are managed via Bower and Node, while Gulp is used to provide the tools and tasks for development in the Pattern Lab interface and export to another project. Pattern Lab itself merely provides a system for building patterns and displaying them to be tested, evaluated, and documented.

    Category

    Tags