Permalink
Browse files

Merge pull request #406 from moonglum/getting-started-improvements

Improvements to the Getting Started guide
  • Loading branch information...
marionschleifer committed Nov 6, 2017
2 parents c51d728 + f78bc22 commit 7030571f81f0288d953d18ea56b8f7cd786ca0cf
Showing with 58 additions and 58 deletions.
  1. +31 −29 source/guides/1.0/getting-started.md
  2. +27 −29 source/guides/1.1/getting-started.md
@@ -177,7 +177,7 @@ As you can see, we have set `HANAMI_ENV` environment variable to instruct our co
Now we have a test, we can see it fail:

```
% rake test
% bundle exec rake test
Run options: --seed 44759
# Running:
@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
</div>
```

Save your changes and see your tests pass!
Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.

The terminology of controllers and actions might be confusing, so let's clear this up: actions form the basis of our Hanami applications; controllers are mere modules that group several actions together.
So while the "controller" is _conceptually_ present in our project, in practice we only deal with actions.
@@ -347,7 +347,11 @@ Open up the file `apps/web/templates/application.html.erb` and edit it to look l
</html>
```

Now you can remove the duplicate lines from the other templates.
Now you can remove the duplicate lines from the other templates. Let's run the tests again to check that everything worked fine:

```
bundle exec rake test
```

A **layout** is like any other template, but it is used to wrap your regular templates.
The `yield` line is replaced with the contents of our regular template.
@@ -386,7 +390,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te

### Migrations To Change Our Database Schema

Let's modify the generated migration to include `title` and `author` fields:
Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:

```ruby
# db/migrations/20161115110038_create_books.rb
@@ -422,7 +426,7 @@ Let's prepare our database for the development and test environments:
An entity is something really close to a plain Ruby object.
We should focus on the behaviors that we want from it and only then, how to save it.

For now, we need to create simple entity class:
For now, we keep the generated entity class:

```ruby
# lib/bookshelf/entities/book.rb
@@ -435,7 +439,7 @@ We can verify it all works as expected with a unit test:

```ruby
# spec/bookshelf/entities/book_spec.rb
require 'spec_helper'
require_relative '../../spec_helper'
describe Book do
it 'can be initialized with attributes' do
@@ -506,8 +510,7 @@ Let's write a test to force this change in our view:

```ruby
# spec/web/views/books/index_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/views/books/index'
require_relative '../../../spec_helper'
describe Web::Views::Books::Index do
let(:exposures) { Hash[books: []] }
@@ -573,8 +576,7 @@ that change:

```ruby
# spec/web/controllers/books/index_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/index'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Index do
let(:action) { Web::Controllers::Books::Index.new }
@@ -630,7 +632,7 @@ Run options: --seed 59133
Finished in 0.042065s, 213.9543 runs/s, 380.3633 assertions/s.
6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
9 runs, 16 assertions, 0 failures, 0 errors, 0 skips
```

## Building Forms To Create Records
@@ -739,8 +741,7 @@ Let's express them as unit tests:

```ruby
# spec/web/controllers/books/create_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/create'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Create do
let(:action) { Web::Controllers::Books::Create.new }
@@ -768,7 +769,7 @@ describe Web::Controllers::Books::Create do
end
```

Making these tests pass is easy enough.
Let's make these tests pass!
We've already seen how we can write entities to our database, and we can use `redirect_to` to implement our redirection:

```ruby
@@ -794,11 +795,13 @@ Run options: --seed 63592
# Running:
...............
...S.S.........
Finished in 0.081961s, 183.0142 runs/s, 305.0236 assertions/s.
12 runs, 14 assertions, 0 failures, 0 errors, 2 skips
15 runs, 23 assertions, 0 failures, 0 errors, 2 skips
You have skipped tests. Run with --verbose for details.
```

Congratulations!
@@ -817,8 +820,7 @@ Let's specify this behaviour as unit tests:

```ruby
# spec/web/controllers/books/create_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/create'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Create do
let(:action) { Web::Controllers::Books::Create.new }
@@ -935,9 +937,7 @@ First, we expect a list of errors to be included in the page when `params` conta

