Library for `#include`-ing HTML files inside other HTML files, with super simple variable substitution.
npm install lb-includeLibrary 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
``sh`
$ npm install --save lb-include
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
Let's assume you have some folder, containing two files, index.html and nav.html.index.html
In 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.
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 alsokriskowal/q
return a -flavored Promise, even if you omit the third argument.
* Optional: yes
* Type: string (a path)process.cwd()
* Default:
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`
* 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 ininclude
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 , 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#include
some way to cache or programmatically transform the contents of other d files.
* Optional: yes
* Type: object
Provide default values for variable substitutions. If a variable is set in both options.varDefaults AND in#include
the 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
* Optional: yes
* Type: object
Forces specific values for variable substitutions. This overrides any values set in options.varDefaults or on#include
the 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
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:
` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras non accumsan arcu. Vestibulum...html`Kilo Corporation
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
});
Let's say you want to move app/pages/team.html to app/pages/team/index.html. If you just do this, all your#include
paths in s 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:
` I don't need to write anything here because you already know our team is awesome!html`Our team
Note that we don't need to change nav.html - relative #includes are always relative to the file in which theylb-include
reside. However, when loading the markup, we need to tell 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
});
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
${page.title}
`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
About our "team"
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.Released under the MIT license © Jeffrey Stanton
See LICENSE.md for full license text