Mephisto supports several different kinds of plugins, including:

  1. FilteredColumn plugins. These add new <macro:*> forms for use in articles. Two good examples are filtered_column_code_macro and filtered_column_haskell_macro.
  2. Custom Drop classes. These add new commands to Mephisto’s Liquid templates. For example, this drop adds an RSS feed sidebar to a site.
  3. True Mephisto plugins. These plugin extend the actual Mephisto interface. A popular example is mephisto_contact_form.

3 APIs for true Mephisto plugins

Here’s where things get a bit complicated. Mephisto’s plugin API has changed several times. This doesn’t really affect FilteredColumn plugins, or custom drops, but it does mean that “true” Mephisto plugins are only compatible with specific versions of Mephisto.

There isn’t a lot of documentation for any of these 3 incompatible plugin APIs. So I can try to explain the history here, but I may make some mistakes. Thanks go to Sven Fuchs and Isaac Kearse, who explained all this to me. Any remaining errors are my own.

  1. The original plugin API. This was a simple, declarative plugin API used in older versions of Mephisto. It made some plugins extremely easy to write, but it apparently didn’t offer an easy way of defining new controllers. You can find some notes by James Crisp on this API.
  2. Sven Fuchs’ engines-based plugin API. Sven Fuchs overhauled the original API, and based it on Engines. For more details, see the porting notes for this API. You can find this API on Mephisto’s master branch.
  3. Isaac’s Kearse’s new engines-based plugin API. Isaac Kearse is trying to combine the best features of the two earlier APIs. For some example code, see his updated version of the Mephisto feedback plugin. You can find this new plugin API on Mephisto’s new-plugins branch. Ideally, it should be extremely easy to port original-style plugins to this new API.

I’m leaning towards merging Isaac Kearse’s new API to the master branch, but he and I would like to solicit feedback from the Mephisto community first. Do you run lots of Mephisto plugins? Do you know what API they’re based on?

In the long run, we’d like to have an extremely stable plugin API, preferably based on the integrated Engines support in Rails 2.3. But we’re still figuring out how to get there. So thank you for your feedback and advice!