Pops - 0.1.0

A component based pattern library.

Features component, pattern, and page generators, using Twig 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/.

The above commands are demoed in the follwoing video.

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.

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.

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.

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.

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.

Want to contribute?

Anyone can help make this project better - check out our Contributing guide!