1 ------------------[ once you've read this, delete it ]---------------------
3 ENGINE DEVELOPERS - HEED THIS!
5 This is a sample README file to guide your users when they are installing what is undoubtedly going to be the finest piece of code they ever got their hands on. Lucky them, but alas they are often foolish, and so this is where you can guide them with the metaphorical beating of twigs. Or just a numbered series of instructions.
7 ANYWAY - you will almost certainly need to tailor this to your specific engine. For instance, your users will probably only need to include modules into the ApplicationController and ApplicationHelper if your engine defines methods to be usable by controllers and views external to your engine.
9 If you engine does not rely on any database tables, you will probably not need migrations either.
11 You are also under no obligation to use the 'config' method for setting options within your modules. Documentation which explains the purpose of the 'config' method is available as part of the Engines plugin itself.
13 Please check the engine development information on the Rails Engines wiki for more information about what to do now:
15 http://rails-engines.rubyforge.org/wiki/wiki.pl?DevelopingAnEngine
17 -----------------------[ remember to delete me! ]--------------------------
19 = <%= engine_class_name %>
21 <%= engine_class_name %> is a ...
23 This software package is developed using the Engines plugin. To find out more about how to use engines in general, go to http://rails-engines.rubyforge.org for general documentation about the Engines mechanism.
27 1. Create your Rails application, set up your databases, grab the Engines plugin and the <%= engine_class_name %>, and install them.
29 2. Install the <%= engine_class_name %> into your vendor/plugins directory
31 3. Modify your Engines.start call in config/environment.rb
33 Engines.start :<%= engine_start_name %> # or :<%= engine_underscored_name %>
35 4. Edit your application.rb file so it looks something like the following:
37 class ApplicationController < ActionController::Base
38 include <%= engine_class_name %>
41 5. Edit your application_helper.rb file:
43 module ApplicationHelper
44 include <%= engine_class_name %>
47 6. Perform any configuration you might need. You'll probably want to set these values in environment.rb (before the call to Engines.start):
49 module <%= engine_class_name %>
50 config :some_option, "some_value"
53 7. Initialize the database tables. You can either use the engine migrations by calling:
57 to move all engines to their latest versions, or
59 rake engine_migrate ENGINE=<%= engine_start_name %>
61 to migrate only this engine.
63 8. The <%= engine_class_name %> provides a default stylesheet and a small javascript helper file, so you'll probably want to include the former and almost certainly the latter in your application's layout. Add the following lines:
65 <%%= engine_stylesheet "<%=engine_start_name%>_engine" %>
66 <%%= engine_javascript "<%=engine_start_name%>_engine" %>
70 A number of configuration parameters are available to allow to you control
71 how the data is stored, should you be unhappy with the defaults. These are
74 module <%= engine_class_name %>
75 config :some_option, "some_value"
78 === Configuration Options
79 +some_option+:: This option will set some_value
82 How to use this engine