README

Fractal statuses extension

Configurable workflow statuses for your Fractal components :vertical_traffic_light:

This plugin is for use with the work-in-progress Fractal v2 release and will not work with earlier versions.

Overview

This extension lets you define a set of statuses which can be applied to your components via their config files.

const statuses = require('@frctl/fractal-extension-statuses');
const fractal = require('@frctl/fractal')({
  src: 'path/to/components'
});

fractal.addExtension(statuses({
  default: 'wip',
  options: [
    {
      name: 'wip',
      label: 'In progress',
      color: 'red'
    },
    {
      name: 'ready',
      label: 'Ready',
      color: 'green'
    }
  ]
}));

fractal.parse((err, components) => {
  if (err) {
    return console.log(err);
  }

  const button = components.find('button');
  console.log(button.status); // {name: 'ready', label: 'Ready', color: 'green' }

  for (const status of components.getStatuses()) {
    //... do something with `status`
  }

  for (const component of components.filterByStatus('ready')) {
    //... do something with `component`
  }

});

Installation

npm i @frctl/fractal-extension-statuses --save

Usage

To give a component a status, add a status property to it's configuration file with the name of the appropriate status:

// @component/config.json
{
  "status": "ready"
}

Default statuses

The following default statuses are defined:

{
  name: 'prototype',
  label: 'Prototype',
  color: 'red'
},
{
  name: 'wip',
  label: 'In progress',
  color: 'orange'
},
{
  name: 'ready',
  label: 'Ready',
  color: 'green'
}

Unless otherwise specified, the default status is prototype.

Custom statuses

To add your own set of statuses, pass a set of status objects as an options array when initialising the extension:

const statusesExtension = require('@frctl/fractal-extension-statuses');
const myStatuses = statusesExtension({
  options: [
    // custom set of statuses
  ]
});

fractal.addExtension(myStatuses);

Each status object should have name, label and color properties, and can optionally have any other additional properties that you require.

API

Properties:

The extension adds a .status property to each component.

The value of this property will be a status object that matches the one specified in the component's config file. If no status is specified, the default status will be used.

API methods:

The extension provides the following API methods:

components.getStatuses() - Returns an array of all possible statuses
components.filterByStatus(status) - Returns an array of components that have been assigned the specified status

Requirements

Node >= v6.0 is required.

Usage no npm install needed!