diff options
Diffstat (limited to 'guides/source/getting_started.md')
| -rw-r--r-- | guides/source/getting_started.md | 91 |
1 files changed, 43 insertions, 48 deletions
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 61658cdfc9..e486c53fe3 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -1,4 +1,4 @@ -**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonrails.org.** +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.** Getting Started with Rails ========================== @@ -90,11 +90,11 @@ $ ruby -v ruby 2.5.0 ``` -Rails requires Ruby version 2.4.1 or later. If the version number returned is +Rails requires Ruby version 2.5.0 or later. If the version number returned is less than that number, you'll need to install a fresh copy of Ruby. -TIP: To quickly install Ruby and Ruby on Rails on your system in Windows, you can use -[Rails Installer](http://railsinstaller.org). For more installation methods for most +TIP: To quickly install Ruby and Ruby on Rails on your system in Windows, you can use +[Rails Installer](http://railsinstaller.org). For more installation methods for most Operating Systems take a look at [ruby-lang.org](https://www.ruby-lang.org/en/documentation/installation/). If you are working on Windows, you should also install the @@ -126,7 +126,7 @@ run the following: $ rails --version ``` -If it says something like "Rails 5.1.1", you are ready to continue. +If it says something like "Rails 5.2.1", you are ready to continue. ### Creating the Blog Application @@ -199,7 +199,7 @@ start a web server on your development machine. You can do this by running the following in the `blog` directory: ```bash -$ bin/rails server +$ rails server ``` TIP: If you are using Windows, you have to pass the scripts under the `bin` @@ -255,7 +255,7 @@ tell it you want a controller called "Welcome" with an action called "index", just like this: ```bash -$ bin/rails generate controller Welcome index +$ rails generate controller Welcome index ``` Rails will create several files and a route for you. @@ -272,8 +272,6 @@ invoke helper create app/helpers/welcome_helper.rb invoke test_unit invoke assets -invoke coffee -create app/assets/javascripts/welcome.coffee invoke scss create app/assets/stylesheets/welcome.scss ``` @@ -305,7 +303,7 @@ Open the file `config/routes.rb` in your editor. Rails.application.routes.draw do get 'welcome/index' - # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html + # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html end ``` @@ -328,9 +326,9 @@ end 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 (`bin/rails generate controller Welcome index`). +controller generator (`rails generate controller Welcome index`). -Launch the web server again if you stopped it to generate the controller (`bin/rails +Launch the web server again if you stopped it to generate the controller (`rails server`) and 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` @@ -364,13 +362,13 @@ Rails.application.routes.draw do end ``` -If you run `bin/rails routes`, you'll see that it has defined routes for all the +If you run `rails routes`, you'll see that it has defined routes for all the standard RESTful actions. The meaning of the prefix column (and other columns) will be seen later, but for now notice that Rails has inferred the singular form `article` and makes meaningful use of the distinction. ```bash -$ bin/rails routes +$ rails routes Prefix Verb URI Pattern Controller#Action welcome_index GET /welcome/index(.:format) welcome#index articles GET /articles(.:format) articles#index @@ -409,7 +407,7 @@ a controller called `ArticlesController`. You can do this by running this command: ```bash -$ bin/rails generate controller Articles +$ rails generate controller Articles ``` If you open up the newly generated `app/controllers/articles_controller.rb` @@ -463,22 +461,19 @@ available, Rails will raise an exception. Let's look at the full error message again: ->ArticlesController#new is missing a template for this request format and variant. request.formats: ["text/html"] request.variant: [] NOTE! For XHR/Ajax or API requests, this action would normally respond with 204 No Content: an empty white screen. Since you're loading it in a web browser, we assume that you expected to actually render a template, not… nothing, so we're showing an error to be extra-clear. If you expect 204 No Content, carry on. That's what you'll get from an XHR or API request. Give it a shot. +>ArticlesController#new is missing a template for request formats: text/html -That's quite a lot of text! Let's quickly go through and understand what each -part of it means. +>NOTE! +>Unless told otherwise, Rails expects an action to render a template with the same name, contained in a folder named after its controller. If this controller is an API responding with 204 (No Content), which does not require a template, then this error will occur when trying to access it via browser, since we expect an HTML template to be rendered for such requests. If that's the case, carry on. -The first part identifies which template is missing. In this case, it's the +The message identifies which template is missing. In this case, it's the `articles/new` template. Rails will first look for this template. If not found, -then it will attempt to load a template called `application/new`. It looks for -one here because the `ArticlesController` inherits from `ApplicationController`. +then it will attempt to load a template called `application/new`, because the +`ArticlesController` inherits from `ApplicationController`. -The next part of the message contains `request.formats` which specifies -the format of template to be served in response. It is set to `text/html` as we -requested this page via browser, so Rails is looking for an HTML template. -`request.variant` specifies what kind of physical devices would be served by -the response and helps Rails determine which template to use in the response. -It is empty because no information has been provided. +Next the message contains `request.formats` which specifies the format of +template to be served in response. It is set to `text/html` as we requested +this page via browser, so Rails is looking for an HTML template. The simplest template that would work in this case would be one located at `app/views/articles/new.html.erb`. The extension of this file name is important: @@ -561,10 +556,10 @@ this: In this example, the `articles_path` helper is passed to the `:url` option. To see what Rails will do with this, we look back at the output of -`bin/rails routes`: +`rails routes`: ```bash -$ bin/rails routes +$ rails routes Prefix Verb URI Pattern Controller#Action welcome_index GET /welcome/index(.:format) welcome#index articles GET /articles(.:format) articles#index @@ -658,7 +653,7 @@ Rails developers tend to use when creating new models. To create the new model, run this command in your terminal: ```bash -$ bin/rails generate model Article title:string text:text +$ rails generate model Article title:string text:text ``` With that command we told Rails that we want an `Article` model, together @@ -677,7 +672,7 @@ models, as that will be done automatically by Active Record. ### Running a Migration -As we've just seen, `bin/rails generate model` created a _database migration_ file +As we've just seen, `rails generate model` created a _database migration_ file inside the `db/migrate` directory. 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 @@ -688,7 +683,7 @@ If you look in the `db/migrate/YYYYMMDDHHMMSS_create_articles.rb` file (remember, yours will have a slightly different name), here's what you'll find: ```ruby -class CreateArticles < ActiveRecord::Migration[5.0] +class CreateArticles < ActiveRecord::Migration[6.0] def change create_table :articles do |t| t.string :title @@ -710,10 +705,10 @@ two timestamp fields to allow Rails to track article creation and update times. TIP: For more information about migrations, refer to [Active Record Migrations] (active_record_migrations.html). -At this point, you can use a bin/rails command to run the migration: +At this point, you can use a rails command to run the migration: ```bash -$ bin/rails db:migrate +$ rails db:migrate ``` Rails will execute this migration command and tell you it created the Articles @@ -730,7 +725,7 @@ 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 another environment, for instance in production, you must explicitly pass it when -invoking the command: `bin/rails db:migrate RAILS_ENV=production`. +invoking the command: `rails db:migrate RAILS_ENV=production`. ### Saving data in the controller @@ -779,10 +774,11 @@ extra fields with values that violated your application's integrity? They would be 'mass assigned' into your model and then into the database along with the good stuff - potentially breaking your application or worse. -We have to whitelist our controller parameters to prevent wrongful mass +We have to define our permitted controller parameters to prevent wrongful mass assignment. In this case, we want to both allow and require the `title` and `text` parameters for valid use of `create`. The syntax for this introduces -`require` and `permit`. The change will involve one line in the `create` action: +`require` and `permit`. The change will involve one line in the `create` +action: ```ruby @article = Article.new(params.require(:article).permit(:title, :text)) @@ -817,7 +813,7 @@ If you submit the form again now, Rails will complain about not finding the `show` action. That's not very useful though, so let's add the `show` action before proceeding. -As we have seen in the output of `bin/rails routes`, the route for `show` action is +As we have seen in the output of `rails routes`, the route for `show` action is as follows: ``` @@ -879,7 +875,7 @@ Visit <http://localhost:3000/articles/new> and give it a try! ### Listing all articles We still need a way to list all our articles, so let's do that. -The route for this as per output of `bin/rails routes` is: +The route for this as per output of `rails routes` is: ``` articles GET /articles(.:format) articles#index @@ -1213,7 +1209,7 @@ view above, will cause form helpers to fill in form fields with the correspondin values of the object. Passing in a symbol scope such as `scope: :article`, as was done in the new view, only creates empty form fields. More details can be found in [form_with documentation] -(http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with). +(https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with). Next, we need to create the `update` action in `app/controllers/articles_controller.rb`. @@ -1349,7 +1345,7 @@ to stand in for either of the other forms is that `@article` is a *resource* corresponding to a full set of RESTful routes, and Rails is able to infer which URI and method to use. For more information about this use of `form_with`, see [Resource-oriented style] -(http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with-label-Resource-oriented+style). +(https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-form_with-label-Resource-oriented+style). Now, let's update the `app/views/articles/new.html.erb` view to use this new partial, rewriting it completely: @@ -1376,7 +1372,7 @@ Then do the same for the `app/views/articles/edit.html.erb` view: We're now ready to cover the "D" part of CRUD, deleting articles from the database. Following the REST convention, the route for -deleting articles as per output of `bin/rails routes` is: +deleting articles as per output of `rails routes` is: ```ruby DELETE /articles/:id(.:format) articles#destroy @@ -1526,7 +1522,7 @@ the `Article` model. This time we'll create a `Comment` model to hold a reference to an article. Run this command in your terminal: ```bash -$ bin/rails generate model Comment commenter:string body:text article:references +$ rails generate model Comment commenter:string body:text article:references ``` This command will generate four files: @@ -1559,7 +1555,7 @@ In addition to the model, Rails has also made a migration to create the corresponding database table: ```ruby -class CreateComments < ActiveRecord::Migration[5.0] +class CreateComments < ActiveRecord::Migration[6.0] def change create_table :comments do |t| t.string :commenter @@ -1577,7 +1573,7 @@ for it, and a foreign key constraint that points to the `id` column of the `arti table. Go ahead and run the migration: ```bash -$ bin/rails db:migrate +$ rails db:migrate ``` Rails is smart enough to only execute the migrations that have not already been @@ -1653,10 +1649,10 @@ With the model in hand, you can turn your attention to creating a matching controller. Again, we'll use the same generator we used before: ```bash -$ bin/rails generate controller Comments +$ rails generate controller Comments ``` -This creates five files and one empty directory: +This creates four files and one empty directory: | File/Directory | Purpose | | -------------------------------------------- | ---------------------------------------- | @@ -1664,7 +1660,6 @@ This creates five files and one empty directory: | app/views/comments/ | Views of the controller are stored here | | test/controllers/comments_controller_test.rb | The test for the controller | | app/helpers/comments_helper.rb | A view helper file | -| app/assets/javascripts/comments.coffee | CoffeeScript for the controller | | app/assets/stylesheets/comments.scss | Cascading style sheet for the controller | Like with any blog, our readers will create their comments directly after |