From 56152d8f60963a3d862f335144a33782723ade83 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 18 Jan 2009 00:18:02 +0000 Subject: Regenerate guides --- .../guides/html/getting_started_with_rails.html | 114 ++++++++++----------- 1 file changed, 57 insertions(+), 57 deletions(-) (limited to 'railties/doc/guides/html/getting_started_with_rails.html') diff --git a/railties/doc/guides/html/getting_started_with_rails.html b/railties/doc/guides/html/getting_started_with_rails.html index 56a7ff6b3e..a79d9903aa 100644 --- a/railties/doc/guides/html/getting_started_with_rails.html +++ b/railties/doc/guides/html/getting_started_with_rails.html @@ -347,7 +347,7 @@ Transferring representations of the state of that resource between system compon

3.1. Installing Rails

In most cases, the easiest way to install Rails is to take advantage of RubyGems:

-
@@ -375,28 +375,28 @@ If you want to keep up with cutting-edge changes to Rails, you’ll want to

3.2. Creating the Blog Application

Open a terminal, navigate to a folder where you have rights to create files, and type:

-
$ rails blog

This will create a Rails application that uses a SQLite database for data storage. If you prefer to use MySQL, run this command instead:

-
$ rails blog -d mysql

And if you’re using PostgreSQL for data storage, run this command:

-
$ rails blog -d postgresql

After you create the blog application, switch to its folder to continue work directly in that application:

-
@@ -495,7 +495,7 @@ The production environment is used when you deploy your application for

Rails comes with built-in support for SQLite, 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 a SQLite database when creating a new project, but you can always change it later.

Here’s the section of the default configuration file with connection information for the development environment:

-
@@ -506,7 +506,7 @@ http://www.gnu.org/software/src-highlite -->

If you don’t have any database set up, SQLite is the easiest to get installed. If you’re on OS X 10.5 or greater on a Mac, you already have it. Otherwise, you can install it using RubyGems:

If you’re not running OS X 10.5 or greater, you’ll need to install the SQLite gem. Similar to installing Rails you just need to run:

-
@@ -514,7 +514,7 @@ http://www.gnu.org/software/src-highlite -->

3.3.2. Configuring a MySQL Database

If you choose to use MySQL, your config/database.yml will look a little different. Here’s the development section:

-
@@ -529,7 +529,7 @@ http://www.gnu.org/software/src-highlite -->

3.3.3. Configuring a PostgreSQL Database

If you choose to use PostgreSQL, your config/database.yml will be customized to use PostgreSQL databases:

-
@@ -543,7 +543,7 @@ http://www.gnu.org/software/src-highlite -->

3.3.4. 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:

-
@@ -553,7 +553,7 @@ http://www.gnu.org/software/src-highlite -->

One of the traditional places to start with a new language is by getting some text up on screen quickly. To do that in Rails, 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:

-
@@ -568,7 +568,7 @@ http://www.gnu.org/software/src-highlite -->

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:

-
@@ -576,7 +576,7 @@ http://www.gnu.org/software/src-highlite -->

4.1. Starting up the Web Server

You actually have a functional Rails application already - after running only two commands! To see it, you need to start a web server on your development machine. You can do this by running another command:

-
@@ -597,14 +597,14 @@ http://www.gnu.org/software/src-highlite -->

4.2. Setting the Application Home Page

You’d probably like to replace the "Welcome Aboard" page with your own application’s home page. The first step to doing this is to delete the default page from your application:

-
$ rm public/index.html

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. At the bottom of the file you’ll see the default routes:

-
@@ -613,7 +613,7 @@ map.connect ':c

The default routes handle simple requests such as /home/index: Rails translates that into a call to the index action in the home controller. As another example, /posts/edit/1 would run the edit action in the posts controller with an id of 1.

To hook up your home page, you need to add another line to the routing file, above the default routes:

-
@@ -637,7 +637,7 @@ http://www.gnu.org/software/src-highlite -->

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:

-
@@ -728,7 +728,7 @@ cellspacing="0" cellpadding="4">

One of the products of the script/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/20081013124235_create_posts.rb file (remember, yours will have a slightly different name), here’s what you’ll find:

