Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Add license and readme

(cherry picked from commit 2acf777)
  • Loading branch information...
commit b10706170b8897aefefa1a3439ce0f285836b2d8 1 parent 2ba4d36
Peter Jones authored November 04, 2011

Showing 2 changed files with 418 additions and 0 deletions. Show diff stats Hide diff stats

  1. 22  LICENSE
  2. 396  README.md
22  LICENSE
... ...
@@ -0,0 +1,22 @@
  1
+This is free and unencumbered software released into the public domain.
  2
+
  3
+Anyone is free to copy, modify, publish, use, compile, sell, or
  4
+distribute this software, either in source code form or as a compiled
  5
+binary, for any purpose, commercial or non-commercial, and by any
  6
+means.
  7
+
  8
+In jurisdictions that recognize copyright laws, the author or authors
  9
+of this software dedicate any and all copyright interest in the
  10
+software to the public domain. We make this dedication for the benefit
  11
+of the public at large and to the detriment of our heirs and
  12
+successors. We intend this dedication to be an overt act of
  13
+relinquishment in perpetuity of all present and future rights to this
  14
+software under copyright law.
  15
+
  16
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  20
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  21
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22
+OTHER DEALINGS IN THE SOFTWARE.
396  README.md
Source Rendered
... ...
@@ -0,0 +1,396 @@
  1
+# Self-guided Ruby on Rails 3.1 Tutorial
  2
+
  3
+This is a small application using Ruby on Rails 3.1 to demonstrate how
  4
+a new application might be bootstrapped and features added over time.
  5
+It's a self-guided tour, you should use this guide to follow along
  6
+with the commits and branches.  Even better, you should try to
  7
+replicate each step on your own using this application as a guide.
  8
+
  9
+Make sure you open each referenced file in your text editor of choice.
  10
+As new features are introduced comments in the source code provide
  11
+guidance as to why they are being used.
  12
+
  13
+This example application is brought to you by [Peter Jones] and
  14
+[Devalot].  For more information about this application please read
  15
+[this article] [article].
  16
+
  17
+[Peter Jones]: https://twitter.com/#!/contextualdev
  18
+[Devalot]: http://www.devalot.com
  19
+[article]: http://www.devalot.com/articles/2011/11/ror-example
  20
+
  21
+## What This Application Does
  22
+
  23
+This is very simple application where you register your car and then
  24
+record basic information each time you go to the gas station and
  25
+refuel.  It then calculates some basic information like miles per
  26
+gallon (my apologies to the rest of the world that uses the much
  27
+preferred metric system).
  28
+
  29
+## How to Use This Guide
  30
+
  31
+Follow along with each step trying to recreate the changes in your own
  32
+application.  Use the features of git to help you see the changes in
  33
+each branch and for each file.  If you are not comfortable with git
  34
+you can use the browser interface on Github.
  35
+
  36
+If you don't understand something Google is your friend.  You can also
  37
+open a ticket or post a comment on Github.
  38
+
  39
+## Dependencies
  40
+
  41
+Before you start you should have a working installation of [Ruby].
  42
+Versions 1.8.7 and 1.9.3 should both work.  You should also have
  43
+[SQLite3] installed.
  44
+
  45
+[ruby]: http://www.ruby-lang.org/
  46
+[sqlite3]: http://www.sqlite.org/
  47
+
  48
+## Using this Application Right Now
  49
+
  50
+If you're going to jump right in and run the application as it is
  51
+right now, you can:
  52
+
  53
+    git clone git://github.com/devalot/ror-example.git
  54
+    cd ror-example
  55
+    bundle install
  56
+    rake db:migrate
  57
+    rails server
  58
+
  59
+## The Beginning: Creating the Application
  60
+
  61
+1. Install the `rails` gem and create a new Ruby on Rails application.
  62
+
  63
+        gem install rails
  64
+        rails new example
  65
+        cd example
  66
+
  67
+    Feel free to use a name other than "example" for your application.
  68
+
  69
+2. Remove some of the default files that we won't be using.
  70
+
  71
+        rm app/assets/images/rails.png
  72
+        rm public/index.html
  73
+        rm public/favicon.ico
  74
+
  75
+3. Edit the `Gemfile` to pick a JavaScript interpreter (I recommend
  76
+   [The Ruby Racer]) then update your `Gemfile.lock` file by running
  77
