Writing Nesta plugins
Nesta plugins are distributed as Ruby gems. They're easy to create and easy to install.
Getting started
The nesta
command can create a new plugin for you:
$ nesta plugin:create my-feature
It will create a new Ruby gem folder called nesta-plugin-my-feature
with some boilerplate Ruby files for you to add your code to.
Quick tour of the files
There are only three files in the top level of your plugin; .gemspec
,
Gemfile
, and Rakefile
.
$ ls
Gemfile lib/
Rakefile nesta-plugin-my-feature.gemspec
The Gemfile
allows you to install your gem's dependencies with
Bundler. The Rakefile
provides a couple of Rake tasks to build and
install the gem.
All the action happens inside the lib/
folder.
$ ls lib/ lib/nesta-plugin-my-feature/
lib/:
nesta-plugin-my-feature/ nesta-plugin-my-feature.rb
lib/nesta-plugin-my-feature/:
init.rb version.rb
When Ruby loads your gem it will automatically require the
lib/nesta-plugin-my-feature.rb
file. You'll also find init.rb
and
version.rb
files inside the lib/nesta-plugin-my-feature/
folder.
version.rb
is where you specify your gem's version number.
init.rb
is where you put your code, and is the only file you need to edit.
Writing your plugin's code
The short version is "add everyting to init.rb
".
Writing your code
This is what the default init.rb
file looks like, at the time of writing:
module Nesta
module Plugin
module My::Feature
module Helpers
# If your plugin needs any helper methods,
# add them here...
end
# Add classes and methods here, within the
# My::Feature module.
end
end
class App
helpers Nesta::Plugin::My::Feature::Helpers
end
end
You can add anything you like inside the App
class (just as you would
inside an app.rb
file in your own site). You can also add new classes,
but its best to keep those inside your plugin's own namespace so that
they can't clash with modules from other plugins.
You can also modify existing models by "monkey patching" Nesta's own
classes. For example, the end of your init.rb
file could end up looking
something like this:
class App
helpers Nesta::Plugin::My::Feature::Helpers
end
class Page
def awesome?
flagged_as?('awesome')
end
end
end
If your plugin has a lot of code feel free to split it up into separate
files and require them from within init.rb
.
How plugins get loaded
This section is only here in case you're interested in how it works; you can skip it without losing any sleep.
When Nesta starts up Ruby reads config.ru
, which tells it to fire up
Bundler and read the Gemfile
. Bundler then requires all the gems in
Gemfile
which loads the nesta
gem, and then your plugin's gem.
At this point Nesta hasn't really been loaded fully (that won't happen
until Ruby gets a few lines further down in config.ru
) so it's not a
good time for a plugin to try and modify Nesta.
Instead, plugins just register themselves with Nesta so that Nesta knows
that they're there, and can load the plugin's actual code once Nesta is
ready. This is why lib/nesta-plugin-my-feature.rb
only contains this
line:
Nesta::Plugin.register(__FILE__)
The final step is when Nesta loads lib/nesta-plugin-my-feature/init.rb
,
at which point you can expect all of Nesta's classes and routes to have
been defined.
Development tips
You'll obviously need a Nesta project to test the plugin with.
Add your plugin to the site's Gemfile
and run Bundler:
$ cd path/to/site
$ echo 'gem "nesta-plugin-my-feature", \
:path => "../nesta-plugin-my-feature"' >> Gemfile
$ bundle
Note the :path
option which tells Bundler to load the gem from the
folder on your file system. Using this option means that the changes you
make to the plugin's source will immediately be reflected when you
reload pages in your test site (so long as you start your site with
mr-sparkle
).
Fire up your site and see if the plugin works as intended.
Building the gem
Open the .gemspec
file in a text editor and replace the placeholder
summary and description with text that describes your plugin:
$ cd nesta-plugin-my-feature
$ vi nesta-plugin-my-feature.gemspec
Your .gemspec
comes preconfigured with Nesta and Rake as dependencies,
so let's start by installing the bundle:
$ bundle install
Now we can run a Rake task to build the plugin's gem. Your .gem
file
will be created inside a pkg/
folder.
$ rake build
If you want to build and install in one step you can also run:
$ rake install
Releasing your plugin
Releasing as a Git repository
Releasing a gem via a git repository is easy. Push your gem to a remote
git repository (e.g. on GitHub) and then tell Bundler (in your site's
Gemfile
) to install the gem from a git repository, like so:
gem "nesta-plugin-my-feature",
:git => "git://github.com/user/nesta-plugin-my-feature.git"
Releasing via rubygems.org
If your plugin is only for your own use, and others wouldn't find it particularly useful, please distribute it as Git repository rather than via rubygems.org. There are two reasons for this:
- Distributing with Git is easier and quicker for you, and
- People who are looking for useful plugins won't have to search through a smorgasbord of irrelevant gems in order to find plugins that will be useful to them.
This convention will also mean that we can query Rubygems to see what plugins have been released for general use:
$ gem list -r nesta-plugin
Okay, assuming your plugin is one for sharing, this is how you release it to rubygems.org:
- Set the correct version number in
version.rb
. - Run
bundle
to make sure that everything is up to date. - Commit any outstanding changes to your Git repository.
- Run
rake release
.
You'll need to register an account with rubygems.org if you don't have one already. The Rake task walks you through this process so I won't repeat those instructions here.
If you've followed all the above (and it worked), Nesta now has one extra plugin. :-)
Documentation
If you'd like to add your plugin to the Plugin Directory
fork a copy of the nestacms.com site and add a page in the
content/pages/docs/plugins
folder. Describe your plugin briefly,
linking to your README file if there are any lengthy instructions
required.
Feel free to include your name and a link to your own site at the end of the page.
When you're done, send a pull request to gma
.
Feedback on the process (and the experience) would be appreciated. Let us know at support@nestacms.com.