diff options
Diffstat (limited to 'guides/source/getting_started.md')
-rw-r--r-- | guides/source/getting_started.md | 43 |
1 files changed, 25 insertions, 18 deletions
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 3fbe64c4a7..9f23f9fc42 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -77,10 +77,17 @@ TIP: The examples below use # and $ to denote superuser and regular user termina ### Installing Rails +Open up a command line prompt. On a mac this is called terminal, on windows it is called command prompt. Any commands prefaced with a dollar sign `$` should be run in the command line. Verify sure you have a current version of Ruby installed: + +```bash +$ ruby -v +ruby 1.9.3p194 +``` + To install Rails, use the `gem install` command provided by RubyGems: ```bash -# gem install rails +$ gem install rails ``` TIP. A number of tools exist to help you quickly install Ruby and Ruby @@ -154,11 +161,11 @@ $ rails server TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and the absence of a runtime will give you an `execjs` error. Usually Mac OS X and Windows come with a JavaScript runtime installed. Rails adds the `therubyracer` gem to Gemfile in a commented line for new apps and you can uncomment if you need it. `therubyrhino` is the recommended runtime for JRuby users and is added by default to Gemfile in apps generated under JRuby. You can investigate about all the supported runtimes at [ExecJS](https://github.com/sstephenson/execjs#readme). -This will fire up WEBrick, a webserver built into Ruby by default. To see your application in action, open a browser window and navigate to [http://localhost:3000](http://localhost:3000). You should see the Rails default information page: +This will fire up WEBrick, a webserver built into Ruby by default. To see your application in action, open a browser window and navigate to <http://localhost:3000>. You should see the Rails default information page: ![Welcome Aboard screenshot](images/rails_welcome.png) -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 restart 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. To verify the server has stopped you should see your command prompt cursor again. For most unix like systems including mac this will be a dollar sign `$`. In development mode, Rails does not generally require you to restart 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. @@ -207,11 +214,11 @@ Open the `app/views/welcome/index.html.erb` file in your text editor and edit it ### 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). At the moment, however, the "Welcome Aboard" smoke test is occupying that spot. +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>. At the moment, however, the "Welcome Aboard" smoke test is occupying that spot. To fix this, delete the `index.html` file located inside the `public` directory of the application. -You need to do this because Rails will serve any static file in the `public` directory that matches a route in preference to any dynamic content you generate from the controllers. The `index.html` file is special: it will be served if a request comes in at the root route, e.g. [http://localhost:3000](http://localhost:3000). If another request such as [http://localhost:3000/welcome](http://localhost:3000/welcome) happened, a static file at `public/welcome.html` would be served first, but only if it existed. +You need to do this because Rails will serve any static file in the `public` directory that matches a route in preference to any dynamic content you generate from the controllers. The `index.html` file is special: it will be served if a request comes in at the root route, e.g. <http://localhost:3000>. If another request such as <http://localhost:3000/welcome> happened, a static file at `public/welcome.html` would be served first, but only if it existed. Next, you have to tell Rails where your actual home page is located. @@ -235,9 +242,9 @@ This is your application's _routing file_ which holds entries in a special DSL ( root :to => "welcome#index" ``` -The `root :to => "welcome#index"` tells Rails to map requests to the root of the application to the welcome controller's index action and `get "welcome/index"` tells Rails to map requests to [http://localhost:3000/welcome/index](http://localhost:3000/welcome/index) to the welcome controller's index action. This was created earlier when you ran the controller generator (`rails generate controller welcome index`). +The `root :to => "welcome#index"` tells Rails to map requests to the root of the application to the welcome controller's index action and `get "welcome/index"` tells Rails to map requests to <http://localhost:3000/welcome/index> to the welcome controller's index action. This was created earlier when you ran the controller generator (`rails generate controller welcome index`). -If you navigate to [http://localhost:3000](http://localhost:3000) in your browser, you'll see the `Hello, Rails!` message you put into `app/views/welcome/index.html.erb`, indicating that this new route is indeed going to `WelcomeController`'s `index` action and is rendering the view correctly. +If you navigate to <http://localhost:3000> in your browser, you'll see the `Hello, Rails!` message you put into `app/views/welcome/index.html.erb`, indicating that this new route is indeed going to `WelcomeController`'s `index` action and is rendering the view correctly. NOTE. For more information about routing, refer to [Rails Routing from the Outside In](routing.html). @@ -256,7 +263,7 @@ It will look a little basic for now, but that's ok. We'll look at improving the ### Laying down the ground work -The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at `/posts/new`. If you attempt to navigate to that now -- by visiting [http://localhost:3000/posts/new](http://localhost:3000/posts/new) -- Rails will give you a routing error: +The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at `/posts/new`. If you attempt to navigate to that now -- by visiting <http://localhost:3000/posts/new> -- Rails will give you a routing error: ![A routing error, no route matches /posts/new](images/getting_started/routing_error_no_route_matches.png) @@ -270,7 +277,7 @@ get "posts/new" This route is a super-simple route: it defines a new route that only responds to `GET` requests, and that the route is at `posts/new`. But how does it know where to go without the use of the `:to` option? Well, Rails uses a sensible default here: Rails will assume that you want this route to go to the new action inside the posts controller. -With the route defined, requests can now be made to `/posts/new` in the application. Navigate to [http://localhost:3000/posts/new](http://localhost:3000/posts/new) and you'll see another routing error: +With the route defined, requests can now be made to `/posts/new` in the application. Navigate to <http://localhost:3000/posts/new> and you'll see another routing error: ![Another routing error, uninitialized constant PostsController](images/getting_started/routing_error_no_controller.png) @@ -289,7 +296,7 @@ end A controller is simply a class that is defined to inherit from `ApplicationController`. It's inside this class that you'll define methods that will become the actions for this controller. These actions will perform CRUD operations on the posts within our system. -If you refresh [http://localhost:3000/posts/new](http://localhost:3000/posts/new) now, you'll get a new error: +If you refresh <http://localhost:3000/posts/new> now, you'll get a new error: ![Unknown action new for PostsController!](images/getting_started/unknown_action_new_for_posts.png) @@ -302,7 +309,7 @@ def new end ``` -With the `new` method defined in `PostsController`, if you refresh [http://localhost:3000/posts/new](http://localhost:3000/posts/new) you'll see another error: +With the `new` method defined in `PostsController`, if you refresh <http://localhost:3000/posts/new> you'll see another error: ![Template is missing for posts/new](images/getting_started/template_is_missing_posts_new.png) @@ -330,7 +337,7 @@ Go ahead now and create a new file at `app/views/posts/new.html.erb` and write t <h1>New Post</h1> ``` -When you refresh [http://localhost:3000/posts/new](http://localhost:3000/posts/new) you'll now see that the page has a title. The route, controller, action and view are now working harmoniously! It's time to create the form for a new post. +When you refresh <http://localhost:3000/posts/new> you'll now see that the page has a title. The route, controller, action and view are now working harmoniously! It's time to create the form for a new post. ### The first form @@ -579,7 +586,7 @@ content: ``` Finally, if you now go to -[http://localhost:3000/posts/new](http://localhost:3000/posts/new) you'll +<http://localhost:3000/posts/new> you'll be able to create a post. Try it! ![Show action for posts](images/getting_started/show_action_for_posts.png) @@ -756,7 +763,7 @@ Notice that inside the `create` action we use `render` instead of `redirect_to` returns `false`. The `render` method is used so that the `@post` object is passed back to the `new` template when it is rendered. This rendering is done within the same request as the form submission, whereas the `redirect_to` will tell the browser to issue another request. If you reload -[http://localhost:3000/posts/new](http://localhost:3000/posts/new) and +<http://localhost:3000/posts/new> and try to save a post without a title, Rails will send you back to the form, but that's not very useful. You need to tell the user that something went wrong. To do that, you'll modify @@ -1037,7 +1044,7 @@ Then do the same for the `app/views/posts/edit.html.erb` view: <%= link_to 'Back', :action => :index %> ``` -Point your browser to [http://localhost:3000/posts/new](http://localhost:3000/posts/new) and +Point your browser to <http://localhost:3000/posts/new> and try creating a new post. Everything still works. Now try editing the post and you'll receive the following error: @@ -1057,10 +1064,10 @@ If you run `rake routes` from the console you'll see that we already have a `posts_path` route, which was created automatically by Rails when we defined the route for the index action. However, we don't have a `post_path` yet, which is the reason why we -received an error before. +received an error before. With your server running you can view your routes by visiting [localhost:3000/rails/info/routes](http://localhost:3000/rails/info/routes), or you can generate them from the command line by running `rake routes`: ```bash -# rake routes +$ rake routes posts GET /posts(.:format) posts#index posts_new GET /posts/new(.:format) posts#new @@ -1198,7 +1205,7 @@ If you run `rake routes`, you'll see that all the routes that we declared before are still available: ```bash -# rake routes +$ rake routes posts GET /posts(.:format) posts#index POST /posts(.:format) posts#create new_post GET /posts/new(.:format) posts#new |