@frontify/frontify-api

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.

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 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 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 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 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 and you are ready to go.

License

MIT © Frontify