# 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:
```sh
gem 'cloudimage'
```
And then execute:
```sh
$ bundle install
```
Or install it yourself as:
```sh
$ 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:
```ruby
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.
```ruby
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.
```ruby
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.
```ruby
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.
```none
uri.height(200).to_url
# NoMethodError (undefined method `height' for #)
```
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.
```ruby
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.
{% hint style="info" %}
For the full set of parameters and detailed implementation instructions, please consult the [github page](https://github.com/scaleflex/cloudimage-rb).
{% endhint %}