@frontify/frontify-api
Version:
Simplifies asset management and UI pattern creation within Frontify.
221 lines (160 loc) • 6.36 kB
Markdown
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](mailto:hello@frontify.com) to get one for your project.
```
$ npm install --save @frontify/frontify-api
```
```
var frontifyApi = require('@frontify/frontify-api');
```
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);
});
```
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"
]
}
}
```
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.
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.
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);
});
```
Returns a Promise
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.
Simply [create a Grunt task](http://gruntjs.com/creating-tasks) and you are ready to go.
MIT © [Frontify](https://frontify.com/)