add documentation about variants

2 files changed, 44 insertions, 0 deletions

diff --git a/guides/CHANGELOG.md b/guides/CHANGELOG.md
index beace1ed6f..798354550b 100644
--- a/guides/CHANGELOG.md
+++ b/guides/CHANGELOG.md
@@ -1,3 +1,8 @@
+*   Added documentation about the `variants` option to `render`
+
+    *Edward Rudd*
+
+
 ## Rails 6.0.0.beta3 (March 11, 2019) ##
 
 *   No changes.
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index a2ae4ea59e..43cc958cb1 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -296,6 +296,7 @@ Calls to the `render` method generally accept five options:
 * `:location`
 * `:status`
 * `:formats`
+* `:variants`
 
 ##### The `:content_type` Option
 
@@ -417,6 +418,44 @@ render formats: [:json, :xml]
 
 If a template with the specified format does not exist an `ActionView::MissingTemplate` error is raised.
 
+##### The `:variants` Option
+
+This tells rails to look for template variations of the same format.
+You can specify a list of variants by passing the `:variants` option with a symbol or an array. 
+
+An example of use would be this.
+
+```ruby
+# called in HomeController#index
+render variants: [:mobile, :desktop]
+```
+
+With this set of variants Rails will look for the following set of templates and use the first that exists.
+
+- `app/views/home/index.html+mobile.erb`
+- `app/views/home/index.html+desktop.erb`
+- `app/views/home/index.html.erb`
+
+If a template with the specified format does not exist an `ActionView::MissingTemplate` error is raised.
+
+Instead of setting the variant on the render call you may also set it on the request object in your controller action.
+
+```ruby
+def index
+  request.variant = determine_variant
+end
+
+private
+
+def determine_variant
+  variant = nil 
+  # some code to determine the variant(s) to use
+  variant = :mobile if session[:use_mobile]
+  
+  variant    
+end
+```
+
 #### Finding Layouts
 
 To find the current layout, Rails first looks for a file in `app/views/layouts` with the same base name as the controller. For example, rendering actions from the `PhotosController` class will use `app/views/layouts/photos.html.erb` (or `app/views/layouts/photos.builder`). If there is no such controller-specific layout, Rails will use `app/views/layouts/application.html.erb` or `app/views/layouts/application.builder`. If there is no `.erb` layout, Rails will use a `.builder` layout if one exists. Rails also provides several ways to more precisely assign specific layouts to individual controllers and actions.