Merge pull request #11 from ovh-ux/feat/pl

Feat/pl

Author: blaryjp

docs/features/drupal-drush.md

@@ -7,6 +7,7 @@ Launch a Drupal command.
 
 ## Config
 
+- `config.drupal.themeFile` - The filename of your YOUR_THEME.info.yml (required for PatternLab tasks)
 - `config.drupal.dir` - The root directory for Drush
 - `config.drupal.command` - The drush command to execute
 

docs/features/pattern-lab.md

@@ -0,0 +1,94 @@
+Build and run a Pattern Lab project.
+
+## Commands
+
+- `gulp pl` - Build Pattern Lab  files
+- `gulp watch:pl` - Watch files and launch `gulp pl`
+
+## Config
+
+@todo
+
+## 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.
+
+```twig
+{% 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`](https://github.com/phase2/drupal-lab) repo; in particular note how both a [node teaser template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/templates/content/node--article--teaser.html.twig) and a [views field template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/templates/views/views-view-fields--newspage--page.html.twig) in the Drupal `templates/` folder can embed the [card template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/pattern-lab/source/_patterns/02-molecules/cards/card.twig) from Pattern Lab while formatting the data.
+
+
+## Additional features
+
+### Asset Injection
+
+If you use `--save` or `--save-dev` on `bower install` it will inject them in Pattern Lab
+
+It adds it to these locations in Pattern Lab:
+
+- `source/_meta/_00-head.twig`
+- `source/_meta/_01-foot.twig`
+
+### Dummy data using `Faker`
+
+[`Faker`](https://github.com/fzaninotto/Faker) generates fake data and the [Faker plugin for Pattern Lab](https://github.com/pattern-lab/plugin-php-faker) is used here. This generates *different* fake content for each compile, and allows [translated content](https://github.com/pattern-lab/plugin-php-faker#locales) as well.
+
+**Faker only works in the global data files** found in `source/_data/` currently until [this bug](https://github.com/pattern-lab/plugin-php-faker/issues/2) is fixed.
+
+Use it like this in `source/_data/data.json`:
+
+```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](https://github.com/fzaninotto/Faker#formatters) - there's tons: numbers, address, names, dates, and more.
+
+---
+
+## Pattern Lab documentation
+
+### Pattern Lab Terms
+
+- **Atoms** are basic tags, such as form labels, inputs or buttons. They also include more abstract elements like color palettes, fonts, and animations.
+- **Molecules** are groups of elements that function together as a unit. For example, a form label, search input, and button atom can combine them together to form a search form molecule.
+- **Organisms** can consist of similar and/or disparate molecule types. For example, a masthead organism might consist of a logo, navigation, and search form, while a “product grid” organism might consist of the same product info molecule repeated over and over.
+- **Templates** are comprised mostly of organisms combined together to form page-level objects. Templates mostly focus on content structure (such as character length, image size, etc) rather than the actual content.
+- **Pages** are specific instances of templates and swap out placeholder content with real representative content.
+
+[More info](http://patternlab.io/about.html)
+
+#### Advanced Pattern Lab Concepts
+
+- [Including Patterns in Patterns](http://patternlab.io/docs/pattern-including.html)
+- [Introduction to JSON & Mustache Variables](http://patternlab.io/docs/data-json-mustache.html)
+    - [Creating Pattern-specific Values](http://patternlab.io/docs/data-pattern-specific.html)
+    - [Creating Lists with `listItems` Variable](http://patternlab.io/docs/data-listitems.html)
+- [Linking to Patterns](http://patternlab.io/docs/data-link-variable.html)
+- [Adding Annotations](http://patternlab.io/docs/pattern-adding-annotations.html)
+- [Pattern Lab's Special Query String Variables](http://patternlab.io/docs/pattern-linking.html)
+- [Using styleModifiers](http://patternlab.io/docs/pattern-stylemodifier.html)
+- [Using Pattern States](http://patternlab.io/docs/pattern-states.html)
+- [Using Pattern Parameters](http://patternlab.io/docs/pattern-parameters.html)
+- [Keyboard Shortcuts](http://patternlab.io/docs/advanced-keyboard-shortcuts.html)
+- [Editing the config.ini Options](http://patternlab.io/docs/advanced-config-options.html)
+
+### More Info
+
+#### About Pattern Lab
+
+- [Pattern Lab Website](http://patternlab.io/)
+- [About Pattern Lab](http://patternlab.io/about.html)
+- [Documentation](http://patternlab.io/docs/index.html)
+- [Demo](http://demo.patternlab.io/)
+
+---

docs/index.md

@@ -10,6 +10,7 @@ This stack core is to be included in your main project and sets up many Gulp tas
 
 - SCSS => CSS compiling with LibSass, PostCSS, linting, CSScomb(x), and SourceMaps
 - JS compiling via Babel, linting and aggregation
+- Pattern Lab Twig compiling & BrowserSync live reload and style injection
 - WebPack module bundling
 - SVG => Font Icons compiling with support for adding mixins and classes to SCSS along with a demo page
 - Drupal file watching to trigger Drush cache clears
@@ -40,6 +41,16 @@ $ vi gulpfile.yml
 # <set the config that you want, and save it>
 ```
 
+### 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/`
+
 
 ## Usage
 

docs/usage.md

@@ -13,6 +13,32 @@ js:
 You can find all the available options and defaults settings inside the `gulpfile.default.yml` file.
 
 
+## Folders structure
+
+- source/ (only for Pattern Lab)
+  - _annotations/ ([annotations](http://patternlab.io/docs/pattern-adding-annotations.html) 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 `<!-- inject -->` tags though; it'll get overwritten)
+- pattern-lab/ (only for 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](http://sassdoc.com).
+- 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](https://en.wikipedia.org/wiki/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.
+
+
 ## Commands
 
 - `gulp` - Run all compile tasks, and watch for changes

gulpfile.default.yml

@@ -86,6 +86,67 @@ icons:
     - eot
     - woff
     - svg
+patternLab:
+  enabled: false
+  configFile: pattern-lab/config/config.yml
+  watchedExtensions:
+    - twig
+    - json
+    - yaml
+    - yml
+    - md
+    - jpg
+    - jpeg
+    - png
+  extraWatches: []
+  injectFiles: []
+  bowerBasePath: ./
+  twigNamespaces:
+    addToDrupalThemeFile: true
+    sets:
+      - namespace: base
+        paths:
+          - 'source/_patterns/00-base'
+      - namespace: atoms
+        paths:
+          - 'source/_patterns/01-atoms'
+      - namespace: molecules
+        paths:
+          - 'source/_patterns/02-molecules'
+      - namespace: organisms
+        paths:
+          - 'source/_patterns/03-organisms'
+      - namespace: templates
+        paths:
+          - 'source/_patterns/04-templates'
+      - namespace: pages
+        paths:
+          - 'source/_patterns/05-pages'
+  scssToJson: []
+    # - src: 'source/_patterns/00-base/05-colors/_color-vars.scss'
+    #   dest: 'source/_patterns/00-base/05-colors/colors.json'
+    #   lineStartsWith: '$c-'
+    #   allowVarValues: false
+    # - src: 'source/_patterns/00-base/15-typography/fonts/_fonts.scss'
+    #   dest: 'source/_patterns/00-base/15-typography/fonts/font-sizes.json'
+    #   lineStartsWith: '$fs--'
+    #   allowVarValues: false
+    # - src: 'source/_patterns/00-base/15-typography/fonts/_fonts.scss'
+    #   dest: 'source/_patterns/00-base/15-typography/fonts/font-families.json'
+    #   lineStartsWith: '$ff--'
+    #   allowVarValues: false
+    # - src: 'source/_patterns/00-base/breakpoints/_breakpoints.scss'
+    #   dest: 'source/_patterns/00-base/breakpoints/breakpoints.json'
+    #   lineStartsWith: '$bp--'
+    #   allowVarValues: false
+    # - src: 'source/_patterns/00-base/10-spacing/_spacing.scss'
+    #   dest: 'source/_patterns/00-base/10-spacing/spacing.json'
+    #   lineStartsWith: '$spacing--'
+    #   allowVarValues: false
+    # - src: 'source/_patterns/00-base/animations/01-transitions/_transitions.scss'
+    #   dest: 'source/_patterns/00-base/animations/01-transitions/transitions.json'
+    #   lineStartsWith: '$trans-'
+    #   allowVarValues: true
 browserSync:
   enabled: false
   port: 3050
@@ -98,8 +159,10 @@ browserSync:
   tunnel: false
   reloadDelay: 50
   reloadDebounce: 750
+  rewriteRules: []
 drupal:
   enabled: false
+  themeFile: patternlab.info.yml
   watch:
     - template.php
     - templates/**

index.js

@@ -27,6 +27,10 @@ module.exports = (gulp, userConfig, tasks) => {
     require('./lib/css')(gulp, config, tasks);
   }
 
+  if (config.patternLab.enabled) {
+    require('./lib/pattern-lab--php-twig')(gulp, config, tasks);
+  }
+
   if (config.drupal.enabled) {
     require('./lib/drupal')(gulp, config, tasks);
   }