Merge pull request #4245 from nbelzer/image-settings#3700

Update image settings documentation

core/spec/models/spree/image/preferences_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe Spree::Image, type: :model do
+  custom_styles = {
+    mini: '48x48>',
+    small: '100x100>',
+    product: '240x240>',
+    large: '600x600>',
+    jumbo: '1200x1200>'
+  }
+  custom_style_default = :other
+
+  it 'correctly sets the image styles ActiveStorage' do
+    stub_spree_preferences(
+      product_image_styles: custom_styles,
+      product_image_style_default: custom_style_default
+    )
+
+    # We make use of a custom class, such that the preferences loaded
+    # are the mocked ones.
+    active_storage_asset = Class.new(Spree::Asset) do
+      include Spree::Image::ActiveStorageAttachment
+    end
+
+    expect(active_storage_asset.attachment_definitions[:attachment][:styles]).to eq(custom_styles)
+    expect(active_storage_asset.attachment_definitions[:attachment][:default_style]).to eq(custom_style_default)
+  end
+
+  it 'correctly sets the image styles Paperclip' do
+    stub_spree_preferences(
+      product_image_styles: custom_styles,
+      product_image_style_default: custom_style_default
+    )
+
+    # We make use of a custom class, such that the preferences loaded
+    # are the mocked ones.
+    paperclip_asset = Class.new(Spree::Asset) do
+      include Spree::Image::PaperclipAttachment
+    end
+
+    expect(paperclip_asset.attachment_definitions[:attachment][:styles]).to eq(custom_styles)
+    expect(paperclip_asset.attachment_definitions[:attachment][:default_style]).to eq(custom_style_default)
+  end
+end

guides/source/developers/getting-started/system-requirements.html.md

