npm package: @frontify/frontify-api
Description: Simplifies asset management and UI pattern creation within Frontify.
Author: Frontify AG
Latest version: 0.3.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Frontify API

Simplifies asset management and UI pattern creation 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, code snippets and external resources 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');
```

### Patterns

#### 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",
  "description": "Basic 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"
    ]
  }
}
```

### Assets

Additionally to syncing patterns the API allows to manage assets, e.g. images, fonts, plugins etc.
Simply loop over a set of assets to sync them to your project.


#### Scenario 1: Complete directory structure

Given the following directory structure:

```
/assets
  /img
    logo.png
    header.png
```

To sync the directory structure above to your project:

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

This looks in the current working directory for the given glob patterns and creates the folders and assets in your project.


#### Scenario 2: Selected assets only

Given the following directory structure:

```
/public
  /assets
    /img
      logo.png
      header.png
```

To just sync selected assets to your project, simply adjust the glob pattern and set the current working directory accordingly:

```
frontifyApi.syncAssets({access_token: '1234', project: 1, cwd: 'public' }, ['**/logo.png']).catch(function(err) {
  console.error(err);
});
```

This only creates the `/assets/img/logo.png` in your project. The `/public` directory is not taken into account because
the cwd (current working directory) is set to `public, i.e. only the paths of the matched files are considered.


#### Scenario 3: Frontify sub-directory

Given the following directory structure:

```
/img
  logo.png
  header.png
```

To achieve the same result as in Scenario 1 - i.e. /assets/img/* - you have to specify the target folder in Frontify:

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


## 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. https://yourbrand.frontify.com (default: https://app.frontify.com)


### syncAssets(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 asset creation to see what would be updated (default = false)
* `baseUrl` (string) - the base url of your pattern library, e.g. https://yourbrand.frontify.com (default: https://app.frontify.com)
* `cwd` (string) - The current working directory to look for the given glob pattern (default = '')
* `target` (string) - The target folder in your Frontify project (default = '')


## 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: 'https://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: 23, baseUrl: 'https://yourbrand.frontify.com'}, 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/)