Google Git
Sign in
apache / sling-org-apache-sling-thumbnails

Apache Sling Thumbnails

Mirrored from https://github.com/apache/sling-org-apache-sling-thumbnails.git
Clone this repo:

Branches

Tags

  1. 1a8edc8 SLING-12459 - Redirect sonarcloud notifications to commits@apache.sling.org by Robert Munteanu · 6 weeks ago master
  2. 04a87b5 [maven-release-plugin] prepare for next development iteration by Dan Klco · 1 year, 2 months ago
  3. 47ba3e9 [maven-release-plugin] prepare release org.apache.sling.thumbnails-1.0.2 by Dan Klco · 1 year, 2 months ago org.apache.sling.thumbnails-1.0.2
  4. d317b42 SLING-12109 - Removing dependency on Guava by Dan Klco · 1 year, 2 months ago
  5. 22d0396 SLING-12111 - Updating to latest release of thumbnailator by Dan Klco · 1 year, 2 months ago

Apache Sling

Build Status Test Status Coverage Sonarcloud Status JavaDoc Maven Central License

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:

  1. Get the resource /content/images/test.png
  2. Apply the transformation my-transformation (found in any CA Config)
  3. 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)