diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/4_2_release_notes.md | 8 | ||||
| -rw-r--r-- | guides/source/action_mailer_basics.md | 10 | ||||
| -rw-r--r-- | guides/source/action_view_overview.md | 22 | ||||
| -rw-r--r-- | guides/source/active_job_basics.md | 35 | ||||
| -rw-r--r-- | guides/source/debugging_rails_applications.md | 2 | ||||
| -rw-r--r-- | guides/source/generators.md | 8 | ||||
| -rw-r--r-- | guides/source/nested_model_forms.md | 5 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 19 |
8 files changed, 69 insertions, 40 deletions
diff --git a/guides/source/4_2_release_notes.md b/guides/source/4_2_release_notes.md index 913bb4fb5f..39655447e3 100644 --- a/guides/source/4_2_release_notes.md +++ b/guides/source/4_2_release_notes.md @@ -161,7 +161,7 @@ Please refer to the [Changelog][railties] for detailed changes. ([Pull Request](https://github.com/rails/rails/pull/16129)) * Introduced a `--skip-gems` option in the app generator to skip gems such as - `turbolinks` and `coffee-rails` that does not have their own specific flags. + `turbolinks` and `coffee-rails` that do not have their own specific flags. ([Commit](https://github.com/rails/rails/commit/10565895805887d4faf004a6f71219da177f78b7)) * Introduced a `bin/setup` script to enable automated setup code when @@ -177,9 +177,6 @@ Please refer to the [Changelog][railties] for detailed changes. * Introduced `Rails.gem_version` as a convenience method to return `Gem::Version.new(Rails.version)`. ([Pull Request](https://github.com/rails/rails/pull/14101)) -* Introduced an `after_bundle` callback in the Rails templates. - ([Pull Request](https://github.com/rails/rails/pull/16359)) - Action Pack ----------- @@ -300,6 +297,9 @@ Please refer to the [Changelog][action-view] for detailed changes. the hidden fields. ([Pull Request](https://github.com/rails/rails/pull/14738)) +* Placeholder I18n follows the same convention as `label` I18n. + ([Pull Request](https://github.com/rails/rails/pull/16438)) + Action Mailer ------------- diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 6b6ce145e4..f981d0da47 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -187,13 +187,13 @@ class UsersController < ApplicationController end ``` -NOTE: By default Active Job is configured to execute the job `:inline`. So you can -use `deliver_later` now to send the emails and when you decide to start sending the -email from a background job you'll just have to setup Active Job to use a queueing +NOTE: Active Job's default behavior is to execute jobs ':inline'. So, you can use +`deliver_later` now to send emails, and when you later decide to start sending +them from a background job, you'll only need to set up Active Job to use a queueing backend (Sidekiq, Resque, etc). -If you want to send the emails right away (from a cronjob for example) just -call `deliver_now`: +If you want to send emails right away (from a cronjob for example) just call +`deliver_now`: ```ruby class SendWeeklySummary diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index f37bb20750..683e633668 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -44,18 +44,18 @@ $ bin/rails generate scaffold article There is a naming convention for views in Rails. Typically, the views share their name with the associated controller action, as you can see above. For example, the index controller action of the `articles_controller.rb` will use the `index.html.erb` view file in the `app/views/articles` directory. -The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Later on this guide you can find a more detailed documentation of each one of these three components. +The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Within this guide you will find more detailed documentation about each of these three components. Templates, Partials and Layouts ------------------------------- -As mentioned before, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`. -Below is a brief overview of each one of them. +As mentioned, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`. +Below is a brief overview of each of them. ### Templates -Action View templates can be written in several ways. If the template file has a `.erb` extension then it uses a mixture of ERB (included in Ruby) and HTML. If the template file has a `.builder` extension then a fresh instance of `Builder::XmlMarkup` library is used. +Action View templates can be written in several ways. If the template file has a `.erb` extension then it uses a mixture of ERB (Embedded Ruby) and HTML. If the template file has a `.builder` extension then the `Builder::XmlMarkup` library is used. Rails supports multiple template systems and uses a file extension to distinguish amongst them. For example, an HTML file using the ERB template system will have `.html.erb` as a file extension. @@ -72,7 +72,7 @@ Consider the following loop for names: <% end %> ``` -The loop is set up in regular embedding tags (`<% %>`) and the name is written using the output embedding tags (`<%= %>`). Note that this is not just a usage suggestion, for regular output functions like `print` or `puts` won't work with ERB templates. So this would be wrong: +The loop is set up using regular embedding tags (`<% %>`) and the name is inserted using the output embedding tags (`<%= %>`). Note that this is not just a usage suggestion: regular output functions such as `print` and `puts` won't be rendered to the view with ERB templates. So this would be wrong: ```html+erb <%# WRONG %> @@ -231,7 +231,7 @@ The `object` and `as` options can also be used together: #### Rendering Collections -It is very common that a template needs to iterate over a collection and render a sub-template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array. +It is very common that a template will need to iterate over a collection and render a sub-template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array. So this example for rendering all the products: @@ -247,7 +247,7 @@ can be rewritten in a single line: <%= render partial: "product", collection: @products %> ``` -When a partial is called like this (eg. with a collection), the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within it you can refer to `product` to get the instance that is being rendered. +When a partial is called with a collection, the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within it you can refer to `product` to get the collection member that is being rendered. You can use a shorthand syntax for rendering collections. Assuming `@products` is a collection of `Product` instances, you can simply write the following to produce the same result: @@ -255,7 +255,7 @@ You can use a shorthand syntax for rendering collections. Assuming `@products` i <%= render @products %> ``` -Rails determines the name of the partial to use by looking at the model name in the collection, `Product` in this case. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection. +Rails determines the name of the partial to use by looking at the model name in the collection, `Product` in this case. In fact, you can even render a collection made up of instances of different models using this shorthand, and Rails will choose the proper partial for each member of the collection. #### Spacer Templates @@ -269,14 +269,14 @@ Rails will render the `_product_ruler` partial (with no data passed to it) betwe ### Layouts -Layouts can be used to render a common view template around the results of Rails controller actions. Typically, every Rails application has a couple of overall layouts that most pages are rendered within. For example, a site might have a layout for a logged in user, and a layout for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us." You would expect each layout to have a different look and feel. You can read more details about Layouts in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide. +Layouts can be used to render a common view template around the results of Rails controller actions. Typically, a Rails application will have a couple of layouts that pages will be rendered within. For example, a site might have one layout for a logged in user and another for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us" pages. You would expect each layout to have a different look and feel. You can read about layouts in more detail in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide. Partial Layouts --------------- -Partials can have their own layouts applied to them. These layouts are different than the ones that are specified globally for the entire action, but they work in a similar fashion. +Partials can have their own layouts applied to them. These layouts are different from those applied to a controller action, but they work in a similar fashion. -Let's say we're displaying an article on a page, that should be wrapped in a `div` for display purposes. First, we'll create a new `Article`: +Let's say we're displaying an article on a page which should be wrapped in a `div` for display purposes. Firstly, we'll create a new `Article`: ```ruby Article.create(body: 'Partial Layouts are cool!') diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index a8e1f22b4d..4632ea1faf 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -105,8 +105,8 @@ Active Job has adapters for the following queueing backends: * [Delayed Job](https://github.com/collectiveidea/delayed_job) * [Qu](https://github.com/bkeepers/qu) * [Que](https://github.com/chanks/que) -* [QueueClassic](https://github.com/ryandotsmith/queue_classic) -* [Resque 1.x](https://github.com/resque/resque) +* [QueueClassic 2.x](https://github.com/ryandotsmith/queue_classic/tree/v2.2.3) +* [Resque 1.x](https://github.com/resque/resque/tree/1-x-stable) * [Sidekiq](https://github.com/mperham/sidekiq) * [Sneakers](https://github.com/jondot/sneakers) * [Sucker Punch](https://github.com/brandonhilkert/sucker_punch) @@ -119,12 +119,12 @@ Active Job has adapters for the following queueing backends: | **Delayed Job** | Yes | Yes | Yes | Job | Global | Global | | **Que** | Yes | Yes | Yes | Job | No | Job | | **Queue Classic** | Yes | Yes | Gem | No | No | No | -| **Resque** | Yes | Yes | Gem | Queue | Global | ? | +| **Resque** | Yes | Yes | Gem | Queue | Global | Yes | | **Sidekiq** | Yes | Yes | Yes | Queue | No | Job | | **Sneakers** | Yes | Yes | No | Queue | Queue | No | | **Sucker Punch** | Yes | Yes | Yes | No | No | No | -| **Active Job** | Yes | Yes | WIP | No | No | No | | **Active Job Inline** | No | Yes | N/A | N/A | N/A | N/A | +| **Active Job** | Yes | Yes | Yes | No | No | No | ### Change Backends @@ -150,8 +150,29 @@ class GuestsCleanupJob < ActiveJob::Base end ``` -NOTE: Make sure your queueing backend "listens" on your queue name. For some backends -you need to specify the queues to listen to. +Also you can prefix the queue name for all your jobs using +`config.active_job.queue_name_prefix` in `application.rb`: + +```ruby +# config/application.rb +module YourApp + class Application < Rails::Application + config.active_job.queue_name_prefix = Rails.env + end +end + +# app/jobs/guests_cleanup.rb +class GuestsCleanupJob < ActiveJob::Base + queue_as :low_priority + #.... +end + +# Now your job will run on queue production_low_priority on your production +# environment and on beta_low_priority on your beta environment +``` + +NOTE: Make sure your queueing backend "listens" on your queue name. For some +backends you need to specify the queues to listen to. Callbacks @@ -203,7 +224,7 @@ is integrated with Action Mailer so you can easily send emails asynchronously: # If you want to send the email now use #deliver_now UserMailer.welcome(@user).deliver_now -# If you want to send the email through ActiveJob use #deliver_later +# If you want to send the email through Active Job use #deliver_later UserMailer.welcome(@user).deliver_later ``` diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md index 53b8566d83..88c6210296 100644 --- a/guides/source/debugging_rails_applications.md +++ b/guides/source/debugging_rails_applications.md @@ -211,7 +211,7 @@ logger.tagged("BCX") { logger.tagged("Jason") { logger.info "Stuff" } } # Logs " ### Impact of Logs on Performance Logging will always have a small impact on performance of your rails app, - particularly when logging to disk.However, there are a few subtleties: + particularly when logging to disk. However, there are a few subtleties: Using the `:debug` level will have a greater performance penalty than `:fatal`, as a far greater number of strings are being evaluated and written to the diff --git a/guides/source/generators.md b/guides/source/generators.md index 2b39ea66d8..f5d2c67cb4 100644 --- a/guides/source/generators.md +++ b/guides/source/generators.md @@ -341,13 +341,17 @@ end If you generate another resource, you can see that we get exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating `edit.html.erb`, `index.html.erb` and so on inside `lib/templates/erb/scaffold`. -Many scaffold templates in Rails are written in ERB tags which need to be escaped, so that the output is valid ERB code. For example, +Scaffold templates in Rails frequently use ERB tags; these tags need to be +escaped so that the generated output is valid ERB code. + +For example, the following escaped ERB tag would be needed in the template +(note the extra `%`)... ```ruby <%%= stylesheet_include_tag :application %> ``` -when passed through the generator, would generate the following output. +...to generate the following output: ```ruby <%= stylesheet_include_tag :application %> diff --git a/guides/source/nested_model_forms.md b/guides/source/nested_model_forms.md index 4f0634d955..f0ee34cfb1 100644 --- a/guides/source/nested_model_forms.md +++ b/guides/source/nested_model_forms.md @@ -1,4 +1,4 @@ -Rails nested model forms +Rails Nested Model Forms ======================== Creating a form for a model _and_ its associations can become quite tedious. Therefore Rails provides helpers to assist in dealing with the complexities of generating these forms _and_ the required CRUD operations to create, update, and destroy associations. @@ -54,6 +54,9 @@ class Person < ActiveRecord::Base end ``` +NOTE: For greater detail on associations see [Active Record Associations](association_basics.html). +For a complete reference on associations please visit the API documentation for [ActiveRecord::Associations::ClassMethods](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html). + ### 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 behavior: diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 8586dc6a62..407445f449 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -148,7 +148,7 @@ Upgrading from Rails 4.0 to Rails 4.1 Or, "whaaat my tests are failing!!!?" Cross-site request forgery (CSRF) protection now covers GET requests with -JavaScript responses, too. That prevents a third-party site from referencing +JavaScript responses, too. This prevents a third-party site from referencing your JavaScript URL and attempting to run it to extract sensitive data. This means that your functional and integration tests that use @@ -199,8 +199,8 @@ secrets, you need to: ``` 2. Use your existing `secret_key_base` from the `secret_token.rb` initializer to - set the SECRET_KEY_BASE environment variable for whichever users run the Rails - app in production mode. Alternately, you can simply copy the existing + set the SECRET_KEY_BASE environment variable for whichever users running the + Rails application in production mode. Alternatively, you can simply copy the existing `secret_key_base` from the `secret_token.rb` initializer to `secrets.yml` under the `production` section, replacing '<%= ENV["SECRET_KEY_BASE"] %>'. @@ -403,8 +403,8 @@ ActiveRecord::FixtureSet.context_class.send :include, FixtureFileHelpers ### I18n enforcing available locales -Rails 4.1 now defaults the I18n option `enforce_available_locales` to `true`, -meaning that it will make sure that all locales passed to it must be declared in +Rails 4.1 now defaults the I18n option `enforce_available_locales` to `true`. This +means that it will make sure that all locales passed to it must be declared in the `available_locales` list. To disable it (and allow I18n to accept *any* locale option) add the following @@ -414,9 +414,10 @@ configuration to your application: config.i18n.enforce_available_locales = false ``` -Note that this option was added as a security measure, to ensure user input could -not be used as locale information unless previously known, so it's recommended not -to disable this option unless you have a strong reason for doing so. +Note that this option was added as a security measure, to ensure user input +cannot be used as locale information unless it is previously known. Therefore, +it's recommended not to disable this option unless you have a strong reason for +doing so. ### Mutator methods called on Relation @@ -524,7 +525,7 @@ Using `render :text` may pose a security risk, as the content is sent as ### PostgreSQL json and hstore datatypes Rails 4.1 will map `json` and `hstore` columns to a string-keyed Ruby `Hash`. -In earlier versions a `HashWithIndifferentAccess` was used. This means that +In earlier versions, a `HashWithIndifferentAccess` was used. This means that symbol access is no longer supported. This is also the case for `store_accessors` based on top of `json` or `hstore` columns. Make sure to use string keys consistently. |