Ruby wrapper

The Ruby wrapper allows you to seamlessly interface with the Cloudimage API.

Supported with Ruby 2.4+, JRuby, and TruffleRuby github

Installation

Add this line to your application's Gemfile:

gem 'cloudimage'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install cloudimage

Usage

The only requirement to get started is your customer token. You can find it within your Admin interface.

In order to interact with Cloudimage, we'll first initialize a client service object:

client = Cloudimage::Client.new(token: 'mysecrettoken')

The Cloudimage client accepts the following options:

Option	Type	Additional info
token	string	Required if cname is missing.
cname	string	Required if token is missing. See CNAME.
salt	string	Optional. See Security. Needed if you are using URL sealing or URL signatures.
signature_length	integer	Optional. Integer value in the range 6..40. Defaults to 18.
sign_urls	boolean	Optional. Defaults to true. See Security.
aliases	hash	Optional. See URL aliases.

The calling path on the client object returns an instance of Cloudimage::URI. It accepts the path to the image as a string and we we will use it to build Cloudimage URLs.

uri = client.path('/assets/image.png')

Here are some common approaches for constructing Cloudimage URLs using this gem:

Hash of params

Pass a hash to to_url. Every key becomes a param in the final Cloudimage URL so this gives you the freedom to pass arbitrary params if need be.

uri.to_url(w: 200, h: 400, sharp: 1, gravity: 'west', ci_info: 1)
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&gravity=west&h=400&sharp=1&w=200"

Chainable helpers

Every param supported by Cloudimage can be used as a helper method.

uri.w(200).h(400).gravity('west').to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?gravity=west&h=400&w=200"

While every key passed into the to_url method gets appended to the URL, chainable helper methods will throw a NoMethodError when using an unsupported method.

uri.height(200).to_url
# NoMethodError (undefined method `height' for #<Cloudimage::URI:0x00007fae461c42a0>)

This is useful for catching typos and identifying deprecated methods in case Cloudimage's API changes.

Method aliases

The gem comes with a handful of useful aliases. Consult the Cloudimage::Params module for their full list.

uri.debug.prevent_enlargement.to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&org_if_sml=1"

From the example above you can see that parameters that only serve as a flag don't need to accept arguments and will be translated into param=1 within the final URL.

For the full set of parameters and detailed implementation instructions, please consult the github page.