/include

plugin that adds the ability to include html from other files

Primary LanguageJavaScriptMIT LicenseMIT

Reshape Include

npm tests dependencies coverage

Include other HTML files ("partials") into your HTML.

Install

npm i reshape-include --save

Usage

Given the following input files:

<!-- index.html -->
<p>Here's my partial:</p>
<include src='_partial.html'></include>
<p>after the partial</p>
<!-- _partial.html -->
<strong>hello from the partial!</strong>

Process them with reshape:

const {readFileSync} = require('fs')
const reshape = require('reshape')
const include = require('reshape-include')

const html = readFileSync('index.html')

reshape({ plugins: include() })
  .process(html)
  .then((result) => console.log(result.output()))

Output:

<p>Here's my partial:</p>
<strong>hello from the partial!</strong>
<p>after the partial</p>

Utilizing Different Parsers

Sometimes, you might want to import a html file into a sgr file. Or maybe a svg. In these cases and any other where you are seeking to mix two files that are processed by different parsers, you can utilize the parserRules config value. Example shown below:

const htmlParser = require('reshape-parser')
const sugarml = require('sugarml')
const include = require('reshape-include')

reshape({
  plugins: [
    include({
      parserRules: [
        { test: /\.sgr$/, parser: sugarml }
        { test: /\.html$/, parser: htmlParser }
      ]
    })
  ]
})

Note that anything not matched by a parserRules test will be parsed by whatever parser is being used by reshape from its primary config. So in the example above, the html test is unnecessary -- since reshape's default parser is reshape-parser, it will already use this for any file not matching .sgr.

Note that any parser can be used here in theory, but it must output a valid Reshape AST. Feel free to make use of the reshape AST validator if you want in the process.

Options

All options are optional, none are required.

Name Description Default
root Root path to resolve the include from the file's path.
alias Object with alias mappings, each key is your reference and the corresponding value is the relative path to your file. { button: './views/button.html }
parserRules Array of objects that can include the test (regex) and parser (fn) keys. See readme for further details

root

Setting root to a static value can be useful for managing nested templates. If you attempt to use relative paths in the src for your includes it won't always work. If you set root to the root folder containing your templates, then you can include any file in any other file using a (partial) full path - partial meaning relative to root.

Reporting Dependencies

This plugin will report its dependencies in the standard format as dictated by reshape-loader if you pass dependencies: [] as an option to reshape when it runs. Dependencies will be available on the output object under the dependencies key. For example:

const reshape = require('reshape')
const include = require('reshape-include')

reshape({ plugins: [include()], dependencies: []})
  .process(someHtml)
  .then((res) => {
    console.log(res.dependencies)
    console.log(res.output())
  })

If you are using this with webpack, reshape-loader takes care of the dependency reporting and you don't have to do anything 😁

License