mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
add documentation about variants
This commit is contained in:
parent
c5efbbbccb
commit
90a8ce6450
2 changed files with 44 additions and 0 deletions
|
@ -1,3 +1,8 @@
|
||||||
|
* Added documentation about the `variants` option to `render`
|
||||||
|
|
||||||
|
*Edward Rudd*
|
||||||
|
|
||||||
|
|
||||||
## Rails 6.0.0.beta3 (March 11, 2019) ##
|
## Rails 6.0.0.beta3 (March 11, 2019) ##
|
||||||
|
|
||||||
* No changes.
|
* No changes.
|
||||||
|
|
|
@ -296,6 +296,7 @@ Calls to the `render` method generally accept five options:
|
||||||
* `:location`
|
* `:location`
|
||||||
* `:status`
|
* `:status`
|
||||||
* `:formats`
|
* `:formats`
|
||||||
|
* `:variants`
|
||||||
|
|
||||||
##### The `:content_type` Option
|
##### 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.
|
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
|
#### 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.
|
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.
|
||||||
|
|
Loading…
Reference in a new issue