-
@@ -750,7 +750,7 @@ http://www.gnu.org/software/src-highlite -->

If you were to translate that into words, it says something like: when this migration is run, create a table named posts with two string columns (name and title) and a text column (content), and generate timestamp fields to track record creation and updating. You can learn the detailed syntax for migrations in the Rails Database Migrations guide.

At this point, you can use a rake command to run the migration:

-
@@ -767,7 +767,7 @@ $ rake db:migrate

6.2. 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:

-
@@ -793,7 +793,7 @@ http://www.gnu.org/software/src-highlite -->

6.4. The Model

The model file, app/models/post.rb is about as simple as it can get:

-
@@ -803,7 +803,7 @@ http://www.gnu.org/software/src-highlite -->

6.5. 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:

-
@@ -815,14 +815,14 @@ http://www.gnu.org/software/src-highlite -->

6.6. 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:

-
$ script/console

After the console loads, you can use it to work with your application’s models:

-
@@ -848,7 +848,7 @@ title: nil,6.7. 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:

-
@@ -871,7 +871,7 @@ http://www.gnu.org/software/src-highlite -->

The respond_to block handles both HTML and XML calls to this action. If you browse to http://localhost:3000/posts.xml, you’ll see all of the posts in XML format. 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/view/posts/index.html.erb:

-
@@ -928,7 +928,7 @@ http://www.gnu.org/software/src-highlite -->

6.8. 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. The script/generate scaffold command automatically created a default layout, app/views/layouts/posts.html.erb, for the posts. Open this layout in your editor and modify the body tag:

-
@@ -953,7 +953,7 @@ http://www.gnu.org/software/src-highlite -->

6.9. Creating New Posts

Creating a new post involves two actions. The first is the new action, which instantiates an empty Post object:

-
@@ -967,7 +967,7 @@ http://www.gnu.org/software/src-highlite --> end

The new.html.erb view displays this empty Post to the user:

-
@@ -1005,7 +1005,7 @@ http://www.gnu.org/software/src-highlite -->

When the user clicks the Create button on this form, the browser will send information back to the create method of the controller (Rails knows to call the create method because the form is sent with an HTTP POST request; that’s one of the conventions that I mentioned earlier):

-
@@ -1028,7 +1028,7 @@ http://www.gnu.org/software/src-highlite -->

6.10. Showing an Individual Post

When you click the show link for a post on the index page, it will bring you to a URL like http://localhost:3000/posts/1. Rails interprets this as a call to the show action for the resource, and passes in 1 as the :id parameter. Here’s the show action:

-
@@ -1042,7 +1042,7 @@ http://www.gnu.org/software/src-highlite --> end

The show action uses Post.find to search for a single record in the database by its id value. After finding the record, Rails displays it by using show.html.erb:

-
@@ -1067,7 +1067,7 @@ http://www.gnu.org/software/src-highlite -->

6.11. Editing Posts

Like creating a new post, editing a post is a two-part process. The first step is a request to edit_post_path(@post) with a particular post. This calls the edit action in the controller:

-
@@ -1076,7 +1076,7 @@ http://www.gnu.org/software/src-highlite --> end

After finding the requested post, Rails uses the edit.html.erb view to display it:

-
@@ -1106,7 +1106,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back', posts_path %>

Submitting the form created by this view will invoke the update action within the controller:

-
@@ -1136,7 +1136,7 @@ http://www.gnu.org/software/src-highlite -->

6.12. Destroying a Post

Finally, clicking one of the destroy links sends the associated id to the destroy action:

-
@@ -1158,7 +1158,7 @@ http://www.gnu.org/software/src-highlite -->

As you saw earlier, the scaffold-generated views for the new and edit actions are largely identical. You can pull the shared code out into a partial template. This requires editing the new and edit views, and adding a new template. The new _form.html.erb template should be saved in the same app/views/posts folder as the files from which it is being extracted:

new.html.erb:

-
@@ -1169,7 +1169,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back', posts_path %>

edit.html.erb:

-
@@ -1181,7 +1181,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back', posts_path %>

_form.html.erb:

-
@@ -1209,7 +1209,7 @@ http://www.gnu.org/software/src-highlite -->

