Needlessly Postulating Minds

    @frontify/frontify-api

    0.3.1 • Public • Published

    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

    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

    Keywords

    Install

    npm i @frontify/frontify-api

    DownloadsWeekly Downloads

    364

    Version

    0.3.1

    License

    MIT

    Last publish

    Collaborators

    • samuel.alev
    • frontify-dev