[sling-org-apache-sling-app-cms] branch master updated: Create image-transformations.md

[dk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dklco pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-app-cms.git


The following commit(s) were added to refs/heads/master by this push:
     new 0d8d883  Create image-transformations.md
0d8d883 is described below

commit 0d8d883beade95bef536624edf2a54705ec504a3
Author: Dan Klco <kl...@users.noreply.github.com>
AuthorDate: Mon Apr 20 10:05:46 2020 -0400

    Create image-transformations.md
---
 docs/image-transformations.md | 59 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/image-transformations.md b/docs/image-transformations.md
new file mode 100644
index 0000000..b17e6c6
--- /dev/null
+++ b/docs/image-transformations.md
@@ -0,0 +1,59 @@
+<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor
+	license agreements. See the NOTICE file distributed with this work for additional
+	information regarding copyright ownership. The ASF licenses this file to
+	you under the Apache License, Version 2.0 (the "License"); you may not use
+	this file except in compliance with the License. You may obtain a copy of
+	the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required
+	by applicable law or agreed to in writing, software distributed under the
+	License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+	OF ANY KIND, either express or implied. See the License for the specific
+	language governing permissions and limitations under the License. -->
+[Apache Sling](https://sling.apache.org) > [Sling CMS](https://github.com/apache/sling-org-apache-sling-app-cms) > [Administration](administration.md) > Image Transformations
+
+# Image Transformations
+
+Image transformations are used to transform a file from one format to an image format, most commonly in generating thumbnails or sized down renditions.
+
+## Transformation Configurations
+
+File transformations should be created per site configuration at via the Configuration Console:
+
+`/conf/[conf-name]/files/transformations`
+
+![Editing a Transformation](docs/img/edit-transformation.png)
+
+Each transformation is defined as a series of handlers which will be executed in order. 
+
+The transformations avaiable in the current site can be retrieved using the [TransformationManager](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/TransformationManager.java) which is available as a Sling Model.
+
+## Transformation Handlers
+
+Transformation handlers handle each step of transforming an image based on the [Thumbnailer](https://github.com/coobird/thumbnailator) library.
+
+Currently, there are two provided Transformation Handlers:
+
+ - [Crop Handler](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/CropHandler.java) - Crops images based on "weights"
+ - [Size Handler](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/SizeHandler.java) - Resizes images
+ 
+To implement a new Transformation Handler, provide a service implementing [TransformationHandler](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/TransformationHandler.java),
+including providing a resource type to configure the transformation handler.
+ 
+## Providing Thumbnails
+
+Thumbnail Providers are used to create renditions of non-image files, for example PDFs or Word documents. There are a number of default providers:
+
+ - [ImageThumbnailProvider](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/ImageThumbnailProvider.java) - Returns the image as the thumbnail
+ - [PdfThumbnailProvider](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/PdfThumbnailProvider.java) - Uses [Apache PDFBox](https://pdfbox.apache.org/) to generate a thumbnail of PDF files
+ - [SlideShowThumbnailProvider](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/SlideShowThumbnailProvider.java) - Uses [Apache POI](https://poi.apache.org/) to generate a thumbnail of PPT and PPTX files
+ - [TikaFallbackProvider](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/internal/TikaFallbackProvider.java) - Uses [Apache Tika](https://tika.apache.org/) to generate a thumbnail of the text of documents
+ 
+To implement a new Thumbnail Providers, provide a service implementing [ThumbnailProvider](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/transformer/src/main/java/org/apache/sling/cms/transformer/ThumbnailProvider.java).
+ 
+## Transformation Servlet
+
+The Transformation Servlet can be used to retrieve tranformed images for any file. The transformed images can be retrieved by using the extensions `transform` and the suffix of the transformation name to execute + the output extension. For example:
+
+`/content/site/a-file.png.transform/a-thumbnail.png`
+
+The transformation servlet is integrated into the [reference image component](https://github.com/apache/sling-org-apache-sling-app-cms/blob/master/docs/reference.md#general).
+