Prerequisites

Node v4 OR v6 (the two LTS versions)
PHP 5.4, 5.5, 5.6, OR 7 (5.3 might work, no promises)
composer

QuickStart

npm install # or `yarn install` if you want 3x the speed
npm start

If you're using Drupal 8, get the Component Libraries module:

drush dl components
drush en components -y

That's it.

Commands

Compile everything:

npm run compile

Start up watches and local server after compiling:

npm run start # or `npm start`

Protip: any config option from gulpconfig.yml can be overwritten with npm start -- --js.enabled='', or by including options in your own ~/.p2-theme-corerc file. See rc for more details.

Run Tests:

npm run test # or `npm test`

Create a new component folder in Pattern Lab with scss, twig, md, & yml/json by running:

npm run new

To update node and composer dependencies (if you see messages about Pattern Lab wanting to Merge or Replace files, merge them):

npm run update

Orientation

source/
- _annotations/ (annotations for Patterns)
- _data/ (Global JSON data files available to all Patterns, can add multiple)
- _patterns/ (Twig, Scss, and JS all in here)
  - 00-base/ (Twig Namespace: @base)
    - Contains what all that follows needs: variables, mixins, and grid layouts for examples
  - 01-atoms/ (Twig Namespace: @atoms)
  - 02-molecules (Twig Namespace: @molecules)
  - 03-organisms (Twig Namespace: @organisms)
  - 04-templates (Twig Namespace: @templates)
  - 05-pages (Twig Namespace: @pages)
- _meta/ (contains the header and footer Twig templates for PL; add any <link> or <script> tags here; don't edit in between the  tags though; it'll get overwritten)
pattern-lab/
- config/config.yml (Pattern Lab configuration)
- public/ (Where Pattern Lab compiles too, it's just static HTML)
- composer.json (run composer update next to this to update dependencies)
scss/ - Sass files that aren't really tied to a component, so not in the above location.
js/ - all js files here and transpiled by Babel and combined into a single dest/script.js file.
images/icons/src/ - all SVGs here are combined into font icons and have classes and Sass mixins made for each based on file name. See atoms/images/icons in Pattern Lab.
dest/ - Many compiled assets end up in here like CSS, JS, Font Icons, and any doc systems like SassDoc.
templates/ - Drupal twig templates. These often will include, embed, or extend the Twig templates found in Pattern Lab like this: {% include "@molecules/branding/branding.twig" with { url: path('<front>') } %}. We keep the components in Pattern Lab "pure" and ignorant of Drupal's data model and use these templates to map the data between the two. Think of these as the Presenter templates in the Model View Presenter approach. Also, Drupal Twig templates that have nothing to do with Pattern Lab go here.
gulpconfig.yml - Configuration for all the gulp tasks, a ton can be controlled here.

IDE/Text Editor Setup

Install an EditorConfig plugin
Ignore the indexing of these directories:
- node_modules/
- bower_components/
- dest/
- pattern-lab/public/
- pattern-lab/vendor/

Details

Pattern Lab

Refer to the Pattern Lab Documentation for extensive info on how to use it. This theme starter is a custom Pattern Lab 2 Edition that is heavily influenced by the Drupal Edition of Pattern Lab and uses the Twig engine to bring it inline with Drupal 8's use of Twig.

Folder Structure Differences

Our folder structure makes a slight but convenient alteration to the typical Pattern Lab folder setup. Basically we move pattern-lab/source/ up one level because we keep Sass in there too and it's the "source" for much of the theme. Here's the difference between the typical and our structure (few folders mentioned for brevity; please see Orientation above for a more thorough list).

Typical Folder Structure

pattern-lab/
- config/
- public/
- source/
  - _patterns/ (contains atoms, molecules, etc folders)
- composer.json

Our Folder Structure

source/
- _patterns/ (contains atoms, molecules, etc folders)
pattern-lab/
- config/
- public/
- composer.json

Dummy data using `Faker`

Faker generates fake data and the Faker plugin for Pattern Lab is used here. This generates different fake content for each compile, and allows translated content as well.

Faker only works in the global data files found in source/_data/ currently until this bug is fixed.

Use it like this in source/_data/data.json:

{
  "description": "Faker.paragraph",
  "text": "Faker.words(3, true)",
  "byline": "Faker.sentence",
  "intro": "Faker.sentences(2, true)"
}

The formatters (things like .paragraph, .words, etc) can accept options, when you see Faker.words(3, true) that means give me 3 random words and I'd like them as a string and not an array of strings. All the formatters and their options are documented here - there's tons: numbers, address, names, dates, and more.

Configuration

It's almost all done in gulpconfig.yml. End all paths with a / please (i.e. path/to/dir/). The local gulpfile.js passes the config object to p2-theme-core - which can be viewed at node_modules/p2-theme-core/ (most stuff in lib/).

Many of the features can be turned off, for example if we didn't want all the JS features like linting and concatenation, just toggle enabled under js in gulpconfig.yml. So you'd just open gulpconfig.yml and change this:

js:
-    enabled: true
+    enabled: false

Documentation for many of the features are found in node_modules/p2-theme-core/docs/ – those are hosted here too.

Linting Config

JS: edit .eslintrc - rule docs
Scss: edit .stylelintrc.js - docs

Disabling Stylelint rules for a certain section

You can use comments to turn off certain rules easily:

// stylelint-disable selector-no-id, declaration-no-important
#id {
  color: pink !important;
}
// stylelint-enable

