commit	9948816b99bb5069a33c7dce988979f8ae8f1417	[log] [tgz]
author	Dan Klco <klco@adobe.com>	Tue Aug 24 08:56:44 2021 -0400
committer	Dan Klco <klco@adobe.com>	Tue Aug 24 08:56:44 2021 -0400
tree	11938363347ca23bf6aa5de892f7239d3af4d993
parent	13e438003848b47f712ee451e973214ca3f4f857 [diff]

tree: 11938363347ca23bf6aa5de892f7239d3af4d993

README.md

Apache Sling Thumbnails

Generate and transform thumbnails from file-like Resources.

Use

This library registers two servlets for generating thumbnails.

Dynamic Transform Servlet

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"

docs/original.jpeg
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:

docs/rendered.jpeg

Saving Thumbnails

The Dynamic Transform Servlet can save the generated thumbnail for any Persistable resource type. To do so add the URL parameter renditionName, e.g.:

http://localhost:8080/bin/sling/thumbnails/transform?resource=/content/image/test.png&format=jpeg&renditionName=myrendition.jpeg

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.

Transform Servlet

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

CA Config Structure

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"
          }
        }
      }
    }
  }
}

Persistence

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.

Installation

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}

Configuration

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 page
errorSuffix - the transformation to call on the error resource if an error occurs instead of returning the default error page
persistedTypes - The types which support persistence of renditions in the format resourceType=rendition-path
supportedTypes - 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.

Primary Concepts

There are two main concepts in this library:

ThumbnailProviders - implement the interface ThumbnailProvider and are responsible for generating a thumbnail from a defined file node
TransformationHandler - 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

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:

Image Thumbnail Provider

Directly uses the image as the thumbnail

Implementation: org.apache.sling.thumbnails.internal.providers.ImageThumbnailProvider

Supported Type(s): All image types, except SVG

PDF Thumbnail Provider

Generates a PDF thumbnail using PDFBox

Implementation: org.apache.sling.thumbnails.internal.providers.PDFThumbnailProvider

Supported Type(s): PDF documents

Slide Show Thumbnail Provider

Generates a thumbnail from PPTX / PPT documents using POI

Implementation: org.apache.sling.thumbnails.internal.providers.SlideShowThumbnailProvider

Supported Type(s): PPTX / PPT documents

Tika Fallback Thumbnail Provider

Generates a thumbnail using Apache Tika

Implementation: org.apache.sling.thumbnails.internal.providers.TikaFallbackProvider

Supported Type(s): Any remaining document type

Transformation Handlers

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:

Colorize Hander

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)

Crop Handler

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

Greyscale Handler

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

Resize Handler

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.

Rotate Handler

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)

Scale Handler

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+)

Transparency Handler

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)