lb-include

Library for #include-ing HTML files inside other HTML files, with super simple variable substitution. Named because in some places # is pronounced 'pound', which is often abbreviated 'lb', hence #include -> lb-include.

Builds hosted by Travis CI:
master: ,
develop:

* Install
* Plugins
* Overview
* Usage
* options.root
* options.fileContents
* options.varDefaults
* options.varOverrides
* Template Syntax
* Root-relative file paths
* Simple variable substitution
* Tests
* License

Install

``sh
$ npm install --save lb-include
`

$3

There are also a few plugins that use lb-include:

* connect-lb-include - Connect/Express middleware that can process static or dynamic responses
* 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-flavored Promise, even if you omit the third argument.




$3

* 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

`

$3

* 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 #included 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 #included files.




$3

* 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
`




$3

* 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



Kilo Corporation

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras non accumsan arcu. Vestibulum...

`

Where app/fragments/header.html is something like:

`html









`

...and app/fragments/footer.html is something like:

`html


`

In this case, you can easily get the transformed markup:

`js
var include = require('lb-include');
include('app/pages/index.html', function(err, markup)
{
//do something here
});
`

$3

Let's say you want to move app/pages/team.html to app/pages/team/index.html. If you just do this, all your
paths in #includes will need an extra ../. Depending on how deep your folders go, it can be hard to manage all
of the ../s in your paths.

Instead, you can specify root-relative URLs for your #includes, like so:

`html



Our team

I 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 #includes 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
});
`




$3



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:

`html






`

Here's how we would include the header:

`html



This is our team. We aren't very large, yet.



`

And this is what the final markup looks like:

`html








This 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

See LICENSE.md for full license text