+   the `bundle` command.
  78
+
  79
+        bundle install
  80
+
  81
+4. Optionally create a new [Git] repository for this rails
  82
+   application.
  83
+
  84
+        git init
  85
+        git add .
  86
+        git ci -m "Initial commit"
  87
+
  88
+[git]: http://git-scm.com/
  89
+[the ruby racer]: https://github.com/cowboyd/therubyracer
  90
+
  91
+## Add Users and Authentication Plumbing
  92
+
  93
+The very first thing we'll want to do is create a model for users and
  94
+a database table for users.  We'll also need some basic authentication
  95
+code in place to store a user's password securely.
  96
+
  97
+To see what the application looks like at the end of this section you
  98
+can use the [01-user-model] branch.  To see a diff for the changes in
  99
+this section use commit [1e32158].
  100
+
  101
+1. Use the rails generator to create a user model.  A shortcut for
  102
+   `rails generate` is `rails g`.
  103
+
  104
+        rails g model user
  105
+
  106
+2. Well be using [FactoryGirl] instead of fixtures, so remove the
  107
+   fixture file that was created.  We could have also given the
  108
+   `--no-fixture` option to the generator to not generate the fixture
  109
+   in the first place.
  110
+
  111
+        rm test/fixtures/users.yml
  112
+
  113
+3. The model generator also created a database migration that needs to
  114
+   be edited so we can properly set up the users table in the
  115
+   database.
  116
+
  117
+   Edit `db/migrate/20111102182704_create_users.rb` then:
  118
+
  119
+        rake db:migrate
  120
+
  121
+4. Add validation and authentication code by editing the following
  122
+   files.
  123
+
  124
+   * `app/models/user.rb`
  125
+   * `test/unit/user_test.rb`
  126
+
  127
+   Then run the tests.
  128
+
  129
+        rake test
  130
+
  131
+[01-user-model]: https://github.com/devalot/ror-example/tree/01-user-model
  132
+[1e32158]: https://github.com/devalot/ror-example/commit/1e32158254b0390907ab88064f5188c606f139ed
  133
+[factorygirl]: https://github.com/thoughtbot/factory_girl/blob/master/GETTING_STARTED.md
  134
+
  135
+## Add the Remaining Models: Car and Refuel
  136
+
  137
+Next we're going to need models and database tables for cars and
  138
+refuels.
  139
+
  140
+To see what the application looks like at the end of this section you
  141
+can use the [02-car-refuel] branch.  To see a diff for the changes in
  142
+this section use commit [8032839] (or diff against the previous
  143
+branch).
  144
+
  145
+1. Create two more model files for cars and refuels.
  146
+
  147
+        rails g model car --no-fixture
  148
+        rails g model refuel --no-fixture
  149
+
  150
+2. Edit the migrations to set up the cars and refuels database tables.
  151
+
  152
+   * `db/migrate/20111102192932_create_cars.rb`
  153
+   * `db/migrate/20111102210426_create_refuels.rb`
  154
+
  155
+   Then migrate the database:
  156
+
  157
+        rake db:migrate
  158
+
  159
+3. Edit the `Gemfile` to add new dependencies: the `money` and
  160
+   `factory_girl_rails` gems.  Then use the `bundle` command to update
  161
+   the `Gemfile.lock` file.
  162
+
  163
+        bundle install
  164
+
  165
+4. Add the appropriate model associations and create the logic for
  166
+   calculating miles per gallon.  Edit the following files.
  167
+
  168
+   * `app/models/user.rb`
  169
+   * `app/models/car.rb`
  170
+   * `app/models/refuel.rb`
  171
+
  172
+   Create a file to hold the testing factories (a simple way to build
  173
+   model objects) and then add some testing logic for the calculations
  174
+   in the refuel model.  Edit the following files.
  175
+
  176
+   * `test/factories.rb`
  177
+   * `test/unit/refuel_test.rb`
  178
+
  179
+   Make sure all the tests are passing.
  180
+
  181
+        rake test
  182
+
  183
+[02-car-refuel]: https://github.com/devalot/ror-example/tree/02-car-refuel
  184
+[8032839]: https://github.com/devalot/ror-example/commit/8032839c25f0068c6a9756f7a0d333cf0a94d998
  185
+
  186
+## Session Management (login, logout)
  187
+
  188
