Cloudex
======
      
Cloudex is an Elixir library that can upload image files or urls to Cloudinary.
There is also a [CLI tool](https://github.com/smeevil/cloudex_cli) available.
## Getting started
```elixir
defp deps do
[ {:cloudex, "~> 0.1.10"}, ]
end
```
The Cloudex app must be started. This can be done by adding :cloudex to
the applications list in your mix.exs file. An example:
```elixir
def application do
[applications: [:logger, :cloudex],
]
end
```
## Settings
Cloudex requires the API credentials of your Cloudinary account.
You can define either as ENV settings using the keys :
```CLOUDEX_API_KEY``` ```CLOUDEX_SECRET``` and ```CLOUDEX_CLOUD_NAME```
or in your config.exs using :
```elixir
config :cloudex,
api_key: "my-api-key",
secret: "my-secret",
cloud_name: "my-cloud-name"
```
## Uploading
You can upload image files or urls pointing to an image as follows :
### example
For uploading a url :
```elixir
Cloudex.upload("http://example.org/test.jpg")
```
For uploading a file :
```elixir
Cloudex.upload("test/assets/test.jpg")
```
You can also upload a list of files, urls, or mix by giving upload a list like :
```elixir
["test/assets/test.jpg", "http://example.org/test.jpg"]
|> Cloudex.upload
```
The response will be a Cloudex.UploadedImage Struct, or a list of those when you uploaded a list, like :
```elixir
%Cloudex.UploadedImage{
bytes: 22659,
created_at: "2015-11-27T10:02:23Z",
etag: "dbb5764565c1b77ff049d20fcfd1d41d",
format: "jpg",
height: 167,
original_filename: "test",
public_id: "i2nruesgu4om3w9mtk1z",
resource_type: "image",
secure_url: "https://d1vibqt9pdnk2f.cloudfront.net/image/upload/v1448618543/i2nruesgu4om3w9mtk1z.jpg",
signature: "77b447746476c82bb4921fdea62a9227c584974b",
source: "http://example.org/test.jpg",
tags: [],
type: "upload",
url: "http://images.cloudassets.mobi/image/upload/v1448618543/i2nruesgu4om3w9mtk1z.jpg",
version: 1448618543,
width: 250
}
```
## Cloudinary URL generation
This package also provides an helper to generate urls from cloudinary given a public id of the image.
As a second argument you can pass in options to transform your image according via cloudinary.
Current supported options are :
```
:aspect_ratio
:border
:color
:coulor
:crop
:default_image
:delay
:density
:dpr
:effect
:fetch_format
:flags
:gravity
:height
:opacity
:overlay
:quality
:radius
:transformation
:underlay
:width
:x
:y
:zoom
```
### Example
```
Cloudex.Url.for("a_public_id")
"//res.cloudinary.com/my_cloud_name/image/upload/a_public_id"
```
```
Cloudex.Url.for("a_public_id", %{width: 400, height: 300})
"//res.cloudinary.com/my_cloud_name/image/upload/h_300,w_400/a_public_id"
```
```
Cloudex.Url.for("a_public_id", %{crop: "fill", fetch_format: 'auto', flags: 'progressive', width: 300, height: 254, quality: "jpegmini", sign_url: true})
"//res.cloudinary.com/my_cloud_name/image/upload/s--jwB_Ds4w--/c_fill,f_auto,fl_progressive,h_254,q_jpegmini,w_300/a_public_id"
```
## Phoenix helper
If you are using phoenix, you can create a small helper called for example cl_image_tag
Create a file containing the following :
```elixir
defmodule MyApp.CloudexImageHelper do
import Phoenix.HTML.Tag
def cl_image_tag(public_id, options \\ []) do
transformation_options = %{}
if Keyword.has_key?(options, :transforms) do
transformation_options = Map.merge(%{}, options[:transforms])
end
image_tag_options = Keyword.delete(options, :transforms)
defaults = [
src: Cloudex.Url.for(public_id, transformation_options),
width: picture.width,
height: picture.height,
alt: "image with name #{public_id}"
]
attributes = Keyword.merge(defaults, image_tag_options)
tag(:img, attributes)
end
end
```
Then in your ```web.ex``` add the following line in the ```def view``` section:
```elixir
import MyApp.CloudexImageHelper
```
You should now be able to use the helper in your views as follows :
```elixir
cl_image_tag(public_id, class: "thumbnail", transforms: %{opacity: "50", quality: "jpegmini", sign_url: true})
```
## Documentation
Documentation can be found at docs/index.html or [online](http://smeevil.github.io/cloudex)
## License
The Cloudex Elixir library is released under the DWTFYW license. See the LICENSE file.
