Frontify Academy Videos

Get a quick overview of the Pattern Library in the Frontify Academy:

How to setup the Pattern Library synchronisation

Synchronising your pattern code and assets to the Frontify Pattern Library allows your design and developer teams to keep up with latest modifications in order to ensure a consistent reuse over all your digital channels. To achieve that, we built an npm package (Frontify API) that enables you to synchronise your code and assets with a task runner of your choice – e.g. gulp, grunt or native npm – to your Frontify Pattern Library. 

In this help article we will focus on using gulp but please feel free to use your preferred task runner.
 

Step 1: Create your Pattern Library and Download your SDK

To get started, create your Pattern Library on the brand dashboard. Unless you create or synchronise patterns, the library shows up empty.  
Click on the "Download (SDK)" in the top navigation bar to download the SDK package. Within this package you'll find everything you will need for synchronising your patterns and assets, including your access token and a demo basic folder structure to start right away. The folder structure provided is only for demo purpose and you are of course completely free how your project is structured.

Please contact your Customer Success Manager in case the Pattern Library has not been activated on your account.
 

Step 2: Preparation for synchronisation

To fill your Pattern Library with existing code and assets, simply open the code base you want to synchronise in your editor. Have a look at the gulpfile.js in the downloaded SDK package to see a code example with three gulp tasks to run a synchronisation. In order to create your script you will need the following information: 

  1. Your access token: can be found in the gulpfile.js of your SDK *.zip package. 
  2. Your project id: can be found in the gulpfile.js of your SDK *.zip package or alternatively in the url when you open your pattern library. Example: https://beta.frontify.com/patterns/5/pattern-library In this example your project id is "5".
  3. Your base url: can be found in the gulpfile.js of your SDK *.zip package or alternatively in the url when you open your pattern library. Example: https://beta.frontify.com/patterns/5/pattern-library In this example your base url is "https://beta.frontify.com"
  4. Your assets and patterns to synchronise: can be specified within the gulp.task. We provided an example for your source structure within the SKD *.zip file

 

Step 3: Fill your Pattern Library with your existing code and assets

Here you find an example set of gulp tasks to sync your code and assets:

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

/*
 * Scenario 1: "Bootstrap" case (HTML only)
 * Have a look at the NPM documentation for further details
 */
gulp.task('patterns-simple', function() {
    frontifyApi.syncPatterns({access_token: '<your access token>', project: <your_project_id>, baseUrl: '<your_base_url>'}, ['patterns/**/*.html']).catch(function(err) {
        console.error(err);
    }); // glob pattern for html files
});

/*
 * Scenario 2: Metadata JSON case (full control)
 * Have a look at the NPM documentation for further details
 */
gulp.task('patterns-advanced', function() {
    frontifyApi.syncPatterns({access_token: '<your access token>', project: <your_project_id>, baseUrl: '<your_base_url>'}, ['patterns/**/*.json']).catch(function(err) {
        console.error(err);
    });  // glob pattern for json metadata files
});

/*
 * Upload assets like images, webfonts, minified css and js files
 */
gulp.task('assets', function() {
    frontifyApi.syncAssets({access_token: '<your access token>', project: <your_project_id>, baseUrl: '<your_base_url>', cwd: ''}, ['assets/**/*.*']).catch(function(err) {
        console.error(err);
    }); // glob pattern for all files under assets/
});

The command frontifyApi.syncPatterns fills up your Pattern Library with the UI pattern code. Once you run it, refresh your pattern library in Frontify to ensure they have been successfully synchronized. 

In Scenario 2 – our recommended way – the Metadata JSON files gives you full control over your patterns and allows you to give your patterns a name, type, and the information for your html snippet and css information. Here is an example:

{
    "name": "Breadcrumb",
    "description": "The breadcrumb navigation gives the user…",
    "type": "molecule",
    "variations": {},
    "assets": {
        "html": [
           "patterns/custom/molecules/breadcrumb/breadcrumb.html"
        ],
        "css": [
            "patterns/custom/molecules/breadcrumb/css/breadcrumb.css"
        ]
    }
}

Please have look at the NPM documentation for further details.

Back in your Pattern Library you can refresh the page and see your UI pattern with the additional information underneath the tile HTML, CSS and the type (atom, molecule or organism):

You can also synchronise additional assets for your patterns, such as images, fonts, styles, etc. For that, use the command frontifyApi.syncAssets. These assets will then be available for your patterns. Check out the SDK for an example.

The power bar on the left allows you to easily switch between the pattern view and the asset view.  After running your script, you can find your assets in the asset view with including potential subfolders.
 

Step 4: Configure external resources

In order to display your patterns correctly, you may want to add additional external resources, such as CSS or Javascripts, which are loaded globally. 

You can set them in the UI Patterns setting to apply them to all your patterns.

You can add an absolute link or relative to your files in the asset folder. 

Step 5: Start documenting your patterns within the Style Guide

Now you're all set up! With the API integration you can synchronise all your UI patterns & assets to your Frontify environment. After that they are ready for documentation by selecting the content block and select the pattern from your pattern library for a live view and code section of the pattern.

Get the most of your Pattern Library and enjoy working with our API!
Thanks for any feedback.

Did this answer your question?