baseplate-core
v1.8.6
Published
A tool for building prototypes and pattern libraries.
Downloads
584
Maintainers
Readme
baseplate-core
A tool for building prototypes and pattern libraries.
Inspired heavily by component-styleguide. This is still very specific to our use-case so you probably want to look at component-styleguide first.
Details
Templating
Handlebars is used as the template engine.
Helpers
Handlebars is a logicless templating engine so you need helpers to do anything interesting in them. A set of helpers are provided in the templates to make prototyping as simple as possible.
| Helper | Description |
| ------ | ----------- |
|{{capitalize 'example'}}
| Capitalize a given string |
|{{couldBeTrue threshold}}
| Returns true/false
based on threshold
, e.g. 0.9
will return true
90% of the time. |
| {{debug object}}
| Will log the provided value to the console |
|{{envIs 'production'}}
| Check the current environment |
|{{envIsNot 'production'}}
| Reverse of envIs
check |
|{{getOrElse maybeValue "Default" }}
| Get a value if it exists otherwise return a default |
|{{htmlEscape '<h1>Hello</h1>'}}
| Escape HTML entities |
|{{inlineFile 'path/to/file.ext'}}
| Returns the contents of a file |
|{{isEqual value1 value2)}}
| Test if two values are equal |
|{{isUndefined value}}
| Test if a value is undefined |
|{{lorem count}}
| Lorem ipsum generator. Returns count
sentences |
|{{loremWords min max}}
| Lorem ipsum generator. Returns random words between min
and max
|
|{{prefixClass array 'letter'}}
| Takes an array of values and adds a prefix |
|{{{{raw}}}}Raw {{block}} helper{{{{/raw}}}}
| Block helper which disables handlebars processing for contents |
|{{#queryString 'param' matches='value' }}
| Block helper to check if a query string parameter matches a certain value |
|{{#repeat count}}block{{/repeat}}
| Repeat a block count
times |
|{{#repeatRange min max}}block{{/repeatRange}}
| Repeat a block between min
and max
times |
|{{stringify obj }}
| Passes input to JSON.stringify
. Useful for debugging |
Common Variables
A handful of root level common variables are exposed for use in templates. They are only available in listings as they are mostly used to get the current URL. If you need this data in a partial then pass it in as an argument.
| Variable | Description |
| -------- | ----------- |
| {{@root.link}}
| Relative link to the current page |
| {{@root.absoluteLink}}
| Absolute link to the current page |
| {{@root.queryString}}
| Raw query string object |
Partials
Everything under components/patterns
is automatically registered as a partial. For example {{> patterns/objects/icon}}
will render components/patterns/objects/icon.html
). This is powerful for making components comprised of other components.
Usage Notes
You can add markdown files in the patterns/
directory and the contents will be displayed alongside the pattern. The file needs to be named the same as the pattern e.g., patterns/base/text.md
alongside patterns/base/text.html
.
Default Collection Mock Data
Any pattern in a collecion can have default JSON data to be rendered in a collections list view. The file needs to be named the same as the file e.g., patterns/base/text.json
alongside patterns/base/text.html
. The format is:
{
"defaults": [{}]"
}
If more than one object is provided in the "defaults"
array the app will randomly select an item from the array. Useful for providing a few variations of mock data.
Global Mock data
All JSON files under data/
are concatenated into one context for the templates. E.g. users.json
containing []
and profile.json
containing {}
will result in the following data for the templates:
{
"users": [],
"profile": {}
}
Now, the {{#users}}
collection can be iterated over in any template.
Static assets
By default anything under /static
will be exposed by the server under /static
(this is configurable). This is just a static directory so you are responsible for loading them in your layout, but this means you have full control over how you manage your assets.
Installation Steps
If you don't want to start with the example app, need to configure some custom options, or just want to start from scratch you should follow these steps:
1. Install baseplate-core
npm init
npm install MadeHQ/baseplate-core --save
2. Structure
Create a directory structure similar to this:
├── baseplate-config.json
├── components
│ ├── pages
│ │ └── example-page.html
│ └── patterns
│ ├── base
│ └── modules
├── data
├── server.js
├── static
│ ├── images
│ ├── javascripts
│ └── stylesheets
└── views
└── layout.html
3. Components
There are two types of component directories: listings which are a simple list of items (used by default for pages) and collections which display items on a single page grouped by folder (used by default for patterns).
You can configure any custom sections you want in baseplate-config.json
, by adding a sections
config.
{
"sections": [{
"type": "list",
"title": "Pages",
"path": "/pages",
"directory": "pages",
"partials": false
}, {
"type": "collection",
"title": "Patterns",
"path": "/patterns",
"directory": "patterns",
"partials": true,
"showUsage": true,
"ordering": [
"base",
"objects",
"modules",
"collections"
]
}, {
"type": "collection",
"title": "Widgets",
"path": "/widgets",
"directory": "widgets",
"showUsage": true,
"partials": true
}]
}
Available options are as follows:
| Option | Description |
| ------ | ----------- |
|type
| Type of view: either list
or collection
|
|title
| Navigation title, shown in toolbar |
|path
| URL path |
|directory
| Directory, relative to components/
|
|partials
| Should these items be available as partials?. If so they will be namespaced under the directory name, e.g. {{> patterns/a/b }}
|
|showUsage
| If enabled and there is a .md
file with the same name as the file (e.g., example.html
and example.md
then usage notes will be shown alongside the item. Only available for collection
type. |
| showSource
| If enabled a "Show source" button will be shown to show the raw Handlebars source for the template |
|ordering
| By default collections will be ordered by directory name, if you want to customise the order, or exclude a directory from listings (but still have it available as partials) then a custom ordering will let you do this. Only available for collection
type. |
4. Layout
In order to display anything you need to add a layout.html
file under views/
.
Three snippets are required: {{> baseplate/styles}}
which returns a link to the pattern library styles and {{> baseplate/scripts}}
which returns a link to the pattern library styles and {{{body}}}
which renders the current view. Otherwise you are free to provide any html you like.
For example:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My Project</title>
<meta name="viewport" content="width=device-width,initial-scale=1">
{{> baseplate/styles}}
<link rel="stylesheet" href="/static/stylesheets/my-styles.css"/>
</head>
<body>
{{{body}}}
{{> baseplate/scripts}}
<script src="/static/javascripts/my-app.js" async></script>
</body>
</html>
Custom partials: You can provide custom partials under views/partials
which are then available in your layout as {{> partials/nameOfPartial }}
. This is mostly useful if you want to break your layout template into smaller parts.
5. Start
Add a server.js
using the following template.
var baseplateConfig = require('./baseplate-config.json');
var baseplate = require('baseplate-core')(baseplateConfig);
baseplate(baseplateConfig).then(function (server) {
server.start();
});
Run it with node server.js
API
baseplate(config<Object>) // returns <Promise>
baseplate(styleguide).then(function (server) {
/**
* server.app contains the Express app used internally
* Helpful if you want to add your own routes or modify the server
*/
server.app.get('/my-custom-route', function(req, res){
res.send('hello world');
});
/**
* Start the server
*/
server.start();
});
License
MIT