@@ -5,7 +5,8 @@ The following software is required to get Solidus running:
 - [Ruby](https://www.ruby-lang.org) 2.2.2 or newer
 - [SQLite 3](https://sqlite.org)
 - [Rails](http://guides.rubyonrails.org/getting_started.html) 5.0.0 or newer
-- [ImageMagick](http://imagemagick.org/script/download.php)
+- [libvips](https://github.com/libvips/libvips) 8.6 or newer, or
+  [ImageMagick](http://imagemagick.org/script/download.php)
 
 We recommend using [Homebrew][brew] to install these dependencies on your
 Mac. Throughout this article, we will use the `brew` command for installing
@@ -15,6 +16,7 @@ Homebrew][ruby-homebrew] if you need to upgrade from your system's Ruby.
 We also recommend configuring your development environment so that you can
 [install RubyGems without `sudo`][gem-install-without-sudo].
 
+[brew]: https://brew.sh
 [ruby-homebrew]: https://www.ruby-lang.org/en/documentation/installation/#homebrew
 [gem-install-without-sudo]: https://www.michaelehead.com/2016/02/06/installing-gems-without-sudo.html
 
@@ -84,6 +86,30 @@ gem install rails
 
 This will install Rails as well as its dependencies.
 
+## Install Libvips
+
+If you are upgrading from an older version of Solidus (where Paperclip was used
+for product images), and are continuing to use Paperclip for your product images
+(see the section on [product images][product-images] for more details), you will
+need to install ImageMagick.
+
+If you set up your store with Solidus v3 or newer, you are using ActiveStorage
+for your product images by default. As outlined in the [the ActiveStorage
+guide][active-storage-guide] you have the choice to install
+[libvips](https://github.com/libvips/libvips) (v8.6 or newer) as an alternative
+to ImageMagick. Libvips can be [both faster and less memory
+intensive](https://github.com/libvips/libvips/wiki/Speed-and-memory-use) than
+ImageMagick.
+
+To install libvips via homebrew, use the command:
+
+```bash
+brew install libvips
+```
+
+[product-images][/developers/products-and-variants/product-images.html]
+[active-storage-guide]: https://guides.rubyonrails.org/active_storage_overview.html#requirements
+
 ## Install ImageMagick
 
 ImageMagick helps you create, edit, and save to hundreds of image file formats.

guides/source/developers/products-and-variants/product-images.html.md

@@ -1,16 +1,16 @@
 # Product images
 
 Product images belong to the `Spree::Image` model and belong to the variants of
-a product. Solidus handles the creation and storage of images using
-[Paperclip][paperclip-gem].
+a product. The latest version (>= 3.0) of Solidus handles the creation and storage
+of images using [Active Storage][activestorage] by default (previously
+[Paperclip][paperclip-gem]).
 
 Take note of these product image properties:
 
 - `viewable_id`: The ID for the variant that this image is linked to.
 - `attachment_width` and `attachment_height`: The width and height of the
-  original image that was uploaded. See the [Paperclip
-  section](#paperclip-settings) of this article for more information about how
-  Solidus resizes product images.
+  original image that was uploaded. See the [image settings](#image-settings)
+  of this article for more information about how Solidus resizes product images.
 - `position`: Sets the image's position in a list of images. For example, an
   image with the `position` of `2` would be displayed after the image with the
   `position` of `1`.
@@ -28,7 +28,7 @@ If you want to change the image that is displayed when a product has no image,
 you can override Solidus's [`noimage` defaults][solidus-noimage] in your project
 by creating a `app/assets/images/noimages` directory.
 
-If you have changed your [Paperclip configuration](#paperclip-settings), make
+If you have changed your [image settings](#image-settings), make
 sure that you include `noimage` images for each of image attachment keys that
 you have defined. The default keys are `mini`, `small`, `product`, and `large`.
 
@@ -41,25 +41,29 @@ for a specific variant or for **All** variants.
 If set to **All**, the `viewable_id` is set to the master variant for the
 current product.
 
-## Paperclip settings
+## Image settings
 
-[Paperclip][paperclip-gem] handles the creation and storage of product images.
-By default, it creates several versions of each image at specific sizes.
+[Active Storage][activestorage] and [Paperclip][paperclip-gem] handle the
+creation and storage of product images. By default, they create several
+versions of each image at specific sizes.
 
-You can check the default settings by calling the `attachment_definitions`
-method on `Spree::Image` in your Rails console:
+You can check the default settings by inspecting the `product_image_styles`
+option on `Spree::Config` in your Rails console:
 
 ```ruby
->> Spree::Image.attachment_definitions[:attachment][:styles]
+>> Spree::Config.product_image_styles
 => {:mini=>"48x48>", :small=>"400x400>", :product=>"680x680>", :large=>"1200x1200>"}
 ```
 
-The default sizes can be changed in an initializer. For example, in your
-`config/initializers/paperclip.rb` file. You can set new defaults like this:
+The default sizes can be changed using the `Spree::Config.product_image_styles`
+option. For example, in your `config/initializers/spree.rb` file. You can set
+new defaults like this:
 
 ```ruby
+# config/initializers/spree.rb
+
 # E.g. these were the default values for Solidus up to version 2.9
-Spree::Image.attachment_definitions[:attachment][:styles] = {
+config.product_image_styles = {
   mini: '48x48>',
   small: '100x100>',
   product: '240x240>',
@@ -69,13 +73,37 @@ Spree::Image.attachment_definitions[:attachment][:styles] = {
 
 ### Regenerate thumbnails
 
-If you change the default image sizes, you must regenerate the Paperclip
-thumbnails by running a Rake task:
+[Active Storage][activestorage] will automatically generate the sizes upon
+initial request.
+
+If you change the default image sizes and are using Paperclip, you must
+regenerate the thumbnails by running a Rake task:
 
 ```bash
 bundle exec rake paperclip:refresh:thumbnails CLASS=Spree::Image
 ```
 
+## Using Paperclip
+
+[Active Storage][activestorage] is the default backend for `Spree::Image`
+starting with Solidus 3.0. As we don't want to force existing stores to migrate
+their existing Paperclip assets, we will support the [maintained fork of
+paperclip][maintained-paperclip-gem] for a while. Because of this we do not
+recommend switching to Paperclip when creating a new Solidus application.
+
+Switching to the Paperclip backend can be achieved by changing the configuration
+for `Spree::Config.image_attachment_module` and
+`Spree::Config.taxon_attachment_module`:
+
+```ruby
+# config/initializers/spree.rb
+
+config.image_attachment_module = 'Spree::Image::PaperclipAttachment'
+config.taxon_attachment_module = 'Spree::Taxon::PaperclipAttachment'
+```
+
+[activestorage]: https://github.com/rails/rails/tree/main/activestorage
 [paperclip-gem]: https://github.com/thoughtbot/paperclip
+[maintained-paperclip-gem]: https://github.com/kreeti/kt-paperclip
 [solidus-backend]: https://github.com/solidusio/solidus/tree/master/backend
 [solidus-noimage]: https://github.com/solidusio/solidus/tree/master/core/app/assets/images/noimage