ImageBoss Helper for Ruby On Rails

Official Gem for generating ImageBoss URLs with Ruby On Rails. It's built on top of imageboss-rb to offer rails specific features.

ImageBoss is a service designed to handle on-demand image processing with content aware recognition, progressive scans, compression, CDN and more.

We recommend using something like Paperclip, Refile, Carrierwave, or s3_direct_upload to handle uploads and make them available. After they've been uploaded, you can then serve them using this gem or you can't disable ImageBoss for spacific environments. Read on.

Table of Contents

• ImageBoss Helper for Ruby On Rails
  • Installation
  • Usage
    • Configuration
      • Same configuration across all environments
      • Environment specific configuration
    • Signing your URLs
    • imageboss_tag
    • Native Rails image_tag options
    • imageboss_url
    • Usage in Sprockets
    • Disable ImageBoss URL on specific environments
  • Compatibility
  • Developer

Installation

Just run the following:

$ bundle add imageboss-rails

Or install it yourself as:

$ gem install imageboss-rails

Usage

imageboss-rails provide you a few helpers to make the integration easier. To know all operations and options available please read the ImageBoss Docs.

Configuration

Same configuration across all environments

Just add the following to config/application.rb:

Rails.application.configure do
  config.imageboss.source = "mywebsite-assets"
end

Environment specific configuration

Just add the following to config/environments/production.rb:

Rails.application.configure do
  config.imageboss.source = "mywebsite-assets-prod"
end

Signing your URLs

Read more about this feature here: https://www.imageboss.me/docs/security

Rails.application.configure do
  config.imageboss.secret = "<MY_SECRET>"
end

imageboss_tag

Just like the Rails' image_tag it will generate an <img> tag for you - but wrapped by the ImageBoss gem adding some more functionalities. The syntax is the following:

<%= imageboss_tag('my-nice-image', :cover, { width: 100, height: 100 }) %>

Will output the following:

<img
  alt="my-nice-image"
  src="https://img.imageboss.me/mywebsite-assets/cover/100x100/assets/my-nice-image.jpg"
/>

Native Rails image_tag options

If you want to provide native image_url helper options just add them to the end of the helper:

<%= imageboss_tag('my-nice-image', :cover, { width: 100, height: 100, options: { blur: 2 } }, alt: "Sunny Lisbon!") %>

Will output the following:

<img
  alt="Sunny Lisbon!"
  src="https://img.imageboss.me/mywebsite-assets/cover/100x100/blur:2/assets/my-nice-image.jpg"
/>

imageboss_url

Just like Rails' asset_url but it will output your path with a fully valid ImageBoss URL.

<%= imageboss_url('my-nice-image', :width, { width: 100 }) %>

Will output the following:

https://img.imageboss.me/mywebsite-assets/width/100/assets/my-nice-image.jpg

Usage in Sprockets

imageboss_url is also pulled in as a Sprockets helper, so you can generate ImageBoss URLs in your asset pipeline files. For example, here's how it would work inside an .scss.erb file:

.user-profile {
  background-image: url(<%= imageboss_url('a-nice-profile.svg', :cover, { width: 400, height: 300 }) %>);
}

Disable ImageBoss URL on specific environments

If on development or test environment you are not sending images to the cloud you can disable the generation of ImageBoss URLs for thos environment. For example, if you want to disable on development, just add the following to your config/environments/development.rb file.

config.imageboss.enabled = false

With this configured in all places you call imageboss_url or imageboss_tag the src or the url generated will fallback straight to your localhost images. For example instead of generating this URL:

https://img.imageboss.me/mywebsite-assets/cover/100x100/assets/my-nice-image.jpg

it will output this:

http://localhost:3000/assets/my-nice-image.jpg

This is nice because you won't need to add any extra code to handle this yourself.

Compatibility

Rails

• 6
• 5
• 4

Ruby

• 2.6.x
• 2.4.x
• 2.3.x
• 2.2.x
• 2.1.x

jRuby

• jruby-9.0.5.x

Rubinius

• rbx-3.x

Developer

To run the tests:

./bin/test