projects.mako.cc - selectricity/blob - 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 %>