]> projects.mako.cc - selectricity/blob - vendor/plugins/engines/generators/engine/templates/README
4d2371ce6ff896f519090d477682319b1cc9efa9
[selectricity] / vendor / plugins / engines / generators / engine / templates / README
1 ------------------[ once you've read this, delete it ]---------------------
2
3 ENGINE DEVELOPERS - HEED THIS!
4
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.
6
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.
8
9 If you engine does not rely on any database tables, you will probably not need migrations either.
10
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.
12
13 Please check the engine development information on the Rails Engines wiki for more information about what to do now:
14   
15   http://rails-engines.rubyforge.org/wiki/wiki.pl?DevelopingAnEngine
16
17 -----------------------[ remember to delete me! ]--------------------------
18
19 = <%= engine_class_name %>
20
21 <%= engine_class_name %> is a ...
22
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.
24
25 == Installation
26
27 1. Create your Rails application, set up your databases, grab the Engines plugin and the <%= engine_class_name %>, and install them.
28
29 2. Install the <%= engine_class_name %> into your vendor/plugins directory
30
31 3. Modify your Engines.start call in config/environment.rb
32
33     Engines.start :<%= engine_start_name %> # or :<%= engine_underscored_name %>
34
35 4. Edit your application.rb file so it looks something like the following:
36
37     class ApplicationController < ActionController::Base
38       include <%= engine_class_name %>
39     end
40
41 5. Edit your application_helper.rb file:
42
43     module ApplicationHelper
44       include <%= engine_class_name %>
45     end
46
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):
48
49     module <%= engine_class_name %>
50       config :some_option, "some_value"
51     end
52
53 7. Initialize the database tables. You can either use the engine migrations by calling:
54
55     rake engine_migrate
56
57   to move all engines to their latest versions, or
58
59     rake engine_migrate ENGINE=<%= engine_start_name %>
60
61   to migrate only this engine.
62
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:
64
65       <%%= engine_stylesheet "<%=engine_start_name%>_engine" %>
66       <%%= engine_javascript "<%=engine_start_name%>_engine" %>
67
68 == Configuration
69
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
72 outlined below. 
73
74   module <%= engine_class_name %>
75     config :some_option, "some_value"
76   end
77
78 === Configuration Options
79 +some_option+:: This option will set some_value 
80
81 == Usage
82 How to use this engine
83
84 == License
85 <%= license %>

Benjamin Mako Hill || Want to submit a patch?