Nitrogen Plugins
Home | Getting Started | API | Elements | Actions | Validators | Handlers | Configuration Options | Plugins | Mobile | Troubleshooting | About
Table of Contents
1 Plugins Overview
Nitrogen 2.2.0 introduced a plugin system for including Nitrogen elements, actions, validators, modules, handlers, and static resources from external sources (typically as rebar dependencies).
Generally speaking, this provides for a simpler way of handling additional modularity, by creating custom reusable elements that can be shared between applications and/or other programmers.
2 Adding a plugin to your app
The simplest way to include a plugin in your app is to include it as a rebar
dependency. In the deps section of your rebar.config file, add something
like the following:
{my_plugin, ".*", {git, "git://github.com/user/my_plugin.git", {branch, master}}},
Then run `make` in your application. It will download the plugin, add to your plugins.hrl file a reference to any include files (.hrl files), copy any static resources into your application's directory structure, and finally recompile everything.
What happens when you add a plugin to your app
The Nitrogen Plugin installer does a handful of things to your Application
directory structure. Any static resources are automatically copied into a
site/static/plugins/<pluginname> directory. Any Erlang includes (.hrl
files) are added as -include calls to the site/include/plugins.hrl file.
And, of course, being an Erlang dependency, the source code for the plugin
will be automatically loaded.
The directories above can all be customized with the plugins.config file found in the root of your Nitrogen release (see the "plugins.config" section of Configuration Options for how to customize your plugin configuration.
3 Finding plugins to include in your app
Currently, the list of available plugins are found on our Plugins Wiki Page on GitHub.
If you've created your own plugins, feel free to include it in that list.
4 Creating your own plugins
Sample Nitrogen Plugin
The simplest way to create your own plugin is to start with the Sample Nitrogen Plugin and expand on it to make your own plugin.
Creating your plugin from scratch
Creating a reusable plugin from scratch is a relatively simple task, and it requires following the following steps:
- A Nitrogen plugin must be a valid Erlang application, that is, it has either a .app file in the ebin directory, or a .app.src file in the src directory.
- In order for Nitrogen to determine that an application is indeed a
Nitrogen plugin, the root of your plugin must contain the file
nitrogen.plugin. This file can be blank. - Place any static resources (javascript, CSS, images, etc) in the
priv/staticdirectory of your plugin. - Place any templates in the
priv/templatesdirectory of your plugin. - Place any necessary Erlang header files (e.g. if this plugin contains
custom elements or actions) in a directory in the root of the plugin
and call it
include. - Finally, place your plugin's Erlang source code in the
srcdirectory.
5 Adding plugin support to an older version of Nitrogen
What if you have a version of Nitrogen pre-2.2.0, but you still want to add support to your Nitrogen app?
There's actually no technical reason you can't do that. In fact, the core of the plugin system is a single script, executed sometime after dependencies are fetched and before compilation.
That script is called do-plugins.escript and it can be found in the main Nitrogen repo. The easiest way, then to add the plugin system to your app is to do the following in the root of your app:
wget https://raw.github.com/nitrogen/nitrogen/master/rel/overlay/common/do-plugins.escript chmod 755 do-plugins.escript
Then simply modify your Makefile so that ./do-plugins.escript is executed
before ./rebar compile
For a good practical example of this, check out the standard Makefile that comes with a Nitrogen install.