@frontify/frontify-api/README.md

# Frontify API

Simplifies the creation of UI patterns within Frontify.
Its a simple brick in your frontend build that handles creating and updating your pattern library.

![Pattern Library Sync](https://cdn.frontify.com/assets/marketing/github/pattern-library-sync.png)

The Frontify API package allows you to use your current project structure as your pattern library master.
Moreover it gives you granular control over which patterns and code snippets to sync.

> Note: an access token is required to use the API. Please write us an in-app message or [email](mailto:hello@frontify.com) to get one for your project.

## Install

```
$ npm install --save @frontify/frontify-api
```

## Usage

```
var frontifyApi = require('@frontify/frontify-api');
```

### Scenario 1: "Bootstrap" case

Simply loop over a set of pattern html files. A pattern is created for every matched html file.
The pattern name is inferred by the name of the file.

```
frontifyApi.syncPatterns({access_token: '1234', project: 1}, ['patterns/**/*.html']).catch(function(err) {
    console.error(err);
});
```

### Scenario 2: Metadata JSON

Loop over a set of pattern metadata json files. A pattern - and possible variants of a pattern - is created for every matched json file.
The json file contains all pattern related data

```
frontifyApi.syncPatterns({access_token: '1234', project: 1}, ['patterns/**/*.json']).catch(function(err) {
    console.error(err);
});
```

#### Sample JSON Structure
```
{
  "name": "Paragraph",
  "type": "atom",
  "stability": "stable",
  "variations": {
    "lead": {
      "name": "Lead paragraph",
      "assets": {
        "html": [
          "test/fixtures/patterns/atoms/paragraph/paragraph_lead.html"
        ],
        "css": [
          "test/fixtures/patterns/atoms/paragraph/css/paragraph_lead.css"
        ]
      }
    }
  },
  "assets": {
    "html": [
      "test/fixtures/patterns/atoms/paragraph/paragraph.html"
    ],
    "css": [
      "test/fixtures/patterns/atoms/paragraph/css/paragraph.css"
    ]
  }
}
```

## API

### syncPatterns(options, glob-pattern)

Returns a Promise

#### options
Type: object

Attributes
* `access_token` (string) - Please write us an in-app message or [email](mailto:hello@frontify.com) to get one for your project
* `project` (number) - Your project id (we will provide it to you)
* `dryRun` (boolean) - True = only dry-run your pattern creation to see what would be updated (default = false)
* `baseUrl` (string) - the base url of your pattern library, e.g. http://yourbrand.frontify.com (default: http://app.frontify.com)

## Advanced Usage
### Gulp Integration

Simply create a gulp task and you are ready to go.

```
gulp.task('frontify', function() {
    frontifyApi.syncPatterns({access_token: '1234', project: 23, baseUrl: 'http://yourbrand.frontify.com'}, ['patterns/**/*.html']).catch(function(err) {
       console.error(err);
    });
});
```

The Frontify API is a Promise-returning node module. This makes it easy to integrate it in your existing gulp streams by using the [vinyl-paths](https://github.com/sindresorhus/vinyl-paths/) module.

```
var vinylPaths = require('vinyl-paths');
var frontifyApi = require('frontify-api');

// sync patterns in the stream
gulp.task('frontify', function () {
    return gulp.src('patterns/**/*.html')
        .pipe(vinylPaths(function(paths) {
            return frontifyApi.syncPatterns({access_token: '1234', project: 1}, paths).catch(function(err) {
                console.error(err);
            });
        }));
});
```

Note that this results in an API call for each pattern. If you experience some performance issues, please refer to the usage above.

### Grunt integration

Simply [create a Grunt task](http://gruntjs.com/creating-tasks) and you are ready to go.

## License

MIT © [Frontify](https://frontify.com/)