diff options
Diffstat (limited to 'guides')
122 files changed, 825 insertions, 1841 deletions
diff --git a/guides/assets/images/getting_started/forbidden_attributes_for_new_post.png b/guides/assets/images/getting_started/forbidden_attributes_for_new_post.png Binary files differnew file mode 100644 index 0000000000..500dfc2c02 --- /dev/null +++ b/guides/assets/images/getting_started/forbidden_attributes_for_new_post.png diff --git a/guides/assets/images/getting_started/routing_error_no_controller.png b/guides/assets/images/getting_started/routing_error_no_controller.png Binary files differindex 407ea2ea06..43ccd25252 100644 --- a/guides/assets/images/getting_started/routing_error_no_controller.png +++ b/guides/assets/images/getting_started/routing_error_no_controller.png diff --git a/guides/assets/images/getting_started/routing_error_no_route_matches.png b/guides/assets/images/getting_started/routing_error_no_route_matches.png Binary files differindex d461807c5d..1b8c0ea57e 100644 --- a/guides/assets/images/getting_started/routing_error_no_route_matches.png +++ b/guides/assets/images/getting_started/routing_error_no_route_matches.png diff --git a/guides/assets/images/getting_started/template_is_missing_posts_new.png b/guides/assets/images/getting_started/template_is_missing_posts_new.png Binary files differindex 6860aaeca7..75980432b2 100644 --- a/guides/assets/images/getting_started/template_is_missing_posts_new.png +++ b/guides/assets/images/getting_started/template_is_missing_posts_new.png diff --git a/guides/assets/images/getting_started/unknown_action_create_for_posts.png b/guides/assets/images/getting_started/unknown_action_create_for_posts.png Binary files differindex 1eca14b988..c6750e1ae1 100644 --- a/guides/assets/images/getting_started/unknown_action_create_for_posts.png +++ b/guides/assets/images/getting_started/unknown_action_create_for_posts.png diff --git a/guides/assets/images/getting_started/unknown_action_new_for_posts.png b/guides/assets/images/getting_started/unknown_action_new_for_posts.png Binary files differindex fd72586573..f4b3eff9dc 100644 --- a/guides/assets/images/getting_started/unknown_action_new_for_posts.png +++ b/guides/assets/images/getting_started/unknown_action_new_for_posts.png diff --git a/guides/assets/stylesheets/main.css b/guides/assets/stylesheets/main.css index 010f8ed228..dd029e6314 100644 --- a/guides/assets/stylesheets/main.css +++ b/guides/assets/stylesheets/main.css @@ -83,6 +83,10 @@ table th { padding: 0.5em 1em; } +img { + max-width: 100%; +} + /* Structure and Layout --------------------------------------- */ diff --git a/guides/code/getting_started/.gitignore b/guides/code/getting_started/.gitignore new file mode 100644 index 0000000000..25a742dff0 --- /dev/null +++ b/guides/code/getting_started/.gitignore @@ -0,0 +1,16 @@ +# See http://help.github.com/ignore-files/ for more about ignoring files. +# +# If you find yourself ignoring temporary files generated by your text editor +# or operating system, you probably want to add a global ignore instead: +# git config --global core.excludesfile '~/.gitignore_global' + +# Ignore bundler config. +/.bundle + +# Ignore the default SQLite database. +/db/*.sqlite3 +/db/*.sqlite3-journal + +# Ignore all logfiles and tempfiles. +/log/*.log +/tmp diff --git a/guides/code/getting_started/Gemfile b/guides/code/getting_started/Gemfile index 670a8523b0..b355c7d91a 100644 --- a/guides/code/getting_started/Gemfile +++ b/guides/code/getting_started/Gemfile @@ -1,38 +1,38 @@ source 'https://rubygems.org' -gem 'rails', '3.2.3' - -# Bundle edge Rails instead: -# gem 'rails', :git => 'git://github.com/rails/rails.git' +gem 'rails', '4.0.0' gem 'sqlite3' - # Gems used only for assets and not required # in production environments by default. group :assets do - gem 'sass-rails', '~> 3.2.3' - gem 'coffee-rails', '~> 3.2.1' + gem 'sprockets-rails' + gem 'sass-rails' + gem 'coffee-rails' # See https://github.com/sstephenson/execjs#readme for more supported runtimes - # gem 'therubyracer', :platform => :ruby + # gem 'therubyracer', platforms: :ruby gem 'uglifier', '>= 1.0.3' end gem 'jquery-rails' +# Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks +gem 'turbolinks' + +# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder +gem 'jbuilder', '~> 1.0.1' + # To use ActiveModel has_secure_password # gem 'bcrypt-ruby', '~> 3.0.0' -# To use Jbuilder templates for JSON -# gem 'jbuilder' - # Use unicorn as the app server # gem 'unicorn' # Deploy with Capistrano -# gem 'capistrano' +# gem 'capistrano', group: :development # To use debugger # gem 'debugger' diff --git a/guides/code/getting_started/Gemfile.lock b/guides/code/getting_started/Gemfile.lock new file mode 100644 index 0000000000..823fac5ff7 --- /dev/null +++ b/guides/code/getting_started/Gemfile.lock @@ -0,0 +1,150 @@ +GIT + remote: git://github.com/rails/activerecord-deprecated_finders.git + revision: 2e7b35d7948cefb2bba96438873d7f7bb1961a03 + specs: + activerecord-deprecated_finders (0.0.2) + +GIT + remote: git://github.com/rails/arel.git + revision: 38d0a222e275d917a2c1d093b24457bafb600a00 + specs: + arel (3.0.2.20120819075748) + +GIT + remote: git://github.com/rails/coffee-rails.git + revision: 052634e6d02d4800d7b021201cc8d5829775b3cd + specs: + coffee-rails (4.0.0.beta) + coffee-script (>= 2.2.0) + railties (>= 4.0.0.beta, < 5.0) + +GIT + remote: git://github.com/rails/sass-rails.git + revision: ae8138a89cac397c0df903dd533e2862902ce8f5 + specs: + sass-rails (4.0.0.beta) + railties (>= 4.0.0.beta, < 5.0) + sass (>= 3.1.10) + sprockets-rails (~> 2.0.0.rc0) + tilt (~> 1.3) + +GIT + remote: git://github.com/rails/sprockets-rails.git + revision: 09917104fdb42245fe369612a7b0e3d77e1ba763 + specs: + sprockets-rails (2.0.0.rc1) + actionpack (>= 3.0) + activesupport (>= 3.0) + sprockets (~> 2.8) + +PATH + remote: /Users/steve/src/rails + specs: + actionmailer (4.0.0.beta) + actionpack (= 4.0.0.beta) + mail (~> 2.5.3) + actionpack (4.0.0.beta) + activesupport (= 4.0.0.beta) + builder (~> 3.1.0) + erubis (~> 2.7.0) + rack (~> 1.4.3) + rack-test (~> 0.6.1) + activemodel (4.0.0.beta) + activesupport (= 4.0.0.beta) + builder (~> 3.1.0) + activerecord (4.0.0.beta) + activemodel (= 4.0.0.beta) + activerecord-deprecated_finders (= 0.0.2) + activesupport (= 4.0.0.beta) + arel (~> 3.0.2) + activesupport (4.0.0.beta) + i18n (~> 0.6) + minitest (~> 4.1) + multi_json (~> 1.3) + thread_safe (~> 0.1) + tzinfo (~> 0.3.33) + rails (4.0.0.beta) + actionmailer (= 4.0.0.beta) + actionpack (= 4.0.0.beta) + activerecord (= 4.0.0.beta) + activesupport (= 4.0.0.beta) + bundler (>= 1.2.2, < 2.0) + railties (= 4.0.0.beta) + sprockets-rails (~> 2.0.0.rc1) + railties (4.0.0.beta) + actionpack (= 4.0.0.beta) + activesupport (= 4.0.0.beta) + rake (>= 0.8.7) + rdoc (~> 3.4) + thor (>= 0.15.4, < 2.0) + +GEM + remote: https://rubygems.org/ + specs: + atomic (1.0.1) + builder (3.1.4) + coffee-script (2.2.0) + coffee-script-source + execjs + coffee-script-source (1.4.0) + erubis (2.7.0) + execjs (1.4.0) + multi_json (~> 1.0) + hike (1.2.1) + i18n (0.6.1) + jbuilder (1.0.2) + activesupport (>= 3.0.0) + jquery-rails (2.2.0) + railties (>= 3.0, < 5.0) + thor (>= 0.14, < 2.0) + json (1.7.6) + mail (2.5.3) + i18n (>= 0.4.0) + mime-types (~> 1.16) + treetop (~> 1.4.8) + mime-types (1.19) + minitest (4.4.0) + multi_json (1.5.0) + polyglot (0.3.3) + rack (1.4.4) + rack-test (0.6.2) + rack (>= 1.0) + rake (10.0.3) + rdoc (3.12) + json (~> 1.4) + sass (3.2.5) + sprockets (2.8.2) + hike (~> 1.2) + multi_json (~> 1.0) + rack (~> 1.0) + tilt (~> 1.1, != 1.3.0) + sqlite3 (1.3.7) + thor (0.16.0) + thread_safe (0.1.0) + atomic + tilt (1.3.3) + treetop (1.4.12) + polyglot + polyglot (>= 0.3.1) + turbolinks (1.0.0) + coffee-rails + tzinfo (0.3.35) + uglifier (1.3.0) + execjs (>= 0.3.0) + multi_json (~> 1.0, >= 1.0.2) + +PLATFORMS + ruby + +DEPENDENCIES + activerecord-deprecated_finders! + arel! + coffee-rails! + jbuilder (~> 1.0.1) + jquery-rails + rails! + sass-rails! + sprockets-rails! + sqlite3 + turbolinks + uglifier (>= 1.0.3) diff --git a/guides/code/getting_started/README.rdoc b/guides/code/getting_started/README.rdoc index b5d7b6436b..dd4e97e22e 100644 --- a/guides/code/getting_started/README.rdoc +++ b/guides/code/getting_started/README.rdoc @@ -1,259 +1,28 @@ -== Welcome to Rails +== README -Rails is a web-application framework that includes everything needed to create -database-backed web applications according to the Model-View-Control pattern. +This README would normally document whatever steps are necessary to get the +application up and running. -This pattern splits the view (also called the presentation) into "dumb" -templates that are primarily responsible for inserting pre-built data in between -HTML tags. The model contains the "smart" domain objects (such as Account, -Product, Person, Post) that holds all the business logic and knows how to -persist themselves to a database. The controller handles the incoming requests -(such as Save New Account, Update Product, Show Post) by manipulating the model -and directing data to the view. +Things you may want to cover: -In Rails, the model is handled by what's called an object-relational mapping -layer entitled Active Record. This layer allows you to present the data from -database rows as objects and embellish these data objects with business logic -methods. You can read more about Active Record in -link:files/vendor/rails/activerecord/README.html. +* Ruby version -The controller and view are handled by the Action Pack, which handles both -layers by its two parts: Action View and Action Controller. These two layers -are bundled in a single package due to their heavy interdependence. This is -unlike the relationship between the Active Record and Action Pack that is much -more separate. Each of these packages can be used independently outside of -Rails. You can read more about Action Pack in -link:files/vendor/rails/actionpack/README.html. +* System dependencies +* Configuration -== Getting Started +* Database creation -1. At the command prompt, create a new Rails application: - <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name) +* Database initialization -2. Change directory to <tt>myapp</tt> and start the web server: - <tt>cd myapp; rails server</tt> (run with --help for options) +* How to run the test suite -3. Go to http://localhost:3000/ and you'll see: - "Welcome aboard: You're riding Ruby on Rails!" +* Services (job queues, cache servers, search engines, etc.) -4. Follow the guidelines to start developing your application. You can find -the following resources handy: +* Deployment instructions -* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html -* Ruby on Rails Tutorial Book: http://www.railstutorial.org/ +* ... -== Debugging Rails - -Sometimes your application goes wrong. Fortunately there are a lot of tools that -will help you debug it and get it back on the rails. - -First area to check is the application log files. Have "tail -f" commands -running on the server.log and development.log. Rails will automatically display -debugging and runtime information to these files. Debugging info will also be -shown in the browser on requests from 127.0.0.1. - -You can also log your own messages directly into the log file from your code -using the Ruby logger class from inside your controllers. Example: - - class WeblogController < ActionController::Base - def destroy - @weblog = Weblog.find(params[:id]) - @weblog.destroy - logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!") - end - end - -The result will be a message in your log file along the lines of: - - Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1! - -More information on how to use the logger is at http://www.ruby-doc.org/core/ - -Also, Ruby documentation can be found at http://www.ruby-lang.org/. There are -several books available online as well: - -* Programming Ruby: http://www.ruby-doc.org/docs/ProgrammingRuby/ (Pickaxe) -* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide) - -These two books will bring you up to speed on the Ruby language and also on -programming in general. - - -== Debugger - -Debugger support is available through the debugger command when you start your -Mongrel or WEBrick server with --debugger. This means that you can break out of -execution at any point in the code, investigate and change the model, and then, -resume execution! You need to install the 'debugger' gem to run the server in debugging -mode. Add gem 'debugger' to your Gemfile and run <tt>bundle</tt> to install it. Example: - - class WeblogController < ActionController::Base - def index - @posts = Post.all - debugger - end - end - -So the controller will accept the action, run the first line, then present you -with a IRB prompt in the server window. Here you can do things like: - - >> @posts.inspect - => "[#<Post:0x14a6be8 - @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>, - #<Post:0x14a6620 - @attributes={"title"=>"Rails", "body"=>"Only ten..", "id"=>"2"}>]" - >> @posts.first.title = "hello from a debugger" - => "hello from a debugger" - -...and even better, you can examine how your runtime objects actually work: - - >> f = @posts.first - => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}> - >> f. - Display all 152 possibilities? (y or n) - -Finally, when you're ready to resume execution, you can enter "cont". - - -== Console - -The console is a Ruby shell, which allows you to interact with your -application's domain model. Here you'll have all parts of the application -configured, just like it is when the application is running. You can inspect -domain models, change values, and save to the database. Starting the script -without arguments will launch it in the development environment. - -To start the console, run <tt>rails console</tt> from the application -directory. - -Options: - -* Passing the <tt>-s, --sandbox</tt> argument will rollback any modifications - made to the database. -* Passing an environment name as an argument will load the corresponding - environment. Example: <tt>rails console production</tt>. - -To reload your controllers and models after launching the console run -<tt>reload!</tt> - -More information about irb can be found at: -link:http://www.rubycentral.org/pickaxe/irb.html - - -== dbconsole - -You can go to the command line of your database directly through <tt>rails -dbconsole</tt>. You would be connected to the database with the credentials -defined in database.yml. Starting the script without arguments will connect you -to the development database. Passing an argument will connect you to a different -database, like <tt>rails dbconsole production</tt>. Currently works for MySQL, -PostgreSQL and SQLite 3. - -== Description of Contents - -The default directory structure of a generated Ruby on Rails application: - - |-- app - | |-- assets - | |-- images - | |-- javascripts - | `-- stylesheets - | |-- controllers - | |-- helpers - | |-- mailers - | |-- models - | `-- views - | `-- layouts - |-- config - | |-- environments - | |-- initializers - | `-- locales - |-- db - |-- doc - |-- lib - | `-- tasks - |-- log - |-- public - |-- script - |-- test - | |-- fixtures - | |-- functional - | |-- integration - | |-- performance - | `-- unit - |-- tmp - | |-- cache - | |-- pids - | |-- sessions - | `-- sockets - `-- vendor - |-- assets - `-- stylesheets - -app - Holds all the code that's specific to this particular application. - -app/assets - Contains subdirectories for images, stylesheets, and JavaScript files. - -app/controllers - Holds controllers that should be named like weblogs_controller.rb for - automated URL mapping. All controllers should descend from - ApplicationController which itself descends from ActionController::Base. - -app/models - Holds models that should be named like post.rb. Models descend from - ActiveRecord::Base by default. - -app/views - Holds the template files for the view that should be named like - weblogs/index.html.erb for the WeblogsController#index action. All views use - eRuby syntax by default. - -app/views/layouts - Holds the template files for layouts to be used with views. This models the - common header/footer method of wrapping views. In your views, define a layout - using the <tt>layout :default</tt> and create a file named default.html.erb. - Inside default.html.erb, call <% yield %> to render the view using this - layout. - -app/helpers - Holds view helpers that should be named like weblogs_helper.rb. These are - generated for you automatically when using generators for controllers. - Helpers can be used to wrap functionality for your views into methods. - -config - Configuration files for the Rails environment, the routing map, the database, - and other dependencies. - -db - Contains the database schema in schema.rb. db/migrate contains all the - sequence of Migrations for your schema. - -doc - This directory is where your application documentation will be stored when - generated using <tt>rake doc:app</tt> - -lib - Application specific libraries. Basically, any kind of custom code that - doesn't belong under controllers, models, or helpers. This directory is in - the load path. - -public - The directory available for the web server. Also contains the dispatchers and the - default HTML files. This should be set as the DOCUMENT_ROOT of your web - server. - -script - Helper scripts for automation and generation. - -test - Unit and functional tests along with fixtures. When using the rails generate - command, template test files will be generated for you and placed in this - directory. - -vendor - External libraries that the application depends on. If the app has frozen rails, - those gems also go here, under vendor/rails/. This directory is in the load path. +Please feel free to use a different markup language if you do not plan to run +<tt>rake doc:app</tt>. diff --git a/guides/code/getting_started/Rakefile b/guides/code/getting_started/Rakefile index e1d1ec8615..05de8bb536 100644 --- a/guides/code/getting_started/Rakefile +++ b/guides/code/getting_started/Rakefile @@ -1,4 +1,3 @@ -#!/usr/bin/env rake # Add your own tasks in files placed in lib/tasks ending in .rake, # for example lib/tasks/capistrano.rake, and they will automatically be available to Rake. diff --git a/guides/code/getting_started/app/assets/javascripts/application.js b/guides/code/getting_started/app/assets/javascripts/application.js index 93cdae76ca..9e83eb5e7e 100644 --- a/guides/code/getting_started/app/assets/javascripts/application.js +++ b/guides/code/getting_started/app/assets/javascripts/application.js @@ -12,4 +12,5 @@ // //= require jquery //= require jquery_ujs +//= require turbolinks //= require_tree . diff --git a/guides/code/getting_started/app/assets/javascripts/comments.js.coffee b/guides/code/getting_started/app/assets/javascripts/comments.js.coffee new file mode 100644 index 0000000000..24f83d18bb --- /dev/null +++ b/guides/code/getting_started/app/assets/javascripts/comments.js.coffee @@ -0,0 +1,3 @@ +# Place all the behaviors and hooks related to the matching controller here. +# All this logic will automatically be available in application.js. +# You can use CoffeeScript in this file: http://coffeescript.org/ diff --git a/guides/code/getting_started/app/assets/javascripts/posts.js.coffee b/guides/code/getting_started/app/assets/javascripts/posts.js.coffee new file mode 100644 index 0000000000..24f83d18bb --- /dev/null +++ b/guides/code/getting_started/app/assets/javascripts/posts.js.coffee @@ -0,0 +1,3 @@ +# Place all the behaviors and hooks related to the matching controller here. +# All this logic will automatically be available in application.js. +# You can use CoffeeScript in this file: http://coffeescript.org/ diff --git a/guides/code/getting_started/app/assets/javascripts/welcome.js.coffee b/guides/code/getting_started/app/assets/javascripts/welcome.js.coffee new file mode 100644 index 0000000000..24f83d18bb --- /dev/null +++ b/guides/code/getting_started/app/assets/javascripts/welcome.js.coffee @@ -0,0 +1,3 @@ +# Place all the behaviors and hooks related to the matching controller here. +# All this logic will automatically be available in application.js. +# You can use CoffeeScript in this file: http://coffeescript.org/ diff --git a/guides/code/getting_started/app/assets/stylesheets/application.css b/guides/code/getting_started/app/assets/stylesheets/application.css index 3b5cc6648e..3192ec897b 100644 --- a/guides/code/getting_started/app/assets/stylesheets/application.css +++ b/guides/code/getting_started/app/assets/stylesheets/application.css @@ -10,4 +10,4 @@ * *= require_self *= require_tree . -*/ + */ diff --git a/guides/code/getting_started/app/assets/stylesheets/comments.css.scss b/guides/code/getting_started/app/assets/stylesheets/comments.css.scss new file mode 100644 index 0000000000..e730912783 --- /dev/null +++ b/guides/code/getting_started/app/assets/stylesheets/comments.css.scss @@ -0,0 +1,3 @@ +// Place all the styles related to the Comments controller here. +// They will automatically be included in application.css. +// You can use Sass (SCSS) here: http://sass-lang.com/ diff --git a/guides/code/getting_started/app/assets/stylesheets/posts.css.scss b/guides/code/getting_started/app/assets/stylesheets/posts.css.scss new file mode 100644 index 0000000000..1a7e15390c --- /dev/null +++ b/guides/code/getting_started/app/assets/stylesheets/posts.css.scss @@ -0,0 +1,3 @@ +// Place all the styles related to the posts controller here. +// They will automatically be included in application.css. +// You can use Sass (SCSS) here: http://sass-lang.com/ diff --git a/guides/code/getting_started/app/assets/stylesheets/welcome.css.scss b/guides/code/getting_started/app/assets/stylesheets/welcome.css.scss new file mode 100644 index 0000000000..77ce11a740 --- /dev/null +++ b/guides/code/getting_started/app/assets/stylesheets/welcome.css.scss @@ -0,0 +1,3 @@ +// Place all the styles related to the welcome controller here. +// They will automatically be included in application.css. +// You can use Sass (SCSS) here: http://sass-lang.com/ diff --git a/guides/code/getting_started/app/controllers/application_controller.rb b/guides/code/getting_started/app/controllers/application_controller.rb index e8065d9505..d83690e1b9 100644 --- a/guides/code/getting_started/app/controllers/application_controller.rb +++ b/guides/code/getting_started/app/controllers/application_controller.rb @@ -1,3 +1,5 @@ class ApplicationController < ActionController::Base - protect_from_forgery + # Prevent CSRF attacks by raising an exception. + # For APIs, you may want to use :null_session instead. + protect_from_forgery with: :exception end diff --git a/guides/code/getting_started/app/controllers/comments_controller.rb b/guides/code/getting_started/app/controllers/comments_controller.rb index cf3d1be42e..0082e9c8ec 100644 --- a/guides/code/getting_started/app/controllers/comments_controller.rb +++ b/guides/code/getting_started/app/controllers/comments_controller.rb @@ -1,9 +1,10 @@ class CommentsController < ApplicationController - http_basic_authenticate_with :name => "dhh", :password => "secret", :only => :destroy + http_basic_authenticate_with name: "dhh", password: "secret", only: :destroy + def create @post = Post.find(params[:post_id]) - @comment = @post.comments.create(params[:comment]) + @comment = @post.comments.create(params[:comment].permit(:commenter, :body)) redirect_to post_path(@post) end @@ -13,5 +14,4 @@ class CommentsController < ApplicationController @comment.destroy redirect_to post_path(@post) end - end diff --git a/guides/code/getting_started/app/mailers/.gitkeep b/guides/code/getting_started/app/controllers/concerns/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/app/mailers/.gitkeep +++ b/guides/code/getting_started/app/controllers/concerns/.keep diff --git a/guides/code/getting_started/app/controllers/posts_controller.rb b/guides/code/getting_started/app/controllers/posts_controller.rb index b74c66ef13..0398395200 100644 --- a/guides/code/getting_started/app/controllers/posts_controller.rb +++ b/guides/code/getting_started/app/controllers/posts_controller.rb @@ -1,7 +1,7 @@ class PostsController < ApplicationController - http_basic_authenticate_with :name => "dhh", :password => "secret", :except => [:index, :show] - + http_basic_authenticate_with name: "dhh", password: "secret", except: [:index, :show] + def index @posts = Post.all end @@ -10,31 +10,31 @@ class PostsController < ApplicationController @post = Post.find(params[:id]) end - def new - @post = Post.new + def edit + @post = Post.find(params[:id]) end - def create - @post = Post.new(params[:post]) + def update + @post = Post.find(params[:id]) - if @post.save - redirect_to :action => :show, :id => @post.id + if @post.update(params[:post].permit(:title, :text)) + redirect_to action: :show, id: @post.id else - render 'new' + render 'edit' end end - def edit - @post = Post.find(params[:id]) + def new + @post = Post.new end - def update - @post = Post.find(params[:id]) + def create + @post = Post.new(params[:post].permit(:title, :text)) - if @post.update(params[:post]) - redirect_to :action => :show, :id => @post.id + if @post.save + redirect_to action: :show, id: @post.id else - render 'edit' + render 'new' end end @@ -42,6 +42,6 @@ class PostsController < ApplicationController @post = Post.find(params[:id]) @post.destroy - redirect_to :action => :index + redirect_to action: :index end end diff --git a/guides/code/getting_started/app/models/.gitkeep b/guides/code/getting_started/app/mailers/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/app/models/.gitkeep +++ b/guides/code/getting_started/app/mailers/.keep diff --git a/guides/code/getting_started/lib/assets/.gitkeep b/guides/code/getting_started/app/models/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/lib/assets/.gitkeep +++ b/guides/code/getting_started/app/models/.keep diff --git a/guides/code/getting_started/lib/tasks/.gitkeep b/guides/code/getting_started/app/models/concerns/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/lib/tasks/.gitkeep +++ b/guides/code/getting_started/app/models/concerns/.keep diff --git a/guides/code/getting_started/app/models/post.rb b/guides/code/getting_started/app/models/post.rb index 21387340b0..64e0d721fd 100644 --- a/guides/code/getting_started/app/models/post.rb +++ b/guides/code/getting_started/app/models/post.rb @@ -1,6 +1,7 @@ class Post < ActiveRecord::Base - validates :title, :presence => true, - :length => { :minimum => 5 } - - has_many :comments, :dependent => :destroy + has_many :comments, dependent: :destroy + + validates :title, + presence: true, + length: { minimum: 5 } end diff --git a/guides/code/getting_started/app/views/comments/_comment.html.erb b/guides/code/getting_started/app/views/comments/_comment.html.erb index 3d2bc1590e..593493339e 100644 --- a/guides/code/getting_started/app/views/comments/_comment.html.erb +++ b/guides/code/getting_started/app/views/comments/_comment.html.erb @@ -2,7 +2,7 @@ <strong>Commenter:</strong> <%= comment.commenter %> </p> - + <p> <strong>Comment:</strong> <%= comment.body %> @@ -10,6 +10,6 @@ <p> <%= link_to 'Destroy Comment', [comment.post, comment], - :method => :delete, - :data => { :confirm => 'Are you sure?' } %> + method: :delete, + data: { confirm: 'Are you sure?' } %> </p> diff --git a/guides/code/getting_started/app/views/layouts/application.html.erb b/guides/code/getting_started/app/views/layouts/application.html.erb index 6578a41da2..95368c37a3 100644 --- a/guides/code/getting_started/app/views/layouts/application.html.erb +++ b/guides/code/getting_started/app/views/layouts/application.html.erb @@ -2,8 +2,8 @@ <html> <head> <title>Blog</title> - <%= stylesheet_link_tag "application", :media => "all" %> - <%= javascript_include_tag "application" %> + <%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" => true %> + <%= javascript_include_tag "application", "data-turbolinks-track" => true %> <%= csrf_meta_tags %> </head> <body> diff --git a/guides/code/getting_started/app/views/posts/_form.html.erb b/guides/code/getting_started/app/views/posts/_form.html.erb index f22139938c..c9fb74af9c 100644 --- a/guides/code/getting_started/app/views/posts/_form.html.erb +++ b/guides/code/getting_started/app/views/posts/_form.html.erb @@ -1,25 +1,27 @@ <%= form_for @post do |f| %> <% if @post.errors.any? %> - <div id="errorExplanation"> - <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2> - <ul> - <% @post.errors.full_messages.each do |msg| %> - <li><%= msg %></li> - <% end %> - </ul> - </div> + <div id="errorExplanation"> + <h2><%= pluralize(@post.errors.count, "error") %> prohibited + this post from being saved:</h2> + <ul> + <% @post.errors.full_messages.each do |msg| %> + <li><%= msg %></li> + <% end %> + </ul> + </div> <% end %> <p> - <%= f.label :title %><br /> + <%= f.label :title %><br> <%= f.text_field :title %> </p> - + <p> - <%= f.label :text %><br /> + <%= f.label :text %><br> <%= f.text_area :text %> </p> - + <p> <%= f.submit %> </p> <% end %> + diff --git a/guides/code/getting_started/app/views/posts/edit.html.erb b/guides/code/getting_started/app/views/posts/edit.html.erb index 911a48569d..393e7430d0 100644 --- a/guides/code/getting_started/app/views/posts/edit.html.erb +++ b/guides/code/getting_started/app/views/posts/edit.html.erb @@ -1,5 +1,5 @@ -<h1>Editing post</h1> - +<h1>Edit post</h1> + <%= render 'form' %> - -<%= link_to 'Back', :action => :index %> + +<%= link_to 'Back', action: :index %> diff --git a/guides/code/getting_started/app/views/posts/index.html.erb b/guides/code/getting_started/app/views/posts/index.html.erb index 9a0e90eadc..7369f0396f 100644 --- a/guides/code/getting_started/app/views/posts/index.html.erb +++ b/guides/code/getting_started/app/views/posts/index.html.erb @@ -1,7 +1,4 @@ -<h1>Listing posts</h1> - -<%= link_to 'New post', :action => :new %> - +<h1>Listing Posts</h1> <table> <tr> <th>Title</th> @@ -10,14 +7,15 @@ <th></th> <th></th> </tr> - + <% @posts.each do |post| %> <tr> <td><%= post.title %></td> <td><%= post.text %></td> - <td><%= link_to 'Show', :action => :show, :id => post.id %> - <td><%= link_to 'Edit', :action => :edit, :id => post.id %> - <td><%= link_to 'Destroy', { :action => :destroy, :id => post.id }, :method => :delete, :data => { :confirm => 'Are you sure?' } %> + <td><%= link_to 'Show', action: :show, id: post.id %></td> + <td><%= link_to 'Edit', action: :edit, id: post.id %></td> + <td><%= link_to 'Destroy', { action: :destroy, id: post.id }, + method: :delete, data: { confirm: 'Are you sure?' } %></td> </tr> <% end %> </table> diff --git a/guides/code/getting_started/app/views/posts/new.html.erb b/guides/code/getting_started/app/views/posts/new.html.erb index ce9523a721..efa81038ec 100644 --- a/guides/code/getting_started/app/views/posts/new.html.erb +++ b/guides/code/getting_started/app/views/posts/new.html.erb @@ -1,5 +1,5 @@ <h1>New post</h1> - + <%= render 'form' %> - -<%= link_to 'Back', :action => :index %> + +<%= link_to 'Back', action: :index %> diff --git a/guides/code/getting_started/app/views/posts/show.html.erb b/guides/code/getting_started/app/views/posts/show.html.erb index 65809033ed..e99e9edbb3 100644 --- a/guides/code/getting_started/app/views/posts/show.html.erb +++ b/guides/code/getting_started/app/views/posts/show.html.erb @@ -2,7 +2,7 @@ <strong>Title:</strong> <%= @post.title %> </p> - + <p> <strong>Text:</strong> <%= @post.text %> @@ -10,9 +10,9 @@ <h2>Comments</h2> <%= render @post.comments %> - + <h2>Add a comment:</h2> <%= render "comments/form" %> - + <%= link_to 'Edit Post', edit_post_path(@post) %> | <%= link_to 'Back to Posts', posts_path %> diff --git a/guides/code/getting_started/app/views/welcome/index.html.erb b/guides/code/getting_started/app/views/welcome/index.html.erb index e04680ea7e..738e12d7dc 100644 --- a/guides/code/getting_started/app/views/welcome/index.html.erb +++ b/guides/code/getting_started/app/views/welcome/index.html.erb @@ -1,2 +1,3 @@ <h1>Hello, Rails!</h1> -<%= link_to "My Blog", :controller => "posts" %> + +<%= link_to "My Blog", controller: "posts" %> diff --git a/guides/code/getting_started/bin/bundle b/guides/code/getting_started/bin/bundle new file mode 100755 index 0000000000..45cf37fba4 --- /dev/null +++ b/guides/code/getting_started/bin/bundle @@ -0,0 +1,4 @@ +#!/usr/bin/env ruby +ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__) +require 'rubygems' +load Gem.bin_path('bundler', 'bundle') diff --git a/guides/code/getting_started/bin/rails b/guides/code/getting_started/bin/rails new file mode 100755 index 0000000000..728cd85aa5 --- /dev/null +++ b/guides/code/getting_started/bin/rails @@ -0,0 +1,4 @@ +#!/usr/bin/env ruby +APP_PATH = File.expand_path('../../config/application', __FILE__) +require_relative '../config/boot' +require 'rails/commands' diff --git a/guides/code/getting_started/bin/rake b/guides/code/getting_started/bin/rake new file mode 100755 index 0000000000..17240489f6 --- /dev/null +++ b/guides/code/getting_started/bin/rake @@ -0,0 +1,4 @@ +#!/usr/bin/env ruby +require_relative '../config/boot' +require 'rake' +Rake.application.run diff --git a/guides/code/getting_started/config/application.rb b/guides/code/getting_started/config/application.rb index d53c9fd8bc..526a782b5c 100644 --- a/guides/code/getting_started/config/application.rb +++ b/guides/code/getting_started/config/application.rb @@ -2,12 +2,8 @@ require File.expand_path('../boot', __FILE__) require 'rails/all' -if defined?(Bundler) - # If you precompile assets before deploying to production, use this line - Bundler.require(*Rails.groups(:assets => %w(development test))) - # If you want your assets lazily compiled in production, use this line - # Bundler.require(:default, :assets, Rails.env) -end +# Assets should be precompiled for production (so we don't need the gems loaded then) +Bundler.require(*Rails.groups(assets: %w(development test))) module Blog class Application < Rails::Application @@ -17,36 +13,5 @@ module Blog # Custom directories with classes and modules you want to be autoloadable. # config.autoload_paths += %W(#{config.root}/extras) - - # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone. - # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC. - # config.time_zone = 'Central Time (US & Canada)' - - # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded. - # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s] - # config.i18n.default_locale = :de - - # Configure the default encoding used in templates for Ruby 1.9. - config.encoding = "utf-8" - - # Configure sensitive parameters which will be filtered from the log file. - config.filter_parameters += [:password] - - # Use SQL instead of Active Record's schema dumper when creating the database. - # This is necessary if your schema can't be completely dumped by the schema dumper, - # like if you have constraints or database-specific column types. - # config.active_record.schema_format = :sql - - # Enforce whitelist mode for mass assignment. - # This will create an empty whitelist of attributes available for mass-assignment for all models - # in your app. As such, your models will need to explicitly whitelist or blacklist accessible - # parameters by using an attr_accessible or attr_protected declaration. - # config.active_record.whitelist_attributes = true - - # Enable the asset pipeline. - config.assets.enabled = true - - # Version of your assets, change this if you want to expire all your assets. - config.assets.version = '1.0' end end diff --git a/guides/code/getting_started/config/environment.rb b/guides/code/getting_started/config/environment.rb index 8f728b7ce7..2d65111004 100644 --- a/guides/code/getting_started/config/environment.rb +++ b/guides/code/getting_started/config/environment.rb @@ -1,5 +1,5 @@ -# Load the rails application +# Load the rails application. require File.expand_path('../application', __FILE__) -# Initialize the rails application +# Initialize the rails application. Blog::Application.initialize! diff --git a/guides/code/getting_started/config/environments/development.rb b/guides/code/getting_started/config/environments/development.rb index cec2b20c0b..d169e9452c 100644 --- a/guides/code/getting_started/config/environments/development.rb +++ b/guides/code/getting_started/config/environments/development.rb @@ -2,10 +2,13 @@ Blog::Application.configure do # Settings specified here will take precedence over those in config/application.rb. # In the development environment your application's code is reloaded on - # every request. This slows down response time but is perfect for development + # every request. This slows down response time but is perfect for development # since you don't have to restart the web server when you make code changes. config.cache_classes = false + # Do not eager load code on boot. + config.eager_load = false + # Show full error reports and disable caching. config.consider_all_requests_local = true config.action_controller.perform_caching = false @@ -19,16 +22,9 @@ Blog::Application.configure do # Only use best-standards-support built into browsers. config.action_dispatch.best_standards_support = :builtin - # Raise exception on mass assignment protection for ActiveRecord models. - config.active_record.mass_assignment_sanitizer = :strict - - # Log the query plan for queries taking more than this (works - # with SQLite, MySQL, and PostgreSQL). - config.active_record.auto_explain_threshold_in_seconds = 0.5 - - # Do not compress assets. - config.assets.compress = false + # Raise an error on page load if there are pending migrations + config.active_record.migration_error = :page_load - # Expands the lines which load the assets. + # Debug mode disables concatenation and preprocessing of assets. config.assets.debug = true end diff --git a/guides/code/getting_started/config/environments/production.rb b/guides/code/getting_started/config/environments/production.rb index ecc35b030b..368a735122 100644 --- a/guides/code/getting_started/config/environments/production.rb +++ b/guides/code/getting_started/config/environments/production.rb @@ -4,24 +4,36 @@ Blog::Application.configure do # Code is not reloaded between requests. config.cache_classes = true + # Eager load code on boot. This eager loads most of Rails and + # your application in memory, allowing both thread web servers + # and those relying on copy on write to perform better. + # Rake tasks automatically ignore this option for performance. + config.eager_load = true + # Full error reports are disabled and caching is turned on. config.consider_all_requests_local = false config.action_controller.perform_caching = true + # Enable Rack::Cache to put a simple HTTP cache in front of your application + # Add `rack-cache` to your Gemfile before enabling this. + # For large-scale production use, consider using a caching reverse proxy like nginx, varnish or squid. + # config.action_dispatch.rack_cache = true + # Disable Rails's static asset server (Apache or nginx will already do this). config.serve_static_assets = false # Compress JavaScripts and CSS. - config.assets.compress = true + config.assets.js_compressor = :uglifier + # config.assets.css_compressor = :sass - # Don't fallback to assets pipeline if a precompiled asset is missed. + # Whether to fallback to assets pipeline if a precompiled asset is missed. config.assets.compile = false # Generate digests for assets URLs. config.assets.digest = true - # Defaults to nil - # config.assets.manifest = YOUR_PATH + # Version of your assets, change this if you want to expire all your assets. + config.assets.version = '1.0' # Specifies the header that your server uses for sending files. # config.action_dispatch.x_sendfile_header = "X-Sendfile" # for apache @@ -30,8 +42,8 @@ Blog::Application.configure do # Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies. # config.force_ssl = true - # See everything in the log (default is :info). - # config.log_level = :debug + # Set to :debug to see everything in the log. + config.log_level = :info # Prepend all log lines with the following tags. # config.log_tags = [ :subdomain, :uuid ] @@ -45,15 +57,14 @@ Blog::Application.configure do # Enable serving of images, stylesheets, and JavaScripts from an asset server. # config.action_controller.asset_host = "http://assets.example.com" - # Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added). + # Precompile additional assets. + # application.js, application.css, and all non-JS/CSS in app/assets folder are already added. # config.assets.precompile += %w( search.js ) - # Disable delivery errors, bad email addresses will be ignored. + # Ignore bad email addresses and do not raise email delivery errors. + # Set this to true and configure the email server for immediate delivery to raise delivery errors. # config.action_mailer.raise_delivery_errors = false - # Enable threaded mode. - # config.threadsafe! - # Enable locale fallbacks for I18n (makes lookups for any locale fall back to # the I18n.default_locale when a translation can not be found). config.i18n.fallbacks = true @@ -61,7 +72,9 @@ Blog::Application.configure do # Send deprecation notices to registered listeners. config.active_support.deprecation = :notify - # Log the query plan for queries taking more than this (works - # with SQLite, MySQL, and PostgreSQL). - # config.active_record.auto_explain_threshold_in_seconds = 0.5 + # Disable automatic flushing of the log to improve performance. + # config.autoflush_log = false + + # Use default logging formatter so that PID and timestamp are not suppressed. + config.log_formatter = ::Logger::Formatter.new end diff --git a/guides/code/getting_started/config/environments/test.rb b/guides/code/getting_started/config/environments/test.rb index f2bc932fb3..00adaa5015 100644 --- a/guides/code/getting_started/config/environments/test.rb +++ b/guides/code/getting_started/config/environments/test.rb @@ -2,11 +2,16 @@ Blog::Application.configure do # Settings specified here will take precedence over those in config/application.rb. # The test environment is used exclusively to run your application's - # test suite. You never need to work with it otherwise. Remember that + # test suite. You never need to work with it otherwise. Remember that # your test database is "scratch space" for the test suite and is wiped - # and recreated between test runs. Don't rely on the data there! + # and recreated between test runs. Don't rely on the data there! config.cache_classes = true + # Do not eager load code on boot. This avoids loading your whole application + # just for the purpose of running a single test. If you are using a tool that + # preloads Rails for running tests, you may have to set it to true. + config.eager_load = false + # Configure static asset server for tests with Cache-Control for performance. config.serve_static_assets = true config.static_cache_control = "public, max-age=3600" @@ -26,9 +31,6 @@ Blog::Application.configure do # ActionMailer::Base.deliveries array. config.action_mailer.delivery_method = :test - # Raise exception on mass assignment protection for Active Record models. - config.active_record.mass_assignment_sanitizer = :strict - # Print deprecation notices to the stderr. config.active_support.deprecation = :stderr end diff --git a/guides/code/getting_started/config/initializers/filter_parameter_logging.rb b/guides/code/getting_started/config/initializers/filter_parameter_logging.rb new file mode 100644 index 0000000000..4a994e1e7b --- /dev/null +++ b/guides/code/getting_started/config/initializers/filter_parameter_logging.rb @@ -0,0 +1,4 @@ +# Be sure to restart your server when you modify this file. + +# Configure sensitive parameters which will be filtered from the log file. +Rails.application.config.filter_parameters += [:password] diff --git a/guides/code/getting_started/config/initializers/inflections.rb b/guides/code/getting_started/config/initializers/inflections.rb index 5d8d9be237..ac033bf9dc 100644 --- a/guides/code/getting_started/config/initializers/inflections.rb +++ b/guides/code/getting_started/config/initializers/inflections.rb @@ -1,15 +1,16 @@ # Be sure to restart your server when you modify this file. -# Add new inflection rules using the following format -# (all these examples are active by default): -# ActiveSupport::Inflector.inflections do |inflect| +# Add new inflection rules using the following format. Inflections +# are locale specific, and you may define rules for as many different +# locales as you wish. All of these examples are active by default: +# ActiveSupport::Inflector.inflections(:en) do |inflect| # inflect.plural /^(ox)$/i, '\1en' # inflect.singular /^(ox)en/i, '\1' # inflect.irregular 'person', 'people' # inflect.uncountable %w( fish sheep ) # end -# + # These inflection rules are supported but not enabled by default: -# ActiveSupport::Inflector.inflections do |inflect| +# ActiveSupport::Inflector.inflections(:en) do |inflect| # inflect.acronym 'RESTful' # end diff --git a/guides/code/getting_started/config/initializers/locale.rb b/guides/code/getting_started/config/initializers/locale.rb new file mode 100644 index 0000000000..d89dac7c6a --- /dev/null +++ b/guides/code/getting_started/config/initializers/locale.rb @@ -0,0 +1,9 @@ +# Be sure to restart your server when you modify this file. + +# Set Time.zone default to the specified zone and make Active Record auto-convert to this zone. +# Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC. +# Rails.application.config.time_zone = 'Central Time (US & Canada)' + +# The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded. +# Rails.application.config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s] +# Rails.application.config.i18n.default_locale = :de diff --git a/guides/code/getting_started/config/initializers/secret_token.rb b/guides/code/getting_started/config/initializers/secret_token.rb index 969ecaad65..aaf57731be 100644 --- a/guides/code/getting_started/config/initializers/secret_token.rb +++ b/guides/code/getting_started/config/initializers/secret_token.rb @@ -2,8 +2,11 @@ # Your secret key for verifying the integrity of signed cookies. # If you change this key, all old signed cookies will become invalid! + # Make sure the secret is at least 30 characters and all random, # no regular words or you'll be exposed to dictionary attacks. -# Make sure your secret key is kept private +# You can use `rake secret` to generate a secure secret key. + +# Make sure your secret_key_base is kept private # if you're sharing your code publicly. -Blog::Application.config.secret_key_base = '685a9bf865b728c6549a191c90851c1b5ec41ecb60b9e94ad79dd3f824749798aa7b5e94431901960bee57809db0947b481570f7f13376b7ca190fa28099c459' +Blog::Application.config.secret_key_base = 'e8aab50cec8a06a75694111a4cbaf6e22fc288ccbc6b268683aae7273043c69b15ca07d10c92a788dd6077a54762cbfcc55f19c3459f7531221b3169f8171a53' diff --git a/guides/code/getting_started/config/initializers/session_store.rb b/guides/code/getting_started/config/initializers/session_store.rb index 3b2ca93ab9..2e37d93799 100644 --- a/guides/code/getting_started/config/initializers/session_store.rb +++ b/guides/code/getting_started/config/initializers/session_store.rb @@ -1,3 +1,3 @@ # Be sure to restart your server when you modify this file. -Blog::Application.config.session_store :cookie_store, key: '_blog_session' +Blog::Application.config.session_store :encrypted_cookie_store, key: '_blog_session' diff --git a/guides/code/getting_started/config/initializers/wrap_parameters.rb b/guides/code/getting_started/config/initializers/wrap_parameters.rb index 999df20181..33725e95fd 100644 --- a/guides/code/getting_started/config/initializers/wrap_parameters.rb +++ b/guides/code/getting_started/config/initializers/wrap_parameters.rb @@ -1,14 +1,14 @@ # Be sure to restart your server when you modify this file. -# + # This file contains settings for ActionController::ParamsWrapper which # is enabled by default. # Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array. ActiveSupport.on_load(:action_controller) do - wrap_parameters format: [:json] + wrap_parameters format: [:json] if respond_to?(:wrap_parameters) end -# Disable root element in JSON by default. -ActiveSupport.on_load(:active_record) do - self.include_root_in_json = false -end +# To enable root element in JSON for ActiveRecord objects. +# ActiveSupport.on_load(:active_record) do +# self.include_root_in_json = true +# end diff --git a/guides/code/getting_started/config/locales/en.yml b/guides/code/getting_started/config/locales/en.yml index 179c14ca52..0653957166 100644 --- a/guides/code/getting_started/config/locales/en.yml +++ b/guides/code/getting_started/config/locales/en.yml @@ -1,5 +1,23 @@ -# Sample localization file for English. Add more files in this directory for other locales. -# See https://github.com/svenfuchs/rails-i18n/tree/master/rails%2Flocale for starting points. +# Files in the config/locales directory are used for internationalization +# and are automatically loaded by Rails. If you want to use locales other +# than English, add the necessary files in this directory. +# +# To use the locales, use `I18n.t`: +# +# I18n.t 'hello' +# +# In views, this is aliased to just `t`: +# +# <%= t('hello') %> +# +# To use a different locale, set it with `I18n.locale`: +# +# I18n.locale = :es +# +# This would use the information in config/locales/es.yml. +# +# To learn more, please read the Rails Internationalization guide +# available at http://guides.rubyonrails.org/i18n.html. en: hello: "Hello world" diff --git a/guides/code/getting_started/config/routes.rb b/guides/code/getting_started/config/routes.rb index d94b0d6f33..9950568629 100644 --- a/guides/code/getting_started/config/routes.rb +++ b/guides/code/getting_started/config/routes.rb @@ -1,63 +1,7 @@ Blog::Application.routes.draw do - resources :posts do resources :comments end - - # The priority is based upon order of creation: - # first created -> highest priority. - - # Sample of regular route: - # match 'products/:id' => 'catalog#view' - # Keep in mind you can assign values other than :controller and :action - - # Sample of named route: - # match 'products/:id/purchase' => 'catalog#purchase', as: :purchase - # This route can be invoked with purchase_url(id: product.id) - - # Sample resource route (maps HTTP verbs to controller actions automatically): - # resources :products - - # Sample resource route with options: - # resources :products do - # member do - # get 'short' - # post 'toggle' - # end - # - # collection do - # get 'sold' - # end - # end - - # Sample resource route with sub-resources: - # resources :products do - # resources :comments, :sales - # resource :seller - # end - - # Sample resource route with more complex sub-resources - # resources :products do - # resources :comments - # resources :sales do - # get 'recent', on: :collection - # end - # end - - # Sample resource route within a namespace: - # namespace :admin do - # # Directs /admin/products/* to Admin::ProductsController - # # (app/controllers/admin/products_controller.rb) - # resources :products - # end - - # You can have the root of your site routed with "root" - # just remember to delete public/index.html. - root :to => "welcome#index" - - # See how all your routes lay out with "rake routes" - - # This is a legacy wild controller route that's not recommended for RESTful applications. - # Note: This route will make all actions in every controller accessible via GET requests. - # match ':controller(/:action(/:id))(.:format)' + + root to: "welcome#index" end diff --git a/guides/code/getting_started/db/migrate/20120420083127_create_posts.rb b/guides/code/getting_started/db/migrate/20130122042648_create_posts.rb index 602bef31ab..602bef31ab 100644 --- a/guides/code/getting_started/db/migrate/20120420083127_create_posts.rb +++ b/guides/code/getting_started/db/migrate/20130122042648_create_posts.rb diff --git a/guides/code/getting_started/db/migrate/20110901012815_create_comments.rb b/guides/code/getting_started/db/migrate/20130122045842_create_comments.rb index adda8078c1..3e51f9c0f7 100644 --- a/guides/code/getting_started/db/migrate/20110901012815_create_comments.rb +++ b/guides/code/getting_started/db/migrate/20130122045842_create_comments.rb @@ -3,10 +3,9 @@ class CreateComments < ActiveRecord::Migration create_table :comments do |t| t.string :commenter t.text :body - t.references :post + t.references :post, index: true t.timestamps end - add_index :comments, :post_id end end diff --git a/guides/code/getting_started/db/schema.rb b/guides/code/getting_started/db/schema.rb index cfb56ca9b9..101fe712a1 100644 --- a/guides/code/getting_started/db/schema.rb +++ b/guides/code/getting_started/db/schema.rb @@ -9,34 +9,25 @@ # from scratch. The latter is a flawed and unsustainable approach (the more migrations # you'll amass, the slower it'll run and the greater likelihood for issues). # -# It's strongly recommended to check this file into your version control system. +# It's strongly recommended that you check this file into your version control system. -ActiveRecord::Schema.define(:version => 20120420083127) do +ActiveRecord::Schema.define(version: 20130122045842) do - create_table "comments", :force => true do |t| + create_table "comments", force: true do |t| t.string "commenter" t.text "body" t.integer "post_id" - t.datetime "created_at", :null => false - t.datetime "updated_at", :null => false + t.datetime "created_at" + t.datetime "updated_at" end - add_index "comments", ["post_id"], :name => "index_comments_on_post_id" + add_index "comments", ["post_id"], name: "index_comments_on_post_id" - create_table "posts", :force => true do |t| + create_table "posts", force: true do |t| t.string "title" t.text "text" - t.datetime "created_at", :null => false - t.datetime "updated_at", :null => false + t.datetime "created_at" + t.datetime "updated_at" end - create_table "tags", :force => true do |t| - t.string "name" - t.integer "post_id" - t.datetime "created_at", :null => false - t.datetime "updated_at", :null => false - end - - add_index "tags", ["post_id"], :name => "index_tags_on_post_id" - end diff --git a/guides/code/getting_started/doc/README_FOR_APP b/guides/code/getting_started/doc/README_FOR_APP deleted file mode 100644 index fe41f5cc24..0000000000 --- a/guides/code/getting_started/doc/README_FOR_APP +++ /dev/null @@ -1,2 +0,0 @@ -Use this README file to introduce your application and point to useful places in the API for learning more. -Run "rake doc:app" to generate API documentation for your models, controllers, helpers, and libraries. diff --git a/guides/code/getting_started/test/fixtures/.gitkeep b/guides/code/getting_started/lib/assets/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/test/fixtures/.gitkeep +++ b/guides/code/getting_started/lib/assets/.keep diff --git a/guides/code/getting_started/test/functional/.gitkeep b/guides/code/getting_started/lib/tasks/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/test/functional/.gitkeep +++ b/guides/code/getting_started/lib/tasks/.keep diff --git a/guides/code/getting_started/test/integration/.gitkeep b/guides/code/getting_started/log/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/test/integration/.gitkeep +++ b/guides/code/getting_started/log/.keep diff --git a/guides/code/getting_started/public/404.html b/guides/code/getting_started/public/404.html index 9a48320a5f..3d875c342e 100644 --- a/guides/code/getting_started/public/404.html +++ b/guides/code/getting_started/public/404.html @@ -2,7 +2,7 @@ <html> <head> <title>The page you were looking for doesn't exist (404)</title> - <style type="text/css"> + <style> body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; } div.dialog { width: 25em; @@ -22,5 +22,6 @@ <h1>The page you were looking for doesn't exist.</h1> <p>You may have mistyped the address or the page may have moved.</p> </div> + <p>If you are the application owner check the logs for more information.</p> </body> </html> diff --git a/guides/code/getting_started/public/422.html b/guides/code/getting_started/public/422.html index 83660ab187..3f1bfb3417 100644 --- a/guides/code/getting_started/public/422.html +++ b/guides/code/getting_started/public/422.html @@ -2,7 +2,7 @@ <html> <head> <title>The change you wanted was rejected (422)</title> - <style type="text/css"> + <style> body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; } div.dialog { width: 25em; diff --git a/guides/code/getting_started/public/500.html b/guides/code/getting_started/public/500.html index f3648a0dbc..012977d3d2 100644 --- a/guides/code/getting_started/public/500.html +++ b/guides/code/getting_started/public/500.html @@ -2,7 +2,7 @@ <html> <head> <title>We're sorry, but something went wrong (500)</title> - <style type="text/css"> + <style> body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; } div.dialog { width: 25em; @@ -21,5 +21,6 @@ <div class="dialog"> <h1>We're sorry, but something went wrong.</h1> </div> + <p>If you are the application owner check the logs for more information.</p> </body> </html> diff --git a/guides/code/getting_started/script/rails b/guides/code/getting_started/script/rails deleted file mode 100755 index f8da2cffd4..0000000000 --- a/guides/code/getting_started/script/rails +++ /dev/null @@ -1,6 +0,0 @@ -#!/usr/bin/env ruby -# This command will automatically be run when you run "rails" with Rails 3 gems installed from the root of your application. - -APP_PATH = File.expand_path('../../config/application', __FILE__) -require File.expand_path('../../config/boot', __FILE__) -require 'rails/commands' diff --git a/guides/code/getting_started/test/unit/.gitkeep b/guides/code/getting_started/test/controllers/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/test/unit/.gitkeep +++ b/guides/code/getting_started/test/controllers/.keep diff --git a/guides/code/getting_started/test/functional/comments_controller_test.rb b/guides/code/getting_started/test/controllers/comments_controller_test.rb index 2ec71b4ec5..2ec71b4ec5 100644 --- a/guides/code/getting_started/test/functional/comments_controller_test.rb +++ b/guides/code/getting_started/test/controllers/comments_controller_test.rb diff --git a/guides/code/getting_started/test/unit/tag_test.rb b/guides/code/getting_started/test/controllers/posts_controller_test.rb index b8498a117c..7a6ee4f1db 100644 --- a/guides/code/getting_started/test/unit/tag_test.rb +++ b/guides/code/getting_started/test/controllers/posts_controller_test.rb @@ -1,6 +1,6 @@ require 'test_helper' -class TagTest < ActiveSupport::TestCase +class PostsControllerTest < ActionController::TestCase # test "the truth" do # assert true # end diff --git a/guides/code/getting_started/test/functional/welcome_controller_test.rb b/guides/code/getting_started/test/controllers/welcome_controller_test.rb index e4d5abae11..dff8e9d2c5 100644 --- a/guides/code/getting_started/test/functional/welcome_controller_test.rb +++ b/guides/code/getting_started/test/controllers/welcome_controller_test.rb @@ -5,4 +5,5 @@ class WelcomeControllerTest < ActionController::TestCase get :index assert_response :success end + end diff --git a/guides/code/getting_started/vendor/plugins/.gitkeep b/guides/code/getting_started/test/fixtures/.keep index e69de29bb2..e69de29bb2 100644 --- a/guides/code/getting_started/vendor/plugins/.gitkeep +++ b/guides/code/getting_started/test/fixtures/.keep diff --git a/guides/code/getting_started/test/fixtures/comments.yml b/guides/code/getting_started/test/fixtures/comments.yml index d33da386bf..0cd36069e4 100644 --- a/guides/code/getting_started/test/fixtures/comments.yml +++ b/guides/code/getting_started/test/fixtures/comments.yml @@ -1,11 +1,11 @@ -# Read about fixtures at http://api.rubyonrails.org/classes/Fixtures.html +# Read about fixtures at http://api.rubyonrails.org/classes/ActiveRecord/Fixtures.html one: commenter: MyString body: MyText - post: + post_id: two: commenter: MyString body: MyText - post: + post_id: diff --git a/guides/code/getting_started/test/fixtures/posts.yml b/guides/code/getting_started/test/fixtures/posts.yml index e1edfd385e..617a24b858 100644 --- a/guides/code/getting_started/test/fixtures/posts.yml +++ b/guides/code/getting_started/test/fixtures/posts.yml @@ -1,4 +1,4 @@ -# Read about fixtures at http://api.rubyonrails.org/classes/Fixtures.html +# Read about fixtures at http://api.rubyonrails.org/classes/ActiveRecord/Fixtures.html one: title: MyString diff --git a/guides/code/getting_started/test/functional/posts_controller_test.rb b/guides/code/getting_started/test/functional/posts_controller_test.rb deleted file mode 100644 index b8f7b07820..0000000000 --- a/guides/code/getting_started/test/functional/posts_controller_test.rb +++ /dev/null @@ -1,49 +0,0 @@ -require 'test_helper' - -class PostsControllerTest < ActionController::TestCase - setup do - @post = posts(:one) - end - - test "should get index" do - get :index - assert_response :success - assert_not_nil assigns(:posts) - end - - test "should get new" do - get :new - assert_response :success - end - - test "should create post" do - assert_difference('Post.count') do - post :create, post: @post.attributes - end - - assert_redirected_to post_path(assigns(:post)) - end - - test "should show post" do - get :show, id: @post.to_param - assert_response :success - end - - test "should get edit" do - get :edit, id: @post.to_param - assert_response :success - end - - test "should update post" do - put :update, id: @post.to_param, post: @post.attributes - assert_redirected_to post_path(assigns(:post)) - end - - test "should destroy post" do - assert_difference('Post.count', -1) do - delete :destroy, id: @post.to_param - end - - assert_redirected_to posts_path - end -end diff --git a/guides/code/getting_started/test/helpers/.keep b/guides/code/getting_started/test/helpers/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/test/helpers/.keep diff --git a/guides/code/getting_started/test/unit/helpers/comments_helper_test.rb b/guides/code/getting_started/test/helpers/comments_helper_test.rb index 2518c16bd5..2518c16bd5 100644 --- a/guides/code/getting_started/test/unit/helpers/comments_helper_test.rb +++ b/guides/code/getting_started/test/helpers/comments_helper_test.rb diff --git a/guides/code/getting_started/test/unit/helpers/posts_helper_test.rb b/guides/code/getting_started/test/helpers/posts_helper_test.rb index 48549c2ea1..48549c2ea1 100644 --- a/guides/code/getting_started/test/unit/helpers/posts_helper_test.rb +++ b/guides/code/getting_started/test/helpers/posts_helper_test.rb diff --git a/guides/code/getting_started/test/helpers/welcome_helper_test.rb b/guides/code/getting_started/test/helpers/welcome_helper_test.rb new file mode 100644 index 0000000000..d6ded5995f --- /dev/null +++ b/guides/code/getting_started/test/helpers/welcome_helper_test.rb @@ -0,0 +1,4 @@ +require 'test_helper' + +class WelcomeHelperTest < ActionView::TestCase +end diff --git a/guides/code/getting_started/test/integration/.keep b/guides/code/getting_started/test/integration/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/test/integration/.keep diff --git a/guides/code/getting_started/test/mailers/.keep b/guides/code/getting_started/test/mailers/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/test/mailers/.keep diff --git a/guides/code/getting_started/test/models/.keep b/guides/code/getting_started/test/models/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/test/models/.keep diff --git a/guides/code/getting_started/test/unit/comment_test.rb b/guides/code/getting_started/test/models/comment_test.rb index b6d6131a96..b6d6131a96 100644 --- a/guides/code/getting_started/test/unit/comment_test.rb +++ b/guides/code/getting_started/test/models/comment_test.rb diff --git a/guides/code/getting_started/test/unit/post_test.rb b/guides/code/getting_started/test/models/post_test.rb index 6d9d463a71..6d9d463a71 100644 --- a/guides/code/getting_started/test/unit/post_test.rb +++ b/guides/code/getting_started/test/models/post_test.rb diff --git a/guides/code/getting_started/test/performance/browsing_test.rb b/guides/code/getting_started/test/performance/browsing_test.rb deleted file mode 100644 index 9342a57b20..0000000000 --- a/guides/code/getting_started/test/performance/browsing_test.rb +++ /dev/null @@ -1,12 +0,0 @@ -require 'test_helper' -require 'rails/performance_test_help' - -class BrowsingTest < ActionDispatch::PerformanceTest - # Refer to the documentation for all available options - # self.profile_options = { runs: 5, metrics: [:wall_time, :memory], - # output: 'tmp/performance', formats: [:flat] } - - def test_homepage - get '/' - end -end diff --git a/guides/code/getting_started/test/test_helper.rb b/guides/code/getting_started/test/test_helper.rb index 3daca18a71..f91a4375dc 100644 --- a/guides/code/getting_started/test/test_helper.rb +++ b/guides/code/getting_started/test/test_helper.rb @@ -3,6 +3,8 @@ require File.expand_path('../../config/environment', __FILE__) require 'rails/test_help' class ActiveSupport::TestCase + ActiveRecord::Migration.check_pending! + # Setup all fixtures in test/fixtures/*.yml for all tests in alphabetical order. # # Note: You'll currently still have to declare fixtures explicitly in integration tests diff --git a/guides/code/getting_started/test/unit/helpers/home_helper_test.rb b/guides/code/getting_started/test/unit/helpers/home_helper_test.rb deleted file mode 100644 index 4740a18dac..0000000000 --- a/guides/code/getting_started/test/unit/helpers/home_helper_test.rb +++ /dev/null @@ -1,4 +0,0 @@ -require 'test_helper' - -class HomeHelperTest < ActionView::TestCase -end diff --git a/guides/code/getting_started/vendor/assets/javascripts/.keep b/guides/code/getting_started/vendor/assets/javascripts/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/vendor/assets/javascripts/.keep diff --git a/guides/code/getting_started/vendor/assets/stylesheets/.keep b/guides/code/getting_started/vendor/assets/stylesheets/.keep new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/guides/code/getting_started/vendor/assets/stylesheets/.keep diff --git a/guides/rails_guides/markdown.rb b/guides/rails_guides/markdown.rb index 650489e6cb..547c6d2c15 100644 --- a/guides/rails_guides/markdown.rb +++ b/guides/rails_guides/markdown.rb @@ -1,3 +1,5 @@ +# encoding: utf-8 + require 'redcarpet' require 'nokogiri' require 'rails_guides/markdown/renderer' @@ -129,7 +131,7 @@ module RailsGuides def generate_title if heading = Nokogiri::HTML(@header).at(:h2) - @title = "Ruby on Rails Guides: #{heading.text}".html_safe + @title = "#{heading.text} — Ruby on Rails Guides".html_safe else @title = "Ruby on Rails Guides" end diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index 80af0c1225..9c157ec0b3 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -3,11 +3,10 @@ Ruby on Rails 4.0 Release Notes Highlights in Rails 4.0: -* Ruby 1.9.3 only +* Ruby 2.0 preferred; 1.9.3+ required * Strong Parameters * Turbolinks * Russian Doll Caching -* Asynchronous Mailers These release notes cover only the major changes. To know about various bug fixes and changes, please refer to the change logs or check out the [list of commits](https://github.com/rails/rails/commits/master) in the main Rails repository on GitHub. @@ -68,6 +67,7 @@ In Rails 4.0, several features have been extracted into gems. You can simply add * Action Caching ([Github](https://github.com/rails/actionpack-action_caching), [Pull Request](https://github.com/rails/rails/pull/7833)) * Page Caching ([Github](https://github.com/rails/actionpack-page_caching), [Pull Request](https://github.com/rails/rails/pull/7833)) * Sprockets ([Github](https://github.com/rails/sprockets-rails)) +* Performance tests ([Github](https://github.com/rails/rails-perftest), [Pull Request](https://github.com/rails/rails/pull/8876)) Documentation ------------- @@ -85,6 +85,8 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt * New test locations `test/models`, `test/helpers`, `test/controllers`, and `test/mailers`. Corresponding rake tasks added as well. ([Pull Request](https://github.com/rails/rails/pull/7878)) +* Your app's executables now live in the `bin/` dir. Run `rake rails:update:bin` to get `bin/bundle`, `bin/rails`, and `bin/rake`. + * Threadsafe on by default ### Deprecations @@ -147,7 +149,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ Action Pack ----------- -Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railties/CHANGELOG.md) for detailed changes. +Please refer to the [Changelog](https://github.com/rails/rails/blob/master/actionpack/CHANGELOG.md) for detailed changes. ### Notable changes @@ -159,7 +161,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt Active Record ------------- -Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railties/CHANGELOG.md) for detailed changes. +Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activerecord/CHANGELOG.md) for detailed changes. ### Notable changes diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 46ff9027fd..da155628f3 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -58,7 +58,7 @@ Parameters You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from an HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the `params` hash in your controller: ```ruby -class ClientsController < ActionController::Base +class ClientsController < ApplicationController # This action uses query string parameters because it gets run # by an HTTP GET request, but this does not make any difference # to the way in which the parameters are accessed. The URL for @@ -114,11 +114,11 @@ To send a hash you include the key name inside the brackets: When this form is submitted, the value of `params[:client]` will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`. -Note that the `params` hash is actually an instance of `HashWithIndifferentAccess` from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys. +Note that the `params` hash is actually an instance of `ActiveSupport::HashWithIndifferentAccess`, which acts like a hash that lets you use symbols and strings interchangeably as keys. -### JSON/XML parameters +### JSON parameters -If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into `params` hash, which you'll be able to access like you would normally do with form data. +If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON format. Rails will automatically convert your parameters into `params` hash, which you'll be able to access like you would normally do with form data. So for example, if you are sending this JSON parameter: @@ -128,7 +128,7 @@ So for example, if you are sending this JSON parameter: You'll get `params[:company]` as `{ :name => "acme", "address" => "123 Carrot Street" }`. -Also, if you've turned on `config.wrap_parameters` in your initializer or calling `wrap_parameters` in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: +Also, if you've turned on `config.wrap_parameters` in your initializer or calling `wrap_parameters` in your controller, you can safely omit the root element in the JSON parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: ```json { "name": "acme", "address": "123 Carrot Street" } @@ -142,6 +142,8 @@ And assume that you're sending the data to `CompaniesController`, it would then You can customize the name of the key or specific parameters you want to wrap by consulting the [API documentation](http://api.rubyonrails.org/classes/ActionController/ParamsWrapper.html) +NOTE: A support for parsing XML parameters has been extracted into a gem named `actionpack-xml_parser` + ### Routing Parameters The `params` hash will always contain the `:controller` and `:action` keys, but you should use the methods `controller_name` and `action_name` instead to access these values. Any other parameters defined by the routing, such as `:id` will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the `:status` parameter in a "pretty" URL: @@ -174,10 +176,10 @@ Session Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and the view and can use one of a number of different storage mechanisms: -* ActionDispatch::Session::CookieStore - Stores everything on the client. -* ActionDispatch::Session::CacheStore - Stores the data in the Rails cache. -* @ActionDispatch::Session::ActiveRecordStore@ - Stores the data in a database using Active Record. (require `activerecord-session_store` gem). -* @ActionDispatch::Session::MemCacheStore@ - Stores the data in a memcached cluster (this is a legacy implementation; consider using CacheStore instead). +* `ActionDispatch::Session::CookieStore` - Stores everything on the client. +* `ActionDispatch::Session::CacheStore` - Stores the data in the Rails cache. +* `ActionDispatch::Session::ActiveRecordStore` - Stores the data in a database using Active Record. (require `activerecord-session_store` gem). +* `ActionDispatch::Session::MemCacheStore` - Stores the data in a memcached cluster (this is a legacy implementation; consider using CacheStore instead). All session stores use a cookie to store a unique ID for each session (you must use a cookie, Rails will not allow you to pass the session ID in the URL as this is less secure). @@ -194,7 +196,7 @@ If you need a different session storage mechanism, you can change it in the `con ```ruby # Use the database for sessions instead of the cookie-based default, # which shouldn't be used to store highly confidential information -# (create the session table with "script/rails g active_record:session_migration") +# (create the session table with "rails g active_record:session_migration") # YourApp::Application.config.session_store :active_record_store ``` @@ -479,7 +481,7 @@ In addition to "before" filters, you can also run filters after an action has be For example, in a website where changes have an approval workflow an administrator could be able to preview them easily, just apply them within a transaction: ```ruby -class ChangesController < ActionController::Base +class ChangesController < ApplicationController around_action :wrap_in_transaction, only: :show private diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 795afd0150..513ae1272f 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -419,7 +419,7 @@ Receiving and parsing emails with Action Mailer can be a rather complex endeavor * Implement a `receive` method in your mailer. -* Configure your email server to forward emails from the address(es) you would like your app to receive to `/path/to/app/script/rails runner 'UserMailer.receive(STDIN.read)'`. +* Configure your email server to forward emails from the address(es) you would like your app to receive to `/path/to/app/bin/rails runner 'UserMailer.receive(STDIN.read)'`. Once a method called `receive` is defined in any mailer, Action Mailer will parse the raw incoming email into an email object, decode it, instantiate a new mailer, and pass the email object to the mailer `receive` instance method. Here's an example: @@ -575,3 +575,25 @@ end ``` In the test we send the email and store the returned object in the `email` variable. We then ensure that it was sent (the first assert), then, in the second batch of assertions, we ensure that the email does indeed contain what we expect. + +NOTE: The `ActionMailer::Base.deliveries` array is only reset automatically in `ActionMailer::TestCase` tests. If you want to have a clean slate outside Action Mailer tests, you can reset it manually with: `ActionMailer::Base.deliveries.clear` + +Intercepting Emails +------------------- +There are situations where you need to edit an email before it's delivered. Fortunately Action Mailer provides hooks to intercept every email. You can register an interceptor to make modifications to mail messages right before they are handed to the delivery agents. + +```ruby +class SandboxEmailInterceptor + def self.delivering_email(message) + message.to = ['sandbox@example.com'] + end +end +``` + +Before the interceptor can do its job you need to register it with the Action Mailer framework. You can do this in an initializer file `config/initializers/sandbox_email_interceptor.rb` + +```ruby +ActionMailer::Base.register_interceptor(SandboxEmailInterceptor) if Rails.env.staging? +``` + +NOTE: The example above uses a custom environment called "staging" for a production like server but for testing purposes. You can read [Creating Rails environments](./configuring.html#creating-rails-environments) for more information about custom Rails environments. diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md index c90f42c492..69d7333e6f 100644 --- a/guides/source/active_record_basics.md +++ b/guides/source/active_record_basics.md @@ -1,6 +1,6 @@ Active Record Basics ==================== - + This guide is an introduction to Active Record. After reading this guide, you will know: @@ -239,12 +239,12 @@ Active Record provides a rich API for accessing data within a database. Below are a few examples of different data access methods provided by Active Record. ```ruby -# return array with all records +# return a collection with all users users = User.all ``` ```ruby -# return the first record +# return the first user user = User.first ``` diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index 20959a1a35..bb42fab101 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -157,7 +157,6 @@ The following methods trigger callbacks: * `save!` * `save(validate: false)` * `toggle!` -* `update` * `update_attribute` * `update` * `update!` @@ -168,7 +167,6 @@ Additionally, the `after_find` callback is triggered by the following finder met * `all` * `first` * `find` -* `find_all_by_*` * `find_by_*` * `find_by_*!` * `find_by_sql` @@ -176,7 +174,7 @@ Additionally, the `after_find` callback is triggered by the following finder met The `after_initialize` callback is triggered every time a new object of the class is initialized. -NOTE: The `find_all_by_*`, `find_by_*` and `find_by_*!` methods are dynamic finders generated automatically for every attribute. Learn more about them at the [Dynamic finders section](active_record_querying.html#dynamic-finders) +NOTE: The `find_by_*` and `find_by_*!` methods are dynamic finders generated automatically for every attribute. Learn more about them at the [Dynamic finders section](active_record_querying.html#dynamic-finders) Skipping Callbacks ------------------ @@ -344,19 +342,17 @@ By using the `after_commit` callback we can account for this case. ```ruby class PictureFile < ActiveRecord::Base - attr_accessor :delete_file - - after_destroy do |picture_file| - picture_file.delete_file = picture_file.filepath - end + after_commit :delete_picture_file_from_disk, :on => [:destroy] - after_commit do |picture_file| - if picture_file.delete_file && File.exist?(picture_file.delete_file) - File.delete(picture_file.delete_file) - picture_file.delete_file = nil + def delete_picture_file_from_disk + if File.exist?(filepath) + File.delete(filepath) end end end ``` +NOTE: the `:on` option specifies when a callback will be fired. If you +don't supply the `:on` option the callback will fire for every action. + The `after_commit` and `after_rollback` callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback. diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 24f98f68ca..bc3b1669d2 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1228,9 +1228,7 @@ Client.unscoped { Dynamic Finders --------------- -For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called `first_name` on your `Client` model for example, you get `find_by_first_name` and `find_all_by_first_name` for free from Active Record. If you have a `locked` field on the `Client` model, you also get `find_by_locked` and `find_all_by_locked` methods. - -You can also use `find_last_by_*` methods which will find the last record matching your argument. +For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called `first_name` on your `Client` model for example, you get `find_by_first_name` for free from Active Record. If you have a `locked` field on the `Client` model, you also get `find_by_locked` and methods. You can specify an exclamation point (`!`) on the end of the dynamic finders to get them to raise an `ActiveRecord::RecordNotFound` error if they do not return any records, like `Client.find_by_name!("Ryan")` @@ -1611,45 +1609,6 @@ EXPLAIN for: SELECT `posts`.* FROM `posts` WHERE `posts`.`user_id` IN (1) under MySQL. -### Automatic EXPLAIN - -Active Record is able to run EXPLAIN automatically on slow queries and log its -output. This feature is controlled by the configuration parameter - -```ruby -config.active_record.auto_explain_threshold_in_seconds -``` - -If set to a number, any query exceeding those many seconds will have its EXPLAIN -automatically triggered and logged. In the case of relations, the threshold is -compared to the total time needed to fetch records. So, a relation is seen as a -unit of work, no matter whether the implementation of eager loading involves -several queries under the hood. - -A threshold of `nil` disables automatic EXPLAINs. - -The default threshold in development mode is 0.5 seconds, and `nil` in test and -production modes. - -INFO. Automatic EXPLAIN gets disabled if Active Record has no logger, regardless -of the value of the threshold. - -#### Disabling Automatic EXPLAIN - -Automatic EXPLAIN can be selectively silenced with `ActiveRecord::Base.silence_auto_explain`: - -```ruby -ActiveRecord::Base.silence_auto_explain do - # no automatic EXPLAIN is triggered here -end -``` - -That may be useful for queries you know are slow but fine, like a heavyweight -report of an admin interface. - -As its name suggests, `silence_auto_explain` only silences automatic EXPLAINs. -Explicit calls to `ActiveRecord::Relation#explain` run. - ### Interpreting EXPLAIN Interpretation of the output of EXPLAIN is beyond the scope of this guide. The diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index a911d6b941..32641d04c1 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -117,7 +117,6 @@ database only if the object is valid: * `save` * `save!` * `update` -* `update` * `update!` The bang versions (e.g. `save!`) raise an exception if the record is invalid. @@ -619,6 +618,35 @@ class GoodnessValidator < ActiveModel::Validator end ``` +Note that the validator will be initialized *only once* for the whole application +life cycle, and not on each validation run, so be careful about using instance +variables inside it. + +If your validator is complex enough that you want instance variables, you can +easily use a plain old Ruby object instead: + +```ruby +class Person < ActiveRecord::Base + validate do |person| + GoodnessValidator.new(person).validate + end +end + +class GoodnessValidator + def initialize(person) + @person = person + end + + def validate + if some_complex_condition_involving_ivars_and_private_methods? + @person.errors[:base] << "This person is evil" + end + end + + # … +end +``` + ### `validates_each` This helper validates attributes against a block. It doesn't have a predefined diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index dd589ff8e3..f02b377832 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -422,24 +422,6 @@ NOTE: Defined in `active_support/core_ext/object/with_options.rb`. Active Support provides several methods to ease access to instance variables. -#### `instance_variable_names` - -Ruby 1.8 and 1.9 have a method called `instance_variables` that returns the names of the defined instance variables. But they behave differently, in 1.8 it returns strings whereas in 1.9 it returns symbols. Active Support defines `instance_variable_names` as a portable way to obtain them as strings: - -```ruby -class C - def initialize(x, y) - @x, @y = x, y - end -end - -C.new(0, 1).instance_variable_names # => ["@y", "@x"] -``` - -WARNING: The order in which the names are returned is unspecified, and it indeed depends on the version of the interpreter. - -NOTE: Defined in `active_support/core_ext/object/instance_variables.rb`. - #### `instance_values` The method `instance_values` returns a hash that maps instance variable names without "@" to their @@ -920,7 +902,7 @@ When interpolated into a string, the `:to` option should become an expression th delegate :logger, to: :Rails # delegates to the receiver's class -delegate :table_name, to: 'self.class' +delegate :table_name, to: :class ``` WARNING: If the `:prefix` option is `true` this is less generic, see below. @@ -1251,6 +1233,8 @@ The method `squish` strips leading and trailing whitespace, and substitutes runs There's also the destructive version `String#squish!`. +Note that it handles both ASCII and Unicode whitespace like mongolian vowel separator (U+180E). + NOTE: Defined in `active_support/core_ext/string/filters.rb`. ### `truncate` @@ -1449,11 +1433,10 @@ As the previous example shows, Active Support knows some irregular plurals and u Active Record uses this method to compute the default table name that corresponds to a model: ```ruby -# active_record/base.rb +# active_record/model_schema.rb def undecorated_table_name(class_name = base_class.name) table_name = class_name.to_s.demodulize.underscore - table_name = table_name.pluralize if pluralize_table_names - table_name + pluralize_table_names ? table_name.pluralize : table_name end ``` diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index b302ef76c6..e939606c88 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -37,9 +37,9 @@ You should use the defaults for all new applications unless you have a specific ### Main Features -The first feature of the pipeline is to concatenate assets. This is important in a production environment, because it can reduce the number of requests that a browser must make to render a web page. Web browsers are limited in the number of requests that they can make in parallel, so fewer requests can mean faster loading for your application. +The first feature of the pipeline is to concatenate assets. This is important in a production environment, because it can reduce the number of requests that a browser makes to render a web page. Web browsers are limited in the number of requests that they can make in parallel, so fewer requests can mean faster loading for your application. -Rails 2.x introduced the ability to concatenate JavaScript and CSS assets by placing `:cache => true` at the end of the `javascript_include_tag` and `stylesheet_link_tag` methods. But this technique has some limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. +Rails 2.x introduced the ability to concatenate JavaScript and CSS assets by placing `cache: true` at the end of the `javascript_include_tag` and `stylesheet_link_tag` methods. But this technique has some limitations. For example, it cannot generate the caches in advance, and it is not able to transparently include assets provided by third-party libraries. Starting with version 3.1, Rails defaults to concatenating all JavaScript files into one master `.js` file and all CSS files into one master `.css` file. As you'll learn later in this guide, you can customize this strategy to group files any way you like. In production, Rails inserts an MD5 fingerprint into each filename so that the file is cached by the web browser. You can invalidate the cache by altering this fingerprint, which happens automatically whenever you change the file contents. @@ -369,8 +369,8 @@ If any of the files in the manifest have changed between requests, the server re Debug mode can also be enabled in the Rails helper methods: ```erb -<%= stylesheet_link_tag "application", :debug => true %> -<%= javascript_include_tag "application", :debug => true %> +<%= stylesheet_link_tag "application", debug: true %> +<%= javascript_include_tag "application", debug: true %> ``` The `:debug` option is redundant if debug mode is on. @@ -445,7 +445,7 @@ NOTE. If you are precompiling your assets locally, you can use `bundle install - The default matcher for compiling files includes `application.js`, `application.css` and all non-JS/CSS files (this will include all image assets automatically): ```ruby -[ Proc.new{ |path| !%w(.js .css).include?(File.extname(path)) }, /application.(css|js)$/ ] +[ Proc.new { |path| !%w(.js .css).include?(File.extname(path)) }, /application.(css|js)$/ ] ``` NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, `.coffee` and `.scss` files are **not** automatically included as they compile to JS/CSS. @@ -460,7 +460,7 @@ Or you can opt to precompile all assets with something like this: ```ruby # config/environments/production.rb -config.assets.precompile << Proc.new { |path| +config.assets.precompile << Proc.new do |path| if path =~ /\.(css|js)\z/ full_path = Rails.application.assets.resolve(path).to_path app_assets_path = Rails.root.join('app', 'assets').to_path @@ -474,7 +474,7 @@ config.assets.precompile << Proc.new { |path| else false end -} +end ``` NOTE. Always specify an expected compiled filename that ends with js or css, even if you want to add Sass or CoffeeScript files to the precompile array. @@ -502,14 +502,14 @@ For Apache: ```apache # The Expires* directives requires the Apache module `mod_expires` to be enabled. -<LocationMatch "^/assets/.*$"> +<Location /assets/> # Use of ETag is discouraged when Last-Modified is present Header unset ETag FileETag None # RFC says only cache for 1 year ExpiresActive On ExpiresDefault "access plus 1 year" -</LocationMatch> +</Location> ``` For nginx: @@ -663,7 +663,7 @@ class Transformer end ``` -To enable this, pass a `new` object to the config option in `application.rb`: +To enable this, pass a new object to the config option in `application.rb`: ```ruby config.assets.css_compressor = Transformer.new @@ -720,7 +720,31 @@ A good example of this is the `jquery-rails` gem which comes with Rails as the s Making Your Library or Gem a Pre-Processor ------------------------------------------ -TODO: Registering gems on [Tilt](https://github.com/rtomayko/tilt) enabling Sprockets to find them. +As Sprockets uses [Tilt](https://github.com/rtomayko/tilt) as a generic +interface to different templating engines, your gem should just +implement the Tilt template protocol. Normally, you would subclass +`Tilt::Template` and reimplement `evaluate` method to return final +output. Template source is stored at `@code`. Have a look at +[`Tilt::Template`](https://github.com/rtomayko/tilt/blob/master/lib/tilt/template.rb) +sources to learn more. + +```ruby +module BangBang + class Template < ::Tilt::Template + # Adds a "!" to original template. + def evaluate(scope, locals, &block) + "#{@code}!" + end + end +end +``` + +Now that you have a `Template` class, it's time to associate it with an +extenstion for template files: + +```ruby +Sprockets.register_engine '.bang', BangBang::Template +``` Upgrading from Old Versions of Rails ------------------------------------ diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md index 773102400a..a270ec7a7e 100644 --- a/guides/source/caching_with_rails.md +++ b/guides/source/caching_with_rails.md @@ -30,101 +30,13 @@ config.action_controller.perform_caching = true Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver (i.e. Apache or nginx), without ever having to go through the Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with. -To enable page caching, you need to use the `caches_page` method. - -```ruby -class ProductsController < ActionController - - caches_page :index - - def index - @products = Product.all - end -end -``` - -Let's say you have a controller called `ProductsController` and an `index` action that lists all the products. The first time anyone requests `/products`, Rails will generate a file called `products.html` and the webserver will then look for that file before it passes the next request for `/products` to your Rails application. - -By default, the page cache directory is set to `Rails.public_path` (which is usually set to the `public` folder) and this can be configured by changing the configuration setting `config.action_controller.page_cache_directory`. Changing the default from `public` helps avoid naming conflicts, since you may want to put other static html in `public`, but changing this will require web server reconfiguration to let the web server know where to serve the cached files from. - -The Page Caching mechanism will automatically add a `.html` extension to requests for pages that do not have an extension to make it easy for the webserver to find those pages and this can be configured by changing the configuration setting `config.action_controller.default_static_extension`. - -In order to expire this page when a new product is added we could extend our example controller like this: - -```ruby -class ProductsController < ActionController - - caches_page :index - - def index - @products = Product.all - end - - def create - expire_page action: :index - end - -end -``` - -By default, page caching automatically gzips files (for example, to `products.html.gz` if user requests `/products`) to reduce the size of data transmitted (web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, compression ratio is maximum). - -Nginx is able to serve compressed content directly from disk by enabling `gzip_static`: - -```nginx -location / { - gzip_static on; # to serve pre-gzipped version -} -``` - -You can disable gzipping by setting `:gzip` option to false (for example, if action returns image): - -```ruby -caches_page :image, gzip: false -``` - -Or, you can set custom gzip compression level (level names are taken from `Zlib` constants): - -```ruby -caches_page :image, gzip: :best_speed -``` - -NOTE: Page caching ignores all parameters. For example `/products?page=1` will be written out to the filesystem as `products.html` with no reference to the `page` parameter. Thus, if someone requests `/products?page=2` later, they will get the cached first page. A workaround for this limitation is to include the parameters in the page's path, e.g. `/products/page/1`. - -INFO: Page caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job. +INFO: Page Caching has been removed from Rails 4. See the [actionpack-page_caching gem](https://github.com/rails/actionpack-page_caching) ### Action Caching Page Caching cannot be used for actions that have before filters - for example, pages that require authentication. This is where Action Caching comes in. Action Caching works like Page Caching except the incoming web request hits the Rails stack so that before filters can be run on it before the cache is served. This allows authentication and other restrictions to be run while still serving the result of the output from a cached copy. -Clearing the cache works in a similar way to Page Caching, except you use `expire_action` instead of `expire_page`. - -Let's say you only wanted authenticated users to call actions on `ProductsController`. - -```ruby -class ProductsController < ActionController - - before_action :authenticate - caches_action :index - - def index - @products = Product.all - end - - def create - expire_action action: :index - end - -end -``` - -You can also use `:if` (or `:unless`) to pass a Proc that specifies when the action should be cached. Also, you can use `layout: false` to cache without layout so that dynamic information in the layout such as logged in user info or the number of items in the cart can be left uncached. This feature is available as of Rails 2.2. - -You can modify the default action cache path by passing a `:cache_path` option. This will be passed directly to `ActionCachePath.path_for`. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance. - -Finally, if you are using memcached or Ehcache, you can also pass `:expires_in`. In fact, all parameters not used by `caches_action` are sent to the underlying cache store. - -INFO: Action caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job. +INFO: Action Caching has been removed from Rails 4. See the [actionpack-action_caching gem](https://github.com/rails/actionpack-action_caching) ### Fragment Caching @@ -173,6 +85,51 @@ This fragment is then available to all actions in the `ProductsController` using ```ruby expire_fragment('all_available_products') ``` +If you want to avoid expiring the fragment manually, whenever an action updates a product, you can define a helper method: + +```ruby +module ProductsHelper + def cache_key_for_products + count = Product.count + max_updated_at = Product.maximum(:updated_at).try(:utc).try(:to_s, :number) + "products/all-#{count}-#{max_updated_at}" + end +end +``` + +This method generates a cache key that depends on all products and can be used in the view: + +```erb +<% cache(cache_key_for_products) do %> + All available products: +<% end %> +``` +You can also use an Active Record model as the cache key: + +```erb +<% Product.all.each do |p| %> + <% cache(p) do %> + <%= link_to p.name, product_url(p) %> + <% end %> +<% end %> +``` + +Behind the scenes, a method called `cache_key` will be invoked on the model and it returns a string like `products/23-20130109142513`. The cache key includes the model name, the id and finally the updated_at timestamp. Thus it will automatically generate a new fragment when the product is updated because the key changes. + +You can also combine the two schemes which is called "Russian Doll Caching": + +```erb +<% cache(cache_key_for_products) do %> + All available products: + <% Product.all.each do |p| %> + <% cache(p) do %> + <%= link_to p.name, product_url(p) %> + <% end %> + <% end %> +<% end %> +``` + +It's called "Russian Doll Caching" because it nests multiple fragments. The advantage is that if a single product is updated, all the other inner fragments can be reused when regenerating the outer fragment. ### SQL Caching @@ -181,7 +138,7 @@ Query caching is a Rails feature that caches the result set returned by each que For example: ```ruby -class ProductsController < ActionController +class ProductsController < ApplicationController def index # Run a find query @@ -196,10 +153,6 @@ class ProductsController < ActionController end ``` -The second time the same query is run against the database, it's not actually going to hit the database. The first time the result is returned from the query it is stored in the query cache (in memory) and the second time it's pulled from memory. - -However, it's important to note that query caches are created at the start of an action and destroyed at the end of that action and thus persist only for the duration of the action. If you'd like to store query results in a more persistent fashion, you can in Rails by using low level caching. - Cache Stores ------------ diff --git a/guides/source/command_line.md b/guides/source/command_line.md index fb15790d90..9d1fb03fab 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -225,7 +225,8 @@ $ rails generate scaffold HighScore game:string score:integer invoke test_unit create test/models/high_score_test.rb create test/fixtures/high_scores.yml - route resources :high_scores + invoke resource_route + route resources :high_scores invoke scaffold_controller create app/controllers/high_scores_controller.rb invoke erb @@ -354,7 +355,7 @@ rake assets:clean # Remove compiled assets rake assets:precompile # Compile all the assets named in config.assets.precompile rake db:create # Create the database from config/database.yml for the current Rails.env ... -rake log:clear # Truncates all *.log files in log/ to zero bytes +rake log:clear # Truncates all *.log files in log/ to zero bytes (specify which logs with LOGS=test,development) rake middleware # Prints out your Rack middleware stack ... rake tmp:clear # Clear session, cache, and socket files from tmp/ (narrow w/ tmp:sessions:clear, tmp:cache:clear, tmp:sockets:clear) @@ -377,7 +378,7 @@ Active Record version 4.0.0.beta Action Pack version 4.0.0.beta Action Mailer version 4.0.0.beta Active Support version 4.0.0.beta -Middleware ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::RemoteIp, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActiveRecord::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::EncryptedCookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::Head, Rack::ConditionalGet, Rack::ETag, ActionDispatch::BestStandardsSupport +Middleware ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::RemoteIp, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActiveRecord::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::EncryptedCookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::Head, Rack::ConditionalGet, Rack::ETag Application root /home/foobar/commandsapp Environment development Database adapter sqlite3 @@ -441,7 +442,7 @@ app/model/post.rb: NOTE. When using specific annotations and custom annotations, the annotation name (FIXME, BUG etc) is not displayed in the output lines. -By default, `rake notes` will look in the `app`, `config`, `lib`, `script` and `test` directories. If you would like to search other directories, you can provide them as a comma separated list in an environment variable `SOURCE_ANNOTATION_DIRECTORIES`. +By default, `rake notes` will look in the `app`, `config`, `lib`, `bin` and `test` directories. If you would like to search other directories, you can provide them as a comma separated list in an environment variable `SOURCE_ANNOTATION_DIRECTORIES`. ```bash $ export SOURCE_ANNOTATION_DIRECTORIES='rspec,vendor' @@ -563,14 +564,20 @@ We had to create the **gitapp** directory and initialize an empty git repository $ cat config/database.yml # PostgreSQL. Versions 8.2 and up are supported. # -# Install the ruby-postgres driver: -# gem install ruby-postgres -# On Mac OS X: -# gem install ruby-postgres -- --include=/usr/local/pgsql +# Install the pg driver: +# gem install pg +# On OS X with Homebrew: +# gem install pg -- --with-pg-config=/usr/local/bin/pg_config +# On OS X with MacPorts: +# gem install pg -- --with-pg-config=/opt/local/lib/postgresql84/bin/pg_config # On Windows: -# gem install ruby-postgres +# gem install pg # Choose the win32 build. # Install PostgreSQL and put its /bin directory on your path. +# +# Configure Using Gemfile +# gem 'pg' +# development: adapter: postgresql encoding: unicode @@ -585,28 +592,3 @@ development: It also generated some lines in our database.yml configuration corresponding to our choice of PostgreSQL for database. NOTE. The only catch with using the SCM options is that you have to make your application's directory first, then initialize your SCM, then you can run the `rails new` command to generate the basis of your app. - -### `server` with Different Backends - -Many people have created a large number of different web servers in Ruby, and many of them can be used to run Rails. Since version 2.3, Rails uses Rack to serve its webpages, which means that any webserver that implements a Rack handler can be used. This includes WEBrick, Mongrel, Thin, and Phusion Passenger (to name a few!). - -NOTE: For more details on the Rack integration, see [Rails on Rack](rails_on_rack.html). - -To use a different server, just install its gem, then use its name for the first parameter to `rails server`: - -```bash -$ sudo gem install mongrel -Building native extensions. This could take a while... -Building native extensions. This could take a while... -Successfully installed gem_plugin-0.2.3 -Successfully installed fastthread-1.0.1 -Successfully installed cgi_multipart_eof_fix-2.5.0 -Successfully installed mongrel-1.1.5 -... -... -Installing RDoc documentation for mongrel-1.1.5... -$ rails server mongrel -=> Booting Mongrel (use 'rails server webrick' to force WEBrick) -=> Rails 3.1.0 application starting on http://0.0.0.0:3000 -... -``` diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 5fe8e2fba6..dbbeec7126 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -177,7 +177,6 @@ The full set of methods that can be used in this block are as follows: * `javascripts` turns on the hook for JavaScript files in generators. Used in Rails for when the `scaffold` generator is run. Defaults to `true`. * `javascript_engine` configures the engine to be used (for eg. coffee) when generating assets. Defaults to `nil`. * `orm` defines which orm to use. Defaults to `false` and will use Active Record by default. -* `performance_tool` defines which performance tool to use. Defaults to `nil`. * `resource_controller` defines which generator to use for generating a controller when using `rails generate resource`. Defaults to `:controller`. * `scaffold_controller` different from `resource_controller`, defines which generator to use for generating a _scaffolded_ controller when using `rails generate scaffold`. Defaults to `:scaffold_controller`. * `stylesheets` turns on the hook for stylesheets in generators. Used in Rails for when the `scaffold` generator is run, but this hook can be used in other generates as well. Defaults to `true`. @@ -208,7 +207,6 @@ Every Rails application comes with a standard set of middleware which it uses in * `ActionDispatch::ParamsParser` parses out parameters from the request into `params`. * `Rack::MethodOverride` allows the method to be overridden if `params[:_method]` is set. This is the middleware which supports the PATCH, PUT, and DELETE HTTP method types. * `ActionDispatch::Head` converts HEAD requests to GET requests and serves them as so. -* `ActionDispatch::BestStandardsSupport` enables "best standards support" so that IE8 renders some elements correctly. Besides these usual middleware, you can add your own by using the `config.middleware.use` method: @@ -231,13 +229,13 @@ config.middleware.insert_after ActionDispatch::Head, Magical::Unicorns Middlewares can also be completely swapped out and replaced with others: ```ruby -config.middleware.swap ActionDispatch::BestStandardsSupport, Magical::Unicorns +config.middleware.swap ActionController::Failsafe, Lifo::Failsafe ``` They can also be removed from the stack completely: ```ruby -config.middleware.delete ActionDispatch::BestStandardsSupport +config.middleware.delete "Rack::MethodOverride" ``` ### Configuring i18n @@ -270,8 +268,6 @@ config.middleware.delete ActionDispatch::BestStandardsSupport * `config.active_record.lock_optimistically` controls whether Active Record will use optimistic locking and is true by default. -* `config.active_record.auto_explain_threshold_in_seconds` configures the threshold for automatic EXPLAINs (`nil` disables this feature). Queries exceeding the threshold get their query plan logged. Default is 0.5 in development mode. - * +config.active_record.cache_timestamp_format+ controls the format of the timestamp value in the cache key. Default is +:number+. The MySQL adapter adds one additional configuration option: @@ -304,6 +300,8 @@ The schema dumper adds one additional configuration option: * `config.action_controller.permit_all_parameters` sets all the parameters for mass assignment to be permitted by default. The default value is `false`. +* `config.action_controller.action_on_unpermitted_params` enables logging or raising an exception if parameters that are not explicitly permitted are found. Set to `:log` or `:raise` to enable. The default value is `:log` in development and test environments, and `false` in all other environments. + ### Configuring Action Dispatch * `config.action_dispatch.session_store` sets the name of the store for session data. The default is `:cookie_store`; other valid options include `:active_record_store`, `:mem_cache_store` or the name of your own custom class. @@ -344,34 +342,6 @@ The schema dumper adds one additional configuration option: * `config.action_view.erb_trim_mode` gives the trim mode to be used by ERB. It defaults to `'-'`. See the [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/) for more information. -* `config.action_view.javascript_expansions` is a hash containing expansions that can be used for the JavaScript include tag. By default, this is defined as: - - ```ruby - config.action_view.javascript_expansions = { :defaults => %w(jquery jquery_ujs) } - ``` - - However, you may add to this by defining others: - - ```ruby - config.action_view.javascript_expansions[:prototype] = [ - 'prototype', 'effects', 'dragdrop', 'controls' - ] - ``` - - And can reference in the view with the following code: - - ```ruby - <%= javascript_include_tag :prototype %> - ``` - -* `config.action_view.stylesheet_expansions` works in much the same way as `javascript_expansions`, but has no default key. Keys defined for this hash can be referenced in the view like such: - - ```ruby - <%= stylesheet_link_tag :special %> - ``` - -* `config.action_view.cache_asset_ids` With the cache enabled, the asset tag helper methods will make fewer expensive file system calls (the default implementation checks the file system timestamp). However this prevents you from modifying any asset files while the server is running. - * `config.action_view.embed_authenticity_token_in_remote_forms` allows you to set the default behavior for `authenticity_token` in forms with `:remote => true`. By default it's set to false, which means that remote forms will not include `authenticity_token`, which is helpful when you're fragment-caching the form. Remote forms get the authenticity from the `meta` tag, so embedding is unnecessary unless you support browsers without JavaScript. In such case you can either pass `:authenticity_token => true` as a form option or set this config setting to `true` * `config.action_view.prefix_partial_path_with_controller_namespace` determines whether or not partials are looked up from a subdirectory in templates rendered from namespaced controllers. For example, consider a controller named `Admin::PostsController` which renders this template: @@ -551,6 +521,15 @@ development: Change the username and password in the `development` section as appropriate. +### Creating Rails Environments + +By default Rails ships with three environments: "development", "test", and "production". While these are sufficient for most use cases, there are circumstances when you want more environments. + +Imagine you have a server which mirrors the production environment but is only used for testing. Such a server is commonly called a "staging server". To define an environment called "staging" for this server just by create a file called `config/environments/staging.rb`. Please use the contents of any existing file in `config/environments` as a starting point and make the necessary changes from there. + +That environment is no different than the default ones, start a server with `rails server -e staging`, a console with `rails console staging`, `Rails.env.staging?` works, etc. + + Rails Environment Settings -------------------------- @@ -583,7 +562,7 @@ Rails has 5 initialization events which can be hooked into (listed in the order * `to_prepare`: Run after the initializers are run for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in `development`, but only once (during boot-up) in `production` and `test`. -* `before_eager_load`: This is run directly before eager loading occurs, which is the default behaviour for the `production` environment and not for the `development` environment. +* `before_eager_load`: This is run directly before eager loading occurs, which is the default behavior for the `production` environment and not for the `development` environment. * `after_initialize`: Run directly after the initialization of the application, but before the application initializers are run. @@ -671,10 +650,6 @@ Below is a comprehensive list of all the initializers found in Rails in the orde * `action_dispatch.configure` Configures the `ActionDispatch::Http::URL.tld_length` to be set to the value of `config.action_dispatch.tld_length`. -* `action_view.cache_asset_ids` Sets `ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids` to `false` when Active Support loads, but only if `config.cache_classes` is too. - -* `action_view.javascript_expansions` Registers the expansions set up by `config.action_view.javascript_expansions` and `config.action_view.stylesheet_expansions` to be recognized by Action View and therefore usable in the views. - * `action_view.set_configs` Sets up Action View by using the settings in `config.action_view` by `send`'ing the method names as setters to `ActionView::Base` and passing the values through. * `action_controller.logger` Sets `ActionController::Base.logger` — if it's not already set — to `Rails.logger`. diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 7c5a472971..7909a00c47 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -85,7 +85,7 @@ You can also run any single test separately: $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.rb ``` -You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server. +You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS.rdoc` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server. ### Warnings @@ -216,6 +216,7 @@ Rails follows a simple set of coding style conventions: * Use `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`. * Use `a = b` and not `a=b`. * Use assert_not methods instead of refute. +* Prefer `method { do_stuff }` instead of `method{do_stuff}` for single-line blocks. * Follow the conventions in the source you see used already. The above are guidelines — please use your best judgment in using them. diff --git a/guides/source/credits.html.erb b/guides/source/credits.html.erb index e25168d58d..ff76fa2b85 100644 --- a/guides/source/credits.html.erb +++ b/guides/source/credits.html.erb @@ -28,7 +28,7 @@ Ruby on Rails Guides: Credits <h3 class="section">Rails Guides Authors</h3> <%= author('Ryan Bigg', 'radar', 'radar.png') do %> -Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has been working with Rails since 2006. He's co-authoring a book called <a href="http://manning.com/katz">Rails 3 in Action</a> and he's written many gems which can be seen on <a href="http://github.com/radar">his GitHub page</a> and he also tweets prolifically as <a href="http://twitter.com/ryanbigg">@ryanbigg</a>. +Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has been working with Rails since 2006. He's co-authoring a book called <a href="http://manning.com/katz">Rails 3 in Action</a> and he's written many gems which can be seen on <a href="https://github.com/radar">his GitHub page</a> and he also tweets prolifically as <a href="http://twitter.com/ryanbigg">@ryanbigg</a>. <% end %> <%= author('Oscar Del Ben', 'oscardelben', 'oscardelben.jpg') do %> diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md index 524fe46408..5531dee343 100644 --- a/guides/source/debugging_rails_applications.md +++ b/guides/source/debugging_rails_applications.md @@ -664,7 +664,7 @@ References ---------- * [ruby-debug Homepage](http://bashdb.sourceforge.net/ruby-debug/home-page.html) -* [debugger Homepage](http://github.com/cldwalker/debugger) +* [debugger Homepage](https://github.com/cldwalker/debugger) * [Article: Debugging a Rails application with ruby-debug](http://www.sitepoint.com/article/debug-rails-app-ruby-debug/) * [ruby-debug Basics screencast](http://brian.maybeyoureinsane.net/blog/2007/05/07/ruby-debug-basics-screencast/) * [Ryan Bates' debugging ruby (revised) screencast](http://railscasts.com/episodes/54-debugging-ruby-revised) diff --git a/guides/source/development_dependencies_install.md b/guides/source/development_dependencies_install.md index db43d62fcf..6493c1e1ec 100644 --- a/guides/source/development_dependencies_install.md +++ b/guides/source/development_dependencies_install.md @@ -174,6 +174,20 @@ $ cd activerecord $ bundle exec rake postgresql:build_databases ``` +It is possible to build databases for both PostgreSQL and MySQL with + +```bash +$ cd activerecord +$ bundle exec rake db:create +``` + +You can cleanup the databases using + +```bash +$ cd activerecord +$ bundle exec rake db:drop +``` + NOTE: Using the rake task to create the test databases ensures they have the correct character set and collation. NOTE: You'll see the following warning (or localized warning) during activating HStore extension in PostgreSQL 9.1.x or earlier: "WARNING: => is deprecated as an operator". diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index e779407fab..c73bbeb90d 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -84,10 +84,6 @@ url: debugging_rails_applications.html description: This guide describes how to debug Rails applications. It covers the different ways of achieving this and how to understand what is happening "behind the scenes" of your code. - - name: Performance Testing Rails Applications - url: performance_testing.html - description: This guide covers the various ways of performance testing a Ruby on Rails application. - - name: Configuring Rails Applications url: configuring.html description: This guide covers the basic configuration settings for a Rails application. @@ -106,7 +102,6 @@ description: This guide documents the asset pipeline. - name: Working with JavaScript in Rails - work_in_progress: true url: working_with_javascript_in_rails.html description: This guide covers the built-in Ajax/JavaScript functionality of Rails. - diff --git a/guides/source/engines.md b/guides/source/engines.md index 116a7e67cd..00939c4ff2 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -16,9 +16,9 @@ After reading this guide, you will know: What are engines? ----------------- -Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the `Rails::Application` class inheriting a lot of its behaviour from `Rails::Engine`. +Engines can be considered miniature applications that provide functionality to their host applications. A Rails application is actually just a "supercharged" engine, with the `Rails::Application` class inheriting a lot of its behavior from `Rails::Engine`. -Therefore, engines and applications can be thought of almost the same thing, just with very minor differences, as you'll see throughout this guide. Engines and applications also share a common structure. +Therefore, engines and applications can be thought of almost the same thing, just with subtle differences, as you'll see throughout this guide. Engines and applications also share a common structure. Engines are also closely related to plugins where the two share a common `lib` directory structure and are both generated using the `rails plugin new` generator. The difference being that an engine is considered a "full plugin" by Rails as indicated by the `--full` option that's passed to the generator command, but this guide will refer to them simply as "engines" throughout. An engine **can** be a plugin, and a plugin **can** be an engine. @@ -28,7 +28,7 @@ Engines can also be isolated from their host applications. This means that an ap It's important to keep in mind at all times that the application should **always** take precedence over its engines. An application is the object that has final say in what goes on in the universe (with the universe being the application's environment) where the engine should only be enhancing it, rather than changing it drastically. -To see demonstrations of other engines, check out [Devise](https://github.com/plataformatec/devise), an engine that provides authentication for its parent applications, or [Forem](https://github.com/radar/forem), an engine that provides forum functionality. There's also [Spree](https://github.com/spree/spree) which provides an e-commerce platform, and [RefineryCMS](https://github.com/resolve/refinerycms), a CMS engine. +To see demonstrations of other engines, check out [Devise](https://github.com/plataformatec/devise), an engine that provides authentication for its parent applications, or [Forem](https://github.com/radar/forem), an engine that provides forum functionality. There's also [Spree](https://github.com/spree/spree) which provides an e-commerce platform, and [RefineryCMS](https://github.com/refinery/refinerycms), a CMS engine. Finally, engines would not have been possible without the work of James Adam, Piotr Sarnacki, the Rails Core Team, and a number of other people. If you ever meet them, don't forget to say thanks! @@ -57,7 +57,7 @@ The `--full` option tells the generator that you want to create an engine, inclu end ``` * A file at `lib/blorgh/engine.rb` which is identical in function to a standard Rails application's `config/application.rb` file: - + ```ruby module Blorgh class Engine < ::Rails::Engine @@ -72,12 +72,12 @@ The `--mountable` option tells the generator that you want to create a "mountabl * A namespaced `ApplicationHelper` stub * A layout view template for the engine * Namespace isolation to `config/routes.rb`: - + ```ruby Blorgh::Engine.routes.draw do end ``` - + * Namespace isolation to `lib/blorgh/engine.rb`: ```ruby @@ -149,9 +149,9 @@ Lastly, the `app/views` directory contains a `layouts` folder which contains a f If you don't want to force a layout on to users of the engine, then you can delete this file and reference a different layout in the controllers of your engine. -#### `script` directory +#### `bin` directory -This directory contains one file, `script/rails`, which enables you to use the `rails` sub-commands and generators just like you would within an application. This means that you will very easily be able to generate new controllers and models for this engine by running commands like this: +This directory contains one file, `bin/rails`, which enables you to use the `rails` sub-commands and generators just like you would within an application. This means that you will very easily be able to generate new controllers and models for this engine by running commands like this: ```bash rails g model @@ -171,7 +171,7 @@ end This line mounts the engine at the path `/blorgh`, which will make it accessible through the application only at that path. -Also in the test directory is the `test/integration` directory, where integration tests for the engine should be placed. Other directories can be created in the `test` directory also. For example, you may wish to create a `test/models` directory for your models tests. +In the test directory there is the `test/integration` directory, where integration tests for the engine should be placed. Other directories can be created in the `test` directory as well. For example, you may wish to create a `test/models` directory for your models tests. Providing engine functionality ------------------------------ @@ -232,7 +232,8 @@ Blorgh::Engine.routes.draw do end ``` -Note here that the routes are drawn upon the `Blorgh::Engine` object rather than the `YourApp::Application` class. This is so that the engine routes are confined to the engine itself and can be mounted at a specific point as shown in the [test directory](#test-directory) section. This is also what causes the engine's routes to be isolated from those routes that are within the application. This is discussed further in the [Routes](#routes) section of this guide. +Note here that the routes are drawn upon the `Blorgh::Engine` object rather than the `YourApp::Application` class. This is so that the engine routes are confined to the engine itself and can be mounted at a specific point as shown in the [test directory](#test-directory) section. It also causes the engine's routes to be isolated from those routes that are within the application. The [Routes](#routes) section of +this guide describes it in details. Next, the `scaffold_controller` generator is invoked, generating a controller called `Blorgh::PostsController` (at `app/controllers/blorgh/posts_controller.rb`) and its related views at `app/views/blorgh/posts`. This generator also generates a test for the controller (`test/controllers/blorgh/posts_controller_test.rb`) and a helper (`app/helpers/blorgh/posts_controller.rb`). @@ -258,11 +259,11 @@ module Blorgh end ``` -This helps prevent conflicts with any other engine or application that may have a post resource also. +This helps prevent conflicts with any other engine or application that may have a post resource as well. -Finally, two files that are the assets for this resource are generated, `app/assets/javascripts/blorgh/posts.js` and `app/assets/javascripts/blorgh/posts.css`. You'll see how to use these a little later. +Finally, two files that are the assets for this resource are generated, `app/assets/javascripts/blorgh/posts.js` and `app/assets/stylesheets/blorgh/posts.css`. You'll see how to use these a little later. -By default, the scaffold styling is not applied to the engine as the engine's layout file, `app/views/blorgh/application.html.erb` doesn't load it. To make this apply, insert this line into the `<head>` tag of this layout: +By default, the scaffold styling is not applied to the engine as the engine's layout file, `app/views/layouts/blorgh/application.html.erb` doesn't load it. To make this apply, insert this line into the `<head>` tag of this layout: ```erb <%= stylesheet_link_tag "scaffold" %> @@ -287,7 +288,7 @@ Now people will only need to go to the root of the engine to see all the posts, ### Generating a comments resource -Now that the engine has the ability to create new blog posts, it only makes sense to add commenting functionality as well. To do get this, you'll need to generate a comment model, a comment controller and then modify the posts scaffold to display comments and allow people to create new ones. +Now that the engine can create new blog posts, it only makes sense to add commenting functionality as well. To do this, you'll need to generate a comment model, a comment controller and then modify the posts scaffold to display comments and allow people to create new ones. Run the model generator and tell it to generate a `Comment` model, with the related table having two columns: a `post_id` integer and `text` text column. @@ -394,7 +395,7 @@ def create @post = Post.find(params[:post_id]) @comment = @post.comments.create(params[:comment]) flash[:notice] = "Comment has been created!" - redirect_to post_path + redirect_to posts_path end ``` @@ -469,7 +470,7 @@ If you have multiple engines that need migrations copied over, use `railties:ins $ rake railties:install:migrations ``` -This command, when run for the first time will copy over all the migrations from the engine. When run the next time, it will only copy over migrations that haven't been copied over already. The first run for this command will output something such as this: +This command, when run for the first time, will copy over all the migrations from the engine. When run the next time, it will only copy over migrations that haven't been copied over already. The first run for this command will output something such as this: ```bash Copied migration [timestamp_1]_create_blorgh_posts.rb from blorgh @@ -531,7 +532,7 @@ before_save :set_author private def set_author - self.author = User.find_or_create_by_name(author_name) + self.author = User.find_or_create_by(name: author_name) end ``` @@ -630,7 +631,7 @@ belongs_to :author, class_name: Blorgh.user_class The `set_author` method also located in this class should also use this class: ```ruby -self.author = Blorgh.user_class.constantize.find_or_create_by_name(author_name) +self.author = Blorgh.user_class.constantize.find_or_create_by(name: author_name) ``` To save having to call `constantize` on the `user_class` result all the time, you could instead just override the `user_class` getter method inside the `Blorgh` module in the `lib/blorgh.rb` file to always call `constantize` on the saved value before returning the result: @@ -644,10 +645,18 @@ end This would then turn the above code for `set_author` into this: ```ruby -self.author = Blorgh.user_class.find_or_create_by_name(author_name) +self.author = Blorgh.user_class.find_or_create_by(name: author_name) ``` -Resulting in something a little shorter, and more implicit in its behaviour. The `user_class` method should always return a `Class` object. +Resulting in something a little shorter, and more implicit in its behavior. The `user_class` method should always return a `Class` object. + +Since we changed the `user_class` method to no longer return a +`String` but a `Class` we must also modify our `belongs_to` definition +in the `Blorgh::Post` model: + +```ruby +belongs_to :author, class_name: Blorgh.user_class.to_s +``` To set this configuration setting within the application, an initializer should be used. By using an initializer, the configuration will be set up before the application starts and calls the engine's models which may depend on this configuration setting existing. @@ -661,7 +670,7 @@ WARNING: It's very important here to use the `String` version of the class, rath Go ahead and try to create a new post. You will see that it works exactly in the same way as before, except this time the engine is using the configuration setting in `config/initializers/blorgh.rb` to learn what the class is. -There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a `find_or_create_by_name` method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced. +There are now no strict dependencies on what the class is, only what the API for the class must be. The engine simply requires this class to define a `find_or_create_by` method which returns an object of that class to be associated with a post when it's created. This object, of course, should have some sort of identifier by which it can be referenced. #### General engine configuration @@ -753,10 +762,9 @@ end #### Implementing Decorator Pattern Using ActiveSupport::Concern -Using `Class#class_eval` is great for simple adjustments, but for more complex class modifications, you might want to consider using [`ActiveSupport::Concern`](http://edgeapi.rubyonrails.org/classes/ActiveSupport/Concern.html) helps manage load order of interlinked dependencies at run time allowing you to significantly modularize your code. +Using `Class#class_eval` is great for simple adjustments, but for more complex class modifications, you might want to consider using [`ActiveSupport::Concern`](http://edgeapi.rubyonrails.org/classes/ActiveSupport/Concern.html). ActiveSupport::Concern manages load order of interlinked dependent modules and classes at run time allowing you to significantly modularize your code. -**Adding** `Post#time_since_created`<br/> -**Overriding** `Post#summary` +**Adding** `Post#time_since_created` and **Overriding** `Post#summary` ```ruby # MyApp/app/models/blorgh/post.rb @@ -789,7 +797,7 @@ module Blorgh::Concerns::Models::Post extend ActiveSupport::Concern # 'included do' causes the included code to be evaluated in the - # conext where it is included (post.rb), rather than be + # context where it is included (post.rb), rather than be # executed in the module's context (blorgh/concerns/models/post). included do attr_accessor :author_name @@ -799,9 +807,9 @@ module Blorgh::Concerns::Models::Post private - def set_author - self.author = User.find_or_create_by_name(author_name) - end + def set_author + self.author = User.find_or_create_by(name: author_name) + end end def summary @@ -839,7 +847,7 @@ Try this now by creating a new file at `app/views/blorgh/posts/index.html.erb` a ### Routes -Routes inside an engine are, by default, isolated from the application. This is done by the `isolate_namespace` call inside the `Engine` class. This essentially means that the application and its engines can have identically named routes, and that they will not clash. +Routes inside an engine are, by default, isolated from the application. This is done by the `isolate_namespace` call inside the `Engine` class. This essentially means that the application and its engines can have identically named routes and they will not clash. Routes inside an engine are drawn on the `Engine` class within `config/routes.rb`, like this: @@ -914,9 +922,10 @@ For more information, read the [Asset Pipeline guide](http://guides.rubyonrails. ### Other gem dependencies -Gem dependencies inside an engine should be specified inside the `.gemspec` file at the root of the engine. The reason for this is because the engine may +Gem dependencies inside an engine should be specified inside the +`.gemspec` file at the root of the engine. The reason is that the engine may be installed as a gem. If dependencies were to be specified inside the `Gemfile`, -these would not be recognised by a traditional gem install and so they would not +these would not be recognized by a traditional gem install and so they would not be installed, causing the engine to malfunction. To specify a dependency that should be installed with the engine during a diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index b7145c46dc..b8681d493a 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -238,7 +238,7 @@ end The corresponding view `app/views/articles/new.html.erb` using `form_for` looks like this: ```erb -<%= form_for @article, url: {action: "create"}, html => {class: "nifty_form"} do |f| %> +<%= form_for @article, url: {action: "create"}, html: {class: "nifty_form"} do |f| %> <%= f.text_field :title %> <%= f.text_area :body, size: "60x12" %> <%= f.submit "Create" %> @@ -428,7 +428,7 @@ WARNING: when `:inlude_blank` or `:prompt:` are not present, `:include_blank` is You can add arbitrary attributes to the options using hashes: ```html+erb -<%= options_for_select([['Lisbon', 1, 'data-size': '2.8 million'], ['Madrid', 2, 'data-size': '3.2 million']], 2) %> +<%= options_for_select([['Lisbon', 1, {'data-size' => '2.8 million'}], ['Madrid', 2, {'data-size' => '3.2 million'}]], 2) %> output: @@ -497,7 +497,7 @@ To leverage time zone support in Rails, you have to ask your users what time zon There is also `time_zone_options_for_select` helper for a more manual (therefore more customizable) way of doing this. Read the API documentation to learn about the possible arguments for these two methods. -Rails _used_ to have a `country_select` helper for choosing countries, but this has been extracted to the [country_select plugin](https://github.com/chrislerum/country_select). When using this, be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from Rails). +Rails _used_ to have a `country_select` helper for choosing countries, but this has been extracted to the [country_select plugin](https://github.com/stefanpenner/country_select). When using this, be aware that the exclusion or inclusion of certain names from the list can be somewhat controversial (and was the reason this functionality was extracted from Rails). Using Date and Time Form Helpers -------------------------------- diff --git a/guides/source/generators.md b/guides/source/generators.md index 62de5a70bb..d7c789e2d8 100644 --- a/guides/source/generators.md +++ b/guides/source/generators.md @@ -176,7 +176,8 @@ $ rails generate scaffold User name:string invoke test_unit create test/models/user_test.rb create test/fixtures/users.yml - route resources :users + invoke resource_route + route resources :users invoke scaffold_controller create app/controllers/users_controller.rb invoke erb @@ -192,8 +193,13 @@ $ rails generate scaffold User name:string create app/helpers/users_helper.rb invoke test_unit create test/helpers/users_helper_test.rb - invoke stylesheets - create app/assets/stylesheets/scaffold.css + invoke assets + invoke coffee + create app/assets/javascripts/users.js.coffee + invoke scss + create app/assets/stylesheets/users.css.scss + invoke scss + create app/assets/stylesheets/scaffolds.css.scss ``` Looking at this output, it's easy to understand how generators work in Rails 3.0 and above. The scaffold generator doesn't actually generate anything, it just invokes others to do the work. This allows us to add/replace/remove any of those invocations. For instance, the scaffold generator invokes the scaffold_controller generator, which invokes erb, test_unit and helper generators. Since each generator has a single responsibility, they are easy to reuse, avoiding code duplication. @@ -304,7 +310,7 @@ In Rails 3.0 and above, generators don't just look in the source root for templa ```erb module <%= class_name %>Helper - attr_reader :<%= plural_name %>, <%= plural_name.singularize %> + attr_reader :<%= plural_name %>, :<%= plural_name.singularize %> end ``` @@ -350,6 +356,7 @@ $ rails generate scaffold Comment body:text invoke shoulda create test/models/comment_test.rb create test/fixtures/comments.yml + invoke resource_route route resources :comments invoke scaffold_controller create app/controllers/comments_controller.rb @@ -360,13 +367,16 @@ $ rails generate scaffold Comment body:text create app/views/comments/show.html.erb create app/views/comments/new.html.erb create app/views/comments/_form.html.erb - create app/views/layouts/comments.html.erb invoke shoulda create test/controllers/comments_controller_test.rb invoke my_helper create app/helpers/comments_helper.rb invoke shoulda create test/helpers/comments_helper_test.rb + invoke assets + invoke coffee + create app/assets/javascripts/comments.js.coffee + invoke scss ``` Fallbacks allow your generators to have a single responsibility, increasing code reuse and reducing the amount of duplication. @@ -402,7 +412,7 @@ This command will generate the `Thud` application, and then apply the template t Templates don't have to be stored on the local system, the `-m` option also supports online templates: ```bash -$ rails new thud -m https://gist.github.com/722911.txt +$ rails new thud -m https://gist.github.com/radar/722911/raw/ ``` Whilst the final section of this guide doesn't cover how to generate the most awesome template known to man, it will take you through the methods available at your disposal so that you can develop it yourself. These same methods are also available for generators. diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index aa841d5867..87f5e43157 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -21,7 +21,7 @@ application from scratch. It does not assume that you have any prior experience with Rails. However, to get the most out of it, you need to have some prerequisites installed: -* The [Ruby](http://www.ruby-lang.org/en/downloads) language version 1.9.3 or higher +* The [Ruby](http://www.ruby-lang.org/en/downloads) language version 1.9.3 or newer * The [RubyGems](http://rubygems.org/) packaging system * To learn more about RubyGems, please read the [RubyGems User Guide](http://docs.rubygems.org/read/book/1) * A working installation of the [SQLite3 Database](http://www.sqlite.org) @@ -45,7 +45,7 @@ code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that it makes web application development more fun. -Rails is opinionated software. It makes the assumption that there is a "best" +Rails is opinionated software. It makes the assumption that there is the "best" way to do things, and it's designed to encourage that way - and in some cases to discourage alternatives. If you learn "The Rails Way" you'll probably discover a tremendous increase in productivity. If you persist in bringing old habits from @@ -71,7 +71,9 @@ By following along with this guide, you'll create a Rails project called (very) simple weblog. Before you can start building the application, you need to make sure that you have Rails itself installed. -TIP: The examples below use # and $ to denote superuser and regular user terminal prompts respectively in a UNIX-like OS. If you are using Windows, your prompt will look something like c:\source_code> +TIP: The examples below use `#` and `$` to denote superuser and regular +user terminal prompts respectively in a UNIX-like OS. If you are using +Windows, your prompt will look something like `c:\source_code>` ### Installing Rails @@ -82,7 +84,7 @@ current version of Ruby installed: ```bash $ ruby -v -ruby 1.9.3p327 +ruby 1.9.3p385 ``` To install Rails, use the `gem install` command provided by RubyGems: @@ -132,17 +134,16 @@ application. Most of the work in this tutorial will happen in the `app/` folder, | File/Folder | Purpose | | ----------- | ------- | |app/|Contains the controllers, models, views, helpers, mailers and assets for your application. You'll focus on this folder for the remainder of this guide.| +|bin/|Contains the rails script that starts your app and can contain other scripts you use to deploy or run your application.| |config/|Configure your application's runtime rules, routes, database, and more. This is covered in more detail in [Configuring Rails Applications](configuring.html)| |config.ru|Rack configuration for Rack based servers used to start the application.| |db/|Contains your current database schema, as well as the database migrations.| -|doc/|In-depth documentation for your application.| |Gemfile<br />Gemfile.lock|These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see [the Bundler website](http://gembundler.com) | |lib/|Extended modules for your application.| |log/|Application log files.| |public/|The only folder seen to the world as-is. Contains the static files and compiled assets.| |Rakefile|This file locates and loads tasks that can be run from the command line. The task definitions are defined throughout the components of Rails. Rather than changing Rakefile, you should add your own tasks by adding files to the lib/tasks directory of your application.| |README.rdoc|This is a brief instruction manual for your application. You should edit this file to tell others what your application does, how to set it up, and so on.| -|script/|Contains the rails script that starts your app and can contain other scripts you use to deploy or run your application.| |test/|Unit tests, fixtures, and other test apparatus. These are covered in [Testing Rails Applications](testing.html)| |tmp/|Temporary files (like cache, pid and session files)| |vendor/|A place for all third-party code. In a typical Rails application, this includes Ruby Gems and the Rails source code (if you optionally install it into your project).| @@ -417,7 +418,7 @@ def create end ``` -The `render` method here is taking a very simple hash with a key of `text` and value of `params[:post].inspect`. The `params` method is the object which represents the parameters (or fields) coming in from the form. The `params` method returns a `HashWithIndifferentAccess` object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. +The `render` method here is taking a very simple hash with a key of `text` and value of `params[:post].inspect`. The `params` method is the object which represents the parameters (or fields) coming in from the form. The `params` method returns an `ActiveSupport::HashWithIndifferentAccess` object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following: @@ -582,9 +583,31 @@ content: </p> ``` -Finally, if you now go to -<http://localhost:3000/posts/new> you'll -be able to create a post. Try it! +If you now go to +<http://localhost:3000/posts/new> you'll *almost* be able to create a post. Try +it! You should get an error that looks like this: + + + +Rails has several security features that help you write secure applications, +and you're running into one of them now. This one is called +'strong_parameters,' which requires us to tell Rails exactly which parameters +we want to accept in our controllers. In this case, we want to allow the +'title' and 'text' parameters, so change your `create` controller action to +look like this: + +``` + def create + @post = Post.new(params[:post].permit(:title, :text)) + + @post.save + redirect_to action: :show, id: @post.id + end +``` + +See the `permit`? It allows us to accept both `title` and `text` in this +action. With this change, you should finally be able to create new `Post`s. +Visit <http://localhost:3000/posts/new> and give it a try!  @@ -710,10 +733,11 @@ class Post < ActiveRecord::Base end ``` -These changes will ensure that all posts have a title that is at least five characters long. -Rails can validate a variety of conditions in a model, including the presence or uniqueness of columns, their -format, and the existence of associated objects. Validations are covered in detail -in [Active Record Validations and Callbacks](active_record_validations_callbacks.html#validations-overview) +These changes will ensure that all posts have a title that is at least five +characters long. Rails can validate a variety of conditions in a model, +including the presence or uniqueness of columns, their format, and the +existence of associated objects. Validations are covered in detail in [Active +Record Validations](active_record_validations.html) With the validation now in place, when you call `@post.save` on an invalid post, it will return `false`. If you open `app/controllers/posts_controller.rb` @@ -728,7 +752,7 @@ def new end def create - @post = Post.new(params[:post]) + @post = Post.new(params[:post].permit(:title, :text)) if @post.save redirect_to action: :show, id: @post.id @@ -830,7 +854,7 @@ it look as follows: <h1>Editing post</h1> <%= form_for :post, url: { action: :update, id: @post.id }, -method: :put do |f| %> +method: :patch do |f| %> <% if @post.errors.any? %> <div id="errorExplanation"> <h2><%= pluralize(@post.errors.count, "error") %> prohibited @@ -863,8 +887,8 @@ method: :put do |f| %> This time we point the form to the `update` action, which is not defined yet but will be very soon. -The `method: :put` option tells Rails that we want this form to be -submitted via the `PUT` HTTP method which is the HTTP method you're expected to use to +The `method: :patch` option tells Rails that we want this form to be submitted +via the `PATCH` HTTP method which is the HTTP method you're expected to use to **update** resources according to the REST protocol. TIP: By default forms built with the _form_for_ helper are sent via `POST`. @@ -873,7 +897,7 @@ Next, we need to add the `update` action. The file `config/routes.rb` will need just one more line: ```ruby -put "posts/:id" => "posts#update" +patch "posts/:id" => "posts#update" ``` And then create the `update` action in `app/controllers/posts_controller.rb`: @@ -882,7 +906,7 @@ And then create the `update` action in `app/controllers/posts_controller.rb`: def update @post = Post.find(params[:id]) - if @post.update(params[:post]) + if @post.update(params[:post].permit(:title, :text)) redirect_to action: :show, id: @post.id else render 'edit' @@ -1051,7 +1075,7 @@ called `post_url` and `post_path` available to our application. These are precisely the methods that the `form_for` needs when editing a post, and so now you'll be able to update posts again. -NOTE: The `:as` option is available on the `post`, `put`, `delete` and `match` +NOTE: The `:as` option is available on the `post`, `patch`, `put`, `delete` and `match` routing methods also. ### Deleting Posts @@ -1145,7 +1169,7 @@ get "posts/new" post "posts" => "posts#create" get "posts/:id" => "posts#show", as: :post get "posts/:id/edit" => "posts#edit" -put "posts/:id" => "posts#update" +patch "posts/:id" => "posts#update" delete "posts/:id" => "posts#destroy" ``` @@ -1387,7 +1411,7 @@ Let's wire up the `create` in `app/controllers/comments_controller.rb`: class CommentsController < ApplicationController def create @post = Post.find(params[:post_id]) - @comment = @post.comments.create(params[:comment]) + @comment = @post.comments.create(params[:comment].permit(:commenter, :body)) redirect_to post_path(@post) end end @@ -1558,6 +1582,9 @@ Then you make the `app/views/posts/show.html.erb` look like the following: <%= @post.text %> </p> +<h2>Comments</h2> +<%= render @post.comments %> + <h2>Add a comment:</h2> <%= render "comments/form" %> diff --git a/guides/source/i18n.md b/guides/source/i18n.md index 2e61bea5ea..5304ca4285 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -102,7 +102,7 @@ The **translations load path** (`I18n.load_path`) is just a Ruby Array of paths NOTE: The backend will lazy-load these translations when a translation is looked up for the first time. This makes it possible to just swap the backend with something else even after translations have already been announced. -The default initializer `locale.rb` file has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines. +The default `application.rb` files has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines. ```ruby # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded. @@ -897,7 +897,7 @@ The I18n API will catch all of these exceptions when they are thrown in the back The reason for this is that during development you'd usually want your views to still render even though a translation is missing. -In other contexts you might want to change this behaviour, though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module or a class with `#call` method: +In other contexts you might want to change this behavior, though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module or a class with `#call` method: ```ruby module I18n @@ -927,7 +927,7 @@ else end ``` -Another example where the default behaviour is less desirable is the Rails TranslationHelper which provides the method `#t` (as well as `#translate`). When a `MissingTranslationData` exception occurs in this context, the helper wraps the message into a span with the CSS class `translation_missing`. +Another example where the default behavior is less desirable is the Rails TranslationHelper which provides the method `#t` (as well as `#translate`). When a `MissingTranslationData` exception occurs in this context, the helper wraps the message into a span with the CSS class `translation_missing`. To do so, the helper forces `I18n#translate` to raise exceptions no matter what exception handler is defined by setting the `:raise` option: diff --git a/guides/source/initialization.md b/guides/source/initialization.md index 457e28383d..8ba5fa4601 100644 --- a/guides/source/initialization.md +++ b/guides/source/initialization.md @@ -26,126 +26,16 @@ quickly. Launch! ------- -A Rails application is usually started with the command `rails server`. +Now we finally boot and initialize the app. It all starts with your app's +`bin/rails` executable. A Rails application is usually started by running +`rails console` or `rails server`. ### `bin/rails` -The actual `rails` command is kept in _bin/rails_: - -```ruby -#!/usr/bin/env ruby - -if File.exists?(File.join(File.expand_path('../../..', __FILE__), '.git')) - railties_path = File.expand_path('../../lib', __FILE__) - $:.unshift(railties_path) -end -require "rails/cli" -``` - -This file will first attempt to push the `railties/lib` directory if -present, and then requires `rails/cli`. - -### `railties/lib/rails/cli.rb` - -This file looks like this: - -```ruby -require 'rbconfig' -require 'rails/script_rails_loader' - -# If we are inside a Rails application this method performs an exec and thus -# the rest of this script is not run. -Rails::ScriptRailsLoader.exec_script_rails! - -require 'rails/ruby_version_check' -Signal.trap("INT") { puts; exit(1) } - -if ARGV.first == 'plugin' - ARGV.shift - require 'rails/commands/plugin_new' -else - require 'rails/commands/application' -end -``` - -The `rbconfig` file from the Ruby standard library provides us with the `RbConfig` class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in `railties/lib/rails/script_rails_loader`. - -```ruby -require 'pathname' - -module Rails - module ScriptRailsLoader - RUBY = File.join(*RbConfig::CONFIG.values_at("bindir", "ruby_install_name")) + RbConfig::CONFIG["EXEEXT"] - SCRIPT_RAILS = File.join('script', 'rails') - ... - - end -end -``` - -The `rails/script_rails_loader` file uses `RbConfig::Config` to obtain the `bin_dir` and `ruby_install_name` values for the configuration which together form the path to the Ruby interpreter. The `RbConfig::CONFIG["EXEEXT"]` will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in `exec_script_rails!`. As for the `SCRIPT_RAILS` constant, we'll see that when we get to the `in_rails_application?` method. - -Back in `rails/cli`, the next line is this: - -```ruby -Rails::ScriptRailsLoader.exec_script_rails! -``` - -This method is defined in `rails/script_rails_loader`: - -```ruby -def self.exec_script_rails! - cwd = Dir.pwd - return unless in_rails_application? || in_rails_application_subdirectory? - exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application? - Dir.chdir("..") do - # Recurse in a chdir block: if the search fails we want to be sure - # the application is generated in the original working directory. - exec_script_rails! unless cwd == Dir.pwd - end -rescue SystemCallError - # could not chdir, no problem just return -end -``` - -This method will first check if the current working directory (`cwd`) is a Rails application or a subdirectory of one. This is determined by the `in_rails_application?` method: - -```ruby -def self.in_rails_application? - File.exists?(SCRIPT_RAILS) -end -``` - -The `SCRIPT_RAILS` constant defined earlier is used here, with `File.exists?` checking for its presence in the current directory. If this method returns `false` then `in_rails_application_subdirectory?` will be used: - -```ruby -def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd)) - File.exists?(File.join(path, SCRIPT_RAILS)) || !path.root? && in_rails_application_subdirectory?(path.parent) -end -``` - -This climbs the directory tree until it reaches a path which contains a `script/rails` file. If a directory containing this file is reached then this line will run: - -```ruby -exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application? -``` - -This is effectively the same as running `ruby script/rails [arguments]`, where `[arguments]` at this point in time is simply "server". - -Rails Initialization --------------------- - -Only now we finally start the real initialization process, beginning -with `script/rails`. - -TIP: If you execute `script/rails` directly from your Rails app you will -skip executing all the code that we've just described. - -### `script/rails` - This file is as follows: ```ruby +#!/usr/bin/env ruby APP_PATH = File.expand_path('../../config/application', __FILE__) require File.expand_path('../../config/boot', __FILE__) require 'rails/commands' @@ -227,7 +117,7 @@ If we used `s` rather than `server`, Rails will use the `aliases` defined in the ```ruby when 'server' # Change to the application's path if there is no config.ru file in current dir. - # This allows us to run script/rails server from other directories, but still get + # This allows us to run `rails server` from other directories, but still get # the main config.ru and properly set the tmp directory. Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exists?(File.expand_path("config.ru")) diff --git a/guides/source/kindle/KINDLE.md b/guides/source/kindle/KINDLE.md index 08937e053e..8c4fad18aa 100644 --- a/guides/source/kindle/KINDLE.md +++ b/guides/source/kindle/KINDLE.md @@ -10,7 +10,7 @@ ## Resources * [Stack Overflow: Kindle Periodical Format](http://stackoverflow.com/questions/5379565/kindle-periodical-format) - * Example Periodical [.ncx](https://gist.github.com/808c971ed087b839d462) and [.opf](https://gist.github.com/d6349aa8488eca2ee6d0) + * Example Periodical [.ncx](https://gist.github.com/mipearson/808c971ed087b839d462) and [.opf](https://gist.github.com/mipearson/d6349aa8488eca2ee6d0) * [Kindle Publishing Guidelines](http://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines.pdf) * [KindleGen & Kindle Previewer](http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621) diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index fa303745b8..339008ab9e 100644 --- a/guides/source/layouts_and_rendering.md +++ b/guides/source/layouts_and_rendering.md @@ -97,7 +97,7 @@ NOTE: The actual rendering is done by subclasses of `ActionView::TemplateHandler ### Using `render` -In most cases, the `ActionController::Base#render` method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behaviour of `render`. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well. +In most cases, the `ActionController::Base#render` method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behavior of `render`. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well. TIP: If you want to see the exact results of a call to `render` without needing to inspect it in a browser, you can call `render_to_string`. This method takes exactly the same options as `render`, but it returns a string instead of sending a response back to the browser. @@ -695,72 +695,6 @@ To include `http://example.com/main.js`: <%= javascript_include_tag "http://example.com/main.js" %> ``` -If the application does not use the asset pipeline, the `:defaults` option loads jQuery by default: - -```erb -<%= javascript_include_tag :defaults %> -``` - -Outputting `script` tags such as this: - -```html -<script src="/javascripts/jquery.js"></script> -<script src="/javascripts/jquery_ujs.js"></script> -``` - -These two files for jQuery, `jquery.js` and `jquery_ujs.js` must be placed inside `public/javascripts` if the application doesn't use the asset pipeline. These files can be downloaded from the [jquery-rails repository on GitHub](https://github.com/indirect/jquery-rails/tree/master/vendor/assets/javascripts) - -WARNING: If you are using the asset pipeline, this tag will render a `script` tag for an asset called `defaults.js`, which would not exist in your application unless you've explicitly created it. - -And you can in any case override the `:defaults` expansion in `config/application.rb`: - -```ruby -config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js) -``` - -You can also define new defaults: - -```ruby -config.action_view.javascript_expansions[:projects] = %w(projects.js tickets.js) -``` - -And use them by referencing them exactly like `:defaults`: - -```erb -<%= javascript_include_tag :projects %> -``` - -When using `:defaults`, if an `application.js` file exists in `public/javascripts` it will be included as well at the end. - -Also, if the asset pipeline is disabled, the `:all` expansion loads every JavaScript file in `public/javascripts`: - -```erb -<%= javascript_include_tag :all %> -``` - -Note that your defaults of choice will be included first, so they will be available to all subsequently included files. - -You can supply the `:recursive` option to load files in subfolders of `public/javascripts` as well: - -```erb -<%= javascript_include_tag :all, recursive: true %> -``` - -If you're loading multiple JavaScript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify `cache: true` in your `javascript_include_tag`: - -```erb -<%= javascript_include_tag "main", "columns", cache: true %> -``` - -By default, the combined file will be delivered as `javascripts/all.js`. You can specify a location for the cached asset file instead: - -```erb -<%= javascript_include_tag "main", "columns", - cache: "cache/main/display" %> -``` - -You can even use dynamic paths such as `cache/#{current_site}/main/display`. - #### Linking to CSS Files with the `stylesheet_link_tag` The `stylesheet_link_tag` helper returns an HTML `<link>` tag for each source provided. @@ -797,33 +731,6 @@ By default, the `stylesheet_link_tag` creates links with `media="screen" rel="st <%= stylesheet_link_tag "main_print", media: "print" %> ``` -If the asset pipeline is disabled, the `all` option links every CSS file in `public/stylesheets`: - -```erb -<%= stylesheet_link_tag :all %> -``` - -You can supply the `:recursive` option to link files in subfolders of `public/stylesheets` as well: - -```erb -<%= stylesheet_link_tag :all, recursive: true %> -``` - -If you're loading multiple CSS files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify `cache: true` in your `stylesheet_link_tag`: - -```erb -<%= stylesheet_link_tag "main", "columns", cache: true %> -``` - -By default, the combined file will be delivered as `stylesheets/all.css`. You can specify a location for the cached asset file instead: - -```erb -<%= stylesheet_link_tag "main", "columns", - cache: "cache/main/display" %> -``` - -You can even use dynamic paths such as `cache/#{current_site}/main/display`. - #### Linking to Images with the `image_tag` The `image_tag` helper builds an HTML `<img />` tag to the specified file. By default, files are loaded from `public/images`. diff --git a/guides/source/migrations.md b/guides/source/migrations.md index 617e01bd15..d738d847e9 100644 --- a/guides/source/migrations.md +++ b/guides/source/migrations.md @@ -344,6 +344,16 @@ create_join_table :products, :categories, column_options: {null: true} will create the `product_id` and `category_id` with the `:null` option as `true`. +`create_join_table` also accepts a block, which you can use to add indices +(which are not created by default) or additional columns: + +```ruby +create_join_table :products, :categories do |t| + t.index :products + t.index :categories +end +``` + ### Changing Tables A close cousin of `create_table` is `change_table`, used for changing existing @@ -444,7 +454,7 @@ class ExampleMigration < ActiveRecord::Migration end ``` -Using `reversible` will insure that the instructions are executed in the +Using `reversible` will ensure that the instructions are executed in the right order too. If the previous example migration is reverted, the `down` block will be run after the `home_page_url` column is removed and right before the table `products` is dropped. @@ -474,7 +484,7 @@ class ExampleMigration < ActiveRecord::Migration t.references :category end - #add a foreign key + # add a foreign key execute <<-SQL ALTER TABLE products ADD CONSTRAINT fk_products_categories @@ -1011,7 +1021,7 @@ with foreign key constraints in the database. Although Active Record does not provide any tools for working directly with such features, the `execute` method can be used to execute arbitrary SQL. You -could also use some plugin like +could also use some gem like [foreigner](https://github.com/matthuhiggins/foreigner) which add foreign key support to Active Record (including support for dumping foreign keys in `db/schema.rb`). diff --git a/guides/source/nested_model_forms.md b/guides/source/nested_model_forms.md index 2b46a9d51e..b90b3bb5fc 100644 --- a/guides/source/nested_model_forms.md +++ b/guides/source/nested_model_forms.md @@ -56,7 +56,7 @@ end ### Custom model -As you might have inflected from this explanation, you _don’t_ necessarily need an ActiveRecord::Base model to use this functionality. The following examples are sufficient to enable the nested model form behaviour: +As you might have inflected from this explanation, you _don’t_ necessarily need an ActiveRecord::Base model to use this functionality. The following examples are sufficient to enable the nested model form behavior: #### Single associated object @@ -98,7 +98,7 @@ A nested model form will _only_ be built if the associated object(s) exist. This Consider the following typical RESTful controller which will prepare a new Person instance and its `address` and `projects` associations before rendering the `new` template: ```ruby -class PeopleController < ActionController:Base +class PeopleController < ApplicationController def new @person = Person.new @person.built_address diff --git a/guides/source/performance_testing.md b/guides/source/performance_testing.md deleted file mode 100644 index ee0059623c..0000000000 --- a/guides/source/performance_testing.md +++ /dev/null @@ -1,686 +0,0 @@ -Performance Testing Rails Applications -====================================== - -This guide covers the various ways of performance testing a Ruby on Rails -application. - -After reading this guide, you will know: - -* The various types of benchmarking and profiling metrics. -* How to generate performance and benchmarking tests. -* How to install and use a GC-patched Ruby binary to measure memory usage and object - allocation. -* The benchmarking information provided by Rails inside the log files. -* Various tools facilitating benchmarking and profiling. - -Performance testing is an integral part of the development cycle. It is very -important that you don't make your end users wait for too long before the page -is completely loaded. Ensuring a pleasant browsing experience for end users and -cutting the cost of unnecessary hardware is important for any non-trivial web -application. - --------------------------------------------------------------------------------- - -Performance Test Cases ----------------------- - -Rails performance tests are a special type of integration tests, designed for -benchmarking and profiling the test code. With performance tests, you can -determine where your application's memory or speed problems are coming from, -and get a more in-depth picture of those problems. - -In a freshly generated Rails application, `test/performance/browsing_test.rb` -contains an example of a performance test: - -```ruby -require 'test_helper' -require 'rails/performance_test_help' - -class BrowsingTest < ActionDispatch::PerformanceTest - # Refer to the documentation for all available options - # self.profile_options = { runs: 5, metrics: [:wall_time, :memory], - # output: 'tmp/performance', formats: [:flat] } - - test "homepage" do - get '/' - end -end -``` - -This example is a simple performance test case for profiling a GET request to -the application's homepage. - -### Generating Performance Tests - -Rails provides a generator called `performance_test` for creating new -performance tests: - -```bash -$ rails generate performance_test homepage -``` - -This generates `homepage_test.rb` in the `test/performance` directory: - -```ruby -require 'test_helper' -require 'rails/performance_test_help' - -class HomepageTest < ActionDispatch::PerformanceTest - # Refer to the documentation for all available options - # self.profile_options = { runs: 5, metrics: [:wall_time, :memory], - # output: 'tmp/performance', formats: [:flat] } - - test "homepage" do - get '/' - end -end -``` - -### Examples - -Let's assume your application has the following controller and model: - -```ruby -# routes.rb -root to: 'home#dashboard' -resources :posts - -# home_controller.rb -class HomeController < ApplicationController - def dashboard - @users = User.last_ten.includes(:avatars) - @posts = Post.all_today - end -end - -# posts_controller.rb -class PostsController < ApplicationController - def create - @post = Post.create(params[:post]) - redirect_to(@post) - end -end - -# post.rb -class Post < ActiveRecord::Base - before_save :recalculate_costly_stats - - def slow_method - # I fire gallzilion queries sleeping all around - end - - private - - def recalculate_costly_stats - # CPU heavy calculations - end -end -``` - -#### Controller Example - -Because performance tests are a special kind of integration test, you can use -the `get` and `post` methods in them. - -Here's the performance test for `HomeController#dashboard` and -`PostsController#create`: - -```ruby -require 'test_helper' -require 'rails/performance_test_help' - -class PostPerformanceTest < ActionDispatch::PerformanceTest - def setup - # Application requires logged-in user - login_as(:lifo) - end - - test "homepage" do - get '/dashboard' - end - - test "creating new post" do - post '/posts', post: { body: 'lifo is fooling you' } - end -end -``` - -You can find more details about the `get` and `post` methods in the -[Testing Rails Applications](testing.html) guide. - -#### Model Example - -Even though the performance tests are integration tests and hence closer to -the request/response cycle by nature, you can still performance test pure model -code. - -Performance test for `Post` model: - -```ruby -require 'test_helper' -require 'rails/performance_test_help' - -class PostModelTest < ActionDispatch::PerformanceTest - test "creation" do - Post.create body: 'still fooling you', cost: '100' - end - - test "slow method" do - # Using posts(:awesome) fixture - posts(:awesome).slow_method - end -end -``` - -### Modes - -Performance tests can be run in two modes: Benchmarking and Profiling. - -#### Benchmarking - -Benchmarking makes it easy to quickly gather a few metrics about each test run. -By default, each test case is run **4 times** in benchmarking mode. - -To run performance tests in benchmarking mode: - -```bash -$ rake test:benchmark -``` - -#### Profiling - -Profiling allows you to make an in-depth analysis of each of your tests by using -an external profiler. Depending on your Ruby interpreter, this profiler can be -native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each -test case is run **once** in profiling mode. - -To run performance tests in profiling mode: - -```bash -$ rake test:profile -``` - -### Metrics - -Benchmarking and profiling run performance tests and give you multiple metrics. -The availability of each metric is determined by the interpreter being used—none -of them support all metrics—and by the mode in use. A brief description of each -metric and their availability across interpreters/modes is given below. - -#### Wall Time - -Wall time measures the real world time elapsed during the test run. It is -affected by any other processes concurrently running on the system. - -#### Process Time - -Process time measures the time taken by the process. It is unaffected by any -other processes running concurrently on the same system. Hence, process time -is likely to be constant for any given performance test, irrespective of the -machine load. - -#### CPU Time - -Similar to process time, but leverages the more accurate CPU clock counter -available on the Pentium and PowerPC platforms. - -#### User Time - -User time measures the amount of time the CPU spent in user-mode, i.e. within -the process. This is not affected by other processes and by the time it possibly -spends blocked. - -#### Memory - -Memory measures the amount of memory used for the performance test case. - -#### Objects - -Objects measures the number of objects allocated for the performance test case. - -#### GC Runs - -GC Runs measures the number of times GC was invoked for the performance test case. - -#### GC Time - -GC Time measures the amount of time spent in GC for the performance test case. - -#### Metric Availability - -##### Benchmarking - -| Interpreter | Wall Time | Process Time | CPU Time | User Time | Memory | Objects | GC Runs | GC Time | -| ------------ | --------- | ------------ | -------- | --------- | ------ | ------- | ------- | ------- | -| **MRI** | yes | yes | yes | no | yes | yes | yes | yes | -| **REE** | yes | yes | yes | no | yes | yes | yes | yes | -| **Rubinius** | yes | no | no | no | yes | yes | yes | yes | -| **JRuby** | yes | no | no | yes | yes | yes | yes | yes | - -##### Profiling - -| Interpreter | Wall Time | Process Time | CPU Time | User Time | Memory | Objects | GC Runs | GC Time | -| ------------ | --------- | ------------ | -------- | --------- | ------ | ------- | ------- | ------- | -| **MRI** | yes | yes | no | no | yes | yes | yes | yes | -| **REE** | yes | yes | no | no | yes | yes | yes | yes | -| **Rubinius** | yes | no | no | no | no | no | no | no | -| **JRuby** | yes | no | no | no | no | no | no | no | - -NOTE: To profile under JRuby you'll need to run `export JRUBY_OPTS="-Xlaunch.inproc=false --profile.api"` -**before** the performance tests. - -### Understanding the Output - -Performance tests generate different outputs inside `tmp/performance` directory -depending on their mode and metric. - -#### Benchmarking - -In benchmarking mode, performance tests generate two types of outputs. - -##### Command Line - -This is the primary form of output in benchmarking mode. Example: - -```bash -BrowsingTest#test_homepage (31 ms warmup) - wall_time: 6 ms - memory: 437.27 KB - objects: 5,514 - gc_runs: 0 - gc_time: 19 ms -``` - -##### CSV Files - -Performance test results are also appended to `.csv` files inside `tmp/performance`. -For example, running the default `BrowsingTest#test_homepage` will generate -following five files: - -* BrowsingTest#test_homepage_gc_runs.csv -* BrowsingTest#test_homepage_gc_time.csv -* BrowsingTest#test_homepage_memory.csv -* BrowsingTest#test_homepage_objects.csv -* BrowsingTest#test_homepage_wall_time.csv - -As the results are appended to these files each time the performance tests are -run in benchmarking mode, you can collect data over a period of time. This can -be very helpful in analyzing the effects of code changes. - -Sample output of `BrowsingTest#test_homepage_wall_time.csv`: - -```bash -measurement,created_at,app,rails,ruby,platform -0.00738224999999992,2009-01-08T03:40:29Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00755874999999984,2009-01-08T03:46:18Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00762099999999993,2009-01-08T03:49:25Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00603075000000008,2009-01-08T04:03:29Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00619899999999995,2009-01-08T04:03:53Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00755449999999991,2009-01-08T04:04:55Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00595999999999997,2009-01-08T04:05:06Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00740450000000004,2009-01-09T03:54:47Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00603150000000008,2009-01-09T03:54:57Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -0.00771250000000012,2009-01-09T15:46:03Z,,3.0.0,ruby-1.8.7.249,x86_64-linux -``` - -#### Profiling - -In profiling mode, performance tests can generate multiple types of outputs. -The command line output is always presented but support for the others is -dependent on the interpreter in use. A brief description of each type and -their availability across interpreters is given below. - -##### Command Line - -This is a very basic form of output in profiling mode: - -```bash -BrowsingTest#test_homepage (58 ms warmup) - process_time: 63 ms - memory: 832.13 KB - objects: 7,882 -``` - -##### Flat - -Flat output shows the metric—time, memory, etc—measure in each method. -[Check Ruby-Prof documentation for a better explanation](http://ruby-prof.rubyforge.org/files/examples/flat_txt.html). - -##### Graph - -Graph output shows the metric measure in each method, which methods call it and -which methods it calls. [Check Ruby-Prof documentation for a better explanation](http://ruby-prof.rubyforge.org/files/examples/graph_txt.html). - -##### Tree - -Tree output is profiling information in calltree format for use by [kcachegrind](http://kcachegrind.sourceforge.net/html/Home.html) -and similar tools. - -##### Output Availability - -| | Flat | Graph | Tree | -| ------------ | ---- | ----- | ---- | -| **MRI** | yes | yes | yes | -| **REE** | yes | yes | yes | -| **Rubinius** | yes | yes | no | -| **JRuby** | yes | yes | no | - -### Tuning Test Runs - -Test runs can be tuned by setting the `profile_options` class variable on your -test class. - -```ruby -require 'test_helper' -require 'rails/performance_test_help' - -class BrowsingTest < ActionDispatch::PerformanceTest - self.profile_options = { runs: 5, metrics: [:wall_time, :memory] } - - test "homepage" - get '/' - end -end -``` - -In this example, the test would run 5 times and measure wall time and memory. -There are a few configurable options: - -| Option | Description | Default | Mode | -| ---------- | ------------------------------------------ | ----------------------------- | --------- | -| `:runs` | Number of runs. | Benchmarking: 4, Profiling: 1 | Both | -| `:output` | Directory to use when writing the results. | `tmp/performance` | Both | -| `:metrics` | Metrics to use. | See below. | Both | -| `:formats` | Formats to output to. | See below. | Profiling | - -Metrics and formats have different defaults depending on the interpreter in use. - -| Interpreter | Mode | Default metrics | Default formats | -| -------------- | ------------ | ------------------------------------------------------- | ----------------------------------------------- | -| **MRI/REE** | Benchmarking | `[:wall_time, :memory, :objects, :gc_runs, :gc_time]` | N/A | -| | Profiling | `[:process_time, :memory, :objects]` | `[:flat, :graph_html, :call_tree, :call_stack]` | -| **Rubinius** | Benchmarking | `[:wall_time, :memory, :objects, :gc_runs, :gc_time]` | N/A | -| | Profiling | `[:wall_time]` | `[:flat, :graph]` | -| **JRuby** | Benchmarking | `[:wall_time, :user_time, :memory, :gc_runs, :gc_time]` | N/A | -| | Profiling | `[:wall_time]` | `[:flat, :graph]` | - -As you've probably noticed by now, metrics and formats are specified using a -symbol array with each name [underscored.](http://api.rubyonrails.org/classes/String.html#method-i-underscore) - -### Performance Test Environment - -Performance tests are run in the `test` environment. But running performance -tests will set the following configuration parameters: - -```bash -ActionController::Base.perform_caching = true -ActiveSupport::Dependencies.mechanism = :require -Rails.logger.level = ActiveSupport::Logger::INFO -``` - -As `ActionController::Base.perform_caching` is set to `true`, performance tests -will behave much as they do in the `production` environment. - -### Installing GC-Patched MRI - -To get the best from Rails' performance tests under MRI, you'll need to build -a special Ruby binary with some super powers. - -The recommended patches for each MRI version are: - -| Version | Patch | -| --------------- | --------- | -| 1.8.6 | ruby186gc | -| 1.8.7 | ruby187gc | -| 1.9.2 and above | gcdata | - -All of these can be found on [RVM's _patches_ directory](https://github.com/wayneeseguin/rvm/tree/master/patches/ruby) -under each specific interpreter version. - -Concerning the installation itself, you can either do this easily by using -[RVM](http://rvm.beginrescueend.com) or you can build everything from source, -which is a little bit harder. - -#### Install Using RVM - -The process of installing a patched Ruby interpreter is very easy if you let RVM -do the hard work. All of the following RVM commands will provide you with a -patched Ruby interpreter: - -```bash -$ rvm install 1.9.2-p180 --patch gcdata -$ rvm install 1.8.7 --patch ruby187gc -$ rvm install 1.9.2-p180 --patch ~/Downloads/downloaded_gcdata_patch.patch -``` - -You can even keep your regular interpreter by assigning a name to the patched -one: - -```bash -$ rvm install 1.9.2-p180 --patch gcdata --name gcdata -$ rvm use 1.9.2-p180 # your regular ruby -$ rvm use 1.9.2-p180-gcdata # your patched ruby -``` - -And it's done! You have installed a patched Ruby interpreter. - -#### Install From Source - -This process is a bit more complicated, but straightforward nonetheless. If -you've never compiled a Ruby binary before, follow these steps to build a -Ruby binary inside your home directory. - -##### Download and Extract - -```bash -$ mkdir rubygc -$ wget <the version you want from ftp://ftp.ruby-lang.org/pub/ruby> -$ tar -xzvf <ruby-version.tar.gz> -$ cd <ruby-version> -``` - -##### Apply the Patch - -```bash -$ curl http://github.com/wayneeseguin/rvm/raw/master/patches/ruby/1.9.2/p180/gcdata.patch | patch -p0 # if you're on 1.9.2! -$ curl http://github.com/wayneeseguin/rvm/raw/master/patches/ruby/1.8.7/ruby187gc.patch | patch -p0 # if you're on 1.8.7! -``` - -##### Configure and Install - -The following will install Ruby in your home directory's `/rubygc` directory. -Make sure to replace `<homedir>` with a full patch to your actual home -directory. - -```bash -$ ./configure --prefix=/<homedir>/rubygc -$ make && make install -``` - -##### Prepare Aliases - -For convenience, add the following lines in your `~/.profile`: - -```bash -alias gcruby='~/rubygc/bin/ruby' -alias gcrake='~/rubygc/bin/rake' -alias gcgem='~/rubygc/bin/gem' -alias gcirb='~/rubygc/bin/irb' -alias gcrails='~/rubygc/bin/rails' -``` - -Don't forget to use your aliases from now on. - -### Using Ruby-Prof on MRI and REE - -Add Ruby-Prof to your applications' Gemfile if you want to benchmark/profile -under MRI or REE: - -```ruby -gem 'ruby-prof' -``` - -Now run `bundle install` and you're ready to go. - -Command Line Tools ------------------- - -Writing performance test cases could be an overkill when you are looking for one -time tests. Rails ships with two command line tools that enable quick and dirty -performance testing: - -### `benchmarker` - -Usage: - -```bash -Usage: rails benchmarker 'Ruby.code' 'Ruby.more_code' ... [OPTS] - -r, --runs N Number of runs. - Default: 4 - -o, --output PATH Directory to use when writing the results. - Default: tmp/performance - -m, --metrics a,b,c Metrics to use. - Default: wall_time,memory,objects,gc_runs,gc_time -``` - -Example: - -```bash -$ rails benchmarker 'Item.all' 'CouchItem.all' --runs 3 --metrics wall_time,memory -``` - -### `profiler` - -Usage: - -```bash -Usage: rails profiler 'Ruby.code' 'Ruby.more_code' ... [OPTS] - -r, --runs N Number of runs. - Default: 1 - -o, --output PATH Directory to use when writing the results. - Default: tmp/performance - -m, --metrics a,b,c Metrics to use. - Default: process_time,memory,objects - -f, --formats x,y,z Formats to output to. - Default: flat,graph_html,call_tree -``` - -Example: - -```bash -$ rails profiler 'Item.all' 'CouchItem.all' --runs 2 --metrics process_time --formats flat -``` - -NOTE: Metrics and formats vary from interpreter to interpreter. Pass `--help` to -each tool to see the defaults for your interpreter. - -Helper Methods --------------- - -Rails provides various helper methods inside Active Record, Action Controller -and Action View to measure the time taken by a given piece of code. The method -is called `benchmark()` in all the three components. - -### Model - -```ruby -Project.benchmark("Creating project") do - project = Project.create("name" => "stuff") - project.create_manager("name" => "David") - project.milestones << Milestone.all -end -``` - -This benchmarks the code enclosed in the `Project.benchmark("Creating project") do...end` -block and prints the result to the log file: - -```ruby -Creating project (185.3ms) -``` - -Please refer to the [API docs](http://api.rubyonrails.org/classes/ActiveSupport/Benchmarkable.html#method-i-benchmark) -for additional options to `benchmark()`. - -### Controller - -Similarly, you could use this helper method inside [controllers.](http://api.rubyonrails.org/classes/ActiveSupport/Benchmarkable.html) - -```ruby -def process_projects - benchmark("Processing projects") do - Project.process(params[:project_ids]) - Project.update_cached_projects - end -end -``` - -NOTE: `benchmark` is a class method inside controllers. - -### View - -And in [views](http://api.rubyonrails.org/classes/ActiveSupport/Benchmarkable.html:) - -```erb -<% benchmark("Showing projects partial") do %> - <%= render @projects %> -<% end %> -``` - -Request Logging ---------------- - -Rails log files contain very useful information about the time taken to serve -each request. Here's a typical log file entry: - -```bash -Processing ItemsController#index (for 127.0.0.1 at 2009-01-08 03:06:39) [GET] -Rendering template within layouts/items -Rendering items/index -Completed in 5ms (View: 2, DB: 0) | 200 OK [http://0.0.0.0/items] -``` - -For this section, we're only interested in the last line: - -```bash -Completed in 5ms (View: 2, DB: 0) | 200 OK [http://0.0.0.0/items] -``` - -This data is fairly straightforward to understand. Rails uses millisecond(ms) as -the metric to measure the time taken. The complete request spent 5 ms inside -Rails, out of which 2 ms were spent rendering views and none was spent -communication with the database. It's safe to assume that the remaining 3 ms -were spent inside the controller. - -Michael Koziarski has an [interesting blog post](http://www.therailsway.com/2009/1/6/requests-per-second) -explaining the importance of using milliseconds as the metric. - -Useful Links ------------- - -### Rails Plugins and Gems - -* [Rails Analyzer](http://rails-analyzer.rubyforge.org) -* [Rails Footnotes](https://github.com/josevalim/rails-footnotes/tree/master) -* [Query Reviewer](https://github.com/nesquena/query_reviewer) -* [MiniProfiler](http://www.miniprofiler.com) - -### Generic Tools - -* [httperf](http://www.hpl.hp.com/research/linux/httperf/) -* [ab](http://httpd.apache.org/docs/2.2/programs/ab.html) -* [JMeter](http://jakarta.apache.org/jmeter/) -* [kcachegrind](http://kcachegrind.sourceforge.net/html/Home.html) - -### Tutorials and Documentation - -* [ruby-prof API Documentation](http://ruby-prof.rubyforge.org) -* [Request Profiling Railscast](http://railscasts.com/episodes/98-request-profiling) - Outdated, but useful for understanding call graphs. - -Commercial Products -------------------- - -Rails has been lucky to have a few companies dedicated to Rails-specific -performance tools. A couple of those are: - -* [New Relic](http://www.newrelic.com) -* [Scout](http://scoutapp.com) diff --git a/guides/source/plugins.md b/guides/source/plugins.md index f8f04c3c67..695f25f8a9 100644 --- a/guides/source/plugins.md +++ b/guides/source/plugins.md @@ -86,7 +86,7 @@ Run `rake` to run the test. This test should fail because we haven't implemented Great - now you are ready to start development. -Then in `lib/yaffle.rb` require `lib/core_ext`: +Then in `lib/yaffle.rb` add `require "yaffle/core_ext"`: ```ruby # yaffle/lib/yaffle.rb diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index 9e694acb98..77138d8871 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -34,7 +34,6 @@ Rails templates API is very self explanatory and easy to understand. Here's an e ```ruby # template.rb -run "rm public/index.html" generate(:scaffold, "person name:string") route "root to: 'people#index'" rake("db:migrate") @@ -158,10 +157,10 @@ generate(:scaffold, "person", "name:string", "address:text", "age:number") ### run(command) -Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `public/index.html` file: +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `README.rdoc` file: ```ruby -run "rm public/index.html" +run "rm README.rdoc" ``` ### rake(command, options = {}) @@ -180,7 +179,7 @@ rake "db:migrate", env: 'production' ### route(routing_code) -Adds a routing entry to the `config/routes.rb` file. In above steps, we generated a person scaffold and also removed `public/index.html`. Now to make `PeopleController#index` as the default page for the application: +Adds a routing entry to the `config/routes.rb` file. In above steps, we generated a person scaffold and also removed `README.rdoc`. Now to make `PeopleController#index` as the default page for the application: ```ruby route "root to: 'person#index'" diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md index a6119eb433..d8477d89e3 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -137,7 +137,6 @@ use ActionDispatch::ParamsParser use Rack::Head use Rack::ConditionalGet use Rack::ETag -use ActionDispatch::BestStandardsSupport run MyApp::Application.routes ``` @@ -215,7 +214,6 @@ And to remove browser related middleware, ```ruby # config/application.rb -config.middleware.delete "ActionDispatch::BestStandardsSupport" config.middleware.delete "Rack::MethodOverride" ``` @@ -307,10 +305,6 @@ Much of Action Controller's functionality is implemented as Middlewares. The fol * Adds ETag header on all String bodies. ETags are used to validate cache. - **`ActionDispatch::BestStandardsSupport`** - -* Enables “best standards support” so that IE8 renders some elements correctly. - TIP: It's possible to use any of the above middlewares in your custom Rack stack. ### Using Rack Builder diff --git a/guides/source/routing.md b/guides/source/routing.md index 14f23d4020..4614169653 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -832,6 +832,19 @@ will recognize incoming paths beginning with `/photos` but route to the `Images` NOTE: Use `photos_path`, `new_photo_path`, etc. to generate paths for this resource. +For namespaced controllers you can use the directory notation. For example: + +```ruby +resources :user_permissions, controller: 'admin/user_permissions' +``` + +This will route to the `Admin::UserPermissions` controller. + +NOTE: Only the directory notation is supported. specifying the +controller with ruby constant notation (eg. `:controller => +'Admin::UserPermissions'`) can lead to routing problems and results in +a warning. + ### Specifying Constraints You can use the `:constraints` option to specify a required format on the implicit `id`. For example: diff --git a/guides/source/security.md b/guides/source/security.md index 0b0cfe69c4..769bd130be 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -9,7 +9,6 @@ After reading this guide, you will know: * The concept of sessions in Rails, what to put in there and popular attack methods. * How just visiting a site can be a security problem (with CSRF). * What you have to pay attention to when working with files or providing an administration interface. -* The Rails-specific mass assignment problem. * How to manage users: Logging in and out and attack methods on all layers. * And the most popular injection attack methods. @@ -210,7 +209,7 @@ The HTTP protocol basically provides two main types of requests - GET and POST ( * The interaction _changes the state_ of the resource in a way that the user would perceive (e.g., a subscription to a service), or * The user is _held accountable for the results_ of the interaction. -If your web application is RESTful, you might be used to additional HTTP verbs, such as PUT or DELETE. Most of today's web browsers, however do not support them - only GET and POST. Rails uses a hidden `_method` field to handle this barrier. +If your web application is RESTful, you might be used to additional HTTP verbs, such as PATCH, PUT or DELETE. Most of today's web browsers, however do not support them - only GET and POST. Rails uses a hidden `_method` field to handle this barrier. _POST requests can be sent automatically, too_. Here is an example for a link which displays www.harmless.com as destination in the browser's status bar. In fact it dynamically creates a new form that sends a POST request. diff --git a/guides/source/testing.md b/guides/source/testing.md index 7747318d32..540197e6e7 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -39,10 +39,10 @@ Rails creates a `test` folder for you as soon as you create a Rails project usin ```bash $ ls -F test -fixtures/ functional/ integration/ performance/ test_helper.rb unit/ +fixtures/ functional/ integration/ test_helper.rb unit/ ``` -The `unit` directory is meant to hold tests for your models, the `functional` directory is meant to hold tests for your controllers, the `integration` directory is meant to hold tests that involve any number of controllers interacting, and the `performance` directory is meant for performance tests. +The `unit` directory is meant to hold tests for your models, the `functional` directory is meant to hold tests for your controllers and the `integration` directory is meant to hold tests that involve any number of controllers interacting. Fixtures are a way of organizing test data; they reside in the `fixtures` folder. @@ -760,14 +760,12 @@ You don't need to set up and run your tests by hand on a test-by-test basis. Rai | Tasks | Description | | ------------------------------- | ----------- | | `rake test` | Runs all unit, functional and integration tests. You can also simply run `rake` as the _test_ target is the default.| -| `rake test:benchmark` | Benchmark the performance tests| | `rake test:controllers` | Runs all the controller tests from `test/controllers`| | `rake test:functionals` | Runs all the functional tests from `test/controllers`, `test/mailers`, and `test/functional`| | `rake test:helpers` | Runs all the helper tests from `test/helpers`| | `rake test:integration` | Runs all the integration tests from `test/integration`| | `rake test:mailers` | Runs all the mailer tests from `test/mailers`| | `rake test:models` | Runs all the model tests from `test/models`| -| `rake test:profile` | Profile the performance tests| | `rake test:recent` | Tests recent changes| | `rake test:uncommitted` | Runs all the tests which are uncommitted. Supports Subversion and Git| | `rake test:units` | Runs all the unit tests from `test/models`, `test/helpers`, and `test/unit`| @@ -776,10 +774,13 @@ You don't need to set up and run your tests by hand on a test-by-test basis. Rai Brief Note About `Test::Unit` ----------------------------- -Ruby ships with a boat load of libraries. One little gem of a library is `Test::Unit`, a framework for unit testing in Ruby. All the basic assertions discussed above are actually defined in `Test::Unit::Assertions`. The class `ActiveSupport::TestCase` which we have been using in our unit and functional tests extends `Test::Unit::TestCase`, allowing +Ruby ships with a boat load of libraries. Ruby 1.8 provides `Test::Unit`, a framework for unit testing in Ruby. All the basic assertions discussed above are actually defined in `Test::Unit::Assertions`. The class `ActiveSupport::TestCase` which we have been using in our unit and functional tests extends `Test::Unit::TestCase`, allowing us to use all of the basic assertions in our tests. +Ruby 1.9 introduced `MiniTest`, an updated version of `Test::Unit` which provides a backwards compatible API for `Test::Unit`. You could also use `MiniTest` in Ruby 1.8 by installing the `minitest` gem. + NOTE: For more information on `Test::Unit`, refer to [test/unit Documentation](http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/) +For more information on `MiniTest`, refer to [Minitest](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/minitest/unit/rdoc/) Setup and Teardown ------------------ @@ -945,7 +946,7 @@ Cheers! This is the right time to understand a little more about writing tests for your mailers. The line `ActionMailer::Base.delivery_method = :test` in `config/environments/test.rb` sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (`ActionMailer::Base.deliveries`). -However often in unit tests, mails will not actually be sent, simply constructed, as in the example above, where the precise content of the email is checked against what it should be. +This way, emails are not actually sent, simply constructed. The precise content of the email can then be checked against what is expected, as in the example above. ### Functional Testing diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index b4a59fe3da..915a008a92 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -16,11 +16,11 @@ The best way to be sure that your application still works after upgrading is to Rails generally stays close to the latest released Ruby version when it's released: -* Rails 3 and above requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. -* Rails 3.2.x will be the last branch to support Ruby 1.8.7. -* Rails 4 will support only Ruby 1.9.3. +* Rails 3 and above require Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially. You should upgrade as early as possible. +* Rails 3.2.x is the last branch to support Ruby 1.8.7. +* Rails 4 prefers Ruby 2.0 and requires 1.9.3 or newer. -TIP: Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition has these fixed since the release of 1.8.7-2010.02. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults, so if you want to use 1.9.x, jump on to 1.9.2 or 1.9.3 for smooth sailing. +TIP: Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition has these fixed since the release of 1.8.7-2010.02. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults, so if you want to use 1.9.x, jump straight to 1.9.3 for smooth sailing. Upgrading from Rails 3.2 to Rails 4.0 ------------------------------------- @@ -45,6 +45,12 @@ Rails 4.0 no longer supports loading plugins from `vendor/plugins`. You must rep * Rails 4.0 has changed `serialized_attributes` and `attr_readonly` to class methods only. Now you shouldn't use instance methods, it's deprecated. You must change them, e.g. `self.serialized_attributes` to `self.class.serialized_attributes`. +* Rails 4.0 has removed `attr_accessible` and `attr_protected` feature in favor of Strong Parameters. You can use the [Protected Attributes gem](https://github.com/rails/protected_attributes) to a smoothly upgrade path. + +### Active Resource + +Rails 4.0 extracted Active Resource to its our gem. If you still need the feature you can add the [Active Resource gem](https://github.com/rails/activeresource) in your Gemfile. + ### Active Model * Rails 4.0 has changed how errors attach with the `ActiveModel::Validations::ConfirmationValidator`. Now when confirmation validations fail the error will be attached to `:#{attribute}_confirmation` instead of `attribute`. @@ -82,6 +88,19 @@ becomes get 'こんにちは', controller: 'welcome', action: 'index' ``` +* Rails 4.0 has removed ActionDispatch::BestStandardsSupport middleware, !DOCTYPE html already triggers standards mode per http://msdn.microsoft.com/en-us/library/jj676915(v=vs.85).aspx and ChromeFrame header has been moved to `config.action_dispatch.default_headers` + +Remember you must also remove any references to the middleware from your application code, for example: + +```ruby +# Raise exception +config.middleware.insert_before(Rack::Lock, ActionDispatch::BestStandardsSupport) +``` + +Also check your environment settings for `config.action_dispatch.best_standards_support` and remove it if present. + +* In Rails 4.0, precompiling assets no longer automatically copies non-JS/CSS assets from `vendor/assets` and `lib/assets`. Rails application and engine developers should put these assets in `app/assets` or configure `config.assets.precompile`. + ### Active Support Rails 4.0 removes the `j` alias for `ERB::Util#json_escape` since `j` is already used for `ActionView::Helpers::JavaScriptHelper#escape_javascript`. diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index a7ca531123..7c4192ee26 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -51,7 +51,7 @@ with an id of `results`. Rails provides quite a bit of built-in support for building web pages with this technique. You rarely have to write this code yourself. The rest of this guide -will show you how Rails can help you write web sites in this manner, but it's +will show you how Rails can help you write websites in this way, but it's all built on top of this fairly simple technique. Unobtrusive JavaScript @@ -111,7 +111,7 @@ paintIt = (element, backgroundColor, textColor) -> element.style.color = textColor $ -> - $("a[data-color]").click -> + $("a[data-background-color]").click -> backgroundColor = $(this).data("background-color") textColor = $(this).data("text-color") paintIt(this, backgroundColor, textColor) |
