Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/smeevil/cloudex

An elixir library which helps with uploading image files or urls to cloudinary
https://github.com/smeevil/cloudex

Last synced: about 2 months ago
JSON representation

An elixir library which helps with uploading image files or urls to cloudinary

Lists

README 

        
Cloudex

======

[![](https://img.shields.io/hexpm/v/cloudex.svg)](https://hex.pm/packages/cloudex) ![](https://img.shields.io/hexpm/dt/cloudex.svg) ![](https://img.shields.io/hexpm/dw/cloudex.svg) ![](https://img.shields.io/coveralls/smeevil/cloudex.svg) [![](https://img.shields.io/github/issues/smeevil/cloudex.svg)](https://github.com/smeevil/cloudex/issues) [![](https://img.shields.io/github/issues-pr/smeevil/cloudex.svg)](https://github.com/smeevil/cloudex/pulls) ![](https://semaphoreci.com/api/v1/smeevil/cloudex/branches/master/shields_badge.svg)



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, "~> 1.3.0"},  ]

end

```



If you are using elixir 1.4, you can skip this step.

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"

```



[Jason](http://github.com/michalmuskala/jason) is the default json library in Cloudex. You can configure Cloudex to use another library. For example:



```elixir

config :cloudex, :json_library, YourLibraryOfChoice

```



## Uploading

You can upload image files or urls pointing to an image as follows :



### example

For uploading a url :

```elixir

iex> Cloudex.upload("http://example.org/test.jpg")

{:ok, %Cloudex.UploadedImage{...}}

```



For uploading a file :

```elixir

iex> Cloudex.upload("test/assets/test.jpg")

{:ok, %Cloudex.UploadedImage{...}}

```

You can also upload a list of files, urls, or mix by giving upload a list like :

```elixir

iex> Cloudex.upload(["/non/existing/file.jpg", "http://example.org/test.jpg"])

[{:error, "File /non/existing/file.jpg does not exist."}, {:ok, %Cloudex.UploadedImage{...}}]

```



An example of the %Cloudex.UploadedImage{} Struct looks as follows:



```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

}

```



You can tag uploaded images with strings:



```elixir

# as array

Cloudex.upload("test/assets/test.jpg", %{tags: ["foo", "bar"]})

# as comma-separated string

Cloudex.upload("test/assets/test.jpg", %{tags: "foo,bar"})



# result

{:ok, %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: ["foo", "bar"],

    type: "upload",

    url: "http://images.cloudassets.mobi/image/upload/v1448618543/i2nruesgu4om3w9mtk1z.jpg",

    version: 1448618543,

    width: 250

}}

```



List of additional parameters you can use with `upload/2`:

http://cloudinary.com/documentation/image_upload_api_reference#upload



## 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 :

```elixir

  :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

```elixir

Cloudex.Url.for("a_public_id")

"//res.cloudinary.com/my_cloud_name/image/upload/a_public_id"

```



```elixir

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"

```



```elixir

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"

```



You can add multiple effects using Cloudex.Url.for/2, an example would be adding an overlay to your image, using:

```elixir

Cloudex.Url.for("a_public_id", [

  %{border: "5px_solid_rgb:c22c33", radius: 5, crop: "fill", height: 246, width: 470, quality: 80},

  %{overlay: "my_overlay", crop: "scale", gravity: "south_east", width: 128 ,x: 5, y: 15}

])

"//res.cloudinary.com/my_cloud_name/image/upload/bo_5px_solid_rgb:c22c33,c_fill,h_246,q_80,r_5,w_470/c_scale,g_south_east,l_my_overlay,w_128,x_5,y_15/a_public_id"

```

## Deleting images

You can request deletion from cloudinary using ```Cloudex.delete/1``` function where the first argument should be the public id of the image you want to delete.



### example:

```elixir

iex> Cloudex.delete("public-id-1")

{:ok, %Cloudex.DeletedImage{public_id: "public-id-1"}}



iex> Cloudex.delete(["public-id-1", "public-id-2"])

[

  {:ok, %Cloudex.DeletedImage{public_id: "public-id-1"}},

  {:ok, %Cloudex.DeletedImage{public_id: "public-id-2"}}

]

```



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