.class {
  color: pink !important; // stylelint-disable-line declaration-no-important
}

Babel JS Transpiling Config

Edit .babelrc for configuration of Babel rules that transpile JS. Default allows ES6 to be transpiled to ES5. Learn about awesome ES6 features here.

Assets

Get front end libraries injected into Drupal theme info file and Pattern Lab with:

bower install {project-name} --save

Using --save shows it's intention to be used in Pattern Lab and Drupal; using --save-dev shows it's just for Pattern Lab. All assets <link> or <script> tag will be automatically injected for Pattern Lab into the header and footer twig files found in source/_meta/.

Sass Libraries

Sass libraries are installed using bower as well; you can see how we import them in the main scss file. These are the ones available:

Normalize - Better style reset
Singularity Grid System - Grid system
Breakpoint - A cleaner way to do breakpoints/media queries
Bourbon - Helpful mixins

Gulp

Gulp 4 is used and the npm run commands above basically trigger gulp without having to install a global dependency. If you want to run specific gulp tasks, run npm run gulp -- OPTIONS TASKS. The -- passes whatever comes after to the gulp command. Run npm run gulp -- --tasks to see the whole list, here's some examples of what you can do:

npm run gulp -- --help - See the help menu
npm run gulp -- css - Compile CSS
npm run gulp -- pl - Compile PL

Add anything to gulpfile.js that you want! Also, you can copy any file from node_modules/p2-theme-core/lib/ into your repo and use it as a starting point (may need to install packages from p2-theme-core too.)

js:
-    enabled: true
+    enabled: false

Also, if you're still getting the annoying (but not harmful) warnings about graceful-fs, run npm update -g npm.

Helpful Gulp 4 resources

Drupal 8 Integration

From your Drupal Twig templates in templates/ you can {% include %}, {% extends %}, and {% embed %} your Pattern Lab Twig template files. Each of the top level folders has a Twig Namespace like @organisms and then you append the path down to the file like below.

{% include "@organisms/path/to/file.twig" with {
  title: label,
  largeCTA: true
} %}

For a demonstration in a sample codebase of how exactly to integrate templates, see the drupal-lab repo; in particular note how both a node teaser template and a views field template in the Drupal templates/ folder can embed the card template from Pattern Lab while formatting the data.

justcallmekat/pattern-lab-starter