]> projects.mako.cc - selectricity/blob - vendor/plugins/engines/README
A few major changes:
[selectricity] / vendor / plugins / engines / README
1 = Welcome
2
3 This document gives an overview of how the Engines mechanism works within a Rails environment. In most cases the code below is just an example. For more information or documentation, please go to http://rails-engines.org.
4
5 == Background
6
7 Rails Engines are a way of dropping in whole chunks of functionality into your
8 existing application without affecting *any* of your existing code. The could also be described as mini-applications, or vertical application slices - top-to-bottom units which provide full MVC coverage for a certain, specific application function.
9
10 As an example, the Login Engine provides a full user login subsystem, including: 
11 * controllers to manage user accounts; 
12 * helpers for you to interact with account information from other 
13   parts of your application; 
14 * the model objects and schemas to create the required tables; 
15 * stylesheets and javascript files to enhance the views; 
16 * and any other library files required.
17
18 Once the Rails Core team decides on a suitable method for packaging plugins, Engines can be distributed using the same mechanisms. If you are developing engines yourself for use across multiple projects, linking them as svn externals allows seamless updating of bugfixes across multiple applications.
19
20
21
22
23
24 = Edge Engines
25
26 If you are using Edge Rails (an SVN copy of Rails, rather than an 'official' release), there are several MASSIVELY IMPORTANT issues that you need to bear in mind.
27
28 Firstly, you are using an unstable version of Rails, so it is possible that things will break. We work hard to keep the Engines plugin up to speed with the changes in Rails at the bleeding edge, but sometimes significant parts of Rails change it WILL cause problems. This is the price of using the bleeding edge. Since edge is synonymous for unstable, the version of the Engines plugin which is compatible with Edge Rails is kept separate from the official release. Please ensure that you have used SVN to get your engines plugin from
29
30   http://svn.rails-engines.org/engines/trunk
31   
32 The normal 'script/plugin install engines' will NOT get you this version.
33
34 Secondly, you NEED to tell the engines plugin if you expect it to perform with Edge behaviour. This is done by adding the following lines at the *very top* of environment.rb (yes, the VERY TOP)
35
36   module Engines
37     CONFIG = {:edge => true}
38   end
39
40 This will set the plugin to work with Edge Rails, rather than expecting an official release.
41
42 If you are having problems, please try and contribute a bug report if you can so we can improve the plugin and keep up to speed with Rails' bleeding edge. Your input is *absolutely crucial* to this. If you're not comfortable with tracking down bugs in Rails' and Engines' internal code, there is a test application available at
43
44   http://svn.rails-engines.org/applications/engines_test
45   
46 which contains an array of tests that might help you (and us) pinpoint where the issue is. Please download this application and consult the README for more information.
47
48 Finally, please don't forget about our website and mailing lists. More information here:
49
50   http://rails-engines.org
51
52
53
54
55
56
57
58 = Using the Engines plugin itself
59
60 There are a number of features of the Engines plugin itself which may be useful to know:
61
62
63 === Engines.log
64 The Engines plugin comes with its own logger, which is invaluable when debugging. To use it,
65 simply call
66
67   Engines.create_logger
68   
69 Two optional arguments may be passed to this method:
70
71   Engines.create_logger(<io>)
72   
73 Would set the outputter to the logger to the given IO object <io>. For example, this could be STDERR or STDOUT (the default). The second argument is the logger level:
74
75   Engines.create_logger(STDOUT, Logger::INFO)
76   
77 The logger can be accessed using either of the following:
78
79   Engines.log.[debug|info|whatever] "message"
80   Engines.logger.[debug|info|whatever] "message"
81   
82 ... essentially it's a Logger object. It's worth noting that if you *don't* create a logger, calls to Engines.log will just be swallowed without a sound, making it very very easy to completely silence Engine logging.
83
84
85 === Engines.config(:root)
86
87 By default, the Engines plugin expects to be starting Engines from within RAILS_ROOT/vendor/plugins. However, if you'd like to store your engines in a different directory, add the following line *before* any call to Engines.start
88
89   Engines.config(:root, "/path/to/your/directory", :force)
90   
91   
92 === Rake Tasks
93
94 The engines plugin comes with a number of handy rake tasks:
95
96   # display version information about the engines subsystem
97   rake engines:info 
98   
99   # migrate engines' database schemas in a controlled way
100   rake db:migrate:engines
101   
102   # generates full documentation for all engines
103   rake doc:engines      
104   
105 There are more, but you'll have to discover them yourself...  
106
107
108 == More information
109
110 For more information about what you can do with the Engines plugin, you'll need to generate the documentation (rake plugindoc), or go to http://rails-engines.org. Good luck!  
111
112
113
114
115
116
117
118
119 = Quickstart
120
121 === Gentlemen, Start your Engines!
122
123
124 Here's an *example* of how you might go about using Rails Engines. Please bear in mind that actual Engines may differ from this, but these are the steps you will *typically* have to take. Refer to individual Engine documentation for specific installation instructions. Anyway, on with the show:
125
126 1. Install the Rails Engines plugin into your plugins directory. You'll probably need to accept the SSL certificate here for the OpenSVN servers. For example:
127
128     $ script/plugin install engines
129
130  or
131
132     $ svn co http://svn.rails-engines.org/plugins/engines <MY_RAILS_APP>/vendor/plugins/engines
133
134 2. Install your engine into the plugins directory in a similar way.
135
136 3. Create the RDoc for the engines plugin and for your engines so you know what's going on:
137
138      $ rake doc:plugins
139      $ rake doc:engines
140
141 4. Initialize any database schema provided. The Engine may provide Rake tasks to do this for you. Beware that accepting an Engine schema might affect any existing database tables you have installed! You are STRONGLY recommended to inspect the <tt>db/schema.rb</tt> file to see exactly what running it might change.
142
143 5. Add configuration to <tt>environment.rb</tt>:
144    e.g.
145
146       # Add your application configuration here
147       module MyEngine
148         config :top_speed, "MegaTurboFast"
149       end
150  
151       Engines.start :my_engine
152
153 6. Run your server!
154
155       $ script/server
156
157
158
159
160 = Building an Engine
161
162 Here's a sample rails application with a detailed listing of an example engines as a concrete example:
163
164   RAILS_ROOT
165     |- app
166     |- lib
167     |- config
168     |- <... other directories ...>
169     |- vendor
170         |-plugins
171             |- engines               <-- the engines plugin
172             |- some_other_plugin 
173             |- my_engine             <-- our example engine
174                   |- init_engine.rb
175                   |- app
176                   |     |- controllers
177                   |     |- models
178                   |     |- helpers
179                   |     |- views
180                   |- db
181                   |- tasks
182                   |- lib
183                   |- public
184                   |     |- javascripts
185                   |     |- stylesheets
186                   |- test
187
188
189 The internal structure of an engine mirrors the familiar core of a Rails application, with most of the engine within the <tt>app</tt> subdirectory. Within <tt>app</tt>, the controllers, views and model objects behave just as you might expect if there in the top-level <tt>app</tt> directory.
190
191 When you call <tt>Engines.start :my_engine</tt> in <tt>environment.rb</tt> a few important bits of black magic voodoo happen:
192 * the engine's controllers, views and models are mixed in to your running Rails application; 
193 * files in the <tt>lib</tt> directory of your engine (and subdirectories) are made available 
194   to the rest of your system
195 * any directory structure in the folder <tt>public/</tt> within your engine is made available to the webserver
196 * the file <tt>init_engine.rb</tt> is loaded from within the engine - just like a plugin. The reason why engines need an init_engine.rb rather than an init.rb is because Rails' default plugin system might try and load an engine before the Engines plugin has been loaded, resulting in all manner of badness. Instead, Rails' skips over any engine plugins, and the Engines plugin handles initializing your Engines plugins when you 'start' each engine.
197
198 From within <tt>init_engine.rb</tt> you should load any libraries from your <tt>lib</tt> directory that your engine might need to function. You can also perform any configuration required.
199
200 === Loading all Engines
201
202 Calling either Engines.start (with no arguments) or Engines.start_all will load all engines available. Please note that your plugin can only be *automatically* detected as an engine by the presence of an 'init_engine.rb' file, or if the engine is in a directory named <something>_engine, or <something>_bundle. If neither of these conditions hold, then your engine will not be loaded by Engines.start() (with no arguments) or Engines.start_all().
203
204
205
206
207
208
209
210 = Configuring Engines
211
212 Often your engine will require a number of configuration parameters set, some of which should be alterable by the user to reflect their particular needs. For example, a Login System might need a unique Salt value set to encrypt user passwords. This value should be unique to each application.
213
214 Engines provides a simple mechanism to handle this, and it's already been hinted at above. Within any module, a new method is now available: <tt>config</tt>. This method creates a special <tt>CONFIG</tt> Hash object within the Module it is called, and can be used to store your parameters. For a user to set these parameters, they should reopen the module (before the corresponding Engines.start call), as follows:
215
216   module MyModule
217     config :some_option, "really_important_value"
218   end
219   Engines.start :my_engine
220
221 Because this config value has been set before the Engine is started, subsequent attempts to set this config value will be ignored and the user-specified value used instead. Of course, there are situations where you *really* want to set the config value, even if it already exists. In such cases the config call can be changed to:
222
223   config :some_option, "no_THIS_really_important_value", :force
224
225 The additional parameter will force the new value to be used. For more information, see Module#config.
226
227
228
229
230 = Tweaking Engines
231
232 One of the best things about Engines is that if you don't like the default behaviour of any component, you can override it without needing to overhaul the whole engine. This makes adding your customisations to engines almost painless, and allows for upgrading/updating engine code without affecting the specialisations you need for your particular application.
233
234
235 === View Tweaks
236 These are the simplest - just drop your customised view (or partial) into you <tt>/app/views</tt> directory in the corresponding location for the engine, and your view will be used in preference to the engine view. For example, if we have a ItemController with an action 'show', it will (normally) expect to find its view as <tt>report/show.rhtml</tt> in the <tt>views</tt> directory. The view is found in the engine at <tt>/vendor/engines/my_engine/app/views/report/show.rhtml</tt>. However, if you create the file <tt>/app/views/report/show.rhtml</tt>, that file will be used instead! The same goes for partials.
237
238
239 === Controller Tweaks
240 You can override controller behaviour by replacing individual controller methods with your custom behaviour. Lets say that our ItemController's 'show' method isn't up to scratch, but the rest of it behaves just fine. To override the single method, create <tt>/app/controllers/item_controller.rb</tt>, just as if it were going to be a new controller in a regular Rails application. then, implement your show method as you would like it to happen.
241
242 ... and that's it. Your custom code will be mixed in to the engine controller, replacing its old method with your custom code.
243
244
245 === Model/Lib Tweaks
246 Alas, tweaking model objects isn't quite so easy (yet). If you need to change the behaviour of model objects, you'll need to copy the model file from the engine into <tt>/app/models</tt> and edit the methods yourself. Library code can be overridden in a similar way.
247
248
249
250
251
252
253
254
255
256 = Public Files
257
258 If the Engine includes a <tt>public</tt> directory, its contents will be mirrored into <tt>RAILS_ROOT/public/engine_files/&lt;engine_name&gt;/</tt> so that these files can be served by your webserver to browsers and users over the internet.
259
260 Engines also provides two convenience methods for loading stylesheets and javascript files in your layouts: <tt>engine_stylesheet</tt> and <tt>engine_javascript</tt>.
261
262 === Engine Stylesheets
263
264   <%= engine_stylesheet "my_engine" %>
265
266 will include <tt>RAILS_ROOT/public/&lt;engine_files&gt;/my_engine/stylesheets/my_engine.css</tt> in your layout. If you have more than one stylesheet, you can include them in the same call:
267
268   <%= engine_stylesheet "my_engine", "stylesheet_2", "another_one" %>
269
270 will give you:
271
272     <link href="/engine_files/my_engine/stylesheets/my_engine.css" media="screen" rel="Stylesheet" type="text/css" />
273     <link href="/engine_files/my_engine/stylesheets/stylesheet_2.css" media="screen" rel="Stylesheet" type="text/css" />
274     <link href="/engine_files/my_engine/stylesheets/another_one.css" media="screen" rel="Stylesheet" type="text/css" />
275
276 in your rendered layout.
277
278 === Engine Javascripts
279
280 The <tt>engine_javascript</tt> command works in exactly the same way as above.
281
282
283
284
285
286
287
288
289
290 = Databases and Engines
291
292 Engine schema information can be handled using similar mechanisms to your normal application schemas.
293
294 == CAVEAT EMPTOR!
295
296 I.E. Big Huge Warning In Flashing Lights.
297
298 PLEASE, PLEASE, PLEASE bear in mind that if you are letting someone
299 ELSE have a say in what tables you are using, you're basically opening
300 your application schema open to potential HAVOC. I cannot stress how
301 serious this is. It is YOUR responsibility to ensure that you trust
302 the schema and migration information, and that it's not going to drop
303 your whole database. You need to inspect these things. YOU do. If you
304 run these voodoo commands and your database essplodes because you
305 didn't double double double check what was going on, your embarassment
306 will be infinite. And your project will be skroo'd if the migration
307 is irreversible.
308
309 That said, if you are working in a team and you all trust each other,
310 which is hopefully true, this can be quite useful.
311
312
313 == Migrating Engines
314
315 To migrate all engines to the latest version:
316
317  rake db:migrate:engines
318
319 To migrate a single engine, for example the login engine:
320
321  rake db:migrate:engines ENGINE=login  (or login_engine)
322
323 To migrate a single engine to a specific revision:
324
325  rake db:migrate:engines ENGINE=login VERSION=4
326
327 This:
328
329  rake db:migrate:engines VERSION=1
330
331 ... will not work, because we felt it was too dangerous to allow ALL
332 engines to be migrated to a specific version, since such versions
333 might be incompatible.
334
335
336
337
338
339
340
341 = Testing Engines
342
343 The Engines plugin comes with mechanisms to help test Engines within a developer's own application. The testing extensions enable developers to load fixtures into specific
344 tables irrespective of the name of the fixtures file. This work is heavily based on
345 patches made by Duane Johnson (canadaduane), viewable at
346 http://dev.rubyonrails.org/ticket/1911
347
348 Engine developers should supply fixture files in the <engine>/test/fixtures directory
349 as normal. Within their tests, they should load the fixtures using the 'fixture' command
350 (rather than the normal 'fixtures' command). For example:
351
352   class UserTest < Test::Unit::TestCase
353     fixture :users, :table_name => LoginEngine.config(:user_table), :class_name => "User"
354  
355     ...
356
357 This will ensure that the fixtures/users.yml file will get loaded into the correct
358 table, and will use the correct model object class.
359
360 Your engine should provide a test_helper.rb file in <engine>/test, the contents of which should include the following:
361
362   # Load the default rails test helper - this will load the environment.
363         require File.dirname(__FILE__) + '/../../../../test/test_helper'
364
365         # ensure that the Engines testing enhancements are loaded and will override Rails own
366         # code where needed. This line is very important!
367         require File.join(Engines.config(:root), "engines", "lib", "testing_extensions")
368
369         # Load the schema - if migrations have been performed, this will be up to date.
370         load(File.dirname(__FILE__) + "/../db/schema.rb")
371
372         # set up the fixtures location to use your engine's fixtures
373         Test::Unit::TestCase.fixture_path = File.dirname(__FILE__)  + "/fixtures/"
374         $LOAD_PATH.unshift(Test::Unit::TestCase.fixture_path)
375
376 == Loading Fixtures
377
378 An additional helpful task for loading fixture data is also provided (thanks to Joe Van Dyk):
379
380   rake db:fixtures:engines:load
381   rake db:fixtures:engines:load PLUGIN=login_engine
382   
383 will load the engine fixture data into your development database.
384
385 === Important Caveat
386 Unlike the new 'fixture' directive described above, this task currently relies on you ensuring that the table name to load fixtures into is the same as the name of the fixtures file you are trying to load. If you are using defaults, this should be fine. If you have changed table names, you will need to rename your fixtures files (and possibly update your tests to reflect this too).
387
388 You should also note that fixtures typically tend to depend on test configuration information (such as test salt values), so not all data will be usable in fixture form.
389
390
391
392 = LICENCE
393
394 Copyright (c) 2006, James Adam
395
396 The MIT License
397
398 Permission is hereby granted, free of charge, to any person obtaining a copy
399 of this software and associated documentation files (the "Software"), to deal
400 in the Software without restriction, including without limitation the rights
401 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
402 copies of the Software, and to permit persons to whom the Software is
403 furnished to do so, subject to the following conditions:
404
405 The above copyright notice and this permission notice shall be included in
406 all copies or substantial portions of the Software.
407
408 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
409 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
410 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
411 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
412 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
413 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
414 THE SOFTWARE.

Benjamin Mako Hill || Want to submit a patch?