2004-11-23 20:04:44 -05:00
|
|
|
== Welcome to Rails
|
|
|
|
|
|
|
|
Rails is a web-application and persistance framework that includes everything
|
|
|
|
needed to create database-backed web-applications according to the
|
|
|
|
Model-View-Control pattern of separation. This pattern splits the view (also
|
|
|
|
called the presentation) into "dumb" templates that are primarily responsible
|
|
|
|
for inserting pre-build data in between HTML tags. The model contains the
|
|
|
|
"smart" domain objects (such as Account, Product, Person, Post) that holds all
|
|
|
|
the business logic and knows how to persist themselves to a database. The
|
|
|
|
controller handles the incoming requests (such as Save New Account, Update
|
|
|
|
Product, Show Post) by manipulating the model and directing data to the view.
|
|
|
|
|
|
|
|
In Rails, the model is handled by what's called a object-relational mapping
|
|
|
|
layer entitled Active Record. This layer allows you to present the data from
|
|
|
|
database rows as objects and embellish these data objects with business logic
|
|
|
|
methods. You can read more about Active Record in
|
|
|
|
link:files/vendor/activerecord/README.html.
|
|
|
|
|
|
|
|
The controller and view is handled by the Action Pack, which handles both
|
|
|
|
layers by its two parts: Action View and Action Controller. These two layers
|
|
|
|
are bundled in a single package due to their heavy interdependence. This is
|
|
|
|
unlike the relationship between the Active Record and Action Pack that is much
|
|
|
|
more separate. Each of these packages can be used independently outside of
|
|
|
|
Rails. You can read more about Action Pack in
|
|
|
|
link:files/vendor/actionpack/README.html.
|
|
|
|
|
|
|
|
|
|
|
|
== Requirements
|
|
|
|
|
|
|
|
* Database and driver (MySQL, PostgreSQL, or SQLite)
|
|
|
|
* Rake[http://rake.rubyforge.org] for running tests and the generating documentation
|
|
|
|
|
|
|
|
== Optionals
|
|
|
|
|
|
|
|
* Apache 1.3.x or 2.x (or any FastCGI-capable webserver with a
|
|
|
|
mod_rewrite-like module)
|
2004-12-12 11:14:20 -05:00
|
|
|
* FastCGI (or mod_ruby) for better performance on Apache
|
2004-11-23 20:04:44 -05:00
|
|
|
|
|
|
|
== Getting started
|
|
|
|
|
2004-12-16 10:45:55 -05:00
|
|
|
1. Run the WEBrick servlet: <tt>ruby script/server</tt>
|
2004-12-12 11:14:20 -05:00
|
|
|
(run with --help for options)
|
|
|
|
2. Go to http://localhost:3000/ and get "Congratulations, you've put Ruby on Rails!"
|
2004-12-16 12:58:29 -05:00
|
|
|
3. Follow the guidelines on the "Congratulations, you've put Ruby on Rails!" screen
|
2004-11-23 20:04:44 -05:00
|
|
|
|
|
|
|
|
|
|
|
== Example for Apache conf
|
|
|
|
|
|
|
|
<VirtualHost *:80>
|
|
|
|
ServerName rails
|
2004-12-12 11:14:20 -05:00
|
|
|
DocumentRoot /path/application/public/
|
2005-02-20 18:51:06 -05:00
|
|
|
ErrorLog /path/application/log/server.log
|
2004-11-23 20:04:44 -05:00
|
|
|
|
|
|
|
<Directory /path/application/public/>
|
|
|
|
Options ExecCGI FollowSymLinks
|
|
|
|
AllowOverride all
|
|
|
|
Allow from all
|
|
|
|
Order allow,deny
|
|
|
|
</Directory>
|
|
|
|
</VirtualHost>
|
|
|
|
|
|
|
|
NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
|
|
|
|
should be on and ".cgi" should respond. All requests from 127.0.0.1 goes
|
|
|
|
through CGI, so no Apache restart is necessary for changes. All other requests
|
|
|
|
goes through FCGI (or mod_ruby) that requires restart to show changes.
|
|
|
|
|
|
|
|
|
2005-02-20 18:51:06 -05:00
|
|
|
== Example for lighttpd conf (with FastCGI)
|
|
|
|
|
|
|
|
server.port = 8080
|
|
|
|
server.bind = "127.0.0.1"
|
|
|
|
# server.event-handler = "freebsd-kqueue" # needed on OS X
|
|
|
|
|
2005-02-20 20:01:24 -05:00
|
|
|
server.modules = ( "mod_rewrite", "mod_fastcgi" )
|
2005-02-20 18:51:06 -05:00
|
|
|
|
2005-02-20 20:01:24 -05:00
|
|
|
url.rewrite = ( "^/$" => "index.html", "^([^.]+)$" => "$1.html" )
|
|
|
|
server.error-handler-404 = "/dispatch.fcgi"
|
2005-02-20 18:51:06 -05:00
|
|
|
|
|
|
|
server.document-root = "/path/application/public"
|
|
|
|
server.errorlog = "/path/application/log/server.log"
|
|
|
|
|
|
|
|
fastcgi.server = ( ".fcgi" =>
|
|
|
|
( "localhost" =>
|
|
|
|
(
|
|
|
|
"min-procs" => 1,
|
|
|
|
"max-procs" => 5,
|
|
|
|
"socket" => "/tmp/application.fcgi.socket",
|
|
|
|
"bin-path" => "/path/application/public/dispatch.fcgi",
|
|
|
|
"bin-environment" => ( "RAILS_ENV" => "development" )
|
|
|
|
)
|
|
|
|
)
|
|
|
|
)
|
|
|
|
|
|
|
|
|
2004-11-23 20:04:44 -05:00
|
|
|
== Debugging Rails
|
|
|
|
|
2005-02-20 18:51:06 -05:00
|
|
|
Have "tail -f" commands running on both the server.log, production.log, and
|
2004-11-23 20:04:44 -05:00
|
|
|
test.log files. Rails will automatically display debugging and runtime
|
|
|
|
information to these files. Debugging info will also be shown in the browser
|
|
|
|
on requests from 127.0.0.1.
|
|
|
|
|
|
|
|
|
2004-12-16 12:58:29 -05:00
|
|
|
== Breakpoints
|
|
|
|
|
|
|
|
Breakpoint support is available through the script/breakpointer client. This
|
|
|
|
means that you can break out of execution at any point in the code, investigate
|
|
|
|
and change the model, AND then resume execution! Example:
|
|
|
|
|
|
|
|
class WeblogController < ActionController::Base
|
|
|
|
def index
|
|
|
|
@posts = Post.find_all
|
|
|
|
breakpoint "Breaking out from the list"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
So the controller will accept the action, run the first line, then present you
|
|
|
|
with a IRB prompt in the breakpointer window. Here you can do things like:
|
|
|
|
|
|
|
|
Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
|
|
|
|
|
|
|
|
>> @posts.inspect
|
|
|
|
=> "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
|
|
|
|
#<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
|
|
|
|
>> @posts.first.title = "hello from a breakpoint"
|
|
|
|
=> "hello from a breakpoint"
|
|
|
|
|
|
|
|
...and even better is that you can examine how your runtime objects actually work:
|
|
|
|
|
|
|
|
>> f = @posts.first
|
|
|
|
=> #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
|
|
|
|
>> f.
|
|
|
|
Display all 152 possibilities? (y or n)
|
|
|
|
|
|
|
|
Finally, when you're ready to resume execution, you press CTRL-D
|
|
|
|
|
|
|
|
|
|
|
|
== Console
|
|
|
|
|
|
|
|
You can interact with the domain model by starting the console through script/console.
|
|
|
|
Here you'll have all parts of the application configured, just like it is when the
|
|
|
|
application is running. You can inspect domain models, change values, and save to the
|
|
|
|
database. Start the script without arguments to see the options.
|
|
|
|
|
|
|
|
|
2004-11-23 20:04:44 -05:00
|
|
|
== Description of contents
|
|
|
|
|
|
|
|
app
|
|
|
|
Holds all the code that's specific to this particular application.
|
|
|
|
|
|
|
|
app/controllers
|
|
|
|
Holds controllers that should be named like weblog_controller.rb for
|
|
|
|
automated URL mapping. All controllers should descend from
|
|
|
|
ActionController::Base.
|
|
|
|
|
|
|
|
app/models
|
|
|
|
Holds models that should be named like post.rb.
|
|
|
|
Most models will descent from ActiveRecord::Base.
|
|
|
|
|
|
|
|
app/views
|
|
|
|
Holds the template files for the view that should be named like
|
|
|
|
weblog/index.rhtml for the WeblogController#index action. All views uses eRuby
|
|
|
|
syntax. This directory can also be used to keep stylesheets, images, and so on
|
|
|
|
that can be symlinked to public.
|
|
|
|
|
|
|
|
app/helpers
|
|
|
|
Holds view helpers that should be named like weblog_helper.rb.
|
|
|
|
|
|
|
|
config
|
|
|
|
Configuration files for Apache, database, and other dependencies.
|
|
|
|
|
2005-02-20 20:01:24 -05:00
|
|
|
components
|
|
|
|
Self-contained mini-applications that can bundle controllers, models, and views together.
|
|
|
|
|
2004-11-23 20:04:44 -05:00
|
|
|
lib
|
|
|
|
Application specific libraries. Basically, any kind of custom code that doesn't
|
|
|
|
belong controllers, models, or helpers. This directory is in the load path.
|
|
|
|
|
|
|
|
public
|
|
|
|
The directory available for Apache, which includes symbolic links to other
|
|
|
|
parts of the structure that are to be made available. Refrain from placing
|
|
|
|
actual files in here if you're using CVS and don't want to check in this
|
|
|
|
directory.
|
|
|
|
|
|
|
|
script
|
|
|
|
Helper scripts for automation and generation.
|
|
|
|
|
|
|
|
test
|
|
|
|
Unit and functional tests along with fixtures.
|
|
|
|
|
|
|
|
vendor
|
|
|
|
External libraries that the application depend on. This directory is in the load path.
|