diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index 0912355e83..aaad63523a 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -1,6 +1,7 @@
h2. Getting Started with Rails
-This guide covers getting up and running with Ruby on Rails. After reading it, you should be familiar with:
+This guide covers getting up and running with Ruby on Rails. After reading it,
+you should be familiar with:
* Installing Rails, creating a new Rails application, and connecting your application to a database
* The general layout of a Rails application
@@ -9,26 +10,31 @@ This guide covers getting up and running with Ruby on Rails. After reading it, y
endprologue.
-WARNING. This Guide is based on Rails 3.1. Some of the code shown here will not work in earlier versions of Rails.
+WARNING. This Guide is based on Rails 3.1. Some of the code shown here will not
+work in earlier versions of Rails.
h3. Guide Assumptions
-This guide is designed for beginners who want to get started with a Rails application from scratch. It does not assume
-that you have any prior experience with Rails. However, to get the most out of it, you need to have some prerequisites
-installed:
+This guide is designed for beginners who want to get started with a Rails
+application from scratch. It does not assume that you have any prior experience
+with Rails. However, to get the most out of it, you need to have some
+prerequisites installed:
* The "Ruby":http://www.ruby-lang.org/en/downloads language version 1.8.7 or higher
-TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3.0. Ruby Enterprise Edition have these
-fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on
-Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
+TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails
+3.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02
+though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults
+on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth
+sailing.
* The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system
** If you want to learn more about RubyGems, please read the "RubyGems User Guide":http://docs.rubygems.org/read/book/1
* A working installation of the "SQLite3 Database":http://www.sqlite.org
-Rails is a web application framework running on the Ruby programming language. If you have no prior experience with
-Ruby, you will find a very steep learning curve diving straight into Rails. There are some good free resources on the
+Rails is a web application framework running on the Ruby programming language.
+If you have no prior experience with Ruby, you will find a very steep learning
+curve diving straight into Rails. There are some good free resources on the
internet for learning Ruby, including:
* "Mr. Neighborly's Humble Little Ruby Book":http://www.humblelittlerubybook.com
@@ -37,15 +43,19 @@ internet for learning Ruby, including:
h3. What is Rails?
-Rails is a web application development framework written in the Ruby language. It is designed to make programming web
-applications easier by making assumptions about what every developer needs to get started. It allows you to write less
-code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that
-it makes web application development more fun.
+Rails is a web application development framework written in the Ruby language.
+It is designed to make programming web applications easier by making assumptions
+about what every developer needs to get started. It allows you to write less
+code while accomplishing more than many other languages and frameworks.
+Experienced Rails developers also report that it makes web application
+development more fun.
-Rails is opinionated software. It makes the assumption that there is a "best" way to do things, and it's designed to
-encourage that way - and in some cases to discourage alternatives. If you learn "The Rails Way" you'll probably discover
-a tremendous increase in productivity. If you persist in bringing old habits from other languages to your Rails
-development, and trying to use patterns you learned elsewhere, you may have a less happy experience.
+Rails is opinionated software. It makes the assumption that there is a "best"
+way to do things, and it's designed to encourage that way - and in some cases to
+discourage alternatives. If you learn "The Rails Way" you'll probably discover a
+tremendous increase in productivity. If you persist in bringing old habits from
+other languages to your Rails development, and trying to use patterns you
+learned elsewhere, you may have a less happy experience.
The Rails philosophy includes several guiding principles:
@@ -57,7 +67,8 @@ i s the fastest way to go.
h4. The MVC Architecture
-At the core of Rails is the Model, View, Controller architecture, usually just called MVC. MVC benefits include:
+At the core of Rails is the Model, View, Controller architecture, usually just
+called MVC. MVC benefits include:
* Isolation of business logic from the user interface
* Ease of keeping code DRY
@@ -65,29 +76,34 @@ At the core of Rails is the Model, View, Controller architecture, usually just c
h5. Models
-A model represents the information (data) of the application and the rules to manipulate that data. In the case of
-Rails, models are primarily used for managing the rules of interaction with a corresponding database table. In most
-cases, each table in your database will correspond to one model in your application. The bulk of your application's
-business logic will be concentrated in the models.
+A model represents the information (data) of the application and the rules to
+manipulate that data. In the case of Rails, models are primarily used for
+managing the rules of interaction with a corresponding database table. In most
+cases, each table in your database will correspond to one model in your
+application. The bulk of your application's business logic will be concentrated
+in the models.
h5. Views
-Views represent the user interface of your application. In Rails, views are often HTML files with embedded Ruby code
-that perform tasks related solely to the presentation of the data. Views handle the job of providing data to the web
+Views represent the user interface of your application. In Rails, views are
+often HTML files with embedded Ruby code that perform tasks related solely to
+the presentation of the data. Views handle the job of providing data to the web
browser or other tool that is used to make requests from your application.
h5. Controllers
-Controllers provide the "glue" between models and views. In Rails, controllers are responsible for processing the
-incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for
+Controllers provide the "glue" between models and views. In Rails, controllers
+are responsible for processing the incoming requests from the web browser,
+interrogating the models for data, and passing that data on to the views for
presentation.
h4. The Components of Rails
-Rails ships as many individual components. Each of these components are briefly explained below. If you are new to
-Rails, as you read this section, don't get hung up on the details of each component, as they will be explained in
-further detail later. For instance, we will bring up Rack applications, but you don't need to know anything about them
-to continue with this guide.
+Rails ships as many individual components. Each of these components are briefly
+explained below. If you are new to Rails, as you read this section, don't get
+hung up on the details of each component, as they will be explained in further
+detail later. For instance, we will bring up Rack applications, but you don't
+need to know anything about them to continue with this guide.
* Action Pack
** Action Controller
@@ -103,63 +119,76 @@ to continue with this guide.
h5. Action Pack
-Action Pack is a single gem that contains Action Controller, Action View and Action Dispatch. The "VC" part of "MVC".
+Action Pack is a single gem that contains Action Controller, Action View and
+Action Dispatch. The "VC" part of "MVC".
h6. Action Controller
-Action Controller is the component that manages the controllers in a Rails application. The Action Controller framework
-processes incoming requests to a Rails application, extracts parameters, and dispatches them to the intended action.
-Services provided by Action Controller include session management, template rendering, and redirect management.
+Action Controller is the component that manages the controllers in a Rails
+application. The Action Controller framework processes incoming requests to a
+Rails application, extracts parameters, and dispatches them to the intended
+action. Services provided by Action Controller include session management,
+template rendering, and redirect management.
h6. Action View
-Action View manages the views of your Rails application. It can create both HTML and XML output by default. Action View
-manages rendering templates, including nested and partial templates, and includes built-in AJAX support. View templates
-are covered in more detail in another guide called "Layouts and Rendering":layouts_and_rendering.html.
+Action View manages the views of your Rails application. It can create both HTML
+and XML output by default. Action View manages rendering templates, including
+nested and partial templates, and includes built-in AJAX support. View
+templates are covered in more detail in another guide called "Layouts and
+Rendering":layouts_and_rendering.html.
h6. Action Dispatch
-Action Dispatch handles routing of web requests and dispatches them as you want, either to your application or any other
-Rack application. Rack applications are a more advanced topic and are covered in a separate guide called "Rails on
+Action Dispatch handles routing of web requests and dispatches them as you want,
+either to your application or any other Rack application. Rack applications are
+a more advanced topic and are covered in a separate guide called "Rails on
Rack":rails_on_rack.html.
h5. Action Mailer
-Action Mailer is a framework for building e-mail services. You can use Action Mailer to receive and process incoming
-email and send simple plain text or complex multipart emails based on flexible templates.
+Action Mailer is a framework for building e-mail services. You can use Action
+Mailer to receive and process incoming email and send simple plain text or
+complex multipart emails based on flexible templates.
h5. Active Model
-Active Model provides a defined interface between the Action Pack gem services and Object Relationship Mapping gems
-such as Active Record. Active Model allows Rails to utilize other ORM frameworks in place of Active Record if your
+Active Model provides a defined interface between the Action Pack gem services
+and Object Relationship Mapping gems such as Active Record. Active Model allows
+Rails to utilize other ORM frameworks in place of Active Record if your
application needs this.
h5. Active Record
-Active Record is the base for the models in a Rails application. It provides database independence, basic CRUD
-functionality, advanced finding capabilities, and the ability to relate models to one another, among other services.
+Active Record is the base for the models in a Rails application. It provides
+database independence, basic CRUD functionality, advanced finding capabilities,
+and the ability to relate models to one another, among other services.
h5. Active Resource
-Active Resource provides a framework for managing the connection between business objects and RESTful web services. It
-implements a way to map web-based resources to local objects with CRUD semantics.
+Active Resource provides a framework for managing the connection between
+business objects and RESTful web services. It implements a way to map web-based
+resources to local objects with CRUD semantics.
h5. Active Support
-Active Support is an extensive collection of utility classes and standard Ruby library extensions that are used in
-Rails, both by the core code and by your applications.
+Active Support is an extensive collection of utility classes and standard Ruby
+library extensions that are used in Rails, both by the core code and by your
+applications.
h5. Railties
-Railties is the core Rails code that builds new Rails applications and glues the various frameworks and plugins together
-in any Rails application.
+Railties is the core Rails code that builds new Rails applications and glues the
+various frameworks and plugins together in any Rails application.
h4. REST
-Rest stands for Representational State Transfer and is the foundation of the RESTful architecture. This is generally
-considered to be Roy Fielding's doctoral thesis, "Architectural Styles and the Design of Network-based Software
-Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. While you can read through the thesis, REST
-in terms of Rails boils down to two main principles:
+Rest stands for Representational State Transfer and is the foundation of the
+RESTful architecture. This is generally considered to be Roy Fielding's doctoral
+thesis, "Architectural Styles and the Design of Network-based Software
+Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. While
+you can read through the thesis, REST in terms of Rails boils down to two main
+principles:
* Using resource identifiers such as URLs to represent resources.
* Transferring representations of the state of that resource between system components.
@@ -168,12 +197,13 @@ For example, to a Rails application a request such as this:
DELETE /photos/17
-would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action - deleting that
-resource. REST is a natural style for the architecture of web applications, and Rails hooks into this shielding you from
-many of the RESTful complexities and browser quirks.
+would be understood to refer to a photo resource with the ID of 17, and to
+indicate a desired action - deleting that resource. REST is a natural style for
+the architecture of web applications, and Rails hooks into this shielding you
+from many of the RESTful complexities and browser quirks.
-If you'd like more details on REST as an architectural style, these resources are more approachable than Fielding's
-thesis:
+If you'd like more details on REST as an architectural style, these resources
+are more approachable than Fielding's thesis:
* "A Brief Introduction to REST":http://www.infoq.com/articles/rest-introduction by Stefan Tilkov
* "An Introduction to REST":http://bitworking.org/news/373/An-Introduction-to-REST (video tutorial) by Joe Gregorio
@@ -183,8 +213,9 @@ Ian Robinson
h3. Creating a New Rails Project
-If you follow this guide, you'll create a Rails project called blog, a (very) simple weblog. Before you can
-start building the application, you need to make sure that you have Rails itself installed.
+If you follow this guide, you'll create a Rails project called blog, a
+(very) simple weblog. Before you can start building the application, you need to
+make sure that you have Rails itself installed.
h4. Installing Rails
@@ -195,15 +226,19 @@ Usually run this as the root user:
# gem install rails
-TIP. If you're working on Windows, you can quickly install Ruby and Rails with "Rails Installer":http://railsinstaller.org.
+TIP. If you're working on Windows, you can quickly install Ruby and Rails with
+"Rails Installer":http://railsinstaller.org.
h4. Creating the Blog Application
-The best way to use this guide is to follow each step as it happens, no code or step needed to make this example
-application has been left out, so you can literally follow along step by step. If you need to see the completed code,
-you can download it from "Getting Started Code":https://github.com/mikel/getting-started-code.
+The best way to use this guide is to follow each step as it happens, no code or
+step needed to make this example application has been left out, so you can
+literally follow along step by step. If you need to see the completed code, you
+can download it from "Getting Started
+Code":https://github.com/mikel/getting-started-code.
-To begin, open a terminal, navigate to a folder where you have rights to create files, and type:
+To begin, open a terminal, navigate to a folder where you have rights to create
+files, and type:
$ rails new blog
@@ -211,17 +246,21 @@ $ rails new blog
This will create a Rails application called Blog in a directory called blog.
-TIP: You can see all of the switches that the Rails application builder accepts by running rails new -h.
+TIP: You can see all of the switches that the Rails application builder accepts
+by running rails new -h.
-After you create the blog application, switch to its folder to continue work directly in that application:
+After you create the blog application, switch to its folder to continue work
+directly in that application:
$ cd blog
-In any case, Rails will create a folder in your working directory called blog. Open up that folder and explore
-its contents. Most of the work in this tutorial will happen in the app/ folder, but here's a basic rundown on
-the function of each folder that Rails creates in a new application by default:
+In any case, Rails will create a folder in your working directory called
+blog. Open up that folder and explore its contents. Most of the work in
+this tutorial will happen in the app/ folder, but here's a basic
+rundown on the function of each folder that Rails creates in a new application
+by default:
|_.File/Folder|_.Purpose|
|Gemfile|This file allows you to specify what gem dependencies are needed for your Rails application. See section on Bundler, below.|
@@ -242,8 +281,9 @@ the function of each folder that Rails creates in a new application by default:
h4. Installing the Required Gems
-Rails applications manage gem dependencies with "Bundler":http://gembundler.com/v1.0/index.html by default. As we don't
-need any other gems beyond the ones in the generated +Gemfile+ we can directly run
+Rails applications manage gem dependencies with
+"Bundler":http://gembundler.com/v1.0/index.html by default. As we don't need any
+other gems beyond the ones in the generated +Gemfile+ we can directly run
$ bundle install
@@ -253,10 +293,11 @@ to have them ready.
h4. Configuring a Database
-Just about every Rails application will interact with a database. The database to use is specified in a configuration
-file, +config/database.yml+.
-If you open this file in a new Rails application, you'll see a default database configuration using SQLite3. The file
-contains sections for three different environments in which Rails can run by default:
+Just about every Rails application will interact with a database. The database
+to use is specified in a configuration file, +config/database.yml+. If you open
+this file in a new Rails application, you'll see a default database
+configuration using SQLite3. The file contains sections for three different
+environments in which Rails can run by default:
* The +development+ environment is used on your development computer as you interact manually with the application.
* The +test+ environment is used to run automated tests.
@@ -264,9 +305,15 @@ contains sections for three different environments in which Rails can run by def
h5. Configuring an SQLite3 Database
-Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later.
+Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is
+a lightweight serverless database application. While a busy production
+environment may overload SQLite, it works well for development and testing.
+Rails defaults to using an SQLite database when creating a new project, but you
+can always change it later.
-Here's the section of the default configuration file (config/database.yml) with connection information for the development environment:
+Here's the section of the default configuration file
+(config/database.yml) with connection information for the development
+environment:
development:
@@ -276,11 +323,17 @@ development:
timeout: 5000
-NOTE: In this guide we are using an SQLite3 database for data storage, because it is a zero configuration database that just works. Rails also supports MySQL and PostgreSQL "out of the box", and has plugins for many database systems. If you are using a database in a production environment Rails most likely has an adapter for it.
+NOTE: In this guide we are using an SQLite3 database for data storage, because
+it is a zero configuration database that just works. Rails also supports MySQL
+and PostgreSQL "out of the box", and has plugins for many database systems. If
+you are using a database in a production environment Rails most likely has an
+adapter for it.
h5. Configuring a MySQL Database
-If you choose to use MySQL instead of the shipped SQLite3 database, your +config/database.yml+ will look a little different. Here's the development section:
+If you choose to use MySQL instead of the shipped SQLite3 database, your
++config/database.yml+ will look a little different. Here's the development
+section:
development:
@@ -293,11 +346,14 @@ development:
socket: /tmp/mysql.sock
-If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the +development+ section as appropriate.
+If your development computer's MySQL installation includes a root user with an
+empty password, this configuration should work for you. Otherwise, change the
+username and password in the +development+ section as appropriate.
h5. Configuring a PostgreSQL Database
-If you choose to use PostgreSQL, your +config/database.yml+ will be customized to use PostgreSQL databases:
+If you choose to use PostgreSQL, your +config/database.yml+ will be customized
+to use PostgreSQL databases:
development:
@@ -311,7 +367,8 @@ development:
h5. Configuring an SQLite3 Database for JRuby Platform
-If you choose to use SQLite3 and using JRuby, your +config/database.yml+ will look a little different. Here's the development section:
+If you choose to use SQLite3 and using JRuby, your +config/database.yml+ will
+look a little different. Here's the development section:
development:
@@ -321,7 +378,8 @@ development:
h5. Configuring a MySQL Database for JRuby Platform
-If you choose to use MySQL and using JRuby, your +config/database.yml+ will look a little different. Here's the development section:
+If you choose to use MySQL and using JRuby, your +config/database.yml+ will look
+a little different. Here's the development section:
development:
@@ -333,7 +391,9 @@ development:
h5. Configuring a PostgreSQL Database for JRuby Platform
-Finally if you choose to use PostgreSQL and using JRuby, your +config/database.yml+ will look a little different. Here's the development section:
+Finally if you choose to use PostgreSQL and using JRuby, your
++config/database.yml+ will look a little different. Here's the development
+section:
development:
@@ -346,51 +406,79 @@ development:
Change the username and password in the +development+ section as appropriate.
-TIP: You don't have to update the database configurations manually. If you had a look at the options of application generator, you have seen that one of them is named --database. It lets you choose an adapter for couple of most used relational databases. You can even run the generator repeatedly: cd .. && rails new blog --database=mysql. When you confirm the overwriting of the +config/database.yml+ file, your application will be configured for MySQL instead of SQLite.
+TIP: You don't have to update the database configurations manually. If you had a
+look at the options of application generator, you have seen that one of them is
+named --database. It lets you choose an adapter for couple of most used
+relational databases. You can even run the generator repeatedly: cd .. &&
+rails new blog --database=mysql. When you confirm the overwriting of the
++config/database.yml+ file, your application will be configured for MySQL
+instead of SQLite.
h4. Creating the Database
-Now that you have your database configured, it's time to have Rails create an empty database for you. You can do this by running a rake command:
+Now that you have your database configured, it's time to have Rails create an
+empty database for you. You can do this by running a rake command:
$ rake db:create
-This will create your development and test SQLite3 databases inside the db/ folder.
+This will create your development and test SQLite3 databases inside the
+db/ folder.
-TIP: Rake is a general-purpose command-runner that Rails uses for many things. You can see the list of available rake commands in your application by running +rake -T+.
+TIP: Rake is a general-purpose command-runner that Rails uses for many things.
+You can see the list of available rake commands in your application by running
++rake -T+.
h3. Hello, Rails!
-One of the traditional places to start with a new language is by getting some text up on screen quickly. To do this, you need to get your Rails application server running.
+One of the traditional places to start with a new language is by getting some
+text up on screen quickly. To do this, you need to get your Rails application
+server running.
h4. Starting up the Web Server
-You actually have a functional Rails application already. To see it, you need to start a web server on your development machine. You can do this by running:
+You actually have a functional Rails application already. To see it, you need to
+start a web server on your development machine. You can do this by running:
$ rails server
-This will fire up an instance of the WEBrick web server by default (Rails can also use several other web servers). To see your application in action, open a browser window and navigate to "http://localhost:3000":http://localhost:3000. You should see Rails' default information page:
+This will fire up an instance of the WEBrick web server by default (Rails can
+also use several other web servers). To see your application in action, open a
+browser window and navigate to "http://localhost:3000":http://localhost:3000.
+You should see Rails' default information page:
!images/rails_welcome.png(Welcome Aboard screenshot)!
-TIP: To stop the web server, hit Ctrl+C in the terminal window where it's running. In development mode, Rails does not generally require you to stop the server; changes you make in files will be automatically picked up by the server.
+TIP: To stop the web server, hit Ctrl+C in the terminal window where it's
+running. In development mode, Rails does not generally require you to stop the
+server; changes you make in files will be automatically picked up by the server.
-The "Welcome Aboard" page is the _smoke test_ for a new Rails application: it makes sure that you have your software configured correctly enough to serve a page. You can also click on the _About your application’s environment_ link to see a summary of your application's environment.
+The "Welcome Aboard" page is the _smoke test_ for a new Rails application: it
+makes sure that you have your software configured correctly enough to serve a
+page. You can also click on the _About your application’s environment_ link to
+see a summary of your application's environment.
h4. Say "Hello", Rails
-To get Rails saying "Hello", you need to create at minimum a controller and a view. Fortunately, you can do that in a single command. Enter this command in your terminal:
+To get Rails saying "Hello", you need to create at minimum a controller and a
+view. Fortunately, you can do that in a single command. Enter this command in
+your terminal:
$ rails generate controller home index
-TIP: If you're on Windows, or your Ruby is set up in some non-standard fashion, you may need to explicitly pass Rails +rails+ commands to Ruby: ruby \path\to\your\application\script\rails generate controller home index.
+TIP: If you're on Windows, or your Ruby is set up in some non-standard fashion,
+you may need to explicitly pass Rails +rails+ commands to Ruby: ruby
+\path\to\your\application\script\rails generate controller home index.
-Rails will create several files for you, including +app/views/home/index.html.erb+. This is the template that will be used to display the results of the +index+ action (method) in the +home+ controller. Open this file in your text editor and edit it to contain a single line of code:
+Rails will create several files for you, including
++app/views/home/index.html.erb+. This is the template that will be used to
+display the results of the +index+ action (method) in the +home+ controller.
+Open this file in your text editor and edit it to contain a single line of code:
Hello, Rails!
@@ -398,17 +486,30 @@ Rails will create several files for you, including +app/views/home/index.html.er
h4. Setting the Application Home Page
-Now that we have made the controller and view, we need to tell Rails when we want "Hello Rails" to show up. In our case, we want it to show up when we navigate to the root URL of our site, "http://localhost:3000":http://localhost:3000, instead of the "Welcome Aboard" smoke test.
+Now that we have made the controller and view, we need to tell Rails when we
+want "Hello Rails" to show up. In our case, we want it to show up when we
+navigate to the root URL of our site,
+"http://localhost:3000":http://localhost:3000, instead of the "Welcome Aboard"
+smoke test.
-The first step to doing this is to delete the default page from your application:
+The first step to doing this is to delete the default page from your
+application:
$ rm public/index.html
-We need to do this as Rails will deliver any static file in the +public+ directory in preference to any dynamic content we generate from the controllers.
+We need to do this as Rails will deliver any static file in the +public+
+directory in preference to any dynamic content we generate from the controllers.
-Now, you have to tell Rails where your actual home page is located. Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+, uncomment it and change it like the following:
+Now, you have to tell Rails where your actual home page is located. Open the
+file +config/routes.rb+ in your editor. This is your application's _routing
+file_ which holds entries in a special DSL (domain-specific language) that tells
+Rails how to connect incoming requests to controllers and actions. This file
+contains many sample routes on commented lines, and one of them actually shows
+you how to connect the root of your site to a specific controller and action.
+Find the line beginning with +root :to+, uncomment it and change it like the
+following:
Blog::Application.routes.draw do
@@ -419,27 +520,42 @@ Blog::Application.routes.draw do
root :to => "home#index"
-The +root :to => "home#index"+ tells Rails to map the root action to the home controller's index action.
+The +root :to => "home#index"+ tells Rails to map the root action to the home
+controller's index action.
-Now if you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see +Hello, Rails!+.
+Now if you navigate to "http://localhost:3000":http://localhost:3000 in your
+browser, you'll see +Hello, Rails!+.
-NOTE. For more information about routing, refer to "Rails Routing from the Outside In":routing.html.
+NOTE. For more information about routing, refer to "Rails Routing from the
+Outside In":routing.html.
h3. Getting Up and Running Quickly with Scaffolding
-Rails _scaffolding_ is a quick way to generate some of the major pieces of an application. If you want to create the models, views, and controllers for a new resource in a single operation, scaffolding is the tool for the job.
+Rails _scaffolding_ is a quick way to generate some of the major pieces of an
+application. If you want to create the models, views, and controllers for a new
+resource in a single operation, scaffolding is the tool for the job.
h3. Creating a Resource
-In the case of the blog application, you can start by generating a scaffolded Post resource: this will represent a single blog posting. To do this, enter this command in your terminal:
+In the case of the blog application, you can start by generating a scaffolded
+Post resource: this will represent a single blog posting. To do this, enter this
+command in your terminal:
$ rails generate scaffold Post name:string title:string content:text
-NOTE. While scaffolding will get you up and running quickly, the code it generates is unlikely to be a perfect fit for your application. You'll most probably want to customize the generated code. Many experienced Rails developers avoid scaffolding entirely, preferring to write all or most of their source code from scratch. Rails, however, makes it really simple to customize templates for generated models, controllers, views and other source files. You'll find more information in the "Creating and Customizing Rails Generators & Templates":generators.html guide.
+NOTE. While scaffolding will get you up and running quickly, the code it
+generates is unlikely to be a perfect fit for your application. You'll most
+probably want to customize the generated code. Many experienced Rails developers
+avoid scaffolding entirely, preferring to write all or most of their source code
+from scratch. Rails, however, makes it really simple to customize templates for
+generated models, controllers, views and other source files. You'll find more
+information in the "Creating and Customizing Rails Generators &
+Templates":generators.html guide.
-The scaffold generator will build 17 files in your application, along with some folders, and edit one more. Here's a quick overview of what it creates:
+The scaffold generator will build 17 files in your application, along with some
+folders, and edit one more. Here's a quick overview of what it creates:
|_.File |_.Purpose|
|db/migrate/20100207214725_create_posts.rb |Migration to create the posts table in your database (your name will include a different timestamp)|
@@ -462,9 +578,15 @@ The scaffold generator will build 17 files in your application, along with some
h4. Running a Migration
-One of the products of the +rails generate scaffold+ command is a _database migration_. Migrations are Ruby classes that are designed to make it simple to create and modify database tables. Rails uses rake commands to run migrations, and it's possible to undo a migration after it's been applied to your database. Migration filenames include a timestamp to ensure that they're processed in the order that they were created.
+One of the products of the +rails generate scaffold+ command is a _database
+migration_. Migrations are Ruby classes that are designed to make it simple to
+create and modify database tables. Rails uses rake commands to run migrations,
+and it's possible to undo a migration after it's been applied to your database.
+Migration filenames include a timestamp to ensure that they're processed in the
+order that they were created.
-If you look in the +db/migrate/20100207214725_create_posts.rb+ file (remember, yours will have a slightly different name), here's what you'll find:
+If you look in the +db/migrate/20100207214725_create_posts.rb+ file (remember,
+yours will have a slightly different name), here's what you'll find:
class CreatePosts < ActiveRecord::Migration
@@ -480,7 +602,14 @@ class CreatePosts < ActiveRecord::Migration
end
-The above migration creates a method name +change+ which will be called when you run this migration. The action defined in that method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it at later date. By default, when you run this migration it will creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide.
+The above migration creates a method name +change+ which will be called when you
+run this migration. The action defined in that method is also reversible, which
+means Rails knows how to reverse the change made by this migration, in case you
+want to reverse it at later date. By default, when you run this migration it
+will creates a +posts+ table with two string columns and a text column. It also
+creates two timestamp fields to track record creation and updating. More
+information about Rails migrations can be found in the "Rails Database
+Migrations":migrations.html guide.
At this point, you can use a rake command to run the migration:
@@ -488,7 +617,8 @@ At this point, you can use a rake command to run the migration:
$ rake db:migrate
-Rails will execute this migration command and tell you it created the Posts table.
+Rails will execute this migration command and tell you it created the Posts
+table.
== CreatePosts: migrating ====================================================
@@ -497,28 +627,43 @@ Rails will execute this migration command and tell you it created the Posts tabl
== CreatePosts: migrated (0.0020s) ===========================================
-NOTE. Because you're working in the development environment by default, this command will apply to the database defined in the +development+ section of your +config/database.yml+ file. If you would like to execute migrations in other environment, for instance in production, you must explicitly pass it when invoking the command: rake db:migrate RAILS_ENV=production.
+NOTE. Because you're working in the development environment by default, this
+command will apply to the database defined in the +development+ section of your
++config/database.yml+ file. If you would like to execute migrations in other
+environment, for instance in production, you must explicitly pass it when
+invoking the command: rake db:migrate RAILS_ENV=production.
h4. Adding a Link
-To hook the posts up to the home page you've already created, you can add a link to the home page. Open +app/views/home/index.html.erb+ and modify it as follows:
+To hook the posts up to the home page you've already created, you can add a link
+to the home page. Open +app/views/home/index.html.erb+ and modify it as follows:
Hello, Rails!
<%= link_to "My Blog", posts_path %>
-The +link_to+ method is one of Rails' built-in view helpers. It creates a hyperlink based on text to display and where to go - in this case, to the path for posts.
+The +link_to+ method is one of Rails' built-in view helpers. It creates a
+hyperlink based on text to display and where to go - in this case, to the path
+for posts.
h4. Working with Posts in the Browser
-Now you're ready to start working with posts. To do that, navigate to "http://localhost:3000":http://localhost:3000/ and then click the "My Blog" link:
+Now you're ready to start working with posts. To do that, navigate to
+"http://localhost:3000":http://localhost:3000/ and then click the "My Blog"
+link:
!images/posts_index.png(Posts Index screenshot)!
-This is the result of Rails rendering the +index+ view of your posts. There aren't currently any posts in the database, but if you click the +New Post+ link you can create one. After that, you'll find that you can edit posts, look at their details, or destroy them. All of the logic and HTML to handle this was built by the single +rails generate scaffold+ command.
+This is the result of Rails rendering the +index+ view of your posts. There
+aren't currently any posts in the database, but if you click the +New Post+ link
+you can create one. After that, you'll find that you can edit posts, look at
+their details, or destroy them. All of the logic and HTML to handle this was
+built by the single +rails generate scaffold+ command.
-TIP: In development mode (which is what you're working in by default), Rails reloads your application with every browser request, so there's no need to stop and restart the web server.
+TIP: In development mode (which is what you're working in by default), Rails
+reloads your application with every browser request, so there's no need to stop
+and restart the web server.
Congratulations, you're riding the rails! Now it's time to see how it all works.
@@ -531,11 +676,16 @@ class Post < ActiveRecord::Base
end
-There isn't much to this file - but note that the +Post+ class inherits from +ActiveRecord::Base+. Active Record supplies a great deal of functionality to your Rails models for free, including basic database CRUD (Create, Read, Update, Destroy) operations, data validation, as well as sophisticated search support and the ability to relate multiple models to one another.
+There isn't much to this file - but note that the +Post+ class inherits from
++ActiveRecord::Base+. Active Record supplies a great deal of functionality to
+your Rails models for free, including basic database CRUD (Create, Read, Update,
+Destroy) operations, data validation, as well as sophisticated search support
+and the ability to relate multiple models to one another.
h4. Adding Some Validation
-Rails includes methods to help you validate the data that you send to models. Open the +app/models/post.rb+ file and edit it:
+Rails includes methods to help you validate the data that you send to models.
+Open the +app/models/post.rb+ file and edit it:
class Post < ActiveRecord::Base
@@ -545,17 +695,24 @@ class Post < ActiveRecord::Base
end
-These changes will ensure that all posts have a name and a title, and that the title is at least five characters long. Rails can validate a variety of conditions in a model, including the presence or uniqueness of columns, their format, and the existence of associated objects.
+These changes will ensure that all posts have a name and a title, and that the
+title is at least five characters long. Rails can validate a variety of
+conditions in a model, including the presence or uniqueness of columns, their
+format, and the existence of associated objects.
h4. Using the Console
-To see your validations in action, you can use the console. The console is a command-line tool that lets you execute Ruby code in the context of your application:
+To see your validations in action, you can use the console. The console is a
+command-line tool that lets you execute Ruby code in the context of your
+application:
$ rails console
-TIP: The default console will make changes to your database. You can instead open a console that will roll back any changes you make by using +rails console --sandbox+.
+TIP: The default console will make changes to your database. You can instead
+open a console that will roll back any changes you make by using +rails console
+--sandbox+.
After the console loads, you can use it to work with your application's models:
@@ -572,15 +729,21 @@ After the console loads, you can use it to work with your application's models:
:name=>["can't be blank"] }>
-This code shows creating a new +Post+ instance, attempting to save it and getting +false+ for a return value (indicating that the save failed), and inspecting the +errors+ of the post.
+This code shows creating a new +Post+ instance, attempting to save it and
+getting +false+ for a return value (indicating that the save failed), and
+inspecting the +errors+ of the post.
When you're finished, type +exit+ and hit +return+ to exit the console.
-TIP: Unlike the development web server, the console does not automatically load your code afresh for each line. If you make changes to your models while the console is open, type +reload!+ at the console prompt to load them.
+TIP: Unlike the development web server, the console does not automatically load
+your code afresh for each line. If you make changes to your models while the
+console is open, type +reload!+ at the console prompt to load them.
h4. Listing All Posts
-The easiest place to start looking at functionality is with the code that lists all posts. Open the file +app/controllers/posts_controller.rb+ and look at the +index+ action:
+The easiest place to start looking at functionality is with the code that lists
+all posts. Open the file +app/controllers/posts_controller.rb+ and look at the
++index+ action:
def index
@@ -593,11 +756,19 @@ def index
end
-+Post.all+ calls the +Post+ model to return all of the posts currently in the database. The result of this call is an array of posts that we store in an instance variable called +@posts+.
++Post.all+ calls the +Post+ model to return all of the posts currently in the
+database. The result of this call is an array of posts that we store in an
+instance variable called +@posts+.
-TIP: For more information on finding records with Active Record, see "Active Record Query Interface":active_record_querying.html.
+TIP: For more information on finding records with Active Record, see "Active
+Record Query Interface":active_record_querying.html.
-The +respond_to+ block handles both HTML and JSON calls to this action. If you browse to "http://localhost:3000/posts.json":http://localhost:3000/posts.json, you'll see a JSON containing all of the posts. The HTML format looks for a view in +app/views/posts/+ with a name that corresponds to the action name. Rails makes all of the instance variables from the action available to the view. Here's +app/views/posts/index.html.erb+:
+The +respond_to+ block handles both HTML and JSON calls to this action. If you
+browse to "http://localhost:3000/posts.json":http://localhost:3000/posts.json,
+you'll see a JSON containing all of the posts. The HTML format looks for a view
+in +app/views/posts/+ with a name that corresponds to the action name. Rails
+makes all of the instance variables from the action available to the view.
+Here's +app/views/posts/index.html.erb+:
Listing posts
@@ -629,18 +800,31 @@ The +respond_to+ block handles both HTML and JSON calls to this action. If you b
<%= link_to 'New post', new_post_path %>
-This view iterates over the contents of the +@posts+ array to display content and links. A few things to note in the view:
+This view iterates over the contents of the +@posts+ array to display content
+and links. A few things to note in the view:
* +link_to+ builds a hyperlink to a particular destination
* +edit_post_path+ and +new_post_path+ are helpers that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes.
-NOTE. In previous versions of Rails, you had to use +<%=h post.name %>+ so that any HTML would be escaped before being inserted into the page. In Rails 3.0, this is now the default. To get unescaped HTML, you now use +<%= raw post.name %>+.
+NOTE. In previous versions of Rails, you had to use +<%=h post.name %>+ so
+that any HTML would be escaped before being inserted into the page. In Rails
+3.0, this is now the default. To get unescaped HTML, you now use +<%= raw
+post.name %>+.
-TIP: For more details on the rendering process, see "Layouts and Rendering in Rails":layouts_and_rendering.html.
+TIP: For more details on the rendering process, see "Layouts and Rendering in
+Rails":layouts_and_rendering.html.
h4. Customizing the Layout
-The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of +layouts+, which are containers for views. When Rails renders a view to the browser, it does so by putting the view's HTML into a layout's HTML. In previous versions of Rails, the +rails generate scaffold+ command would automatically create a controller specific layout, like +app/views/layouts/posts.html.erb+, for the posts controller. However this has been changed in Rails 3.0. An application specific +layout+ is used for all the controllers and can be found in +app/views/layouts/application.html.erb+. Open this layout in your editor and modify the +body+ tag:
+The view is only part of the story of how HTML is displayed in your web browser.
+Rails also has the concept of +layouts+, which are containers for views. When
+Rails renders a view to the browser, it does so by putting the view's HTML into
+a layout's HTML. In previous versions of Rails, the +rails generate scaffold+
+command would automatically create a controller specific layout, like
++app/views/layouts/posts.html.erb+, for the posts controller. However this has
+been changed in Rails 3.0. An application specific +layout+ is used for all the
+controllers and can be found in +app/views/layouts/application.html.erb+. Open
+this layout in your editor and modify the +body+ tag:
@@ -659,11 +843,13 @@ The view is only part of the story of how HTML is displayed in your web browser.