](https://travis-ci.org/jffry/lb-include),
`develop`: [
](https://travis-ci.org/jffry/lb-include)
* [Install](#install)
* [Plugins](#plugins)
* [Overview](#overview)
* [Usage](#usage)
* [options.root](#optionsroot)
* [options.fileContents](#optionsfilecontents)
* [options.varDefaults](#optionsvardefaults)
* [options.varOverrides](#optionsvaroverrides)
* [Template Syntax](#template-syntax)
* [Root-relative file paths](#root-relative-file-paths)
* [Simple variable substitution](#simple-variable-substitution)
* [Tests](#tests)
* [License](#license)
## Install
```sh
$ npm install --save lb-include
```
### Plugins
There are also a few plugins that use `lb-include`:
* [`connect-lb-include`](https://github.com/jffry/connect-lb-include) - Connect/Express middleware that can process static or dynamic responses
* [`gulp-lb-include`](https://github.com/jffry/gulp-lb-include) - Use `lb-include` as part of a gulp task
## Overview
Let's assume you have some folder, containing two files, `index.html` and `nav.html`.
In `index.html` let's say you have this:
```html
```
Likewise, in `nav.html`, let's say you have this:
```html
```
If you want to be able to do something like this, then `lb-include` is the right tool for you. It's a simple little
tool which you can wire up into your own stuff (like a Connect middleware, or maybe a Gulp/Grunt/Broccoli plugin).
In this example, all you need to do is:
```js
var include = require('lb-include');
include('path/to/index.html', function (err, markup)
{
//do whatever here
});
```
This will asynchronously load and transform the markup.
## Usage
`lb-include` can be used in two different asynchronous styles
```js
var lb_include = require('lb-include');
//callback style
lb_include('path/to/file.html', options, function (err, markup) {
//do whatever here
});
//promises style (kriskowal/q)
lb_include('path/to/file.html', options).then(function (markup) {
//do whatever here
});
```
The first argument is required, and should be the path to the file to be loaded and resolved.
The second argument, `options`, is an optional object hash with properties described below. This may be omitted.
The third argument is a standard callback function, and it is optional. `lb-include` will also
return a [`kriskowal/q`](https://github.com/kriskowal/q)-flavored Promise, even if you omit the third argument.
### options.root
* Optional: yes
* Type: `string` (a path)
* Default: `process.cwd()`
The root directory, from which root-relative includes are performed. Use: If you have nested folders, you may not want to
have to use file-relative paths, which are fragile and will break if you move the parent file to a different folder:
```html
```
Instead, you might want to define root-relative paths, and then tell **lb-include** what the root folder is:
```html
```
### options.fileContents
* Optional: yes
* Type: `string` or `Buffer`
If you are trying to `include()` a file, but you already happen to have the unprocessed source hanging around in
memory (perhaps because you're writing a Gulp plugin or a Connect middleware), then you can pass it in here. For
the file passed as the first argument to `include`, this value will be used instead of reading the file from disk.
Note that any files `#include`d from within this file will always be read from disk. In the future, there may be
some way to cache or programmatically transform the contents of other `#include`d files.
### options.varDefaults
* Optional: yes
* Type: `object`
Provide default values for variable substitutions. If a variable is set in both `options.varDefaults` AND in
the `#include` directive, the variable from the `#include` wins. For example, if we have these files:
```html
You have: ${count} ${item}
```
```html
```
...and we run this code:
```js
var include = require('lb-include');
var defaults = {
'${count}': 5,
'${item}': 'apples'
};
include('path/to/index.html', { varDefaults: defaults }, function (err, markup)
{
//do whatever here
});
```
...will yield this output:
```html
You have: 5 bananas
```
### options.varOverrides
* Optional: yes
* Type: `object`
Forces specific values for variable substitutions. This overrides any values set in `options.varDefaults` or on
the `#include` directive.
```html
You have: ${count} ${item}
```
```html
```
...and we run this code:
```js
var include = require('lb-include');
var overrides = {
'${count}': 5,
'${item}': 'apples'
};
include('path/to/index.html', { varOverrides: overrides }, function (err, markup)
{
//do whatever here
});
```
...will yield this output:
```html
You have: 5 apples
```
## Template Syntax
Let's say you have a folder structure like this:
```
app/
|- pages/
| |- index.html
| \- team.html
\- fragments/
|- header.html
|- nav.html
\- footer.html
```
In `app/pages/index.html` and `app/pages/team.html` you might want to do something like this:
```html
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras non accumsan arcu. Vestibulum...
``` Where `app/fragments/header.html` is something like: ```htmlI don't need to write anything here because you already know our team is awesome!
``` Note that we don't need to change `nav.html` - relative `#include`s are always relative to the file in which they reside. However, when loading the markup, we need to tell `lb-include` what the root folder is: ```js var include = require('lb-include'); include('app/pages/team/index.html', {'root':'app/fragments/'}, function(err, markup) { //do something here }); ``` ### Simple variable substitution In addition to the `file="..."` part of your `#include`, you can have any number of other key/value pairs, which will then get substituted before the output markup is returned. Let's imagine that when we include `header.html`, we might want to change the page title and meta tag description so that each page is unique. So here's `header.html`: ```htmlThis is our team. We aren't very large, yet.
``` And this is what the final markup looks like: ```htmlThis is our team. We aren't very large, yet.
... ``` The keys can be named any combination of characters other than whitespace and the equals sign. These will be replaced verbatim with their output, hence why I used identifiers armored with `${}` above. You could as easily use `@pageTitle` or `$pageTitle` or whatever you want - just be aware that replacement is done via unintelligent search-and-replace. The values are JSON-quoted single-line strings. So `${key}="apples\nbananas"` will replace all instances of `${key}` with a output containing a newline. This also lets you have double quotes in your substituted output.npm Note that the replacement is not HTML-encoded before it gets stuck into the output, as it's assumed at template-time that you know what you are doing (and it might be useful to include bits and bobs of HTML in places) ## Tests To run the tests, checkout this repo and then `npm install` then `npm test`. To rerun the tests automatically as you edit files, use `npm run test-watch` instead. ## License Released under the MIT license © [Jeffrey Stanton](https://github.com/jffry) See [LICENSE.md](LICENSE.md) for full license text --- _Source: https://npm.io/package/lb-include · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._