Libraries
imgix-java build
Installation
Dependencies
The library itself has no external dependencies. Although if you want to build from source (or run tests) then you need ant
and the JDK 1.6+
.
Install Options
Gradle & JCenter
To add Imgix-Java to your project, include the following in your project's build.gradle:
dependencies {
compile "com.imgix:imgix-java:2.3.2"
}
And if this is your first external MavenCentral dependency you'll need to add, again to your project level build.gradle, the following:
buildscript {
repositories {
mavenCentral()
}
}
Creating a Jar
To create a jar from source:
gradle build
This creates imgix-java-{VERSION_NUMBER}.jar
under ./build/libs
Once a new version has been merged into main on GitHub (don't forget to update the version numbers in build.gradle first!), it can be deployed to Bintray with gradle build && gradle bintrayUpload
. After that, the new version can be viewed via the Bintray web interface.
Usage
To begin creating imgix URLs, add the jar to your project's classpath and import the imgix library. The URL builder can be reused to create URLs for any images on the domains it is provided.
HTTPS support is available by default. However, if you need HTTP support, call setUseHttps on the builder:
Signed URLs
To produce a signed URL, you must enable secure URLs on your source and then provide your signature key to the URL builder.
Srcset Generation
The imgix-java library allows for generation of custom srcset
attributes, which can be invoked through createSrcSet()
. By default, the srcset
generated will allow for responsive size switching by building a list of image-width mappings.
The above will produce the following srcset attribute value which can then be served to the client:
Fixed-Width Images
In cases where enough information is provided about an image's dimensions, createSrcSet()
will instead build a srcset
that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are w
(width) and h
(height).
By invoking createSrcSet()
with either a width or height provided, a different srcset
will be generated for a fixed-size image instead.
Will produce the following attribute value:
For more information to better understand srcset
, we recommend Eric Portis' "Srcset and sizes" article which goes into depth about the subject.
Variable Quality
This library will automatically append a variable q
parameter mapped to each dpr
parameter when generating a fixed-width image srcset. This technique is commonly used to compensate for the increased file size of high-DPR images.
Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall file size without sacrificing perceived visual quality. For more information and examples of this technique in action, see this blog post.
This behavior will respect any overriding q
value passed in as a parameter. Additionally, it can be disabled altogether by passing disableVariableQuality = true
to createSrcSet
.
This behavior specifically occurs when a fixed-width image is rendered, for example:
The above will generate a srcset with the following q
to dpr
query params
:
Fluid-Width Images
Custom Widths
In situations where specific widths are desired when generating srcset
pairs, a user can specify them by passing an array of positive integers as widths
:
Note: in situations where a srcset
is being rendered as a fixed image, any custom widths
passed in will be ignored.
Additionally, if both widths
and a width tol
erance are passed to the createSrcSet
method, the custom widths list will take precedence.
Width Ranges
In certain circumstances, you may want to limit the minimum or maximum value of the non-fixed (fluid-width) srcset
generated by the createSrcSet
method. To do this, you can specify the widths at which a srcset should begin
and end
:
Formatted version of the above srcset attribute:
Width Tolerance
The srcset
width tol
erance dictates the maximum tol
erated difference between an image's downloaded size and its rendered size.
For example, setting this value to 0.1 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate.
A lower tolerance means images will render closer to their native size (thereby increasing perceived image quality), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.
By default, srcset width tol
erance is set to 0.08
(8 percent), which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by providing a positive scalar value as width tol
erance:
In this case, the width tol
erance is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair:
Running Tests
To run tests clone this project and run:
gradle test
Dependencies for running tests (junit, etc) are provided (in test/lib
and referenced in the build config).
License
More Core Libraries
- imgix-csharpbuildA C# client library for generating image URLs with imgixC# 14 a year ago
- imgix-gobuildA Go client library for generating image URLs with imgixGo 12 a year ago
- imgix-phpbuildA PHP client library for generating URLs with imgixPHP 111 a year ago
- imgix-pythonbuildA Python client library for generating URLs with imgixPython 36 a year ago
- imgix-rbbuildA Ruby gem for generating image URLs with imgixRuby 76 a year ago
- imgix-swiftbuildA Swift client library for generating URLs with imgixSwift 25 9 months ago
- @imgix/js-corebuildA JavaScript client library for generating image URLs with imgixJavaScript 120 5 days ago