Generate and transform thumbnails from file-like Resources.
This library registers two servlets for generating thumbnails.
Generates and transforms thumbnails "on the fly" based on a request path, format and transformation JSON payload. Available for POST requests at the path /bin/sling/thumbnails/transform
with the parameters resource
(required) and format
(optional), for example, given the following image at /content/image/test.png
"
Image credit Markos Mant from Unsplash
Sending a request like:
URL: http://localhost:8080/bin/sling/thumbnails/transform?resource=/content/image/test.png&format=jpeg
BODY:
[
{
"handlerType": "sling/thumbnails/transformers/crop",
"properties": {
"width": 300,
"height": 300
}
},
{
"handlerType": "sling/thumbnails/transformers/colorize",
"properties": {
"red": 112,
"green": 66,
"blue": 20,
"alpha": 0.4
}
}
]
Will result in the following thumbnail:
The Dynamic Transform Servlet can save the generated thumbnail for any Persistable resource type. To do so add the URL parameter renditionName
, e.g.:
Once saved, the rendition can be access directly using the configured Rendition Path for the Resource Type or using the Transform Servlet. Note that the rendition will only be available on the resource the servlet is executed on.
The second servlet uses Sling Context Aware Configurations to generate thumbnails based on pre-defined transformation pipelines. Note that the RenderedResource model is useful for retrieving the available transformation pipelines and existing renditions for a particular resource.
Each available transformation can then be accessed in the form:
{/path/to/file.ext}.transform/{transformation-name}.{final-extension}
This for a request like:
/content/images/test.png.transform/my-transformation.jpeg
The servlet would:
- Get the resource
/content/images/test.png
- Apply the transformation
my-transformation
(found in any CA Config) - Convert the result to a JPEG
The structure for the transformations under the CA Config root (e.g. /conf/global/) should include files/transformations, as such:
/conf/global: {
"jcr:primaryType": "sling:Folder",
"files": {
"jcr:primaryType": "sling:Folder",
"transformations": {
"jcr:primaryType": "sling:Folder",
"transformation": {
"jcr:primaryType": "nt:unstructured",
"name": "transformation",
"sling:resourceType": "sling/thumbnails/transformation",
"handlers": {
"jcr:primaryType": "nt:unstructured",
"resize": {
"jcr:primaryType": "nt:unstructured",
"height": 200,
"width": 200,
"sling:resourceType": "sling/thumbnails/transformers/resize"
}
}
}
}
}
}
The Transform Servlet supports persisting renditions and using the persisted renditions instead of rendering the image on the fly. To persist renditions, you must configure the persistableTypes
in the Thumbnail Support Configuration
The persistableTypes
node type must also be in the supportedTypes
list. The rendition will be persisted at the provided path as an nt:file
node with the name provided when requesting the rendition.
This library can be installed on Sling 11+ but does require the following libraries:
- org.apache.commons:commons-compress:1.20
- org.apache.commons:commons-math3:3.6.1
- org.apache.servicemix.bundles:org.apache.servicemix.bundles.poi:4.1.2_2
- org.apache.servicemix.bundles:org.apache.servicemix.bundles.xmlbeans:3.1.0_2
Add a service user sling-thumbnails
with the following permissions:
- jcr:write,jcr:nodeTypeManagement,jcr:versionManagement on /content
- jcr:read on /
Add a service user mapping: org.apache.sling.thumbnails:sling-commons-thumbnails=sling-thumbnails
Note that this library generates Sling Feature Models which can be used to install it easily with the Sling Feature Launcher:
- org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:base:{RELEASE_VERSION}
- org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:default:{RELEASE_VERSION}
- org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:dependencies:{RELEASE_VERSION}
This module requires configuring the following pid:
PID = org.apache.sling.thumbnails.internal.ThumbnailSupportImpl
errorResourcePath = /static/sling-cms/thumbnails/file.png
errorSuffix = /sling-cms-thumbnail.png
persistedTypes = []
supportedTypes = [nt:file=jcr:content/jcr:mimeType]
The the values should be set as follows:
errorResourcePath
- the path to a resource to transform if an error occurs instead of returning the default error pageerrorSuffix
- the transformation to call on the error resource if an error occurs instead of returning the default error pagepersistedTypes
- The types which support persistence of renditions in the format resourceType=rendition-pathsupportedTypes
- The types which support thumbnail generation and transformation in the format resourceType=metdata-path
Note: the supportedTypes (and by extension persistedTypes) must be adaptable to from a Resource to an java.io.InputStream.
Generally, this configuration should be provided by the application including this functionality. See ThumbnailSupportConfig for more on the configuration values.
There are two main concepts in this library:
ThumbnailProviders
- implement the interface ThumbnailProvider and are responsible for generating a thumbnail from a defined file nodeTransformationHandler
- implement the class TransformationHandler and are responsible for executing a single transformation as part of a thumbnail transformation pipeline
Default Thumbnail Providers and Transformation Handlers are provided with this library and both interfaces are available for extension.
Thumbnail Providers implement the ThumbnailProvider
interface and are responsible for generating a thumbnail from a file resource. Each handler is expected to indicate whether or not it can handle the provided resource / mime type and will be evaluated in order of their Service Ranking with the TikaFallbackProvider
having a service ranking of Integer.MIN_VALUE
The following are the included Thumbnail Providers:
Directly uses the image as the thumbnail
Implementation: org.apache.sling.thumbnails.internal.providers.ImageThumbnailProvider
Supported Type(s): All image types, except SVG
Generates a PDF thumbnail using PDFBox
Implementation: org.apache.sling.thumbnails.internal.providers.PDFThumbnailProvider
Supported Type(s): PDF documents
Generates a thumbnail from PPTX / PPT documents using POI
Implementation: org.apache.sling.thumbnails.internal.providers.SlideShowThumbnailProvider
Supported Type(s): PPTX / PPT documents
Generates a thumbnail using Apache Tika
Implementation: org.apache.sling.thumbnails.internal.providers.TikaFallbackProvider
Supported Type(s): Any remaining document type
Transformation Handlers implement the TransformationHandler
interface and are responsible for invoking tranformation effects on thumbnails. Each Transformation Handler is identified by a Handler Type which should correspond to a Sling Resource Type. Only one Transformation Handler is expected to be registered per resource type.
Most of the transformnation handlers use the Thumbnailator library under the hood to perform the transformations.
The following are the included Transformation Handlers:
Adds a color tint to an image.
Implementation: org.apache.sling.thumbnails.internal.transformers.ColorizeHandler
Handler Type: sling/thumbnails/transformers/colorize
Parameters
- red - the red color value (0-255)
- green - the green color value (0-255)
- blue - the blue color value (0-255)
- alpha - the level of transparency, with lower being more transparent (0.0 - 1.0)
Crops an image to the size specified. Note the width and height must be specified.
Implementation: org.apache.sling.thumbnails.internal.transformers.ColorizeHandler
Handler Type: sling/thumbnails/transformers/colorize
Parameters
- height - the height to constrain the crop (1+)
- width - the width to constrain the crop (1+)
- position - one of:
- BOTTOM_CENTER
- BOTTOM_LEFT
- BOTTOM_RIGHT
- CENTER
- CENTER_LEFT
- CENTER_RIGHT
- TOP_CENTER
- TOP_LEFT
- TOP_RIGHT
Converts an image to greyscale. Note this will remove transparency.
Implementation: org.apache.sling.thumbnails.internal.transformers.GreyscaleHandler
Handler Type: sling/thumbnails/transformers/greyscale
Parameters
N/A
Resizes an image to the size specified. If only one dimension is specified the image will be sized to the other
Implementation: org.apache.sling.thumbnails.internal.transformers.ResizeHandler
Handler Type: sling/thumbnails/transformers/resize
Parameters
- height - the height to constrain the crop (1+)
- width - the width to constrain the crop (1+)
- keepAspectRatio - boolean, if false, the exact width and height will be used which will not preserve the aspect ratio of the original image.
Rotates an image.
Implementation: org.apache.sling.thumbnails.internal.transformers.RotateHandler
Handler Type: sling/thumbnails/transformers/rotate
Parameters
- degrees - the number of degrees to rotate the image (any number)
Sets the scaling factor for the width and height of the image. If the scaling factor for the width and height are not equal, then the image will not preserve the aspect ratio of the original image.
Note: either both or the width+height must be set.
Implementation: org.apache.sling.thumbnails.internal.transformers.ScaleHandler
Handler Type: sling/thumbnails/transformers/scale
Parameters
- both - scale the thumbnail by the same factor for width and height (0+ - 1.0+)
- width - scale the thumbnail width (0+ - 1.0+)
- height - scale the thumbnail height (0+ - 1.0+)
Makes an image transparent
Implementation: org.apache.sling.thumbnails.internal.transformers.TransparencyHandler
Handler Type: sling/thumbnails/transformers/transparency
Parameters
- alpha - the level of transparency, with lower being more transparent (0.0 - 1.0)