rails 4.2.10 → 6.1.3

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of rails might be problematic. Click here for more details.

Files changed (218) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +54 -36
  3. metadata +90 -251
  4. data/guides/CHANGELOG.md +0 -93
  5. data/guides/Rakefile +0 -92
  6. data/guides/assets/images/akshaysurve.jpg +0 -0
  7. data/guides/assets/images/belongs_to.png +0 -0
  8. data/guides/assets/images/book_icon.gif +0 -0
  9. data/guides/assets/images/bullet.gif +0 -0
  10. data/guides/assets/images/chapters_icon.gif +0 -0
  11. data/guides/assets/images/check_bullet.gif +0 -0
  12. data/guides/assets/images/credits_pic_blank.gif +0 -0
  13. data/guides/assets/images/csrf.png +0 -0
  14. data/guides/assets/images/edge_badge.png +0 -0
  15. data/guides/assets/images/favicon.ico +0 -0
  16. data/guides/assets/images/feature_tile.gif +0 -0
  17. data/guides/assets/images/footer_tile.gif +0 -0
  18. data/guides/assets/images/fxn.png +0 -0
  19. data/guides/assets/images/getting_started/article_with_comments.png +0 -0
  20. data/guides/assets/images/getting_started/challenge.png +0 -0
  21. data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
  22. data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
  23. data/guides/assets/images/getting_started/form_with_errors.png +0 -0
  24. data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
  25. data/guides/assets/images/getting_started/new_article.png +0 -0
  26. data/guides/assets/images/getting_started/rails_welcome.png +0 -0
  27. data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
  28. data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
  29. data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
  30. data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
  31. data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
  32. data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
  33. data/guides/assets/images/grey_bullet.gif +0 -0
  34. data/guides/assets/images/habtm.png +0 -0
  35. data/guides/assets/images/has_many.png +0 -0
  36. data/guides/assets/images/has_many_through.png +0 -0
  37. data/guides/assets/images/has_one.png +0 -0
  38. data/guides/assets/images/has_one_through.png +0 -0
  39. data/guides/assets/images/header_backdrop.png +0 -0
  40. data/guides/assets/images/header_tile.gif +0 -0
  41. data/guides/assets/images/i18n/demo_html_safe.png +0 -0
  42. data/guides/assets/images/i18n/demo_localized_pirate.png +0 -0
  43. data/guides/assets/images/i18n/demo_translated_en.png +0 -0
  44. data/guides/assets/images/i18n/demo_translated_pirate.png +0 -0
  45. data/guides/assets/images/i18n/demo_translation_missing.png +0 -0
  46. data/guides/assets/images/i18n/demo_untranslated.png +0 -0
  47. data/guides/assets/images/icons/README +0 -5
  48. data/guides/assets/images/icons/callouts/1.png +0 -0
  49. data/guides/assets/images/icons/callouts/10.png +0 -0
  50. data/guides/assets/images/icons/callouts/11.png +0 -0
  51. data/guides/assets/images/icons/callouts/12.png +0 -0
  52. data/guides/assets/images/icons/callouts/13.png +0 -0
  53. data/guides/assets/images/icons/callouts/14.png +0 -0
  54. data/guides/assets/images/icons/callouts/15.png +0 -0
  55. data/guides/assets/images/icons/callouts/2.png +0 -0
  56. data/guides/assets/images/icons/callouts/3.png +0 -0
  57. data/guides/assets/images/icons/callouts/4.png +0 -0
  58. data/guides/assets/images/icons/callouts/5.png +0 -0
  59. data/guides/assets/images/icons/callouts/6.png +0 -0
  60. data/guides/assets/images/icons/callouts/7.png +0 -0
  61. data/guides/assets/images/icons/callouts/8.png +0 -0
  62. data/guides/assets/images/icons/callouts/9.png +0 -0
  63. data/guides/assets/images/icons/caution.png +0 -0
  64. data/guides/assets/images/icons/example.png +0 -0
  65. data/guides/assets/images/icons/home.png +0 -0
  66. data/guides/assets/images/icons/important.png +0 -0
  67. data/guides/assets/images/icons/next.png +0 -0
  68. data/guides/assets/images/icons/note.png +0 -0
  69. data/guides/assets/images/icons/prev.png +0 -0
  70. data/guides/assets/images/icons/tip.png +0 -0
  71. data/guides/assets/images/icons/up.png +0 -0
  72. data/guides/assets/images/icons/warning.png +0 -0
  73. data/guides/assets/images/nav_arrow.gif +0 -0
  74. data/guides/assets/images/oscardelben.jpg +0 -0
  75. data/guides/assets/images/polymorphic.png +0 -0
  76. data/guides/assets/images/radar.png +0 -0
  77. data/guides/assets/images/rails4_features.png +0 -0
  78. data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
  79. data/guides/assets/images/rails_guides_logo.gif +0 -0
  80. data/guides/assets/images/rails_logo_remix.gif +0 -0
  81. data/guides/assets/images/session_fixation.png +0 -0
  82. data/guides/assets/images/tab_grey.gif +0 -0
  83. data/guides/assets/images/tab_info.gif +0 -0
  84. data/guides/assets/images/tab_note.gif +0 -0
  85. data/guides/assets/images/tab_red.gif +0 -0
  86. data/guides/assets/images/tab_yellow.gif +0 -0
  87. data/guides/assets/images/tab_yellow.png +0 -0
  88. data/guides/assets/images/vijaydev.jpg +0 -0
  89. data/guides/assets/javascripts/guides.js +0 -59
  90. data/guides/assets/javascripts/jquery.min.js +0 -4
  91. data/guides/assets/javascripts/responsive-tables.js +0 -43
  92. data/guides/assets/javascripts/syntaxhighlighter/shBrushAS3.js +0 -59
  93. data/guides/assets/javascripts/syntaxhighlighter/shBrushAppleScript.js +0 -75
  94. data/guides/assets/javascripts/syntaxhighlighter/shBrushBash.js +0 -59
  95. data/guides/assets/javascripts/syntaxhighlighter/shBrushCSharp.js +0 -65
  96. data/guides/assets/javascripts/syntaxhighlighter/shBrushColdFusion.js +0 -100
  97. data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js +0 -97
  98. data/guides/assets/javascripts/syntaxhighlighter/shBrushCss.js +0 -91
  99. data/guides/assets/javascripts/syntaxhighlighter/shBrushDelphi.js +0 -55
  100. data/guides/assets/javascripts/syntaxhighlighter/shBrushDiff.js +0 -41
  101. data/guides/assets/javascripts/syntaxhighlighter/shBrushErlang.js +0 -52
  102. data/guides/assets/javascripts/syntaxhighlighter/shBrushGroovy.js +0 -67
  103. data/guides/assets/javascripts/syntaxhighlighter/shBrushJScript.js +0 -52
  104. data/guides/assets/javascripts/syntaxhighlighter/shBrushJava.js +0 -57
  105. data/guides/assets/javascripts/syntaxhighlighter/shBrushJavaFX.js +0 -58
  106. data/guides/assets/javascripts/syntaxhighlighter/shBrushPerl.js +0 -72
  107. data/guides/assets/javascripts/syntaxhighlighter/shBrushPhp.js +0 -88
  108. data/guides/assets/javascripts/syntaxhighlighter/shBrushPlain.js +0 -33
  109. data/guides/assets/javascripts/syntaxhighlighter/shBrushPowerShell.js +0 -74
  110. data/guides/assets/javascripts/syntaxhighlighter/shBrushPython.js +0 -64
  111. data/guides/assets/javascripts/syntaxhighlighter/shBrushRuby.js +0 -55
  112. data/guides/assets/javascripts/syntaxhighlighter/shBrushSass.js +0 -94
  113. data/guides/assets/javascripts/syntaxhighlighter/shBrushScala.js +0 -51
  114. data/guides/assets/javascripts/syntaxhighlighter/shBrushSql.js +0 -66
  115. data/guides/assets/javascripts/syntaxhighlighter/shBrushVb.js +0 -56
  116. data/guides/assets/javascripts/syntaxhighlighter/shBrushXml.js +0 -69
  117. data/guides/assets/javascripts/syntaxhighlighter/shCore.js +0 -17
  118. data/guides/assets/stylesheets/fixes.css +0 -16
  119. data/guides/assets/stylesheets/kindle.css +0 -11
  120. data/guides/assets/stylesheets/main.css +0 -713
  121. data/guides/assets/stylesheets/print.css +0 -52
  122. data/guides/assets/stylesheets/reset.css +0 -43
  123. data/guides/assets/stylesheets/responsive-tables.css +0 -50
  124. data/guides/assets/stylesheets/style.css +0 -13
  125. data/guides/assets/stylesheets/syntaxhighlighter/shCore.css +0 -226
  126. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDefault.css +0 -328
  127. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDjango.css +0 -331
  128. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEclipse.css +0 -339
  129. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEmacs.css +0 -324
  130. data/guides/assets/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +0 -328
  131. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMDUltra.css +0 -324
  132. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMidnight.css +0 -324
  133. data/guides/assets/stylesheets/syntaxhighlighter/shCoreRDark.css +0 -324
  134. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDefault.css +0 -117
  135. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDjango.css +0 -120
  136. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEclipse.css +0 -128
  137. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEmacs.css +0 -113
  138. data/guides/assets/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +0 -117
  139. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMDUltra.css +0 -113
  140. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMidnight.css +0 -113
  141. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRDark.css +0 -113
  142. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +0 -116
  143. data/guides/bug_report_templates/action_controller_gem.rb +0 -47
  144. data/guides/bug_report_templates/action_controller_master.rb +0 -54
  145. data/guides/bug_report_templates/active_record_gem.rb +0 -40
  146. data/guides/bug_report_templates/active_record_master.rb +0 -49
  147. data/guides/bug_report_templates/generic_gem.rb +0 -15
  148. data/guides/bug_report_templates/generic_master.rb +0 -26
  149. data/guides/rails_guides.rb +0 -63
  150. data/guides/rails_guides/generator.rb +0 -248
  151. data/guides/rails_guides/helpers.rb +0 -53
  152. data/guides/rails_guides/indexer.rb +0 -68
  153. data/guides/rails_guides/kindle.rb +0 -119
  154. data/guides/rails_guides/levenshtein.rb +0 -37
  155. data/guides/rails_guides/markdown.rb +0 -167
  156. data/guides/rails_guides/markdown/renderer.rb +0 -82
  157. data/guides/source/2_2_release_notes.md +0 -435
  158. data/guides/source/2_3_release_notes.md +0 -621
  159. data/guides/source/3_0_release_notes.md +0 -611
  160. data/guides/source/3_1_release_notes.md +0 -559
  161. data/guides/source/3_2_release_notes.md +0 -568
  162. data/guides/source/4_0_release_notes.md +0 -279
  163. data/guides/source/4_1_release_notes.md +0 -730
  164. data/guides/source/4_2_release_notes.md +0 -877
  165. data/guides/source/_license.html.erb +0 -2
  166. data/guides/source/_welcome.html.erb +0 -23
  167. data/guides/source/action_controller_overview.md +0 -1192
  168. data/guides/source/action_mailer_basics.md +0 -757
  169. data/guides/source/action_view_overview.md +0 -1561
  170. data/guides/source/active_job_basics.md +0 -339
  171. data/guides/source/active_model_basics.md +0 -554
  172. data/guides/source/active_record_basics.md +0 -374
  173. data/guides/source/active_record_callbacks.md +0 -413
  174. data/guides/source/active_record_migrations.md +0 -1018
  175. data/guides/source/active_record_postgresql.md +0 -433
  176. data/guides/source/active_record_querying.md +0 -1781
  177. data/guides/source/active_record_validations.md +0 -1179
  178. data/guides/source/active_support_core_extensions.md +0 -3856
  179. data/guides/source/active_support_instrumentation.md +0 -488
  180. data/guides/source/api_documentation_guidelines.md +0 -361
  181. data/guides/source/asset_pipeline.md +0 -1304
  182. data/guides/source/association_basics.md +0 -2245
  183. data/guides/source/autoloading_and_reloading_constants.md +0 -1311
  184. data/guides/source/caching_with_rails.md +0 -379
  185. data/guides/source/command_line.md +0 -625
  186. data/guides/source/configuring.md +0 -1070
  187. data/guides/source/contributing_to_ruby_on_rails.md +0 -628
  188. data/guides/source/credits.html.erb +0 -80
  189. data/guides/source/debugging_rails_applications.md +0 -861
  190. data/guides/source/development_dependencies_install.md +0 -289
  191. data/guides/source/documents.yaml +0 -205
  192. data/guides/source/engines.md +0 -1412
  193. data/guides/source/form_helpers.md +0 -1024
  194. data/guides/source/generators.md +0 -676
  195. data/guides/source/getting_started.md +0 -2086
  196. data/guides/source/i18n.md +0 -1087
  197. data/guides/source/index.html.erb +0 -28
  198. data/guides/source/initialization.md +0 -704
  199. data/guides/source/kindle/copyright.html.erb +0 -1
  200. data/guides/source/kindle/layout.html.erb +0 -27
  201. data/guides/source/kindle/rails_guides.opf.erb +0 -52
  202. data/guides/source/kindle/toc.html.erb +0 -24
  203. data/guides/source/kindle/toc.ncx.erb +0 -64
  204. data/guides/source/kindle/welcome.html.erb +0 -5
  205. data/guides/source/layout.html.erb +0 -140
  206. data/guides/source/layouts_and_rendering.md +0 -1226
  207. data/guides/source/maintenance_policy.md +0 -78
  208. data/guides/source/nested_model_forms.md +0 -228
  209. data/guides/source/plugins.md +0 -444
  210. data/guides/source/rails_application_templates.md +0 -266
  211. data/guides/source/rails_on_rack.md +0 -335
  212. data/guides/source/routing.md +0 -1155
  213. data/guides/source/ruby_on_rails_guides_guidelines.md +0 -127
  214. data/guides/source/security.md +0 -1024
  215. data/guides/source/testing.md +0 -1132
  216. data/guides/source/upgrading_ruby_on_rails.md +0 -1186
  217. data/guides/source/working_with_javascript_in_rails.md +0 -407
  218. data/guides/w3c_validator.rb +0 -97
