🌱 asynchronous inline content replacement
Switch branches/tags
Nothing to show
Clone or download
Latest commit ade7af4 Apr 25, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.editorconfig Add code Mar 21, 2018
.gitattributes Add code Mar 21, 2018
.gitignore Add ignore Mar 21, 2018
.npmrc Add code Mar 21, 2018
.travis.yml Add code Mar 21, 2018
.yo-rc.json Add code Mar 21, 2018
LICENSE Add code Mar 21, 2018
README.md Preserve non-existing handler content Apr 21, 2018
implant-logo.png Update logo and readme Mar 22, 2018
index.js Fix linting Apr 25, 2018
index.test.js Fix linting Apr 25, 2018
package.json Fix version Apr 25, 2018

README.md

Implant

🌱 asynchronous inline content replacement

Build Status Coverage Status NPM Version XO code style

Support the development of Implant.

Install

$ yarn add implant

Fetching Network Resources

Reference an Implant handler from your HTML:

<p>{get: "https://f1lt3r.github.io/foobar/bazqux.html"}</p>

Write the Implant handler:

const request = require('request')

const handlers = {
    get: url => new Promise((resolve, reject) => {
        request(url, (err, res, body) => {
            if (err) {
                return reject(err)
            }

            resolve(body)
        })
    })
}

const result = implant(html, handlers)'

The content of bazqux.html is fetched from the web when implant handler is executed.

Checkout the result:

<p><h1>Hello, wombat!</h1></p>

Using JavaScript Objects

You can use plain JavaScript object within your HTML:

<div>
    <!-- Implant reference object -->
    {article: {
        id: 8421,
        section: 3
    }}
</div>

Your Implant handler can reference data using the properties you pass:

// Some store of data
const articles = {
    8421: {
        sections: {
            3: 'Foo. Or foo not. There is no bar.'
        }
    }
}

// Implant handler returns data from store
const handlers = {
    article: ref => {
        const {id, section} = ref
        return articles[id].sections[section]
    }
}

const result = implant(html, handlers)

Result:

<div>Foo. Or foo not. There is no bar.</div>

Using Illegal JavaScript Values

It is also possible to use illegal JavaScript values, such as references to objects that do not exist. For example:

<div>{foo: i.find.your.lack.of.qux.disturbing}</div>

When an illegal value is encountered, Implant pass back a stringified version of the handler.

const handlers = {
    foo: uri => console.log
    // 'i.find.your.lack.of.qux.disturbing'
}

Handling values this way allows you to write cleaner syntax in your content templates by excluding quotes; or designing your own custom syntax.

You might use this feature to reference filenames without quotes:

<div>{article: programming-101.md}</div>

Then you could fetch and render the article like this.

const handlers = {
    foo: uri => fetchPost(uri)
}

Recusion

You can recurse through the result of you implant like this:

const html = {
    level1: '<div>1 {include: level2}</div>',
    level2: '<div>2 {include: level3}</div>',
    level3: '<div>3 {include: level4}</div>'
}

const handlers = {
    include: ref => {
        return html[ref]
    }
}

const opts = {
    maxRecursion: 3
}

;(async () => {
    const result = await implant(html.level1, handlers, opts)

})()

Result:

<div>1 <div>2 <div>3 {include: level4}</div></div></div>

Why Recusion?

You may want to use recursion if you are building a just-in-time dependancy tree. For example: if your implant fetched a dependency that contained a reference to another depdendancy.

Note: if you do not specify the maxRecusion option, implant will only run once.

Credits

Thanks to the following designers from the Noun Project for the vectors used in the lead graphic.