rails 4.2.11 → 5.0.0

data/guides/source/active_job_basics.md

@@ -1,339 +0,0 @@
-Active Job Basics
-=================
-
-This guide provides you with all you need to get started in creating,
-enqueueing and executing background jobs.
-
-After reading this guide, you will know:
-
-* How to create jobs.
-* How to enqueue jobs.
-* How to run jobs in the background.
-* How to send emails from your application async.
-
---------------------------------------------------------------------------------
-
-
-Introduction
-------------
-
-Active Job is a framework for declaring jobs and making them run on a variety
-of queueing backends. These jobs can be everything from regularly scheduled
-clean-ups, to billing charges, to mailings. Anything that can be chopped up
-into small units of work and run in parallel, really.
-
-
-The Purpose of Active Job
------------------------------
-The main point is to ensure that all Rails apps will have a job infrastructure
-in place, even if it's in the form of an "immediate runner". We can then have
-framework features and other gems build on top of that, without having to
-worry about API differences between various job runners such as Delayed Job
-and Resque. Picking your queuing backend becomes more of an operational concern,
-then. And you'll be able to switch between them without having to rewrite your jobs.
-
-
-Creating a Job
---------------
-
-This section will provide a step-by-step guide to creating a job and enqueuing it.
-
-### Create the Job
-
-Active Job provides a Rails generator to create jobs. The following will create a
-job in `app/jobs` (with an attached test case under `test/jobs`):
-
-```bash
-$ bin/rails generate job guests_cleanup
-invoke  test_unit
-create    test/jobs/guests_cleanup_job_test.rb
-create  app/jobs/guests_cleanup_job.rb
-```
-
-You can also create a job that will run on a specific queue:
-
-```bash
-$ bin/rails generate job guests_cleanup --queue urgent
-```
-
-If you don't want to use a generator, you could create your own file inside of
-`app/jobs`, just make sure that it inherits from `ActiveJob::Base`.
-
-Here's what a job looks like:
-
-```ruby
-class GuestsCleanupJob < ActiveJob::Base
-  queue_as :default
-
-  def perform(*guests)
-    # Do something later
-  end
-end
-```
-
-Note that you can define `perform` with as many arguments as you want.
-
-### Enqueue the Job
-
-Enqueue a job like so:
-
-```ruby
-# Enqueue a job to be performed as soon the queuing system is
-# free.
-GuestsCleanupJob.perform_later guest
-```
-
-```ruby
-# Enqueue a job to be performed tomorrow at noon.
-GuestsCleanupJob.set(wait_until: Date.tomorrow.noon).perform_later(guest)
-```
-
-```ruby
-# Enqueue a job to be performed 1 week from now.
-GuestsCleanupJob.set(wait: 1.week).perform_later(guest)
-```
-
-```ruby
-# `perform_now` and `perform_later` will call `perform` under the hood so
-# you can pass as many arguments as defined in the latter.
-GuestsCleanupJob.perform_later(guest1, guest2, filter: 'some_filter')
-```
-
-That's it!
-
-Job Execution
--------------
-
-If no adapter is set, the job is immediately executed.
-
-### Backends
-
-Active Job has built-in adapters for multiple queueing backends (Sidekiq,
-Resque, Delayed Job and others). To get an up-to-date list of the adapters
-see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
-
-### Setting the Backend
-
-You can easily set your queueing backend:
-
-```ruby
-# config/application.rb
-module YourApp
-  class Application < Rails::Application
-    # Be sure to have the adapter's gem in your Gemfile and follow
-    # the adapter's specific installation and deployment instructions.
-    config.active_job.queue_adapter = :sidekiq
-  end
-end
-```
-
-
-Queues
-------
-
-Most of the adapters support multiple queues. With Active Job you can schedule
-the job to run on a specific queue:
-
-```ruby
-class GuestsCleanupJob < ActiveJob::Base
-  queue_as :low_priority
-  #....
-end
-```
-
-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 staging_low_priority on your staging
-# environment
-```
-
-The default queue name prefix delimiter is '\_'.  This can be changed by setting
-`config.active_job.queue_name_delimiter` in `application.rb`:
-
-```ruby
-# config/application.rb
-module YourApp
-  class Application < Rails::Application
-    config.active_job.queue_name_prefix = Rails.env
-    config.active_job.queue_name_delimiter = '.'
-  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 staging.low_priority on your staging
-# environment
-```
-
-If you want more control on what queue a job will be run you can pass a `:queue`
-option to `#set`:
-
-```ruby
-MyJob.set(queue: :another_queue).perform_later(record)
-```
-
-To control the queue from the job level you can pass a block to `#queue_as`. The
-block will be executed in the job context (so you can access `self.arguments`)
-and you must return the queue name:
-
-```ruby
-class ProcessVideoJob < ActiveJob::Base
-  queue_as do
-    video = self.arguments.first
-    if video.owner.premium?
-      :premium_videojobs
-    else
-      :videojobs
-    end
-  end
-
-  def perform(video)
-    # do process video
-  end
-end
-
-ProcessVideoJob.perform_later(Video.last)
-```
-
-NOTE: Make sure your queueing backend "listens" on your queue name. For some
-backends you need to specify the queues to listen to.
-
-
-Callbacks
----------
-
-Active Job provides hooks during the lifecycle of a job. Callbacks allow you to
-trigger logic during the lifecycle of a job.
-
-### Available callbacks
-
-* `before_enqueue`
-* `around_enqueue`
-* `after_enqueue`
-* `before_perform`
-* `around_perform`
-* `after_perform`
-
-### Usage
-
-```ruby
-class GuestsCleanupJob < ActiveJob::Base
-  queue_as :default
-
-  before_enqueue do |job|
-    # do something with the job instance
-  end
-
-  around_perform do |job, block|
-    # do something before perform
-    block.call
-    # do something after perform
-  end
-
-  def perform
-    # Do something later
-  end
-end
-```
-
-
-Action Mailer
-------------
-
-One of the most common jobs in a modern web application is sending emails outside
-of the request-response cycle, so the user doesn't have to wait on it. Active Job
-is integrated with Action Mailer so you can easily send emails asynchronously:
-
-```ruby
-# If you want to send the email now use #deliver_now
-UserMailer.welcome(@user).deliver_now
-
-# If you want to send the email through Active Job use #deliver_later
-UserMailer.welcome(@user).deliver_later
-```
-
-
-Internationalization
---------------------
-
-Each job uses the `I18n.locale` set when the job was created. Useful if you send
-emails asynchronously:
-
-```ruby
-I18n.locale = :eo
-
-UserMailer.welcome(@user).deliver_later # Email will be localized to Esparanto.
-```
-
-
-GlobalID
---------
-
-Active Job supports GlobalID for parameters. This makes it possible to pass live
-Active Record objects to your job instead of class/id pairs, which you then have
-to manually deserialize. Before, jobs would look like this:
-
-```ruby
-class TrashableCleanupJob < ActiveJob::Base
-  def perform(trashable_class, trashable_id, depth)
-    trashable = trashable_class.constantize.find(trashable_id)
-    trashable.cleanup(depth)
-  end
-end
-```
-
-Now you can simply do:
-
-```ruby
-class TrashableCleanupJob < ActiveJob::Base
-  def perform(trashable, depth)
-    trashable.cleanup(depth)
-  end
-end
-```
-
-This works with any class that mixes in `GlobalID::Identification`, which
-by default has been mixed into Active Model classes.
-
-
-Exceptions
-----------
-
-Active Job provides a way to catch exceptions raised during the execution of the
-job:
-
-```ruby
-
-class GuestsCleanupJob < ActiveJob::Base
-  queue_as :default
-
-  rescue_from(ActiveRecord::RecordNotFound) do |exception|
-   # do something with the exception
-  end
-
-  def perform
-    # Do something later
-  end
-end
-```

