Ruby library to generate and sign LibPixel URLs.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
CHANGELOG.md
Gemfile
LICENSE
README.md
Rakefile
libpixel.gemspec

README.md

LibPixel

Build Status

Ruby library and Rails plugin to generate and sign LibPixel URLs.

Installation

Add this line to your application's Gemfile:

gem 'libpixel'

And then execute:

$ bundle

Or install it yourself as:

$ gem install libpixel

Usage

Configure the LibPixel client:

LibPixel.setup do |config|
  config.host = "test.libpx.com" # Your LibPixel domain. Required.
  config.https = true # Generates HTTPS URLs. Optional. Default is false.
  config.secret = "..." # Auth secret for your LibPixel account. Required for signing requests.
  config.default_source = "us-east-1/source" # optional source to be used, can be overriden
end

The configuration for host and secret will be automatically set from the environment variables LIBPIXEL_HOST and LIBPIXEL_SECRET if they are present.

Sign URLs

You can sign an existing URL using the sign function:

url = LibPixel.sign("http://test.libpx.com/images/1.jpg?width=400")

Generate URLs

You can also generate and sign URLs at the same time with the url function:

url = LibPixel.url("/us-east-1/images/1.jpg", height: 400, blur: 20, saturation: -80)

If you're using the src parameter, you can skip the path:

url = LibPixel.url(src: "http://...", width: 300)

But even simpler, if the library sees a url beginning with http or https it knows what to do:

url = LibPixel.url("http://...", width: 300)

You can specify whether you what an http or https url in your call:

url = LibPixel.url("/us-east-1/images/1.jpg", height: 400, blur: 20, saturation: -80, https: true)

If you are using a default_source, you don't need to specify it in the path:

url = LibPixel.url("1.jpg", height: 400, blur: 20, saturation: -80)

But you can override it with the source parameter:

url = LibPixel.url("1.jpg", height: 400, blur: 20, saturation: -80, source: "us-west-1/source2")

Multiple clients

It's also possible to have multiple instances of LibPixel clients (e.g. when dealing with multiple accounts):

client = LibPixel::Client.new(host: "test.libpx.com", https: true, secret: "...")

You may then call the #url and #sign methods on the client object.

Ruby on Rails

The LibPixel gem includes a Rails plugin that provides a view helper that you can use in place of normal calls to image_tag. The libpixel host and libpixel secret settings should be set in an initializer, or will be automatically picked up from the environment variables LIBPIXEL_HOST and LIBPIXEL_SECRET.

libpixel_image_tag("eu-west-1/source/foo.jpg")
=> "<img src=\"http://example.libpx.com/eu-west-1/source/foo.jpg\" alt=\"Foo\" />"

You specify the libpixel processing parameters in a hash within the normal options hash, denoted by the key :libpixel.

libpixel_image_tag("eu-west-1/source/foo.jpg", libpixel: {width: 300})

The normal parameters that Rails uses will also work.

libpixel_image_tag("eu-west-1/source/foo.jpg", libpixel: {width: 300, dpr: 2}, size: "300x250")

If all your images are from the same source, it's helpful to configure a default_source in an initializer.

LibPixel.default_source = "eu-west-1/source"

Then you can omit the source in your tags.

libpixel_image_tag("foo.jpg", libpixel: {width: 300, dpr: 2}, size: "300x250")

If you need to override the default source, you can do that using the source parameter.

libpixel_image_tag("foo.jpg", libpixel: {width: 300, dpr: 2, source: "eu-west-1/source2"}, size: "300x250")

Referring to an image outside of your configured sources is also possible.

libpixel_image_tag("http://example.com/images/foo.jpg", libpixel: {width: 300, dpr: 2}, size: "300x250")

You can configure your generated image src urls to use https or http in your initializer.

LibPixel.https = true  # default is false

And you can specify it on a per-tag basis.

libpixel_image_tag("us-east-1/source/foo.jpg", libpixel: {https: true})
=> "<img src=\"https://example.libpx.com/us-east-1/source/foo.jpg\" alt=\"Foo\" />"

License

MIT