# Pops - 0.1.0

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url]

[![NPM](https://nodei.co/npm/pops.png?downloads=true&downloadRank=true)](https://nodei.co/npm/pops/)

A component based pattern library.

Features component, pattern, and page generators, 
using [Twig](https://twig.sensiolabs.org/) templating system and context data to allow for includes and faking server data.

## Requirements

Pops requires a node js installation.
The node version must be greater than 6.

## Installation

Install pops globally.

    $ npm install -g pops

Once installed you will have access to the pops commandline-client.

    $ pops

          ██████╗  ██████╗ ██████╗ ███████╗
          ██╔══██╗██╔═══██╗██╔══██╗██╔════╝
          ██████╔╝██║   ██║██████╔╝███████╗
          ██╔═══╝ ██║   ██║██╔═══╝ ╚════██║
          ██║     ╚██████╔╝██║     ███████║
          ╚═╝      ╚═════╝ ╚═╝     ╚══════╝
        
          Usage: pops <command> [options]
        
          Commands:
            serve            Serves Pops' pattern library
            watch            Serves Pops' pattern library and watches for changes
            init             Creates a pops.config.js in the current folder
            ----------------------------------------------------------------
            make:component   Creates one or multiple components/s
            make:pattern     Creates one or multiple patterns/s
            make:page        Creates one or multiple page/s
            ----------------------------------------------------------------
            version          Prints pops version
            help             Prints this dialogue

## Quickstart

In order to quickly create a pops pattern library run the following.

    $ mkdir pops-example
    $ cd pops-example
    $ pops init                 # Creates the pops.config.js file which contains the pops settings
    $ pops make:component test  # creates a test component
    $ pops serve                # start the server

Once the above have been executed navigate to [http://127.0.0.1:9095/](http://127.0.0.1:9095/).

The above commands are demoed in the follwoing video.

[https://vimeo.com/214039477](https://vimeo.com/214039477)

## Config

To start a pops pattern library you will first need a `pops.config.js` file.
After installing pops run `pops init` to generate a `pops.config.js` in the current
directory. The contents of the generated file should look like the following.

```javascript
var path = require('path')

module.exports = {
    // folder where components, patterns, and pages will be placed
    src: path.join(__dirname, './pattern-library'),
    // meta info that will be included in the api under the meta key
    meta: {
        // appears in pattern library
        name: 'Pops Pattern Library',
        // current pattern library version
        version: '0.1.0',
        // keep short as overviews should be used for more substantial info
        summary: 'A pattern library of Atomic components.',
        authors: [
            // list of developers who have worked on the project
            'Brian Douglas'
        ]
    },
    // relative path to a template twig file which pops will use as it's pattern library template
    // Note: this should left as an empty string unless you want to change the pops ui
    template: '',
    // color pallette
    colors: [
        {name: 'white', color: '#FFFFFF'},
        {name: 'grey', color: '#AAAAAA'},
        {name: 'black', color: '#000000'}
    ],
    // list of fonts
    fonts: [
        {name: 'Roboto', font: 'https://fonts.googleapis.com/css?family=Roboto'}
    ],
    // file extensions that will be used
    // Note: if scripts or styles is an empty string they will not be generated
    ext: {
        templates: 'twig',
        styles: 'scss',
        scripts: 'js'
    },
    // stylesheets and scripts that will be placed in pattern library head
    globals: {
        stylesheets: [
            // Include stylesheets
        ],
        javascripts: [
            // Include scripts
        ]
    }
}
```

### src

The `src` option tells pops where it should place any generated items. It is also
where pops will look when serving it's pattern library.

### meta

Meta information about the pattern library. The name and summary will be displayed in the ui.

### template

This should be a relative path to a twig file to be used in place of the pops default ui.
Should you wish to add a new template the pops default template can be used as a base. 
It can be found [here](https://github.com/BrianDGLS/pops/blob/develop/web/templates/pattern-library.twig).

### colors

Colors corresponds to your sites color pallette and will be displayed as a list of swatched in the pattern library.
Colors should be added in the following format.

```javascript
colors: [
   {name: 'white', color: '#FFFFFF'},
   {name: 'grey', color: '#AAAAAA'},
   {name: 'black', color: '#000000'}
]
```

### fonts

These are the fonts used in your site.
A list of fonts and example text will be displayed in the ui.
Font shoudl be added in the following format.

```javascript
fonts: [
   {name: 'Roboto', font: 'https://fonts.googleapis.com/css?family=Roboto'}
]
```

### ext

The `ext` option tells pops what file extension you wish to use. Pops will read this
and create files using these intructions.

**Note**: if scripts or styles is an empty string they will not be generated.

### globals

The `globals` option refers to global stylesheets and javascripts that are used by
the pattern library items. 
These should contain the urls of your sites stylesheets and javascripts.


## FAQs

**How can I include components and patterns as partials?**

Pops uses Twig and due to this components and patterns can be required as partials.
Below is an example of including a component and pattern within pops.

```
// include component
{% include 'components/header/header.twig' %}

// include pattern
{% include 'patterns/button/button.twig' %}

// include component with data 
{% include 'components/header/header.twig' with vars %}
{% include 'components/header/header.twig' with {'foo': 'bar'} %}
```

**How can I generate multiple pages, components, or patterns at a time?**

By seperating each name with a space, see example below.

```
// generates test component
pops make:component test

// ganerates foo and bar components
pops make:component foo bar
```

**How can I change the port pops server runs on?**

The port can be passed in as an enviroment variable.
The following commands will start the pops server at port 8888.

```
PORT=8888 pops serve
 
// or 

PORT=8888 pops watch 
```

## Changelog

The changelog can be found [here](/CHANGELOG.md).

## Want to contribute?

Anyone can help make this project better - check out our [Contributing guide](/CONTRIBUTING.md)!


[downloads-image]: https://img.shields.io/npm/dm/pops.svg
[npm-url]: https://www.npmjs.com/package/pops
[npm-image]: https://img.shields.io/npm/v/pops.svg