7.2. Using Filters to Eliminate Controller Duplication

At this point, if you look at the controller for posts, you’ll see some duplication:

-
@@ -1236,7 +1236,7 @@ http://www.gnu.org/software/src-highlite --> end

Four instances of the exact same line of code doesn’t seem very DRY. Rails provides filters as a way to address this sort of repeated code. In this case, you can DRY things up by using a before_filter:

-
@@ -1272,7 +1272,7 @@ http://www.gnu.org/software/src-highlite -->

8.1. Generating a Model

Models in Rails use a singular name, and their corresponding database tables use a plural name. For the model to hold comments, the convention is to use the name Comment. Even if you don’t want to use the entire apparatus set up by scaffolding, most Rails developers still use generators to make things like models and controllers. To create the new model, run this command in your terminal:

-
@@ -1297,7 +1297,7 @@ http://www.gnu.org/software/src-highlite -->

First, take a look at comment.rb:

-
@@ -1307,7 +1307,7 @@ http://www.gnu.org/software/src-highlite -->

This is very similar to the post.rb model that you saw earlier. The difference is the line belongs_to :post, which sets up an Active Record association. You’ll learn a little about associations in the next section of this guide.

In addition to the model, Rails has also made a migration to create the corresponding database table:

-
@@ -1328,7 +1328,7 @@ http://www.gnu.org/software/src-highlite --> end

The t.references line sets up a foreign key column for the association between the two models. Go ahead and run the migration:

-
@@ -1350,7 +1350,7 @@ One post can have many comments

In fact, this is very close to the syntax that Rails uses to declare this association. You’ve already seen the line of code inside the Comment model that makes each comment belong to a Post:

-
@@ -1359,7 +1359,7 @@ http://www.gnu.org/software/src-highlite --> end

You’ll need to edit the post.rb file to add the other side of the association:

-
@@ -1380,7 +1380,7 @@ http://www.gnu.org/software/src-highlite -->

8.3. Adding a Route

Routes are entries in the config/routes.rb file that tell Rails how to match incoming HTTP requests to controller actions. Open up that file and find the existing line referring to posts. Then edit it as follows:

-
@@ -1399,7 +1399,7 @@ http://www.gnu.org/software/src-highlite -->

8.4. Generating a Controller

With the model in hand, you can turn your attention to creating a matching controller. Again, there’s a generator for this:

-
@@ -1444,7 +1444,7 @@ http://www.gnu.org/software/src-highlite -->

The controller will be generated with empty methods for each action that you specified in the call to script/generate controller:

-
@@ -1464,7 +1464,7 @@ http://www.gnu.org/software/src-highlite --> end

You’ll need to flesh this out with code to actually process requests appropriately in each method. Here’s a version that (for simplicity’s sake) only responds to requests that require HTML:

-
@@ -1513,7 +1513,7 @@ http://www.gnu.org/software/src-highlite -->

You’ll see a bit more complexity here than you did in the controller for posts. That’s a side-effect of the nesting that you’ve set up; each request for a comment has to keep track of the post to which the comment is attached.

In addition, the code takes advantage of some of the methods available for an association. For example, in the new method, it calls

-
@@ -1523,7 +1523,7 @@ http://www.gnu.org/software/src-highlite -->

Because you skipped scaffolding, you’ll need to build views for comments "by hand." Invoking script/generate controller will give you skeleton views, but they’ll be devoid of actual content. Here’s a first pass at fleshing out the comment views.

The index.html.erb view:

-
@@ -1552,7 +1552,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back to Post', @post %>

The new.html.erb view:

-
@@ -1577,7 +1577,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back', post_comments_path(@post) %>

The show.html.erb view:

-
@@ -1597,7 +1597,7 @@ http://www.gnu.org/software/src-highlite --> <%= link_to 'Back', post_comments_path(@post) %>

The edit.html.erb view:

-
@@ -1625,7 +1625,7 @@ http://www.gnu.org/software/src-highlite -->

8.6. Hooking Comments to Posts

As a final step, I’ll modify the show.html.erb view for a post to show the comments on that post, and to allow managing those comments:

-
-- cgit v1.2.3