@@ -1,339 +0,0 @@
1
- Active Job Basics
2
- =================
3
-
4
- This guide provides you with all you need to get started in creating,
5
- enqueueing and executing background jobs.
6
-
7
- After reading this guide, you will know:
8
-
9
- * How to create jobs.
10
- * How to enqueue jobs.
11
- * How to run jobs in the background.
12
- * How to send emails from your application async.
13
-
14
- --------------------------------------------------------------------------------
15
-
16
-
17
- Introduction
18
- ------------
19
-
20
- Active Job is a framework for declaring jobs and making them run on a variety
21
- of queueing backends. These jobs can be everything from regularly scheduled
22
- clean-ups, to billing charges, to mailings. Anything that can be chopped up
23
- into small units of work and run in parallel, really.
24
-
25
-
26
- The Purpose of Active Job
27
- -----------------------------
28
- The main point is to ensure that all Rails apps will have a job infrastructure
29
- in place, even if it's in the form of an "immediate runner". We can then have
30
- framework features and other gems build on top of that, without having to
31
- worry about API differences between various job runners such as Delayed Job
32
- and Resque. Picking your queuing backend becomes more of an operational concern,
33
- then. And you'll be able to switch between them without having to rewrite your jobs.
34
-
35
-
36
- Creating a Job
37
- --------------
38
-
39
- This section will provide a step-by-step guide to creating a job and enqueuing it.
40
-
41
- ### Create the Job
42
-
43
- Active Job provides a Rails generator to create jobs. The following will create a
44
- job in `app/jobs` (with an attached test case under `test/jobs`):
45
-
46
- ```bash
47
- $ bin/rails generate job guests_cleanup
48
- invoke test_unit
49
- create test/jobs/guests_cleanup_job_test.rb
50
- create app/jobs/guests_cleanup_job.rb
51
- ```
52
-
53
- You can also create a job that will run on a specific queue:
54
-
55
- ```bash
56
- $ bin/rails generate job guests_cleanup --queue urgent
57
- ```
58
-
59
- If you don't want to use a generator, you could create your own file inside of
60
- `app/jobs`, just make sure that it inherits from `ActiveJob::Base`.
61
-
62
- Here's what a job looks like:
63
-
64
- ```ruby
65
- class GuestsCleanupJob < ActiveJob::Base
66
- queue_as :default
67
-
68
- def perform(*guests)
69
- # Do something later
70
- end
71
- end
72
- ```
73
-
74
- Note that you can define `perform` with as many arguments as you want.
75
-
76
- ### Enqueue the Job
77
-
78
- Enqueue a job like so:
79
-
80
- ```ruby
81
- # Enqueue a job to be performed as soon the queuing system is
82
- # free.
83
- GuestsCleanupJob.perform_later guest
84
- ```
85
-
86
- ```ruby
87
- # Enqueue a job to be performed tomorrow at noon.
88
- GuestsCleanupJob.set(wait_until: Date.tomorrow.noon).perform_later(guest)
89
- ```
90
-
91
- ```ruby
92
- # Enqueue a job to be performed 1 week from now.
93
- GuestsCleanupJob.set(wait: 1.week).perform_later(guest)
94
- ```
95
-
96
- ```ruby
97
- # `perform_now` and `perform_later` will call `perform` under the hood so
98
- # you can pass as many arguments as defined in the latter.
99
- GuestsCleanupJob.perform_later(guest1, guest2, filter: 'some_filter')
100
- ```
101
-
102
- That's it!
103
-
104
- Job Execution
105
- -------------
106
-
107
- If no adapter is set, the job is immediately executed.
108
-
109
- ### Backends
110
-
111
- Active Job has built-in adapters for multiple queueing backends (Sidekiq,
112
- Resque, Delayed Job and others). To get an up-to-date list of the adapters
113
- see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
114
-
115
- ### Setting the Backend
116
-
117
- You can easily set your queueing backend:
118
-
119
- ```ruby
120
- # config/application.rb
121
- module YourApp
122
- class Application < Rails::Application
123
- # Be sure to have the adapter's gem in your Gemfile and follow
124
- # the adapter's specific installation and deployment instructions.
125
- config.active_job.queue_adapter = :sidekiq
126
- end
127
- end
128
- ```
129
-
130
-
131
- Queues
132
- ------
133
-
134
- Most of the adapters support multiple queues. With Active Job you can schedule
135
- the job to run on a specific queue:
136
-
137
- ```ruby
138
- class GuestsCleanupJob < ActiveJob::Base
139
- queue_as :low_priority
140
- #....
141
- end
142
- ```
143
-
144
- You can prefix the queue name for all your jobs using
145
- `config.active_job.queue_name_prefix` in `application.rb`:
146
-
147
- ```ruby
148
- # config/application.rb
149
- module YourApp
150
- class Application < Rails::Application
151
- config.active_job.queue_name_prefix = Rails.env
152
- end
153
- end
154
-
155
- # app/jobs/guests_cleanup.rb
156
- class GuestsCleanupJob < ActiveJob::Base
157
- queue_as :low_priority
158
- #....
159
- end
160
-
161
- # Now your job will run on queue production_low_priority on your
162
- # production environment and on staging_low_priority on your staging
163
- # environment
164
- ```
165
-
166
- The default queue name prefix delimiter is '\_'. This can be changed by setting
167
- `config.active_job.queue_name_delimiter` in `application.rb`:
168
-
169
- ```ruby
170
- # config/application.rb
171
- module YourApp
172
- class Application < Rails::Application
173
- config.active_job.queue_name_prefix = Rails.env
174
- config.active_job.queue_name_delimiter = '.'
175
- end
176
- end
177
-
178
- # app/jobs/guests_cleanup.rb
179
- class GuestsCleanupJob < ActiveJob::Base
180
- queue_as :low_priority
181
- #....
182
- end
183
-
184
- # Now your job will run on queue production.low_priority on your
185
- # production environment and on staging.low_priority on your staging
186
- # environment
187
- ```
188
-
189
- If you want more control on what queue a job will be run you can pass a `:queue`
190
- option to `#set`:
191
-
192
- ```ruby
193
- MyJob.set(queue: :another_queue).perform_later(record)
194
- ```
195
-
196
- To control the queue from the job level you can pass a block to `#queue_as`. The
197
- block will be executed in the job context (so you can access `self.arguments`)
198
- and you must return the queue name:
199
-
200
- ```ruby
201
- class ProcessVideoJob < ActiveJob::Base
202
- queue_as do
203
- video = self.arguments.first
204
- if video.owner.premium?
205
- :premium_videojobs
206
- else
207
- :videojobs
208
- end
209
- end
210
-
211
- def perform(video)
212
- # do process video
213
- end
214
- end
215
-
216
- ProcessVideoJob.perform_later(Video.last)
217
- ```
218
-
219
- NOTE: Make sure your queueing backend "listens" on your queue name. For some
220
- backends you need to specify the queues to listen to.
221
-
222
-
223
- Callbacks
224
- ---------
225
-
226
- Active Job provides hooks during the lifecycle of a job. Callbacks allow you to
227
- trigger logic during the lifecycle of a job.
228
-
229
- ### Available callbacks
230
-
231
- * `before_enqueue`
232
- * `around_enqueue`
233
- * `after_enqueue`
234
- * `before_perform`
235
- * `around_perform`
236
- * `after_perform`
237
-
238
- ### Usage
239
-
240
- ```ruby
241
- class GuestsCleanupJob < ActiveJob::Base
242
- queue_as :default
243
-
244
- before_enqueue do |job|
245
- # do something with the job instance
246
- end
247
-
248
- around_perform do |job, block|
249
- # do something before perform
250
- block.call
251
- # do something after perform
252
- end
253
-
254
- def perform
255
- # Do something later
256
- end
257
- end
258
- ```
259
-
260
-
261
- Action Mailer
262
- ------------
263
-
264
- One of the most common jobs in a modern web application is sending emails outside
265
- of the request-response cycle, so the user doesn't have to wait on it. Active Job
266
- is integrated with Action Mailer so you can easily send emails asynchronously:
267
-
268
- ```ruby
269
- # If you want to send the email now use #deliver_now
270
- UserMailer.welcome(@user).deliver_now
271
-
272
- # If you want to send the email through Active Job use #deliver_later
273
- UserMailer.welcome(@user).deliver_later
274
- ```
275
-
276
-
277
- Internationalization
278
- --------------------
279
-
280
- Each job uses the `I18n.locale` set when the job was created. Useful if you send
281
- emails asynchronously:
282
-
283
- ```ruby
284
- I18n.locale = :eo
285
-
286
- UserMailer.welcome(@user).deliver_later # Email will be localized to Esparanto.
287
- ```
288
-
289
-
290
- GlobalID
291
- --------
292
-
293
- Active Job supports GlobalID for parameters. This makes it possible to pass live
294
- Active Record objects to your job instead of class/id pairs, which you then have
295
- to manually deserialize. Before, jobs would look like this:
296
-
297
- ```ruby
298
- class TrashableCleanupJob < ActiveJob::Base
299
- def perform(trashable_class, trashable_id, depth)
300
- trashable = trashable_class.constantize.find(trashable_id)
301
- trashable.cleanup(depth)
302
- end
303
- end
304
- ```
305
-
306
- Now you can simply do:
307
-
308
- ```ruby
309
- class TrashableCleanupJob < ActiveJob::Base
310
- def perform(trashable, depth)
311
- trashable.cleanup(depth)
312
- end
313
- end
314
- ```
315
-
316
- This works with any class that mixes in `GlobalID::Identification`, which
317
- by default has been mixed into Active Model classes.
318
-
319
-
320
- Exceptions
321
- ----------
322
-
323
- Active Job provides a way to catch exceptions raised during the execution of the
324
- job:
325
-
326
- ```ruby
327
-
328
- class GuestsCleanupJob < ActiveJob::Base
329
- queue_as :default
330
-
331
- rescue_from(ActiveRecord::RecordNotFound) do |exception|
332
- # do something with the exception
333
- end
334
-
335
- def perform
336
- # Do something later
337
- end
338
- end
339
- ```
@@ -1,554 +0,0 @@
1
- Active Model Basics
2
- ===================
3
-
4
- This guide should provide you with all you need to get started using model
5
- classes. Active Model allows for Action Pack helpers to interact with
6
- plain Ruby objects. Active Model also helps build custom ORMs for use
7
- outside of the Rails framework.
8
-
9
- After reading this guide, you will be able to add to plain Ruby objects:
10
-
11
- * The ability to behave like an Active Record model.
12
- * Callbacks and validations like Active Record.
13
- * Serializers.
14
- * Integration with the Rails internationalization (i18n) framework.
15
-
16
- --------------------------------------------------------------------------------
17
-
18
- Introduction
19
- ------------
20
-
21
- Active Model is a library containing various modules used in developing
22
- classes that need some features present on Active Record.
23
- Some of these modules are explained below.
24
-
25
- ### Attribute Methods
26
-
27
- The `ActiveModel::AttributeMethods` module can add custom prefixes and suffixes
28
- on methods of a class. It is used by defining the prefixes and suffixes and
29
- which methods on the object will use them.
30
-
31
- ```ruby
32
- class Person
33
- include ActiveModel::AttributeMethods
34
-
35
- attribute_method_prefix 'reset_'
36
- attribute_method_suffix '_highest?'
37
- define_attribute_methods 'age'
38
-
39
- attr_accessor :age
40
-
41
- private
42
- def reset_attribute(attribute)
43
- send("#{attribute}=", 0)
44
- end
45
-
46
- def attribute_highest?(attribute)
47
- send(attribute) > 100
48
- end
49
- end
50
-
51
- person = Person.new
52
- person.age = 110
53
- person.age_highest? # => true
54
- person.reset_age # => 0
55
- person.age_highest? # => false
56
- ```
57
-
58
- ### Callbacks
59
-
60
- `ActiveModel::Callbacks` gives Active Record style callbacks. This provides an
61
- ability to define callbacks which run at appropriate times.
62
- After defining callbacks, you can wrap them with before, after and around
63
- custom methods.
64
-
65
- ```ruby
66
- class Person
67
- extend ActiveModel::Callbacks
68
-
69
- define_model_callbacks :update
70
-
71
- before_update :reset_me
72
-
73
- def update
74
- run_callbacks(:update) do
75
- # This method is called when update is called on an object.
76
- end
77
- end
78
-
79
- def reset_me
80
- # This method is called when update is called on an object as a before_update callback is defined.
81
- end
82
- end
83
- ```
84
-
85
- ### Conversion
86
-
87
- If a class defines `persisted?` and `id` methods, then you can include the
88
- `ActiveModel::Conversion` module in that class and call the Rails conversion
89
- methods on objects of that class.
90
-
91
- ```ruby
92
- class Person
93
- include ActiveModel::Conversion
94
-
95
- def persisted?
96
- false
97
- end
98
-
99
- def id
100
- nil
101
- end
102
- end
103
-
104
- person = Person.new
105
- person.to_model == person # => true
106
- person.to_key # => nil
107
- person.to_param # => nil
108
- ```
109
-
110
- ### Dirty
111
-
112
- An object becomes dirty when it has gone through one or more changes to its
113
- attributes and has not been saved. `ActiveModel::Dirty` gives the ability to
114
- check whether an object has been changed or not. It also has attribute based
115
- accessor methods. Let's consider a Person class with attributes `first_name`
116
- and `last_name`:
117
-
118
- ```ruby
119
- class Person
120
- include ActiveModel::Dirty
121
- define_attribute_methods :first_name, :last_name
122
-
123
- def first_name
124
- @first_name
125
- end
126
-
127
- def first_name=(value)
128
- first_name_will_change!
129
- @first_name = value
130
- end
131
-
132
- def last_name
133
- @last_name
134
- end
135
-
136
- def last_name=(value)
137
- last_name_will_change!
138
- @last_name = value
139
- end
140
-
141
- def save
142
- # do save work...
143
- changes_applied
144
- end
145
- end
146
- ```
147
-
148
- #### Querying object directly for its list of all changed attributes.
149
-
150
- ```ruby
151
- person = Person.new
152
- person.changed? # => false
153
-
154
- person.first_name = "First Name"
155
- person.first_name # => "First Name"
156
-
157
- # returns if any attribute has changed.
158
- person.changed? # => true
159
-
160
- # returns a list of attributes that have changed before saving.
161
- person.changed # => ["first_name"]
162
-
163
- # returns a hash of the attributes that have changed with their original values.
164
- person.changed_attributes # => {"first_name"=>nil}
165
-
166
- # 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.
167
- person.changes # => {"first_name"=>[nil, "First Name"]}
168
- ```
169
-
170
- #### Attribute based accessor methods
171
-
172
- Track whether the particular attribute has been changed or not.
173
-
174
- ```ruby
175
- # attr_name_changed?
176
- person.first_name # => "First Name"
177
- person.first_name_changed? # => true
178
- ```
179
-
180
- Track what was the previous value of the attribute.
181
-
182
- ```ruby
183
- # attr_name_was accessor
184
- person.first_name_was # => nil
185
- ```
186
-
187
- Track both previous and current value of the changed attribute. Returns an array
188
- if changed, else returns nil.
189
-
190
- ```ruby
191
- # attr_name_change
192
- person.first_name_change # => [nil, "First Name"]
193
- person.last_name_change # => nil
194
- ```
195
-
196
- ### Validations
197
-
198
- `ActiveModel::Validations` module adds the ability to validate class objects
199
- like in Active Record.
200
-
201
- ```ruby
202
- class Person
203
- include ActiveModel::Validations
204
-
205
- attr_accessor :name, :email, :token
206
-
207
- validates :name, presence: true
208
- validates_format_of :email, with: /\A([^\s]+)((?:[-a-z0-9]\.)[a-z]{2,})\z/i
209
- validates! :token, presence: true
210
- end
211
-
212
- person = Person.new
213
- person.token = "2b1f325"
214
- person.valid? # => false
215
- person.name = 'vishnu'
216
- person.email = 'me'
217
- person.valid? # => false
218
- person.email = 'me@vishnuatrai.com'
219
- person.valid? # => true
220
- person.token = nil
221
- person.valid? # => raises ActiveModel::StrictValidationFailed
222
- ```
223
-
224
- ### Naming
225
-
226
- `ActiveModel::Naming` adds a number of class methods which make the naming and routing
227
- easier to manage. The module defines the `model_name` class method which
228
- will define a number of accessors using some `ActiveSupport::Inflector` methods.
229
-
230
- ```ruby
231
- class Person
232
- extend ActiveModel::Naming
233
- end
234
-
235
- Person.model_name.name # => "Person"
236
- Person.model_name.singular # => "person"
237
- Person.model_name.plural # => "people"
238
- Person.model_name.element # => "person"
239
- Person.model_name.human # => "Person"
240
- Person.model_name.collection # => "people"
241
- Person.model_name.param_key # => "person"
242
- Person.model_name.i18n_key # => :person
243
- Person.model_name.route_key # => "people"
244
- Person.model_name.singular_route_key # => "person"
245
- ```
246
-
247
- ### Model
248
-
249
- `ActiveModel::Model` adds the ability to a class to work with Action Pack and
250
- Action View right out of the box.
251
-
252
- ```ruby
253
- class EmailContact
254
- include ActiveModel::Model
255
-
256
- attr_accessor :name, :email, :message
257
- validates :name, :email, :message, presence: true
258
-
259
- def deliver
260
- if valid?
261
- # deliver email
262
- end
263
- end
264
- end
265
- ```
266
-
267
- When including `ActiveModel::Model` you get some features like:
268
-
269
- - model name introspection
270
- - conversions
271
- - translations
272
- - validations
273
-
274
- It also gives you the ability to initialize an object with a hash of attributes,
275
- much like any Active Record object.
276
-
277
- ```ruby
278
- email_contact = EmailContact.new(name: 'David',
279
- email: 'david@example.com',
280
- message: 'Hello World')
281
- email_contact.name # => 'David'
282
- email_contact.email # => 'david@example.com'
283
- email_contact.valid? # => true
284
- email_contact.persisted? # => false
285
- ```
286
-
287
- Any class that includes `ActiveModel::Model` can be used with `form_for`,
288
- `render` and any other Action View helper methods, just like Active Record
289
- objects.
290
-
291
- ### Serialization
292
-
293
- `ActiveModel::Serialization` provides a basic serialization for your object.
294
- You need to declare an attributes hash which contains the attributes you want to
295
- serialize. Attributes must be strings, not symbols.
296
-
297
- ```ruby
298
- class Person
299
- include ActiveModel::Serialization
300
-
301
- attr_accessor :name
302
-
303
- def attributes
304
- {'name' => nil}
305
- end
306
- end
307
- ```
308
-
309
- Now you can access a serialized hash of your object using the `serializable_hash`.
310
-
311
- ```ruby
312
- person = Person.new
313
- person.serializable_hash # => {"name"=>nil}
314
- person.name = "Bob"
315
- person.serializable_hash # => {"name"=>"Bob"}
316
- ```
317
-
318
- #### ActiveModel::Serializers
319
-
320
- Rails provides two serializers `ActiveModel::Serializers::JSON` and
321
- `ActiveModel::Serializers::Xml`. Both of these modules automatically include
322
- the `ActiveModel::Serialization`.
323
-
324
- ##### ActiveModel::Serializers::JSON
325
-
326
- To use the `ActiveModel::Serializers::JSON` you only need to change from
327
- `ActiveModel::Serialization` to `ActiveModel::Serializers::JSON`.
328
-
329
- ```ruby
330
- class Person
331
- include ActiveModel::Serializers::JSON
332
-
333
- attr_accessor :name
334
-
335
- def attributes
336
- {'name' => nil}
337
- end
338
- end
339
- ```
340
-
341
- With the `as_json` you have a hash representing the model.
342
-
343
- ```ruby
344
- person = Person.new
345
- person.as_json # => {"name"=>nil}
346
- person.name = "Bob"
347
- person.as_json # => {"name"=>"Bob"}
348
- ```
349
-
350
- From a JSON string you define the attributes of the model.
351
- You need to have the `attributes=` method defined on your class:
352
-
353
- ```ruby
354
- class Person
355
- include ActiveModel::Serializers::JSON
356
-
357
- attr_accessor :name
358
-
359
- def attributes=(hash)
360
- hash.each do |key, value|
361
- send("#{key}=", value)
362
- end
363
- end
364
-
365
- def attributes
366
- {'name' => nil}
367
- end
368
- end
369
- ```
370
-
371
- Now it is possible to create an instance of person and set the attributes using `from_json`.
372
-
373
- ```ruby
374
- json = { name: 'Bob' }.to_json
375
- person = Person.new
376
- person.from_json(json) # => #<Person:0x00000100c773f0 @name="Bob">
377
- person.name # => "Bob"
378
- ```
379
-
380
- ##### ActiveModel::Serializers::Xml
381
-
382
- To use the `ActiveModel::Serializers::Xml` you only need to change from
383
- `ActiveModel::Serialization` to `ActiveModel::Serializers::Xml`.
384
-
385
- ```ruby
386
- class Person
387
- include ActiveModel::Serializers::Xml
388
-
389
- attr_accessor :name
390
-
391
- def attributes
392
- {'name' => nil}
393
- end
394
- end
395
- ```
396
-
397
- With the `to_xml` you have a XML representing the model.
398
-
399
- ```ruby
400
- person = Person.new
401
- person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n <name nil=\"true\"/>\n</person>\n"
402
- person.name = "Bob"
403
- person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n <name>Bob</name>\n</person>\n"
404
- ```
405
-
406
- From a XML string you define the attributes of the model.
407
- You need to have the `attributes=` method defined on your class:
408
-
409
- ```ruby
410
- class Person
411
- include ActiveModel::Serializers::Xml
412
-
413
- attr_accessor :name
414
-
415
- def attributes=(hash)
416
- hash.each do |key, value|
417
- send("#{key}=", value)
418
- end
419
- end
420
-
421
- def attributes
422
- {'name' => nil}
423
- end
424
- end
425
- ```
426
-
427
- Now it is possible to create an instance of person and set the attributes using `from_xml`.
428
-
429
- ```ruby
430
- xml = { name: 'Bob' }.to_xml
431
- person = Person.new
432
- person.from_xml(xml) # => #<Person:0x00000100c773f0 @name="Bob">
433
- person.name # => "Bob"
434
- ```
435
-
436
- ### Translation
437
-
438
- `ActiveModel::Translation` provides integration between your object and the Rails
439
- internationalization (i18n) framework.
440
-
441
- ```ruby
442
- class Person
443
- extend ActiveModel::Translation
444
- end
445
- ```
446
-
447
- With the `human_attribute_name` you can transform attribute names into a more
448
- human format. The human format is defined in your locale file.
449
-
450
- * config/locales/app.pt-BR.yml
451
-
452
- ```yml
453
- pt-BR:
454
- activemodel:
455
- attributes:
456
- person:
457
- name: 'Nome'
458
- ```
459
-
460
- ```ruby
461
- Person.human_attribute_name('name') # => "Nome"
462
- ```
463
-
464
- ### Lint Tests
465
-
466
- `ActiveModel::Lint::Tests` allow you to test whether an object is compliant with
467
- the Active Model API.
468
-
469
- * app/models/person.rb
470
-
471
- ```ruby
472
- class Person
473
- include ActiveModel::Model
474
-
475
- end
476
- ```
477
-
478
- * test/models/person_test.rb
479
-
480
- ```ruby
481
- require 'test_helper'
482
-
483
- class PersonTest < ActiveSupport::TestCase
484
- include ActiveModel::Lint::Tests
485
-
486
- def setup
487
- @model = Person.new
488
- end
489
- end
490
- ```
491
-
492
- ```bash
493
- $ rake test
494
-
495
- Run options: --seed 14596
496
-
497
- # Running:
498
-
499
- ......
500
-
501
- Finished in 0.024899s, 240.9735 runs/s, 1204.8677 assertions/s.
502
-
503
- 6 runs, 30 assertions, 0 failures, 0 errors, 0 skips
504
- ```
505
-
506
- An object is not required to implement all APIs in order to work with
507
- Action Pack. This module only intends to provide guidance in case you want all
508
- features out of the box.
509
-
510
- ### SecurePassword
511
-
512
- `ActiveModel::SecurePassword` provides a way to securely store any
513
- password in an encrypted form. On including this module, a
514
- `has_secure_password` class method is provided which defines
515
- an accessor named `password` with certain validations on it.
516
-
517
- #### Requirements
518
-
519
- `ActiveModel::SecurePassword` depends on the [`bcrypt`](https://github.com/codahale/bcrypt-ruby 'BCrypt'),
520
- so include this gem in your Gemfile to use `ActiveModel::SecurePassword` correctly.
521
- In order to make this work, the model must have an accessor named `password_digest`.
522
- The `has_secure_password` will add the following validations on the `password` accessor:
523
-
524
- 1. Password should be present.
525
- 2. Password should be equal to its confirmation.
526
- 3. This maximum length of a password is 72 (required by `bcrypt` on which ActiveModel::SecurePassword depends)
527
-
528
- #### Examples
529
-
530
- ```ruby
531
- class Person
532
- include ActiveModel::SecurePassword
533
- has_secure_password
534
- attr_accessor :password_digest
535
- end
536
-
537
- person = Person.new
538
-
539
- # When password is blank.
540
- person.valid? # => false
541
-
542
- # When the confirmation doesn't match the password.
543
- person.password = 'aditya'
544
- person.password_confirmation = 'nomatch'
545
- person.valid? # => false
546
-
547
- # When the length of password, exceeds 72.
548
- person.password = person.password_confirmation = 'a' * 100
549
- person.valid? # => false
550
-
551
- # When all validations are passed.
552
- person.password = person.password_confirmation = 'aditya'
553
- person.valid? # => true
554
- ```