Using Plugins, Extending Functionality

0.4.x

OLD: This is an old version of documentation. You probably want the most recent version of this document, from the sidebar on the right.

Inject’s plugin support allows you to transform and manipulate assets that may not be JavaScript by default. By converting them to JavaScript, you can use these assets just like any other require resource. This page talks about how to use the three default plugins that ship with Inject. Feel free to add your own plugins by following the example. Eventually, we expect to have a library of plugins for all.

If you’re interested in using a plugin popularized by the AMD Specification, please read the how-to for AMD.

Enabling Inject Plugins

Enabling Inject Plugins can be done by adding a script tag to your existing page:

<!-- Just below inject.js, add inject-plugins.js -->
<script type="text/javascript" src="/inject.js"></script>
<script type="text/javascript" src="/inject-plugins.js"></script>

You’re now ready to use the default plugins installed with Inject.

The Text Plugin

A sample “text” resource:

I'm some really cool text

Using this text in your code:

var text = require('text!/path/to/text/file.txt');

The text plugin is the simplest of plugins. It reads in the contents of a text file, and makes it available as a requireable resource.

The CSS Plugin

A sample “css” resource:

body {
  font-size: 999px;
}

Using this CSS in your code:

var css = require('css!/path/to/css/file.css');
css.attach();

The CSS plugin takes a given CSS file, and transforms it into a JavaScript object. The JS object has a single method attach() which will apply the styles to the current page in a cross-browser way. This is really helpful in scenarios where you are bundling a complete HTML and CSS combination, but want to wait to attach the styles to minimze reflows.

The JSON Plugin

A sample “JSON” resource:

{
  "stuff": ["one", "two", "three"],
  "things": {
    "one": "eno",
    "two": "owt",
    "three": "eerht"
  }
}

Using this JSON in your code:

var data = require('json!/path/to/json/file.json');
console.log(data);

The JSON plugin reads the JSON file in as text, and automatically performs a JSON.parse() on the file contents. The resulting object is made available as the result of the require() call.

Writing Your Own Plugin

Start with the Inject Plugin API. It’s syntax is similar to addRule, but comes with additional functionality to add globally reachable functions to Inject, and pre-build your regex matches for you.