Skip to content

Commit 0586754

Browse files
jonathanhefnerjonathanhefner
committed
Move Representable#variant options doc to API docs [ci-skip]
1 parent d89fc12 commit 0586754

File tree

2 files changed

+66
-38
lines changed

2 files changed

+66
-38
lines changed

‎activestorage/app/models/active_storage/blob/representable.rb

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,72 @@ module ActiveStorage::Blob::Representable
3131
# Raises ActiveStorage::InvariableError if the variant processor cannot
3232
# transform the blob. To determine whether a blob is variable, call
3333
# ActiveStorage::Blob#variable?.
34+
#
35+
# ==== Options
36+
#
37+
# Options are defined by the {image_processing gem}[https://github.com/janko/image_processing],
38+
# and depend on which variant processor you are using:
39+
# {Vips}[https://github.com/janko/image_processing/blob/master/doc/vips.md] or
40+
# {MiniMagick}[https://github.com/janko/image_processing/blob/master/doc/minimagick.md].
41+
# However, both variant processors support the following options:
42+
#
43+
# [+:resize_to_limit+]
44+
# Downsizes the image to fit within the specified dimensions while retaining
45+
# the original aspect ratio. Will only resize the image if it's larger than
46+
# the specified dimensions.
47+
#
48+
# user.avatar.variant(resize_to_limit: [100, 100])
49+
#
50+
# [+:resize_to_fit+]
51+
# Resizes the image to fit within the specified dimensions while retaining
52+
# the original aspect ratio. Will downsize the image if it's larger than the
53+
# specified dimensions or upsize if it's smaller.
54+
#
55+
# user.avatar.variant(resize_to_fit: [100, 100])
56+
#
57+
# [+:resize_to_fill+]
58+
# Resizes the image to fill the specified dimensions while retaining the
59+
# original aspect ratio. If necessary, will crop the image in the larger
60+
# dimension.
61+
#
62+
# user.avatar.variant(resize_to_fill: [100, 100])
63+
#
64+
# [+:resize_and_pad+]
65+
# Resizes the image to fit within the specified dimensions while retaining
66+
# the original aspect ratio. If necessary, will pad the remaining area with
67+
# transparent color if source image has alpha channel, black otherwise.
68+
#
69+
# user.avatar.variant(resize_and_pad: [100, 100])
70+
#
71+
# [+:crop+]
72+
# Extracts an area from an image. The first two arguments are the left and
73+
# top edges of area to extract, while the last two arguments are the width
74+
# and height of the area to extract.
75+
#
76+
# user.avatar.variant(crop: [20, 50, 300, 300])
77+
#
78+
# [+:rotate+]
79+
# Rotates the image by the specified angle.
80+
#
81+
# user.avatar.variant(rotate: 90)
82+
#
83+
# Some options, including those listed above, can accept additional
84+
# processor-specific values which can be passed as a trailing hash:
85+
#
86+
# <!-- Vips supports configuring `crop` for many of its transformations -->
87+
# <%= image_tag user.avatar.variant(resize_to_fill: [100, 100, { crop: :centre }]) %>
88+
#
89+
# If migrating an existing application between MiniMagick and Vips, you will
90+
# need to update processor-specific options:
91+
#
92+
# <!-- MiniMagick -->
93+
# <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg,
94+
# sampling_factor: "4:2:0", strip: true, interlace: "JPEG", colorspace: "sRGB", quality: 80) %>
95+
#
96+
# <!-- Vips -->
97+
# <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg,
98+
# saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %>
99+
#
34100
def variant(transformations)
35101
if variable?
36102
variant_class.new(self, ActiveStorage::Variation.wrap(transformations).default_to(default_variant_transformations))

‎guides/source/active_storage_overview.md

Lines changed: 0 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1005,49 +1005,11 @@ Active Storage can use either [Vips][] or MiniMagick as the variant processor.
10051005
The default depends on your `config.load_defaults` target version, and the
10061006
processor can be changed by setting [`config.active_storage.variant_processor`][].
10071007

1008-
The parameters available are defined by the [`image_processing`][] gem and depend on the
1009-
variant processor that you are using, but both support the following parameters:
1010-
1011-
| Parameter | Example | Description |
1012-
| ------------------- | ---------------- | ----- |
1013-
| `resize_to_limit` | `resize_to_limit: [100, 100]` | Downsizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it's larger than the specified dimensions. |
1014-
| `resize_to_fit` | `resize_to_fit: [100, 100]` | Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will downsize the image if it's larger than the specified dimensions or upsize if it's smaller. |
1015-
| `resize_to_fill` | `resize_to_fill: [100, 100]` | Resizes the image to fill the specified dimensions while retaining the original aspect ratio. If necessary, will crop the image in the larger dimension. |
1016-
| `resize_and_pad` | `resize_and_pad: [100, 100]` | Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. If necessary, will pad the remaining area with transparent color if source image has alpha channel, black otherwise. |
1017-
| `crop` | `crop: [20, 50, 300, 300]` | Extracts an area from an image. The first two arguments are the left and top edges of area to extract, while the last two arguments are the width and height of the area to extract. |
1018-
| `rotate` | `rotate: 90` | Rotates the image by the specified angle. |
1019-
1020-
[`image_processing`][] has all parameters available in its own documentation
1021-
for both the
1022-
[Vips](https://github.com/janko/image_processing/blob/master/doc/vips.md) and
1023-
[MiniMagick](https://github.com/janko/image_processing/blob/master/doc/minimagick.md)
1024-
processors.
1025-
1026-
Some parameters, including those listed above, accept additional processor
1027-
specific options which can be passed as `key: value` pairs inside a hash:
1028-
1029-
```erb
1030-
<!-- Vips supports configuring `crop` for many of its transformations -->
1031-
<%= image_tag user.avatar.variant(resize_to_fill: [100, 100, { crop: :centre }]) %>
1032-
```
1033-
1034-
If migrating an existing application between MiniMagick and Vips, processor
1035-
specific options will need to be updated:
1036-
1037-
```erb
1038-
<!-- MiniMagick -->
1039-
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, sampling_factor: "4:2:0", strip: true, interlace: "JPEG", colorspace: "sRGB", quality: 80) %>
1040-
1041-
<!-- Vips -->
1042-
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %>
1043-
```
1044-
10451008
[`config.active_storage.variable_content_types`]: configuring.html#config-active-storage-variable-content-types
10461009
[`config.active_storage.variant_processor`]: configuring.html#config-active-storage-variant-processor
10471010
[`config.active_storage.web_image_content_types`]: configuring.html#config-active-storage-web-image-content-types
10481011
[`variant`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-variant
10491012
[Vips]: https://www.rubydoc.info/gems/ruby-vips/Vips/Image
1050-
[`image_processing`]: https://github.com/janko/image_processing
10511013

10521014
### Previewing Files
10531015

0 commit comments

Comments
 (0)