+Now we can add the files necessary to play with the application in a
  189
+web browser.  We're going to add the ability to log in and log out of
  190
+the application.
  191
+
  192
+To see what the application looks like at the end of this section you
  193
+can use the [03-sessions] branch.  To see a diff for the changes in
  194
+this section use commit [2ba4d36] (or diff against the previous
  195
+branch).
  196
+
  197
+1. Generate two controllers.
  198
+
  199
+        rails g controller cars
  200
+        rails g controller sessions
  201
+
  202
+2. Remove files we don't need.
  203
+
  204
+        rm app/assets/javascripts/cars.js.coffee
  205
+        rm app/assets/stylesheets/cars.css.scss
  206
+        rm app/assets/javascripts/sessions.js.coffee
  207
+        rm app/assets/stylesheets/sessions.css.scss
  208
+
  209
+3. Add routes and authentication helpers by editing the following files.
  210
+
  211
+   * `config/routes.rb`
  212
+   * `app/controllers/application_controller.rb`
  213
+
  214
+4. Add session logic (login, logout) by editing the following files.
  215
+
  216
+   * `app/controllers/sessions_controller.rb`
  217
+   * `app/views/sessions/new.html.erb`
  218
+
  219
+5. Add minimum logic to the cars controller.
  220
+
  221
+    Edit the following files:
  222
+
  223
+    * `app/controllers/cars_controller.rb`
  224
+    * `app/views/cars/index.html.erb`
  225
+
  226
+6. Test session management.
  227
+
  228
+   Generate a new integration test:
  229
+
  230
+        rails g integration_test login_flow
  231
+
  232
+    Edit the following files:
  233
+
  234
+    * `test/functional/sessions_controller_test.rb`
  235
+    * `test/integration/login_flow_test.rb`
  236
+
  237
+    Then run the tests:
  238
+
  239
+        rake test
  240
+
  241
+7. Create a user record for yourself.
  242
+
  243
+   Start the rails console and add a user record to the database.  The
  244
+   console allows you to interactively type in Ruby code:
  245
+
  246
+        rails console
  247
+
  248
+        User.create!(:first_name => 'John',
  249
+                     :last_name  => 'Doe',
  250
+                     :email      => 'john@doe.com',
  251
+                     :password   => 'foobar',
  252
+                     :password_confirmation => 'foobar')
  253
+
  254
+8. Now see if you can log in, keeping in mind that you can't yet add a
  255
