Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add documentation for our new image helpers
Damian Legawiec03870c818f65
diff --git a/docs/developer/storefront/images.mdx b/docs/developer/storefront/images.mdxnew file mode 100644index 0000000000..945351bbaa--- /dev/null+++ b/docs/developer/storefront/images.mdx@@ -0,0 +1,87 @@+---+title: Images & Assets+---++<Warning>+You need to be on Spree 5.0.1 or higher to use these helpers. If you're on 5.0.0 please run `bundle update spree` to update your Spree version.+</Warning>++Spree comes with a handful of helper methods to make it easier to work with images and assets.++## Helpers++Spree provides several helper methods for working with images in your storefront. These methods are defined in `Spree::ImagesHelper` and are available in your views.++### `spree_image_tag`++This helper generates an image with specified width and height. It automatically scales the width and height by 2x to look great on retina screens. The output will be always in WebP format for great performance.++``` erb+<%= spree_image_tag(+ product.image,+ width: 100,+ height: 100,+ loading: :lazy,+ class: 'w-full group-hover:opacity-0 transition-opacity duration-500 z-10 relative h-full bg-background product-card !max-h-full object-cover object-center',+ title: 'Product Image',+ alt: 'Product Image')+%>+```++this will generate HTML image element with the following attributes:++```html+<img+ width="100"+ height="100"+ loading="lazy"+ class="w-full group-hover:opacity-0 transition-opacity duration-500 z-10 relative h-full bg-background product-card !max-h-full object-cover object-center"+ src="https://yourspreestore.com/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MjEwNywicHVyIjoiYmxvYl9pZCJ9fQ==--61de214902195c6ad6cf382ef777b1ab737c9eea/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9LCJyZXNpemVfdG9fZmlsbCI6WzYwMCw2MDBdfSwicHVyIjoidmFyaWF0aW9uIn19--34a1e32c85a20d458ee056019da3ed415a92106e/Photo-8.png">+```++If both width and height are not provided, the helper will keep the image original aspect ratio. If necessary, will crop the image in the larger dimension.++If only one of the width or height is provided, the helper will be resized only by the provided dimension.++You can pass additional options same as with standard Rails `image_tag` helper.++The first argument needs to be a either ActiveStorage attachment (eg. `taxon.image`) or a [Spree::Asset](https://github.com/spree/spree/blob/main/core/app/models/spree/asset.rb) object.++Under the hood this helper uses `spree_image_url` to generate the image URL.++### `spree_image_url`++This helper generates a URL for a Spree image. It automatically scales the width and height by 2x to look great on retina screens. The output will be always in WebP format for great performance.++```erb+<%= spree_image_url(product.image, width: 100, height: 100) %>+```++This will generate a URL for the image with the specified width and height.++```http+https://yourspreestore.com/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MjEwNywicHVyIjoiYmxvYl9pZCJ9fQ==--61de214902195c6ad6cf382ef777b1ab737c9eea/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9LCJyZXNpemVfdG9fZmlsbCI6WzYwMCw2MDBdfSwicHVyIjoidmFyaWF0aW9uIn19--34a1e32c85a20d458ee056019da3ed415a92106e/Photo-8.png+```++If both width and height are not provided, the helper will keep the image original aspect ratio. If necessary, will crop the image in the larger dimension.++<Info>+URLs generated by this helper are always static and can be easily cached by [CDNs](/developer/deployment/cdn). You shouldn't use this helper method for private assets!+</Info>++### `spree_asset_aspect_ratio`++This helper returns the aspect ratio of an image or video. It can be used in CSS to maintain the correct aspect ratio of an image.++```erb+<%= spree_asset_aspect_ratio(product.image) %>+```++This will return the aspect ratio of the image as a float.++```ruby+1.5+```++It can auto-detect if the asset is a portrait or landscape image and return the correct aspect ratio.+If both width and height are equal, it will return `1`.\ No newline at end of filediff --git a/docs/docs.json b/docs/docs.jsonindex b0f6729857..3751251a25 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -51,6 +51,7 @@"developer/storefront/pages","developer/storefront/sections-blocks","developer/storefront/links",+ "developer/storefront/images","developer/storefront/custom-javascript","developer/storefront/custom-css"]