diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/5_1_release_notes.md | 3 | ||||
| -rw-r--r-- | guides/source/5_2_release_notes.md | 50 | ||||
| -rw-r--r-- | guides/source/action_view_overview.md | 14 | ||||
| -rw-r--r-- | guides/source/active_record_basics.md | 2 | ||||
| -rw-r--r-- | guides/source/active_record_migrations.md | 3 | ||||
| -rw-r--r-- | guides/source/active_storage_overview.md | 126 | ||||
| -rw-r--r-- | guides/source/association_basics.md | 8 | ||||
| -rw-r--r-- | guides/source/configuring.md | 4 | ||||
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.md | 4 | ||||
| -rw-r--r-- | guides/source/documents.yaml | 2 | ||||
| -rw-r--r-- | guides/source/engines.md | 12 |
11 files changed, 131 insertions, 97 deletions
diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md index 6b9a950a42..852d04b1f6 100644 --- a/guides/source/5_1_release_notes.md +++ b/guides/source/5_1_release_notes.md @@ -355,6 +355,9 @@ Please refer to the [Changelog][action-pack] for detailed changes. ([Commit](https://github.com/rails/rails/commit/79a5ea9eadb4d43b62afacedc0706cbe88c54496), [Commit](https://github.com/rails/rails/commit/57e1c99a280bdc1b324936a690350320a1cd8111)) +* Removed deprecated support for calling `HashWithIndifferentAccess` methods on `ActionController::Parameters`. + ([Commit](https://github.com/rails/rails/pull/26746/commits/7093ceb480ad6a0a91b511832dad4c6a86981b93)) + ### Deprecations * Deprecated `config.action_controller.raise_on_unfiltered_parameters`. diff --git a/guides/source/5_2_release_notes.md b/guides/source/5_2_release_notes.md index eb361e200a..7b5c4b87e3 100644 --- a/guides/source/5_2_release_notes.md +++ b/guides/source/5_2_release_notes.md @@ -63,9 +63,20 @@ Railties Please refer to the [Changelog][railties] for detailed changes. -### Removals +### Deprecations -ToDo +* Deprecate `capify!` method in generators and templates. + ([Pull Request](https://github.com/rails/rails/pull/29493)) + +* Deprecated passing the environment's name as a regular argument to the + `rails dbconsole` and `rails console` commands. + ([Pull Request](https://github.com/rails/rails/pull/29358)) + +* Deprecated using subclass of `Rails::Application` to start the Rails server. + ([Pull Request](https://github.com/rails/rails/pull/30127)) + +* Deprecated `after_bundle` callback in Rails plugin templates. + ([Pull Request](https://github.com/rails/rails/pull/29446)) ### Notable changes @@ -76,9 +87,18 @@ Action Cable Please refer to the [Changelog][action-cable] for detailed changes. +### Removals + +* Removed deprecated evented redis adapter. + ([Commit](https://github.com/rails/rails/commit/48766e32d31)) + ### Notable changes -ToDo +* Added support for `host`, `port`, `db` and `password` options in cable.yml + ([Pull Request](https://github.com/rails/rails/pull/29528)) + +* Added support for compatibility with redis-rb gem for 4.0 version. + ([Pull Request](https://github.com/rails/rails/pull/30748)) Action Pack ----------- @@ -87,11 +107,14 @@ Please refer to the [Changelog][action-pack] for detailed changes. ### Removals -ToDo +* Removed deprecated `ActionController::ParamsParser::ParseError`. + ([Commit](https://github.com/rails/rails/commit/e16c765ac6d)) ### Deprecations -ToDo +* Deprecated `#success?`, `#missing?` and `#error?` aliases of + `ActionDispatch::TestResponse`. + ([Pull Request](https://github.com/rails/rails/pull/30104)) ### Notable changes @@ -104,11 +127,14 @@ Please refer to the [Changelog][action-view] for detailed changes. ### Removals -ToDo +* Removed deprecated Erubis ERB handler. + ([Commit](https://github.com/rails/rails/commit/7de7f12fd14)) ### Deprecations -ToDo +* Deprecated `image_alt` helper which used to add default alt text to + the images generated by `image_tag`. + ([Pull Request](https://github.com/rails/rails/pull/30213)) ### Notable changes @@ -151,15 +177,6 @@ ToDo ToDo -Active Storage --------------- - -Please refer to the [Changelog][active-support] for detailed changes. - -### Notable changes - -ToDo - Active Support -------------- @@ -205,6 +222,5 @@ framework it is. Kudos to all of them. [action-cable]: https://github.com/rails/rails/blob/5-2-stable/actioncable/CHANGELOG.md [active-record]: https://github.com/rails/rails/blob/5-2-stable/activerecord/CHANGELOG.md [active-model]: https://github.com/rails/rails/blob/5-2-stable/activemodel/CHANGELOG.md -[active-storage]: https://github.com/rails/rails/blob/5-2-stable/activestorage/CHANGELOG.md [active-support]: https://github.com/rails/rails/blob/5-2-stable/activesupport/CHANGELOG.md [active-job]: https://github.com/rails/rails/blob/5-2-stable/activejob/CHANGELOG.md diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index fde2040173..1cba5c6fb6 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -807,20 +807,22 @@ The core method of this helper, `form_for`, gives you the ability to create a fo The HTML generated for this would be: ```html -<form action="/people/create" method="post"> - <input id="person_first_name" name="person[first_name]" type="text" /> - <input id="person_last_name" name="person[last_name]" type="text" /> - <input name="commit" type="submit" value="Create" /> +<form class="new_person" id="new_person" action="/people" accept-charset="UTF-8" method="post"> + <input name="utf8" type="hidden" value="✓" /> + <input type="hidden" name="authenticity_token" value="lTuvBzs7ANygT0NFinXj98tfw3Emfm65wwYLbUvoWsK2pngccIQSUorM2C035M9dZswXgWTvKwFS8W5TVblpYw==" /> + <input type="text" name="person[first_name]" id="person_first_name" /> + <input type="text" name="person[last_name]" id="person_last_name" /> + <input type="submit" name="commit" value="Create" data-disable-with="Create" /> </form> ``` The params object created when this form is submitted would look like: ```ruby -{ "action" => "create", "controller" => "people", "person" => { "first_name" => "William", "last_name" => "Smith" } } +{"utf8" => "✓", "authenticity_token" => "lTuvBzs7ANygT0NFinXj98tfw3Emfm65wwYLbUvoWsK2pngccIQSUorM2C035M9dZswXgWTvKwFS8W5TVblpYw==", "person" => {"first_name" => "William", "last_name" => "Smith"}, "commit" => "Create", "controller" => "people", "action" => "create"} ``` -The params hash has a nested person value, which can therefore be accessed with params[:person] in the controller. +The params hash has a nested person value, which can therefore be accessed with `params[:person]` in the controller. #### check_box diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md index 069a624984..9be9c6c7b7 100644 --- a/guides/source/active_record_basics.md +++ b/guides/source/active_record_basics.md @@ -38,7 +38,7 @@ object on how to write to and read from the database. ### Object Relational Mapping -Object Relational Mapping, commonly referred to as its abbreviation ORM, is +[Object Relational Mapping](https://en.wikipedia.org/wiki/Object-relational_mapping), commonly referred to as its abbreviation ORM, is a technique that connects the rich objects of an application to tables in a relational database management system. Using ORM, the properties and relationships of the objects in an application can be easily stored and diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md index f8f36bf600..ab3af438f5 100644 --- a/guides/source/active_record_migrations.md +++ b/guides/source/active_record_migrations.md @@ -353,8 +353,7 @@ create_table :products, options: "ENGINE=BLACKHOLE" do |t| end ``` -will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table -(when using MySQL or MariaDB, the default is `ENGINE=InnoDB`). +will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table. Also you can pass the `:comment` option with any description for the table that will be stored in database itself and can be viewed with database administration diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index dc94046084..f45dbdee3e 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -1,7 +1,7 @@ **DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonrails.org.** -Active Storage -============== +Active Storage Overview +======================= This guide covers how to attach files to your Active Record models. @@ -43,7 +43,7 @@ migration. Declare Active Storage services in `config/storage.yml`. For each service your application uses, provide a name and the requisite configuration. The example -below declares three services named `local`, `test`, and `s3`: +below declares three services named `local`, `test`, and `amazon`: ```yaml local: @@ -54,7 +54,7 @@ test: service: Disk root: <%= Rails.root.join("tmp/storage") %> -s3: +amazon: service: S3 access_key_id: "" secret_access_key: "" @@ -65,19 +65,19 @@ Tell Active Storage which service to use by setting likely use a different service, it is recommended to do this on a per-environment basis. To use the disk service from the previous example in the development environment, you would add the following to -config/environments/development.rb: +`config/environments/development.rb`: ```ruby # Store files locally. config.active_storage.service = :local ``` -To use the s3 service in production, you add the following to +To use the Amazon S3 service in production, you add the following to `config/environments/production.rb`: ```ruby -# Store files in S3. -config.active_storage.service = :s3 +# Store files on Amazon S3. +config.active_storage.service = :amazon ``` Continue reading for more information on the built-in service adapters (e.g. @@ -87,7 +87,7 @@ Continue reading for more information on the built-in service adapters (e.g. Declare a Disk service in `config/storage.yml`: -``` yaml +```yaml local: service: Disk root: <%= Rails.root.join("storage") %> @@ -97,17 +97,18 @@ local: Declare an S3 service in `config/storage.yml`: -``` yaml -s3: +```yaml +amazon: service: S3 access_key_id: "" secret_access_key: "" region: "" bucket: "" ``` -Also, add the S3 client gem to your Gemfile: -``` ruby +Add the [`aws-sdk-s3`](https://github.com/aws/aws-sdk-ruby) gem to your `Gemfile`: + +```ruby gem "aws-sdk-s3", require: false ``` @@ -115,7 +116,7 @@ gem "aws-sdk-s3", require: false Declare an Azure Storage service in `config/storage.yml`: -``` yaml +```yaml azure: service: AzureStorage path: "" @@ -124,9 +125,9 @@ azure: container: "" ``` -Also, add the Microsoft Azure Storage client gem to your Gemfile: +Add the [`azure-storage`](https://github.com/Azure/azure-storage-ruby) gem to your `Gemfile`: -``` ruby +```ruby gem "azure-storage", require: false ``` @@ -134,28 +135,37 @@ gem "azure-storage", require: false Declare a Google Cloud Storage service in `config/storage.yml`: -``` yaml +```yaml +google: + service: GCS + credentials: <%= Rails.root.join("path/to/keyfile.json") %> + project: "" + bucket: "" +``` + +Optionally provide a Hash of credentials instead of a keyfile path: + +```yaml google: service: GCS - keyfile: { - type: "service_account", - project_id: "", - private_key_id: "", - private_key: "", - client_email: "", - client_id: "", - auth_uri: "https://accounts.google.com/o/oauth2/auth", - token_uri: "https://accounts.google.com/o/oauth2/token", - auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs", + credentials: + type: "service_account" + project_id: "" + private_key_id: <%= Rails.application.credentials.dig(:gcs, :private_key_id) %> + private_key: <%= Rails.application.credentials.dig(:gcs, :private_key) %> + client_email: "" + client_id: "" + auth_uri: "https://accounts.google.com/o/oauth2/auth" + token_uri: "https://accounts.google.com/o/oauth2/token" + auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs" client_x509_cert_url: "" - } project: "" bucket: "" ``` -Also, add the Google Cloud Storage client gem to your Gemfile: +Add the [`google-cloud-storage`](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-storage) gem to your `Gemfile`: -``` ruby +```ruby gem "google-cloud-storage", "~> 1.3", require: false ``` @@ -169,7 +179,7 @@ service to the new, then go all-in on the new service. Define each of the services you'd like to use as described above and reference them from a mirrored service. -``` yaml +```yaml s3_west_coast: service: S3 access_key_id: "" @@ -193,18 +203,18 @@ production: NOTE: Files are served from the primary service. -Attach Files to a Model ------------------------ +Attaching Files to Records +-------------------------- ### `has_one_attached` The `has_one_attached` macro sets up a one-to-one mapping between records and files. Each record can have one file attached to it. -For example, suppose your application has a User model. If you want each user to +For example, suppose your application has a `User` model. If you want each user to have an avatar, define the `User` model like this: -``` ruby +```ruby class User < ApplicationRecord has_one_attached :avatar end @@ -212,10 +222,10 @@ end You can create a user with an avatar: -``` ruby +```ruby class SignupController < ApplicationController def create - user = Users.create!(user_params) + user = User.create!(user_params) session[:user_id] = user.id redirect_to root_path end @@ -245,7 +255,7 @@ The `has_many_attached` macro sets up a one-to-many relationship between records and files. Each record can have many files attached to it. For example, suppose your application has a `Message` model. If you want each -message to have many images, define the Message model like this: +message to have many images, define the `Message` model like this: ```ruby class Message < ApplicationRecord @@ -281,8 +291,8 @@ Call `images.attached?` to determine whether a particular message has any images @message.images.attached? ``` -Remove File Attached to Model ------------------------------ +Removing Files +-------------- To remove an attachment from a model, call `purge` on the attachment. Removal can be done in the background if your application is setup to use Active Job. @@ -296,8 +306,8 @@ user.avatar.purge user.avatar.purge_later ``` -Link to Attachments -------------------- +Linking to Files +---------------- Generate a permanent URL for the blob that points to the application. Upon access, a redirect to the actual service endpoint is returned. This indirection @@ -316,20 +326,20 @@ helper allows you to set the disposition. rails_blob_path(user.avatar, disposition: "attachment") ``` -Transform Images ----------------- +Transforming Images +------------------- To create variation of the image, call `variant` on the Blob. You can pass any [MiniMagick](https://github.com/minimagick/minimagick) supported transformation to the method. -To enable variants, add `mini_magick` to your Gemfile: +To enable variants, add `mini_magick` to your `Gemfile`: -``` ruby +```ruby gem 'mini_magick' ``` -When the browser hits the variant URL, ActiveStorage will lazy transform the +When the browser hits the variant URL, Active Storage will lazy transform the original blob into the format you specified and redirect to its new service location. @@ -337,8 +347,8 @@ location. <%= image_tag user.avatar.variant(resize: "100x100") %> ``` -Preview Non-image Files ------------------------ +Previewing Files +---------------- Some non-image files can be previewed: that is, they can be presented as images. For example, a video file can be previewed by extracting its first frame. Out of @@ -360,8 +370,8 @@ install them yourself to use the built-in previewers. Before you install and use third-party software, make sure you understand the licensing implications of doing so. -Upload Directly to Service --------------------------- +Direct Uploads +-------------- Active Storage, with its included JavaScript library, supports uploading directly from the client to the cloud. @@ -498,16 +508,16 @@ input[type=file][data-direct-upload-url][disabled] { } ``` -Clean up Stored Files Store During System Tests ------------------------------------------------ +Discarding Files Stored During System Tests +------------------------------------------- System tests clean up test data by rolling back a transaction. Because destroy is never called on an object, the attached files are never cleaned up. If you want to clear the files, you can do it in an `after_teardown` callback. Doing it here ensures that all connections created during the test are complete and -you won't receive an error from ActiveStorage saying it can't find a file. +you won't receive an error from Active Storage saying it can't find a file. -``` ruby +```ruby class ApplicationSystemTestCase < ActionDispatch::SystemTestCase driven_by :selenium, using: :chrome, screen_size: [1400, 1400] @@ -529,7 +539,7 @@ the purge job is executed immediately rather at an unknown time in the future. You may also want to use a separate service definition for the test environment so your tests don't delete the files you create during development. -``` ruby +```ruby # Use inline job processing to make things happen immediately config.active_job.queue_adapter = :inline @@ -537,8 +547,8 @@ config.active_job.queue_adapter = :inline config.active_storage.service = :local_test ``` -Support Additional Cloud Services ---------------------------------- +Implementing Support for Other Cloud Services +--------------------------------------------- If you need to support a cloud service other than these, you will need to implement the Service. Each service extends diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 9616647f15..b5e236b790 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -1561,7 +1561,8 @@ The `collection.size` method returns the number of objects in the collection. ##### `collection.find(...)` -The `collection.find` method finds objects within the collection. It uses the same syntax and options as `ActiveRecord::Base.find`. +The `collection.find` method finds objects within the collection. It uses the same syntax and options as +[`ActiveRecord::Base.find`](http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-find). ```ruby @available_book = @author.books.find(1) @@ -2091,7 +2092,8 @@ The `collection.size` method returns the number of objects in the collection. ##### `collection.find(...)` -The `collection.find` method finds objects within the collection. It uses the same syntax and options as `ActiveRecord::Base.find`. It also adds the additional condition that the object must be in the collection. +The `collection.find` method finds objects within the collection. It uses the same syntax and options as +[`ActiveRecord::Base.find`](http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-find). ```ruby @assembly = @part.assemblies.find(1) @@ -2099,7 +2101,7 @@ The `collection.find` method finds objects within the collection. It uses the sa ##### `collection.where(...)` -The `collection.where` method finds objects within the collection based on the conditions supplied but the objects are loaded lazily meaning that the database is queried only when the object(s) are accessed. It also adds the additional condition that the object must be in the collection. +The `collection.where` method finds objects within the collection based on the conditions supplied but the objects are loaded lazily meaning that the database is queried only when the object(s) are accessed. ```ruby @new_assemblies = @part.assemblies.where("created_at > ?", 2.days.ago) diff --git a/guides/source/configuring.md b/guides/source/configuring.md index b1e472bb74..1668f9e81a 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -66,8 +66,6 @@ These configuration methods are to be called on a `Rails::Railtie` object, such * `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to `false` in development mode, and `true` in test and production modes. -* `config.action_view.cache_template_loading` controls whether or not templates should be reloaded on each request. Defaults to whatever is set for `config.cache_classes`. - * `config.beginning_of_week` sets the default beginning of week for the application. Accepts a valid week day symbol (e.g. `:monday`). @@ -538,6 +536,8 @@ Defaults to `'signed cookie'`. `config.action_view` includes a small number of configuration settings: +* `config.action_view.cache_template_loading` controls whether or not templates should be reloaded on each request. Defaults to whatever is set for `config.cache_classes`. + * `config.action_view.field_error_proc` provides an HTML generator for displaying errors that come from Active Model. The default is ```ruby diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 7424818757..967c992c05 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -84,7 +84,9 @@ discussions new features require. Helping to Resolve Existing Issues ---------------------------------- -As a next step beyond reporting issues, you can help the core team resolve existing issues. If you check the [issues list](https://github.com/rails/rails/issues) in GitHub Issues, you'll find lots of issues already requiring attention. What can you do for these? Quite a bit, actually: +As a next step beyond reporting issues, you can help the core team resolve existing ones by providing feedback about them. If you are new to Rails core development, that might be a great way to walk your first steps, you'll get familiar with the code base and the processes. + +If you check the [issues list](https://github.com/rails/rails/issues) in GitHub Issues, you'll find lots of issues already requiring attention. What can you do for these? Quite a bit, actually: ### Verifying Bug Reports diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index 388f3761b1..5cddf79eeb 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -84,7 +84,7 @@ url: active_job_basics.html description: This guide provides you with all you need to get started creating, enqueuing, and executing background jobs. - - name: Active Storage + name: Active Storage Overview url: active_storage_overview.html description: This guide covers how to attach files to your Active Record models. - diff --git a/guides/source/engines.md b/guides/source/engines.md index 33694cf76a..8d81296fa5 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -1516,12 +1516,12 @@ To hook into the initialization process of one of the following classes use the These are the available configuration hooks. They do not hook into any particular framework, but instead they run in context of the entire application. -| Hook | Use Case | -| ---------------------- | ------------------------------------------------------------------------------------- | -| `before_configuration` | First configurable block to run. Called before any initializers are run. | -| `before_initialize` | Second configurable block to run. Called before frameworks initialize. | -| `before_eager_load` | Third configurable block to run. Does not run if `config.cache_classes` set to false. | -| `after_initialize` | Last configurable block to run. Called after frameworks initialize. | +| Hook | Use Case | +| ---------------------- | ---------------------------------------------------------------------------------- | +| `before_configuration` | First configurable block to run. Called before any initializers are run. | +| `before_initialize` | Second configurable block to run. Called before frameworks initialize. | +| `before_eager_load` | Third configurable block to run. Does not run if `config.eager_load` set to false. | +| `after_initialize` | Last configurable block to run. Called after frameworks initialize. | ### Example |