+   new car.  Start the rails server then open [http://localhost:3000]
  256
+   [localhost].
  257
+
  258
+        rails server
  259
+
  260
+[03-sessions]: https://github.com/devalot/ror-example/commits/03-sessions
  261
+[2ba4d36]: https://github.com/devalot/ror-example/commit/2ba4d369eff2126ea813e30dfc24ccb0113568df
  262
+[localhost]: http://localhost:3000
  263
+
  264
+## Add the Ability to Create Cars and Refuels
  265
+
  266
+Finally, we're going to add the ability to create cars and refuels in
  267
+the browser.
  268
+
  269
+To see what the application looks like at the end of this section you
  270
+can use the [04-create-refuels] branch.  To see a diff for the changes
  271
+in this section use commit [da7d7de] (or diff against the previous
  272
+branch).
  273
+
  274
+1. Add the controller logic and views to create and edit cars.
  275
+
  276
+   Edit the following files:
  277
+
  278
+   * `app/controllers/cars_controller.rb`
  279
+   * `app/views/cars/new.html.erb`
  280
+   * `app/views/cars/edit.html.erb`
  281
+   * `app/views/cars/index.html.erb`
  282
+
  283
+2. Play with the new interface.
  284
+
  285
+   Start the rails server:
  286
+
  287
+        rails server
  288
+
  289
+   Try the following URLs:
  290
+
  291
+   * [http://localhost:3000/cars] [cars]
  292
+   * [http://localhost:3000/cars.xml] [xml]
  293
+   * [http://localhost:3000/cars.json] [json]
  294
+
  295
+3. Create a controller and the interface for working with refuels.
  296
+
  297
+   Create the controller:
  298
+
  299
+        rails g controller refuels
  300
+        rm app/assets/javascripts/refuels.js.coffee
  301
+        rm app/assets/stylesheets/refuels.css.scss
  302
+
  303
+   Edit the following files:
  304
+
  305
+   * `config/routes.rb`
  306
+   * `app/controllers/refuels_controller.rb`
  307
+   * `app/views/refuels/index.html.erb`
  308
+   * `app/views/refuels/new.html.erb`
  309
+   * `app/views/refuels/_form.html.erb`
  310
+   * `app/views/refuels/edit.html.erb`
  311
+   * `app/views/refuels/show.html.erb`
  312
+
  313
+4. Show information about the last refuel on the cars index.
  314
+
  315
+   Add a `scope` to keep logic in the model.  Also add some methods to
  316
+   format the MPG attribute and calculate a cost per mile.  Edit the
  317
+   following file:
  318
+
  319
+   * `app/models/refuel.rb`
  320
+
  321
+   Add some additional details to the cars index to show MPG and cost
  322
+   per mile for the most recent refuel.  Edit the following file:
  323
+
  324
+   * `app/views/cars/index.html.erb`
  325
+
  326
+5. Improve the look and feel by adding some CSS and HTML changes.
  327
+
  328
+   Edit the following files:
  329
+
  330
+   * `app/views/layouts/application.html.erb`
  331
+   * `app/assets/stylesheets/basic.css.scss`
  332
+   * `app/assets/stylesheets/forms.css.scss`
  333
+
  334
+6. Play with the application.
  335
+
  336
+   Start the rails server and open [http://localhost:3000/] [cars].
  337
+
  338
+[cars]: http://localhost:3000/cars
  339
+[xml]: http://localhost:3000/cars.xml
  340
+[json]: http://localhost:3000/cars.json
  341
+[04-create-refuels]: https://github.com/devalot/ror-example/commits/04-create-refuels
  342
+[da7d7de]: https://github.com/devalot/ror-example/commit/da7d7def6331d24a388802dbed0715dde737ef01
  343
+
  344
+## Some Things to Consider
  345
+
  346
+1. If you are creating a car or refuel record and omit a required
  347
+   field, the model validations will prevent the record from being
  348
+   saved to the database.  In prior versions of Rails a list of error
  349
+   messages would be shown above the form.
  350
+
  351
+   That feature was removed in Rails 3 in order to make it easier to
  352
+   translate your application into multiple languages.  This means
  353
+   that you must generate your own user error messages.
  354
+
  355
+   You can also install the [dynamic_form] plug-in to get these helper
  356
+   methods back into Rails 3 until you are ready to write them
  357
+   yourself.
  358
+
  359
+2. Instead of implementing your own session management and
  360
+   authentication logic you may want to look at one of these plug-ins
  361
+   for Rails:
  362
+
  363
+   * [Devise]
  364
+   * [Authlogic]
  365
+
  366
+[dynamic_form]: https://github.com/rails/dynamic_form
  367
+[devise]: https://github.com/plataformatec/devise
  368
+[authlogic]: https://github.com/binarylogic/authlogic
  369
+
  370
+## Exercises Left for the Reader
  371
+
  372
+1. If you edit an existing refuel object and change the odometer or
  373
+   gallons attributes, the refuel object directly following the one
  374
+   you edited will have wrong values for distance and mpg.  Update the
  375
+   refuel model to recalculate these values when this happens.  Start
  376
+   by writing a test that fails.  This will also happen if you delete
  377
+   a refuel.
  378
+
  379
+1. Write a `users` controller to allow a user to create an account.
  380
+
  381
+2. Write a `passwords` controller to allow a user to change their
  382
+   password.  How would a user reset their password if they forgot
  383
+   it?
  384
+
  385
+3. If a user enters the wrong password while logging in, set a
  386
+   `login_timeout` user attribute to `Time.now + 5.seconds` and don't
  387
+   let the user log in while `login_timeout` is in the future.  Each
  388
+   time the user tries to log in with the wrong password increase the
  389
+   number of seconds in the future the `login_timeout` is set for.
  390
+   Display the `login_timeout` in the login form so the user knows
  391
+   what's going on.  Tip: it may help to have a `failed_logins`
  392
+   counter in the users table.  Don't forget to reset it to 0 when the
  393
+   user successfully logs in.
  394
+
  395
+4. Explore using Ajax to create cars and refuels so the user doesn't
  396
+   have to bounce around the application for each activity.

0 notes on commit b107061

Please sign in to comment.
Something went wrong with that request. Please try again.