fabricator-assemble
v1.4.0
Published
The assembly engine behind Fabricator
Downloads
1,874
Readme
Fabricator Assemble
The assembly engine behind Fabricator. Not associated with Assemble.
Turn this:
---
title: Document Name
name: World
---
<h1>{{home.greeting}}, {{name}}!</h1>
{{> button}}into this:
<!doctype html>
<html lang="en">
<head>
<title>Document Name</title>
</head>
<body>
<h1>Hello, World!</h1>
<a href="#" class="button">Click me!</a>
</body>
</html>Usage
The task returns a promise, so it can be used in an async task runner, like Gulp:
var assemble = require('fabricator-assemble');
var gulp = require('gulp');
gulp.task('assemble', function () {
return assemble(options);
});The task accepts options, but assumes this directory structure:
└── src
├── data
│ └── *.{json,yml}
├── docs
│ └── *.md
├── materials
│ └── components
│ └── *.html
└── views
├── *.html
└── layouts
└── default.htmlOptions
Default options:
{
layout: 'default',
layouts: 'src/views/layouts/*',
layoutIncludes: 'src/views/layouts/includes/*',
views: ['src/views/**/*', '!src/views/+(layouts)/**'],
materials: 'src/materials/**/*',
data: 'src/data/**/*.{json,yml}',
docs: 'src/docs/**/*.md',
keys: {
materials: 'materials',
views: 'views',
docs: 'docs'
},
helpers: {},
logErrors: false,
onError: function(error) {},
dest: 'dist',
baseUrl: '',
}options.layout
Type: String
Default: default
Name of the default layout template.
options.layouts
Type: String or Array
Default: src/views/layouts/*
Files to use as layout templates.
options.layoutIncludes
Type: String or Array
Default: src/views/layouts/includes/*
Files to use as layout includes.
options.views
Type: String or Array
Default: ['src/views/**/*', '!src/views/+(layouts)/**']
Pages to pass through the assembler to be templated. Fabricator pages are stored at the root level views and user-defined views can be stored in subdirectories.
options.materials
Type: String or Array
Default: src/materials/**/*
Files to use a partials/helpers. These are the materials that make up your toolkit. by default, Fabricator comes with "components" and "structures", but you can define your own taxonomy.
options.data
Type: String or Array
Default: src/data/**/*.{json,yml}
JSON or YAML files to use as data for views.
options.docs
Type: String or Array
Default: src/docs/**/*.md
Markdown files containing toolkit-wide documentation
options.keys
Type: Objects
Default: materials/views/docs
Object keywords for accessing "materials", "views", and "docs" in a view templating context. Fabricator uses some specific terms like "materials" to describe what are really "partials" in Handelbars. This option give you the flexibility to define your own terms for materials, views, and docs.
For example:
assemble({
keys: {
materials: 'patterns'
}
});<!-- formerly `{{#each materials}}` -->
{{#each patterns}}
<h1>{{name}}</h1>
{{#each items}}
<h2>{{name}}</h2>
{{/each}}
{{/each}}Note: this will also change the built-in {{material <foo>}} helper to use the singular form of whatever is defined for the materials key. e.g. materialKey: 'patterns' -> {{pattern <foo>}}. If you set a new key for materials, you will also need to update the f-item-content.html include to use the new helper name.
options.helpers
Type: Object
Default: {}
User-defined helpers. E.g.:
helpers: {
markdown: require('helper-markdown'),
foo: function () {
return 'bar';
}
}options.logErrors
Type: Boolean
Default: false
Whether or not to log errors to console. If set to false, the app will exit on error.
options.onError
Type: Function
Default: null
Error handler function. Receives an error object param.
options.dest
Type: String
Default: dist
Destination of compiled views (where files are saved to)
options.baseUrl
Type: String
Default: ''
Changes the baseurl path. Useful in build that require better path definitions for assets (ie: production builds).
options.GLOBAL
Type: Object
Default: {}
Sets up global values across your fabircator instance. Global values can be accessed by their keys.
For example:
{{ GLOBAL.SIGN_IN_LINK }}
Globals in fabricator work in a similar manner to Webpacks DefinePlugin.
Usage
Definitions
- Layouts: wrapper templates
- Views: individual pages
- Materials: partial views; registered as "partials" and "helpers" in Handlebars
- Data: Data piped in as template context
- Docs: Markdown files containing documentation.
Layouts
Layouts are wrappers for pages. You can define as many layouts as you want by creating .html files in your layouts folder.
Example layout:
<!doctype html>
<html lang="en">
<head>
<title>{{title}}</title>
</head>
<body>
{% body %}
</body>
</html>Page content is inserted in the {% body %} placeholder.
Context can be passed from a page to the layout via front matter.
The layout a page uses is also defined in front matter:
---
layout: custom-layout
title: My Custom Layout
---This would use custom-layout.html.
When no layout property is defined, the page uses the default layout.
Views
Views are unique pages templated using Handlebars. These are both Fabricator pages and user-created pages (i.e. example templates)
View example:
---
title: Document Name
name: World
---
<h1>{{home.greeting}}, {{name}}!</h1>
{{> button}}
This outputs a page that uses the default layout (since no layout was defined).
The front matter block at the top provides context to both the layout and the page itself.
Context is also piped in from data files (see below). In this example, {{home.greeting}} refers to the greeting property in home.json.
Fabricator pages are typically stored at the root level of the views directory and user-created views (e.g. "templates", "pages", "interfaces") should be stored in subdirectories.
Materials
Materials are partial templates; think of them as the materials used to build pages.
They are accessed as a "partial" using the > syntax in Handlebars:
{{> material-name}}Any file in the glob defined in options.materials is turned into a partial/helper and can be accessed as such. For example, assume the components contains materials:
└── components
├── button.html
└── form-toggle.htmlThe content within these files can be accessed as such:
{{> button}}
{{> form-toggle}}Ordering
You can manually order materials by prefixing the file name with numbers:
01-foo.html
01.01-bar.html
02-qux.htmlThis defines the order in which materials will appear in the side menu or other places the materials.items context is used.
Note: The number prefixes are ignored when registering partials, so you'll still be able to access them using the material name per usual. e.g.:
{{> foo}}
{{> bar}}
{{> qux}}The numbers are also ignored in the .name property. The materials above would list as:
Foo
Bar
QuxData
Data is defined as JSON or YAML.
The data folder can contain several .json or .yml files:
└── data
├── home.json
└── contact.ymlhome.json:
{
"greeting": "Hello"
}The data within each file can be accessed using dot notation:
{{home.greeting}}
{{contact.propName}}Docs
Docs are just a generic way to capture toolkit documenation that's not specific to a material. This could be something like JavaScript architecture, accessibility guidelines, etc.
Docs are written in markdown and are stored in src/docs by default.