LibPixel
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\" />"