data/guides/source/active_model_basics.md

@@ -1,554 +0,0 @@
-Active Model Basics
-===================
-
-This guide should provide you with all you need to get started using model
-classes. Active Model allows for Action Pack helpers to interact with
-plain Ruby objects. Active Model also helps build custom ORMs for use
-outside of the Rails framework.
-
-After reading this guide, you will be able to add to plain Ruby objects:
-
-* The ability to behave like an Active Record model.
-* Callbacks and validations like Active Record.
-* Serializers.
-* Integration with the Rails internationalization (i18n) framework.
-
---------------------------------------------------------------------------------
-
-Introduction
-------------
-
-Active Model is a library containing various modules used in developing
-classes that need some features present on Active Record.
-Some of these modules are explained below.
-
-### Attribute Methods
-
-The `ActiveModel::AttributeMethods` module can add custom prefixes and suffixes
-on methods of a class. It is used by defining the prefixes and suffixes and
-which methods on the object will use them.
-
-```ruby
-class Person
-  include ActiveModel::AttributeMethods
-
-  attribute_method_prefix 'reset_'
-  attribute_method_suffix '_highest?'
-  define_attribute_methods 'age'
-
-  attr_accessor :age
-
-  private
-    def reset_attribute(attribute)
-      send("#{attribute}=", 0)
-    end
-
-    def attribute_highest?(attribute)
-      send(attribute) > 100
-    end
-end
-
-person = Person.new
-person.age = 110
-person.age_highest?  # => true
-person.reset_age     # => 0
-person.age_highest?  # => false
-```
-
-### Callbacks
-
-`ActiveModel::Callbacks` gives Active Record style callbacks. This provides an
-ability to define callbacks which run at appropriate times.
-After defining callbacks, you can wrap them with before, after and around
-custom methods.
-
-```ruby
-class Person
-  extend ActiveModel::Callbacks
-
-  define_model_callbacks :update
-
-  before_update :reset_me
-
-  def update
-    run_callbacks(:update) do
-      # This method is called when update is called on an object.
-    end
-  end
-
-  def reset_me
-    # This method is called when update is called on an object as a before_update callback is defined.
-  end
-end
-```
-
-### Conversion
-
-If a class defines `persisted?` and `id` methods, then you can include the
-`ActiveModel::Conversion` module in that class and call the Rails conversion
-methods on objects of that class.
-
-```ruby
-class Person
-  include ActiveModel::Conversion
-
-  def persisted?
-    false
-  end
-
-  def id
-    nil
-  end
-end
-
-person = Person.new
-person.to_model == person  # => true
-person.to_key              # => nil
-person.to_param            # => nil
-```
-
-### Dirty
-
-An object becomes dirty when it has gone through one or more changes to its
-attributes and has not been saved. `ActiveModel::Dirty` gives the ability to
-check whether an object has been changed or not. It also has attribute based
-accessor methods. Let's consider a Person class with attributes `first_name`
-and `last_name`:
-
-```ruby
-class Person
-  include ActiveModel::Dirty
-  define_attribute_methods :first_name, :last_name
-
-  def first_name
-    @first_name
-  end
-
-  def first_name=(value)
-    first_name_will_change!
-    @first_name = value
-  end
-
-  def last_name
-    @last_name
-  end
-
-  def last_name=(value)
-    last_name_will_change!
-    @last_name = value
-  end
-
-  def save
-    # do save work...
-    changes_applied
-  end
-end
-```
-
-#### Querying object directly for its list of all changed attributes.
-
-```ruby
-person = Person.new
-person.changed? # => false
-
-person.first_name = "First Name"
-person.first_name # => "First Name"
-
-# returns if any attribute has changed.
-person.changed? # => true
-
-# returns a list of attributes that have changed before saving.
-person.changed # => ["first_name"]
-
-# returns a hash of the attributes that have changed with their original values.
-person.changed_attributes # => {"first_name"=>nil}
-
-# returns a hash of changes, with the attribute names as the keys, and the values will be an array of the old and new value for that field.
-person.changes # => {"first_name"=>[nil, "First Name"]}
-```
-
-#### Attribute based accessor methods
-
-Track whether the particular attribute has been changed or not.
-
-```ruby
-# attr_name_changed?
-person.first_name # => "First Name"
-person.first_name_changed? # => true
-```
-
-Track what was the previous value of the attribute.
-
-```ruby
-# attr_name_was accessor
-person.first_name_was # => nil
-```
-
-Track both previous and current value of the changed attribute. Returns an array
-if changed, else returns nil.
-
-```ruby
-# attr_name_change
-person.first_name_change # => [nil, "First Name"]
-person.last_name_change # => nil
-```
-
-### Validations
-
-`ActiveModel::Validations` module adds the ability to validate class objects
-like in Active Record.
-
-```ruby
-class Person
-  include ActiveModel::Validations
-
-  attr_accessor :name, :email, :token
-
-  validates :name, presence: true
-  validates_format_of :email, with: /\A([^\s]+)((?:[-a-z0-9]\.)[a-z]{2,})\z/i
-  validates! :token, presence: true
-end
-
-person = Person.new
-person.token = "2b1f325"
-person.valid?                        # => false
-person.name = 'vishnu'
-person.email = 'me'
-person.valid?                        # => false
-person.email = 'me@vishnuatrai.com'
-person.valid?                        # => true
-person.token = nil
-person.valid?                        # => raises ActiveModel::StrictValidationFailed
-```
-
-### Naming
-
-`ActiveModel::Naming` adds a number of class methods which make the naming and routing
-easier to manage. The module defines the `model_name` class method which
-will define a number of accessors using some `ActiveSupport::Inflector` methods.
-
-```ruby
-class Person
-  extend ActiveModel::Naming
-end
-
-Person.model_name.name                # => "Person"
-Person.model_name.singular            # => "person"
-Person.model_name.plural              # => "people"
-Person.model_name.element             # => "person"
-Person.model_name.human               # => "Person"
-Person.model_name.collection          # => "people"
-Person.model_name.param_key           # => "person"
-Person.model_name.i18n_key            # => :person
-Person.model_name.route_key           # => "people"
-Person.model_name.singular_route_key  # => "person"
-```
-
-### Model
-
-`ActiveModel::Model` adds the ability to a class to work with Action Pack and
-Action View right out of the box.
-
-```ruby
-class EmailContact
-  include ActiveModel::Model
-
-  attr_accessor :name, :email, :message
-  validates :name, :email, :message, presence: true
-
-  def deliver
-    if valid?
-      # deliver email
-    end
-  end
-end
-```
-
-When including `ActiveModel::Model` you get some features like:
-
-- model name introspection
-- conversions
-- translations
-- validations
-
-It also gives you the ability to initialize an object with a hash of attributes,
-much like any Active Record object.
-
-```ruby
-email_contact = EmailContact.new(name: 'David',
-                                 email: 'david@example.com',
-                                 message: 'Hello World')
-email_contact.name       # => 'David'
-email_contact.email      # => 'david@example.com'
-email_contact.valid?     # => true
-email_contact.persisted? # => false
-```
-
-Any class that includes `ActiveModel::Model` can be used with `form_for`,
-`render` and any other Action View helper methods, just like Active Record
-objects.
-
-### Serialization
-
-`ActiveModel::Serialization` provides a basic serialization for your object.
-You need to declare an attributes hash which contains the attributes you want to
-serialize. Attributes must be strings, not symbols.
-
-```ruby
-class Person
-  include ActiveModel::Serialization
-
-  attr_accessor :name
-
-  def attributes
-    {'name' => nil}
-  end
-end
-```
-
-Now you can access a serialized hash of your object using the `serializable_hash`.
-
-```ruby
-person = Person.new
-person.serializable_hash   # => {"name"=>nil}
-person.name = "Bob"
-person.serializable_hash   # => {"name"=>"Bob"}
-```
-
-#### ActiveModel::Serializers
-
-Rails provides two serializers `ActiveModel::Serializers::JSON` and
-`ActiveModel::Serializers::Xml`. Both of these modules automatically include
-the `ActiveModel::Serialization`.
-
-##### ActiveModel::Serializers::JSON
-
-To use the `ActiveModel::Serializers::JSON` you only need to change from
-`ActiveModel::Serialization` to `ActiveModel::Serializers::JSON`.
-
-```ruby
-class Person
-  include ActiveModel::Serializers::JSON
-
-  attr_accessor :name
-
-  def attributes
-    {'name' => nil}
-  end
-end
-```
-
-With the `as_json` you have a hash representing the model.
-
-```ruby
-person = Person.new
-person.as_json # => {"name"=>nil}
-person.name = "Bob"
-person.as_json # => {"name"=>"Bob"}
-```
-
-From a JSON string you define the attributes of the model.
-You need to have the `attributes=` method defined on your class:
-
-```ruby
-class Person
-  include ActiveModel::Serializers::JSON
-
-  attr_accessor :name
-
-  def attributes=(hash)
-    hash.each do |key, value|
-      send("#{key}=", value)
-    end
-  end
-
-  def attributes
-    {'name' => nil}
-  end
-end
-```
-
-Now it is possible to create an instance of person and set the attributes using `from_json`.
-
-```ruby
-json = { name: 'Bob' }.to_json
-person = Person.new
-person.from_json(json) # => #<Person:0x00000100c773f0 @name="Bob">
-person.name            # => "Bob"
-```
-
-##### ActiveModel::Serializers::Xml
-
-To use the `ActiveModel::Serializers::Xml` you only need to change from
-`ActiveModel::Serialization` to `ActiveModel::Serializers::Xml`.
-
-```ruby
-class Person
-  include ActiveModel::Serializers::Xml
-
-  attr_accessor :name
-
-  def attributes
-    {'name' => nil}
-  end
-end
-```
-
-With the `to_xml` you have a XML representing the model.
-
-```ruby
-person = Person.new
-person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n  <name nil=\"true\"/>\n</person>\n"
-person.name = "Bob"
-person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n  <name>Bob</name>\n</person>\n"
-```
-
-From a XML string you define the attributes of the model.
-You need to have the `attributes=` method defined on your class:
-
-```ruby
-class Person
-  include ActiveModel::Serializers::Xml
-
-  attr_accessor :name
-
-  def attributes=(hash)
-    hash.each do |key, value|
-      send("#{key}=", value)
-    end
-  end
-
-  def attributes
-    {'name' => nil}
-  end
-end
-```
-
-Now it is possible to create an instance of person and set the attributes using `from_xml`.
-
-```ruby
-xml = { name: 'Bob' }.to_xml
-person = Person.new
-person.from_xml(xml) # => #<Person:0x00000100c773f0 @name="Bob">
-person.name          # => "Bob"
-```
-
-### Translation
-
-`ActiveModel::Translation` provides integration between your object and the Rails
-internationalization (i18n) framework.
-
-```ruby
-class Person
-  extend ActiveModel::Translation
-end
-```
-
-With the `human_attribute_name` you can transform attribute names into a more
-human format. The human format is defined in your locale file.
-
-* config/locales/app.pt-BR.yml
-
-  ```yml
-  pt-BR:
-    activemodel:
-      attributes:
-        person:
-          name: 'Nome'
-  ```
-
-```ruby
-Person.human_attribute_name('name') # => "Nome"
-```
-
-### Lint Tests
-
-`ActiveModel::Lint::Tests` allow you to test whether an object is compliant with
-the Active Model API.
-
-* app/models/person.rb
-
-    ```ruby
-    class Person
-      include ActiveModel::Model
-
-    end
-    ```
-
-* test/models/person_test.rb
-
-    ```ruby
-    require 'test_helper'
-
-    class PersonTest < ActiveSupport::TestCase
-      include ActiveModel::Lint::Tests
-
-      def setup
-        @model = Person.new
-      end
-    end
-    ```
-
-```bash
-$ rake test
-
-Run options: --seed 14596
-
-# Running:
-
-......
-
-Finished in 0.024899s, 240.9735 runs/s, 1204.8677 assertions/s.
-
-6 runs, 30 assertions, 0 failures, 0 errors, 0 skips
-```
-
-An object is not required to implement all APIs in order to work with
-Action Pack. This module only intends to provide guidance in case you want all
-features out of the box.
-
-### SecurePassword
-
-`ActiveModel::SecurePassword` provides a way to securely store any
-password in an encrypted form. On including this module, a
-`has_secure_password` class method is provided which defines
-an accessor named `password` with certain validations on it.
-
-#### Requirements
-
-`ActiveModel::SecurePassword` depends on the [`bcrypt`](https://github.com/codahale/bcrypt-ruby 'BCrypt'),
-so include this gem in your Gemfile to use `ActiveModel::SecurePassword` correctly.
-In order to make this work, the model must have an accessor named `password_digest`.
-The `has_secure_password` will add the following validations on the `password` accessor:
-
-1. Password should be present.
-2. Password should be equal to its confirmation.
-3. This maximum length of a password is 72 (required by `bcrypt` on which ActiveModel::SecurePassword depends)
-
-#### Examples
-
-```ruby
-class Person
-  include ActiveModel::SecurePassword
-  has_secure_password
-  attr_accessor :password_digest
-end
-
-person = Person.new
-
-# When password is blank.
-person.valid? # => false
-
-# When the confirmation doesn't match the password.
-person.password = 'aditya'
-person.password_confirmation = 'nomatch'
-person.valid? # => false
-
-# When the length of password, exceeds 72.
-person.password = person.password_confirmation = 'a' * 100
-person.valid? # => false
-
-# When all validations are passed.
-person.password = person.password_confirmation = 'aditya'
-person.valid? # => true
-```