Cloudimage - Documentation

Ruby wrapper

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

github

Supported with Ruby 2.4+, JRuby and TruffleRuby

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 initialise 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.

Calling path on the client object returns an instance of Cloudimage::URI. It accepts 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/v7/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/v7/assets/image.png?gravity=west&h=400&w=200"

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

uri.heigth(200).to_url
# NoMethodError (undefined method `heigth' 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 Cloudimage::Params module for their full list.

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

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

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