```ruby
# spec/web/views/books/new_spec.rb
require 'spec_helper'
require 'ostruct'
require_relative '../../../../apps/web/views/books/new'
require_relative '../../../spec_helper'
describe Web::Views::Books::New do
let(:params) { OpenStruct.new(valid?: false, error_messages: ['Title must be filled', 'Author must be filled']) }
@@ -980,7 +980,7 @@ end
```

In our template we can loop over `params.errors` (if there are any) and display a friendly message.
Open up `apps/web/templates/books/new.html.erb`:
Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:

```erb
<% unless params.valid? %>
@@ -1003,11 +1003,13 @@ Run options: --seed 59940
# Running:
..................
......S..........
Finished in 0.188950s, 89.9707 runs/s, 179.9413 assertions/s.
Finished in 0.078112s, 230.4372 runs/s, 473.6765 assertions/s.
17 runs, 34 assertions, 0 failures, 0 errors, 1 skips
15 runs, 27 assertions, 0 failures, 0 errors, 1 skips
You have skipped tests. Run with --verbose for details.
```

### Improving Our Use Of The Router
@@ -1031,7 +1033,7 @@ resources :books, only: [:index, :new, :create]
```

To get a sense of what routes are defined, now we've made this change, you can
use the special command-line task `routes` to inspect the end result:
run `bundle exec hanami routes` on your command-line to inspect the end result:

```
% bundle exec hanami routes
@@ -1043,10 +1045,10 @@ use the special command-line task `routes` to inspect the end result:
books POST /books Web::Controllers::Books::Create
```

The output for `hanami routes` shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
The output shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.

Now we've applied the `resources` helper method, we can take advantage of the named route methods.
Remember how we built our form using `form_for`?
Remember how we built our form using `form_for` in `apps/web/templates/books/new.html.erb`?

```erb
<%=
@@ -1056,7 +1058,7 @@ Remember how we built our form using `form_for`?
%>
```

It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
We can use the `routes` helper method that is available in our views and actions to access route-specific helper methods:

```erb
@@ -177,7 +177,7 @@ As you can see, we have set `HANAMI_ENV` environment variable to instruct our co
Now we have a test, we can see it fail:

```
% rake test
% bundle exec rake test
Run options: --seed 44759
# Running:
@@ -319,7 +319,7 @@ To make our test pass, we need to edit our newly generated template file in `app
</div>
```

Save your changes and see your tests pass!
Save your changes and see your tests pass! The output will also contain a skipped test. This is due to an autogenerated test in `spec/web/views/books/index_spec.rb`.

The terminology of controllers and actions might be confusing, so let's clear this up: actions form the basis of our Hanami applications; controllers are mere modules that group several actions together.
So while the "controller" is _conceptually_ present in our project, in practice we only deal with actions.
@@ -347,7 +347,7 @@ Open up the file `apps/web/templates/application.html.erb` and edit it to look l
</html>
```

Now you can remove the duplicate lines from the other templates.
Now you can remove the duplicate lines from the other templates. Let's run the tests again to check that everything worked fine.

A **layout** is like any other template, but it is used to wrap your regular templates.
The `yield` line is replaced with the contents of our regular template.
@@ -386,7 +386,7 @@ The generator gives us an entity, a repository, a migration, and accompanying te

### Migrations To Change Our Database Schema

Let's modify the generated migration to include `title` and `author` fields:
Let's modify the generated migration (the path to the migration will differ for you, because it contains a timestamp) to include `title` and `author` fields:

```ruby
# db/migrations/20161115110038_create_books.rb
@@ -422,7 +422,7 @@ Let's prepare our database for the development and test environments:
An entity is something really close to a plain Ruby object.
We should focus on the behaviors that we want from it and only then, how to save it.

For now, we need to create simple entity class:
For now, we keep the generated entity class:

```ruby
# lib/bookshelf/entities/book.rb
@@ -435,7 +435,7 @@ We can verify it all works as expected with a unit test:

```ruby
# spec/bookshelf/entities/book_spec.rb
require 'spec_helper'
require_relative '../../spec_helper'
describe Book do
it 'can be initialized with attributes' do
@@ -506,8 +506,7 @@ Let's write a test to force this change in our view:

```ruby
# spec/web/views/books/index_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/views/books/index'
require_relative '../../../spec_helper'
describe Web::Views::Books::Index do
let(:exposures) { Hash[books: []] }
@@ -573,8 +572,7 @@ that change:

