How do I convert an existing Rails 3 Application into an Engine?

Question

How can I convert the Forum application I've been developing into a Rails Engine, so that it may be embedded inside other applications?

What should I add, keep, or remove? Should I offer a way to integrate the models? How do I set up routes and user configuration? How do I package it into a Gem? What should I watch out for?

---

After reading the articles and the documentation, I managed to narrow down my questions:

• Should I namespace the models? That is, should I keep them in my Engine's module and in the app/models/engine folder?
• What configuration files in config should I keep around?
• What about the public folder? In Rails 3.1, stylesheets and javascripts were moved to the app/assets folder, which solved this problem, but how do I achieve the same effect in Rails 3.0?

Answer 1

Too many questions here to answer them all properly. This is one of those things that will pay off for you by just digging in and trying it out. As you get deeper into it, come back and ask new specific questions.

Here are some of the resources I used when I recently did this.

• http://www.themodestrubyist.com/2010/03/05/rails-3-plugins---part-2---writing-an-engine/
• http://www.themodestrubyist.com/2010/03/16/rails-3-plugins---part-3---rake-tasks-generators-initializers-oh-my/
• http://pragprog.com/titles/jvrails/crafting-rails-applications
• http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/

For the most part, you can keep the things in your app directory where they are. You should also be able to keep your routes.rb in the config directory, but there can be some gotchas if some of your routes collide with those of the app.

You will likely want to create a generator to create a migration that has all of the tables your engine requires. Other generators can be created to override default views and that sort of thing.

Do create a test application that uses your gem. Many of the issues you will run into are making sure you are loading your engine's dependencies properly. While you are in development, edit the Gemfile of your test application to point straight to the source of your gem... something like this:

gem 'my-forum', :path => '~/work/my-forum'

Namespacing

You should at least name your tables/models so you don't run into naming collisions. Looking at your current forum app, I'd at least prefix all of your tables with 'forum_'. It is quite likely that someone using your engine will have a different model named Category for example... so ForumCategory would be a better choice.

Definitely namespace any classes you create in the lib directory.

Config Files

You'll want to keep your routes.rb in the config directory. You may also need to keep your initializers around as well. Any app specific things will likely need to get moved elsewhere.

Public Files

With Rails 3.0.x, you can keep stylesheets and javascripts in the public directory. I think there is a bit of code you need to add to your Engine class though...

initializer "static assets" do |app|
  app.middleware.use ::ActionDispatch::Static, "#{root}/public"
end