diff options
Diffstat (limited to 'guides/source')
32 files changed, 229 insertions, 1097 deletions
diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index 597ac99be0..52571fab60 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -68,6 +68,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 +86,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 @@ -142,6 +145,7 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ * BufferedLogger is deprecated. Use ActiveSupport::Logger, or the logger from Ruby stdlib. +* Deprecate `assert_present` and `assert_blank` in favor of `assert object.blank?` and `assert object.present?` Action Pack ----------- @@ -150,6 +154,8 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt ### Notable changes +* Change the stylesheet of exception pages for development mode. Additionally display also the line of code and fragment that raised the exception in all exceptions pages. + ### Deprecations diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 46ff9027fd..cc80334af3 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -114,7 +114,7 @@ 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 @@ -174,10 +174,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 +194,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 ``` diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 795afd0150..7c6ef52f4a 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: diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md index 883c2dda4a..062bcd49f4 100644 --- a/guides/source/active_record_basics.md +++ b/guides/source/active_record_basics.md @@ -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 ``` @@ -277,7 +277,7 @@ value, like so: ```ruby user = User.find_by_name('David') -user.update_attributes(name: 'Dave') +user.update(name: 'Dave') ``` This is most useful when updating several attributes at once. If, on the other @@ -307,10 +307,10 @@ models and validate that an attribute value is not empty, is unique and not already in the database, follows a specific format and many more. Validation is a very important issue to consider when persisting to database, so -the methods `create`, `save` and `update_attributes` take it into account when +the methods `create`, `save` and `update` take it into account when running: they return `false` when validation fails and they didn't actually perform any operation on database. All of these have a bang counterpart (that -is, `create!`, `save!` and `update_attributes!`), which are stricter in that +is, `create!`, `save!` and `update!`), which are stricter in that they raise the exception `ActiveRecord::RecordInvalid` if validation fails. A quick example to illustrate: diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index 0a93f61f6d..3747b00b82 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -159,8 +159,8 @@ The following methods trigger callbacks: * `toggle!` * `update` * `update_attribute` -* `update_attributes` -* `update_attributes!` +* `update` +* `update!` * `valid?` Additionally, the `after_find` callback is triggered by the following finder methods: @@ -168,7 +168,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 +175,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 ------------------ diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 24f98f68ca..62d6294ae5 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")` diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index 822d12aa3a..a911d6b941 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -117,11 +117,11 @@ database only if the object is valid: * `save` * `save!` * `update` -* `update_attributes` -* `update_attributes!` +* `update` +* `update!` The bang versions (e.g. `save!`) raise an exception if the record is invalid. -The non-bang versions don't: `save` and `update_attributes` return `false`, +The non-bang versions don't: `save` and `update` return `false`, `create` and `update` just return the objects. ### Skipping Validations @@ -656,8 +656,6 @@ class Coffee < ActiveRecord::Base end ``` -TIP: `:allow_nil` is ignored by the presence validator. - ### `:allow_blank` The `:allow_blank` option is similar to the `:allow_nil` option. This option @@ -673,8 +671,6 @@ Topic.create("title" => "").valid? # => true Topic.create("title" => nil).valid? # => true ``` -TIP: `:allow_blank` is ignored by the presence validator. - ### `:message` As you've already seen, the `:message` option lets you specify the message that diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 23736020ec..3c1bb0f132 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. @@ -1449,11 +1431,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 ``` @@ -2413,9 +2394,9 @@ or yields them in turn if a block is passed: ```html+erb <% sample.in_groups_of(3) do |a, b, c| %> <tr> - <td><%=h a %></td> - <td><%=h b %></td> - <td><%=h c %></td> + <td><%= a %></td> + <td><%= b %></td> + <td><%= c %></td> </tr> <% end %> ``` diff --git a/guides/source/active_support_instrumentation.md b/guides/source/active_support_instrumentation.md index cf5a51fc5b..6b3be69942 100644 --- a/guides/source/active_support_instrumentation.md +++ b/guides/source/active_support_instrumentation.md @@ -432,7 +432,7 @@ from block args like this: ```ruby ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args| - event = ActiveSupport::Notification::Event.new args + event = ActiveSupport::Notifications::Event.new *args event.name # => "process_action.action_controller" event.duration # => 10 (in milliseconds) diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index b302ef76c6..fffa31927d 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -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..0228d463cf 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 @@ -196,10 +108,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 746226fa96..12d39ea1cc 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 @@ -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::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, ActionDispatch::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, ActionDispatch::BestStandardsSupport Application root /home/foobar/commandsapp Environment development Database adapter sqlite3 @@ -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 6e93932d49..cd0b99b177 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`. @@ -197,7 +196,7 @@ Every Rails application comes with a standard set of middleware which it uses in * `Rails::Rack::Logger` notifies the logs that the request has began. After request is complete, flushes all the logs. * `ActionDispatch::ShowExceptions` rescues any exception returned by the application and renders nice exception pages if the request is local or if `config.consider_all_requests_local` is set to `true`. If `config.action_dispatch.show_exceptions` is set to `false`, exceptions will be raised regardless. * `ActionDispatch::RequestId` makes a unique X-Request-Id header available to the response and enables the `ActionDispatch::Request#uuid` method. -* `ActionDispatch::RemoteIp` checks for IP spoofing attacks. Configurable with the `config.action_dispatch.ip_spoofing_check` and `config.action_dispatch.trusted_proxies` settings. +* `ActionDispatch::RemoteIp` checks for IP spoofing attacks and gets valid `client_ip` from request headers. Configurable with the `config.action_dispatch.ip_spoofing_check`, and `config.action_dispatch.trusted_proxies` options. * `Rack::Sendfile` intercepts responses whose body is being served from a file and replaces it with a server specific X-Sendfile header. Configurable with `config.action_dispatch.x_sendfile_header`. * `ActionDispatch::Callbacks` runs the prepare callbacks before serving the request. * `ActiveRecord::ConnectionAdapters::ConnectionManagement` cleans active connections after each request, unless the `rack.test` key in the request environment is set to `true`. @@ -304,6 +303,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.raise_on_unpermitted_parameters` enables raising an exception if parameters that are not explicitly permitted are found. The default value is `true` in development and test environments, `false` otherwise. + ### 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. @@ -583,7 +584,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. diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index ce2a5a4902..baef620c6c 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -214,7 +214,9 @@ Rails follows a simple set of coding style conventions: * Prefer `&&`/`||` over `and`/`or`. * Prefer class << self over self.method for class methods. * Use `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`. -* Use a = b and not a=b. +* 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. @@ -403,7 +405,7 @@ following: ```bash $ git fetch upstream -$ git checkout my_pull_request +$ git checkout my_pull_request $ git rebase upstream/master $ git rebase -i 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 2e90e8728c..5531dee343 100644 --- a/guides/source/debugging_rails_applications.md +++ b/guides/source/debugging_rails_applications.md @@ -29,7 +29,7 @@ The `debug` helper will return a \<pre>-tag that renders the object using the YA <%= debug @post %> <p> <b>Title:</b> - <%=h @post.title %> + <%= @post.title %> </p> ``` @@ -58,7 +58,7 @@ Displaying an instance variable, or any other object or method, in YAML format c <%= simple_format @post.to_yaml %> <p> <b>Title:</b> - <%=h @post.title %> + <%= @post.title %> </p> ``` @@ -88,7 +88,7 @@ Another useful method for displaying object values is `inspect`, especially when <%= [1, 2, 3, 4, 5].inspect %> <p> <b>Title:</b> - <%=h @post.title %> + <%= @post.title %> </p> ``` @@ -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/documents.yaml b/guides/source/documents.yaml index e779407fab..13f982d7e2 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. diff --git a/guides/source/engines.md b/guides/source/engines.md index 116a7e67cd..f35233993c 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. @@ -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,7 +259,7 @@ 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. @@ -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 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. 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. @@ -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,10 @@ 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. 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 +662,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 @@ -800,7 +801,7 @@ module Blorgh::Concerns::Models::Post 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 end @@ -914,9 +915,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 8ab44ea0bb..b8681d493a 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -1,7 +1,7 @@ Form Helpers ============ -Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails deals away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use. +Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails does away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use. After reading this guide, you will know: @@ -148,7 +148,9 @@ Output: As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one, and `params[:age]` will contain either "child" or "adult". -NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and make it easier for users to click the inputs by expanding the clickable region. +NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and, +by expanding the clickable region, +make it easier for users to click the inputs. ### Other Helpers of Interest @@ -215,7 +217,7 @@ will produce output similar to <input id="person_name" name="person[name]" type="text" value="Henry"/> ``` -Upon form submission the value entered by the user will be stored in `params[:person][:name]`. The `params[:person]` hash is suitable for passing to `Person.new` or, if `@person` is an instance of Person, `@person.update_attributes`. While the name of an attribute is the most common second parameter to these helpers this is not compulsory. In the example above, as long as person objects have a `name` and a `name=` method Rails will be happy. +Upon form submission the value entered by the user will be stored in `params[:person][:name]`. The `params[:person]` hash is suitable for passing to `Person.new` or, if `@person` is an instance of Person, `@person.update`. While the name of an attribute is the most common second parameter to these helpers this is not compulsory. In the example above, as long as person objects have a `name` and a `name=` method Rails will be happy. WARNING: You must pass the name of an instance variable, i.e. `:person` or `"person"`, not an actual instance of your model object. @@ -236,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" %> @@ -426,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: @@ -458,7 +460,7 @@ As with other helpers, if you were to use the `select` helper on a form builder <%= f.select(:city_id, ...) %> ``` -WARNING: If you are using `select` (or similar helpers such as `collection_select`, `select_tag`) to set a `belongs_to` association you must pass the name of the foreign key (in the example above `city_id`), not the name of association itself. If you specify `city` instead of `city_id` Active Record will raise an error along the lines of ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` when you pass the `params` hash to `Person.new` or `update_attributes`. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. +WARNING: If you are using `select` (or similar helpers such as `collection_select`, `select_tag`) to set a `belongs_to` association you must pass the name of the foreign key (in the example above `city_id`), not the name of association itself. If you specify `city` instead of `city_id` Active Record will raise an error along the lines of ` ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) ` when you pass the `params` hash to `Person.new` or `update`. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. ### Option Tags from a Collection of Arbitrary Objects @@ -495,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 -------------------------------- @@ -534,7 +536,7 @@ The `:prefix` option is the key used to retrieve the hash of date components fro ### Model Object Helpers `select_date` does not work well with forms that update or create Active Record objects as Active Record expects each element of the `params` hash to correspond to one attribute. -The model object helpers for dates and times submit parameters with special names, when Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example: +The model object helpers for dates and times submit parameters with special names; when Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example: ```erb <%= date_select :person, :birth_date %> @@ -554,7 +556,7 @@ which results in a `params` hash like {:person => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}} ``` -When this is passed to `Person.new` (or `update_attributes`), Active Record spots that these parameters should all be used to construct the `birth_date` attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as `Date.civil`. +When this is passed to `Person.new` (or `update`), Active Record spots that these parameters should all be used to construct the `birth_date` attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as `Date.civil`. ### Common Options @@ -620,7 +622,7 @@ Unlike other forms making an asynchronous file upload form is not as simple as p Customizing Form Builders ------------------------- -As mentioned previously the object yielded by `form_for` and `fields_for` is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example +As mentioned previously the object yielded by `form_for` and `fields_for` is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying form elements for a single object. While you can of course write helpers for your forms in the usual way, you can also subclass FormBuilder and add the helpers there. For example ```erb <%= form_for @person do |f| %> @@ -805,7 +807,7 @@ Sometimes when you submit data to an external resource, like payment gateway, fi <% end %> ``` -The same technique is available for the `form_for` too: +The same technique is also available for `form_for`: ```erb <%= form_for @invoice, url: external_url, authenticity_token: 'external_token' do |f| %> diff --git a/guides/source/generators.md b/guides/source/generators.md index 62de5a70bb..8b91dfc5a5 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. @@ -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. diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 02ec024e5b..7d86b3866a 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -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 @@ -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: @@ -830,7 +831,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,7 +864,7 @@ 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 +The `method: :patch` 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 **update** resources according to the REST protocol. @@ -873,7 +874,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 +883,7 @@ And then create the `update` action in `app/controllers/posts_controller.rb`: def update @post = Post.find(params[:id]) - if @post.update_attributes(params[:post]) + if @post.update(params[:post]) redirect_to action: :show, id: @post.id else render 'edit' @@ -890,13 +891,13 @@ def update end ``` -The new method, `update_attributes`, is used when you want to update a record +The new method, `update`, is used when you want to update a record that already exists, and it accepts a hash containing the attributes that you want to update. As before, if there was an error updating the post we want to show the form back to the user. -TIP: You don't need to pass all attributes to `update_attributes`. For -example, if you'd call `@post.update_attributes(title: 'A new title')` +TIP: You don't need to pass all attributes to `update`. For +example, if you'd call `@post.update(title: 'A new title')` Rails would only update the `title` attribute, leaving all other attributes untouched. @@ -1051,7 +1052,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 +1146,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" ``` diff --git a/guides/source/i18n.md b/guides/source/i18n.md index 2e61bea5ea..69232d9bd4 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -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 32df508f9c..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,18 +117,18 @@ 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")) require 'rails/commands/server' - Rails::Server.new.tap { |server| + Rails::Server.new.tap do |server| # We need to require application after the server sets environment, # otherwise the --environment option given to the server won't propagate. require APP_PATH Dir.chdir(Rails.application.root) server.start - } + end ``` This file will change into the root of the directory (a path two directories back from `APP_PATH` which points at `config/application.rb`), but only if the `config.ru` file isn't found. This then requires `rails/commands/server` which sets up the `Rails::Server` class. diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index dbaa3ec576..7c26512046 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. @@ -137,7 +137,7 @@ If you want to render the view that corresponds to a different template within t ```ruby def update @book = Book.find(params[:id]) - if @book.update_attributes(params[:book]) + if @book.update(params[:book]) redirect_to(@book) else render "edit" @@ -145,14 +145,14 @@ def update end ``` -If the call to `update_attributes` fails, calling the `update` action in this controller will render the `edit.html.erb` template belonging to the same controller. +If the call to `update` fails, calling the `update` action in this controller will render the `edit.html.erb` template belonging to the same controller. If you prefer, you can use a symbol instead of a string to specify the action to render: ```ruby def update @book = Book.find(params[:id]) - if @book.update_attributes(params[:book]) + if @book.update(params[:book]) redirect_to(@book) else render :edit @@ -782,7 +782,7 @@ To include `app/assets/stylesheets/main.css` and `app/assets/stylesheets/columns To include `app/assets/stylesheets/main.css` and `app/assets/stylesheets/photos/columns.css`: ```erb -<%= stylesheet_link_tag "main", "/photos/columns" %> +<%= stylesheet_link_tag "main", "photos/columns" %> ``` To include `http://example.com/main.css`: diff --git a/guides/source/migrations.md b/guides/source/migrations.md index 62b70b5571..617e01bd15 100644 --- a/guides/source/migrations.md +++ b/guides/source/migrations.md @@ -79,7 +79,7 @@ end Alternatively, you can use `up` and `down` instead of `change`: -``ruby +```ruby class ChangeProductsPrice < ActiveRecord::Migration def up change_table :products do |t| @@ -108,7 +108,9 @@ of the migration. The name of the migration class (CamelCased version) should match the latter part of the file name. For example `20080906120000_create_products.rb` should define class `CreateProducts` and `20080906120001_add_details_to_products.rb` should define -`AddDetailsToProducts`. +`AddDetailsToProducts`. Rails uses this timestamp to determine which migration +should be run and in what order, so if you're copying a migration from another +application or generate a file yourself, be aware of its position in the order. Of course, calculating timestamps is no fun, so Active Record provides a generator to handle making it for you: @@ -200,6 +202,25 @@ end This migration will create a `user_id` column and appropriate index. +There is also a generator which will produce join tables if `JoinTable` is part of the name: + +```bash +rails g migration CreateJoinTableCustomerProduct customer product +``` + +will produce the following migration: + +```ruby +class CreateJoinTableCustomerProduct < ActiveRecord::Migration + def change + create_join_table :customers, :products do |t| + # t.index [:customer_id, :product_id] + # t.index [:product_id, :customer_id] + end + end +end +``` + ### Model Generators The model and scaffold generators will create migrations appropriate for adding diff --git a/guides/source/nested_model_forms.md b/guides/source/nested_model_forms.md index 2b46a9d51e..93d8e8dfcd 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 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/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 1fac6d9883..a6119eb433 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -37,11 +37,11 @@ Rails on Rack Here's how `rails server` creates an instance of `Rack::Server` ```ruby -Rails::Server.new.tap { |server| +Rails::Server.new.tap do |server| require APP_PATH Dir.chdir(Rails.application.root) server.start -} +end ``` The `Rails::Server` inherits from `Rack::Server` and calls the `Rack::Server#start` method this way: @@ -229,7 +229,7 @@ Much of Action Controller's functionality is implemented as Middlewares. The fol **`Rack::Lock`** -* Sets `env["rack.multithread"]` flag to `true` and wraps the application within a Mutex. +* Sets `env["rack.multithread"]` flag to `false` and wraps the application within a Mutex. **`ActiveSupport::Cache::Strategy::LocalCache::Middleware`** diff --git a/guides/source/security.md b/guides/source/security.md index 0b0cfe69c4..3706a61431 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -210,7 +210,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 a9bce04522..09d6d2d5ee 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. @@ -77,7 +77,7 @@ steve: profession: guy with keyboard ``` -Each fixture is given a name followed by an indented list of colon-separated key/value pairs. Records are typically separated by a blank space. You can place comments in a fixture file by using the # character in the first column. +Each fixture is given a name followed by an indented list of colon-separated key/value pairs. Records are typically separated by a blank space. You can place comments in a fixture file by using the # character in the first column. Keys which resemble YAML keywords such as 'yes' and 'no' are quoted so that the YAML Parser correctly interprets them. #### ERB'in It Up @@ -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`| @@ -830,7 +828,7 @@ Above, the `setup` method is called before each test and so `@post` is available Let's see the earlier example by specifying `setup` callback by specifying a method name as a symbol: ```ruby -require '../test_helper' +require 'test_helper' class PostsControllerTest < ActionController::TestCase diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 0f5acfba3c..a7ca531123 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -66,37 +66,38 @@ Here's the simplest way to write JavaScript. You may see it referred to as 'inline JavaScript': ```html -<a href="#" onclick="alert('Hello, world.')">Here</a> +<a href="#" onclick="this.style.backgroundColor='#990000'">Paint it red</a> ``` - -When clicked, the alert will trigger. Here's the problem: what happens when -we have lots of JavaScript we want to execute on a click? +When clicked, the link background will become red. Here's the problem: what +happens when we have lots of JavaScript we want to execute on a click? ```html -<a href="#" onclick="function fib(n){return n<2?n:fib(n-1)+fib(n-2);};alert('fib of 15 is: ' + fib(15) + '.');">Calculate</a> +<a href="#" onclick="this.style.backgroundColor='#009900';this.style.color='#FFFFFF';">Paint it green</a> ``` Awkward, right? We could pull the function definition out of the click handler, and turn it into CoffeeScript: ```coffeescript -fib = (n) -> - (if n < 2 then n else fib(n - 1) + fib(n - 2)) +paintIt = (element, backgroundColor, textColor) -> + element.style.backgroundColor = backgroundColor + if textColor? + element.style.color = textColor ``` And then on our page: ```html -<a href="#" onclick="alert('fib of 15 is: ' + fib(15) + '.');">Calculate</a> +<a href="#" onclick="paintIt(this, '#990000')">Paint it red</a> ``` That's a little bit better, but what about multiple links that have the same effect? ```html -<a href="#" onclick="alert('fib of 16 is: ' + fib(16) + '.');">Calculate</a> -<a href="#" onclick="alert('fib of 17 is: ' + fib(17) + '.');">Calculate</a> -<a href="#" onclick="alert('fib of 18 is: ' + fib(18) + '.');">Calculate</a> +<a href="#" onclick="paintIt(this, '#990000')">Paint it red</a> +<a href="#" onclick="paintIt(this, '#009900', '#FFFFFF')">Paint it green</a> +<a href="#" onclick="paintIt(this, '#000099', '#FFFFFF')">Paint it blue</a> ``` Not very DRY, eh? We can fix this by using events instead. We'll add a `data-*` @@ -104,19 +105,21 @@ attribute to our link, and then bind a handler to the click event of every link that has that attribute: ```coffeescript -fib = (n) -> - (if n < 2 then n else fib(n - 1) + fib(n - 2)) - -$(document).ready -> - $("a[data-fib]").click (e) -> - count = $(this).data("fib") - alert "fib of #{count} is: #{fib(count)}." - -... later ... - -<a href="#" data-fib="15">Calculate</a> -<a href="#" data-fib="16">Calculate</a> -<a href="#" data-fib="17">Calculate</a> +paintIt = (element, backgroundColor, textColor) -> + element.style.backgroundColor = backgroundColor + if textColor? + element.style.color = textColor + +$ -> + $("a[data-color]").click -> + backgroundColor = $(this).data("background-color") + textColor = $(this).data("text-color") + paintIt(this, backgroundColor, textColor) +``` +```html +<a href="#" data-background-color="#990000">Paint it red</a> +<a href="#" data-background-color="#009900" data-text-color="#FFFFFF">Paint it green</a> +<a href="#" data-background-color="#000099" data-text-color="#FFFFFF">Paint it blue</a> ``` We call this 'unobtrusive' JavaScript because we're no longer mixing our @@ -204,7 +207,7 @@ is a helper that assists with generating links. It has a `:remote` option you can use like this: ```erb -<%= link_to "first post", @post, remote: true %> +<%= link_to "a post", @post, remote: true %> ``` which generates @@ -214,20 +217,19 @@ which generates ``` You can bind to the same Ajax events as `form_for`. Here's an example. Let's -assume that we have a resource `/fib/:n` that calculates the `n`th Fibonacci -number. We would generate some HTML like this: +assume that we have a list of posts that can be deleted with just one +click. We would generate some HTML like this: ```erb -<%= link_to "Calculate", "/fib/15", remote: true, data: { fib: 15 } %> +<%= link_to "Delete post", @post, remote: true, method: :delete %> ``` and write some CoffeeScript like this: ```coffeescript -$(document).ready -> - $("a[data-fib]").on "ajax:success", (e, data, status, xhr) -> - count = $(this).data("fib") - alert "fib of #{count} is: #{data}." +$ -> + $("a[data-remote]").on "ajax:success", (e, data, status, xhr) -> + alert "The post was deleted." ``` ### button_to |