```ruby
# spec/web/controllers/books/index_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/index'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Index do
let(:action) { Web::Controllers::Books::Index.new }
@@ -630,7 +628,7 @@ Run options: --seed 59133
Finished in 0.042065s, 213.9543 runs/s, 380.3633 assertions/s.
6 runs, 7 assertions, 0 failures, 0 errors, 0 skips
9 runs, 16 assertions, 0 failures, 0 errors, 0 skips
```

## Building Forms To Create Records
@@ -739,8 +737,7 @@ Let's express them as unit tests:

```ruby
# spec/web/controllers/books/create_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/create'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Create do
let(:action) { Web::Controllers::Books::Create.new }
@@ -768,7 +765,7 @@ describe Web::Controllers::Books::Create do
end
```

Making these tests pass is easy enough.
Let's make these tests pass!
We've already seen how we can write entities to our database, and we can use `redirect_to` to implement our redirection:

```ruby
@@ -794,11 +791,13 @@ Run options: --seed 63592
# Running:
...............
...S.S.........
Finished in 0.081961s, 183.0142 runs/s, 305.0236 assertions/s.
12 runs, 14 assertions, 0 failures, 0 errors, 2 skips
15 runs, 23 assertions, 0 failures, 0 errors, 2 skips
You have skipped tests. Run with --verbose for details.
```

Congratulations!
@@ -817,8 +816,7 @@ Let's specify this behaviour as unit tests:

```ruby
# spec/web/controllers/books/create_spec.rb
require 'spec_helper'
require_relative '../../../../apps/web/controllers/books/create'
require_relative '../../../spec_helper'
describe Web::Controllers::Books::Create do
let(:action) { Web::Controllers::Books::Create.new }
@@ -935,9 +933,7 @@ First, we expect a list of errors to be included in the page when `params` conta

```ruby
# spec/web/views/books/new_spec.rb
require 'spec_helper'
require 'ostruct'
require_relative '../../../../apps/web/views/books/new'
require_relative '../../../spec_helper'
describe Web::Views::Books::New do
let(:params) { OpenStruct.new(valid?: false, error_messages: ['Title must be filled', 'Author must be filled']) }
@@ -980,7 +976,7 @@ end
```

In our template we can loop over `params.errors` (if there are any) and display a friendly message.
Open up `apps/web/templates/books/new.html.erb`:
Open up `apps/web/templates/books/new.html.erb` and add the following at the top of the file:

```erb
<% unless params.valid? %>
@@ -1003,11 +999,13 @@ Run options: --seed 59940
# Running:
..................
......S..........
Finished in 0.188950s, 89.9707 runs/s, 179.9413 assertions/s.
Finished in 0.078112s, 230.4372 runs/s, 473.6765 assertions/s.
17 runs, 34 assertions, 0 failures, 0 errors, 1 skips
15 runs, 27 assertions, 0 failures, 0 errors, 1 skips
You have skipped tests. Run with --verbose for details.
```

### Improving Our Use Of The Router
@@ -1031,7 +1029,7 @@ resources :books, only: [:index, :new, :create]
```

To get a sense of what routes are defined, now we've made this change, you can
use the special command-line task `routes` to inspect the end result:
run `bundle exec hanami routes` on your command-line to inspect the end result:

```
% bundle exec hanami routes
@@ -1043,10 +1041,10 @@ use the special command-line task `routes` to inspect the end result:
books POST /books Web::Controllers::Books::Create
```

The output for `hanami routes` shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.
The output shows you the name of the defined helper method (you can suffix this name with `_path` or `_url` and call it on the `routes` helper), the allowed HTTP method, the path and finally the controller action that will be used to handle the request.

Now we've applied the `resources` helper method, we can take advantage of the named route methods.
Remember how we built our form using `form_for`?
Remember how we built our form using `form_for` in `apps/web/templates/books/new.html.erb`?

```erb
<%=
@@ -1056,7 +1054,7 @@ Remember how we built our form using `form_for`?
%>
```

It's silly to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
We don't need to include a hard-coded path in our template, when our router is already perfectly aware of which route to point the form to.
We can use the `routes` helper method that is available in our views and actions to access route-specific helper methods:

```erb

0 comments on commit 7030571

Please sign in to comment.