Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 84 lines (42 sloc) 4.836 kB
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
1 The engines plugin enhances Rails' own plugin framework, making it simple to share controllers, helpers, models, public assets, routes and migrations in plugins.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
2
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
3 For more information, see http://rails-engines.org
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
4
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
5 = Using the plugin
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
6
64ea89d Updated some documentation and other misc things for Rails 2.0
lazyatom authored
7 Once you've installed the engines plugin, you'll need to add a single line to the top of config/environment.rb:
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
8
64ea89d Updated some documentation and other misc things for Rails 2.0
lazyatom authored
9 require File.join(File.dirname(__FILE__), '../vendor/plugins/engines/boot')
10
11 You should add this line just below the require for Rails' own boot.rb file. This will enabled the enhanced plugin loading mechanism automatically for you (i.e. you don't need to set config.plugin_loader manually).
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
12
64ea89d Updated some documentation and other misc things for Rails 2.0
lazyatom authored
13 With that aside, you're now ready to start using more powerful plugins in your application. Read on to find out more about what the engines plugin enables.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
14
15
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
16 == Better plugins
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
17
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
18 In addition to the regular set of plugin-supported files (lib, init.rb, tasks, generators, tests), plugins can carry the following when the engines plugin is also installed.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
19
20
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
21 === Controllers, Helpers, and Views
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
22
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
23 Include these files in an <tt>app</tt> directory just like you would in a normal Rails application. If you need to override a method, view or partial, create the corresponding file in your main <tt>app</tt> directory and it will be used instead.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
24
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
25 * Controllers & Helpers: See Engines::RailsExtensions::Dependencies for more information.
8c4f141 @lazyatom Updated the README to reflect the removal of the RailsExtensions::Tem…
lazyatom authored
26 * Views: now handled almost entirely by ActionView itself (see Engines::Plugin#add_plugin_view_paths for more information)
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
27
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
28 === Models
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
29
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
30 Model code can similarly be placed in an <tt>app/models/</tt> directory. Unfortunately, it's not possible to automatically override methods within a model; if your application needs to change the way a model behaves, consider creating a subclass, or replacing the model entirely within your application's <tt>app/models/</tt> directory. See Engines::RailsExtensions::Dependencies for more information.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
31
daf57e2 Added note regarding overloading of code [Ticket 266]
lazyatom authored
32 IMPORTANT NOTE: when you load code from within plugins, it is typically not handled well by Rails in terms of unloading and reloading changes. Look here for more information - http://rails-engines.org/development/common-issues-when-overloading-code-from-plugins/
33
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
34 === Routes
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
35
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
36 Include your route declarations in a <tt>routes.rb</tt> file at the root of your plugins, e.g.:
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
37
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
38 connect "/my/url", :controller => "some_controller"
39 my_named_route "do_stuff", :controller => "blah", :action => "stuff"
40 # etc.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
41
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
42 You can then load these files into your application by declaring their inclusion in the application's <tt>config/routes.rb</tt>:
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
43
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
44 map.from_plugin :plugin_name
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
45
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
46 See Engines::RailsExtensions::Routing for more information.
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
47
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
48 === Migrations
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
49
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
50 Migrations record the changes in your database as your application evolves. With engines 1.2, migrations from plugins can also join in this evolution as first-class entities. To add migrations to a plugin, include a <tt>db/migrate/</tt> folder and add migrations there as normal. These migrations can then be integrated into the main flow of database evolution by running the plugin_migration generator:
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
51
5c099cb Major documentation drive. Most modules are now fully documented, alo…
lazyatom authored
52 script/generate plugin_migration
d11f657 Added documentation and tidied up Rake tasks
lazyatom authored
53
fd4e9ac Drastically improved handling of documentation and testing tasks for …
lazyatom authored
54 This will produce a migration in your application. Running this migration (via <tt>rake db:migrate</tt>, as normal) will migrate the database according to the latest migrations in each plugin. See Engines::RailsExtensions::Migrations for more information.
55
56
57 === More powerful Rake tasks
58
59 The engines plugin enhances and adds to the suite of default rake tasks for working with plugins. The <tt>doc:plugins</tt> task now includes controllers, helpers and models under <tt>app</tt>, and anything other code found under the plugin's <tt>code_paths</tt> attribute. New testing tasks have been added to run unit, functional and integration tests from plugins, whilst making it easier to load fixtures from plugins. See Engines::Testing for more details about testing, and run
60
61 rake -T
62
7fe93e5 @lazyatom Updated the README to include details of the new test task, and updat…
lazyatom authored
63 to see the set of rake tasks available.
64
65 = Testing the engines plugin itself
66
67 Because of the way the engines plugin modifies Rails, the simplest way to consistently test it against multiple versions is by generating a test harness application - a full Rails application that includes tests to verify the engines plugin behaviour in a real, running environment.
68
69 Run the tests like this:
70
71 $ cd engines
72 $ rake test
73
74 This will generate a test_app directory within the engines plugin (using the default 'rails' command), import tests and code into that application and then run the test suite.
75
76 If you wish to test against a specific version of Rails, run the tests with the RAILS environment variable set to the local directory containing your Rails checkout
77
78 $ rake test RAILS=/Users/james/Code/rails_edge_checkout
79
80 Alternatively, you can clone the latest version of Rails ('edge rails') from github like so:
81
82 $ rake test RAILS=edge
83
Something went wrong with that request. Please try again.