diff --git a/content/docs/api/db/record/thumbnail/contents.lr b/content/docs/api/db/record/thumbnail/contents.lr index babd3849..d784e877 100644 --- a/content/docs/api/db/record/thumbnail/contents.lr +++ b/content/docs/api/db/record/thumbnail/contents.lr @@ -4,18 +4,35 @@ summary: Creates a thumbnail for an image. --- type: method --- -signature: width, height=None, crop=False, quality=None +signature: width=None, height=None, mode=None, upscale=None, quality=None --- body: +!! From Lektor 2.0 to 3.1.2 cropping was set with `crop=True`. This is now deprecated and instead crop is an available mode, which can be set as `mode=crop`. + This method is available on attachments that are images and can be used to automatically generate a thumbnail. The return value is a thumbnail proxy that can be either used directly or with the `|url` filter. -If cropping is not enabled the thumbnail is scaled down to fit into the -given reactangle of width and height. If height is not specified it will -match the width and the height is set accordingly. If cropping is enabled -it's cropped around the edges to fit into the center. +The outcome differs depending on the operation mode, which can be one of "fit" +(the default), "crop" or "stretch". + +In "fit" mode, the thumbnail is scaled to fit into the rectangle of given +width and height. If either dimension is `None`, it will be computed to match +the other one accordingly. + +In "crop" mode, width and height are both required. The image is scaled +to cover the given rectangle, center-aligned, and then cropped so that +anything outside those bounds gets trimmed. + +In "stretch" mode, the image is resized precisely to the required dimensions, +so the original proportions are not preserved. Most of the time this is not +what you want. + +By setting the `upscale` parameter to `False` you can prevent the images +from being scaled up if the resulting thumbnail would be larger than the original +image. In this case the original is returned instead. +(Note that in a future version this will be the default in "fit" mode.) The quality parameter determines the compression of images where possible. If not passed the jpeg images get a default quality of 85 and png images get a default quality of 75. @@ -26,9 +43,6 @@ It provides the following attributes: * `url_path` the URL path of the thumbnail. This is absolute and needs to be made relative with the `|url` filter. -!!! Starting with Lektor 2.0 you can also pass `crop=True` to crop the image -to the exact dimensions provided instead of scaling it uncropped. - ## Example ```html+jinja @@ -38,5 +52,11 @@ to the exact dimensions provided instead of scaling it uncropped. ``` ```html+jinja - +{% for image in this.attachments.images %} + +{% endfor %} +``` + +```html+jinja + ``` diff --git a/content/docs/api/utils/process-image/contents.lr b/content/docs/api/utils/process-image/contents.lr index d5448b9b..5e3a1b6d 100644 --- a/content/docs/api/utils/process-image/contents.lr +++ b/content/docs/api/utils/process-image/contents.lr @@ -2,7 +2,7 @@ title: process_image --- module: lektor.imagetools --- -signature: ctx, source_image, dst_filename, width, height=None +signature: ctx, source_image, dst_filename, width=None, height=None, mode=ThumbnailMode.DEFAULT --- summary: Build an image from a source image, optionally compressing and resizing. --- @@ -12,7 +12,11 @@ version_added: 2.0 --- body: -This function takes a [Context :ref](../../build/context/) object, the absolute paths to the image's source and target files, and the target image's width. If height is `None`, it is calculated from the source image width and the target width so that the image is scaled proportionally. +This function takes a [Context :ref](../../build/context/) object, the +absolute paths to the image's source and target files, the target image's +width and/or height, and the operation mode. +In the default mode, if width or height are `None`, they are calculated +from the source image's dimensions so that the image is scaled proportionally. Used internally for the implementation of [thumbnail :ref](../../db/record/thumbnail), and exposed as an API for image-processing plugins. @@ -22,24 +26,24 @@ Used internally for the implementation of [thumbnail :ref](../../db/record/thumb from lektor.build_programs import AttachmentBuildProgram from lektor.context import get_ctx from lektor.db import Image -from lektor.imagetools import process_image +from lektor.imagetools import process_image, ThumbnailMode from lektor.pluginsystem import Plugin -class ResizeBuildProgram(AttachmentBuildProgram): +class ImageCropBuildProgram(AttachmentBuildProgram): def build_artifact(self, artifact): ctx = get_ctx() - width = 1024 + width, height = 600, 400 source_img = artifact.source_obj.attachment_filename artifact.ensure_dir() process_image(ctx, source_img, artifact.dst_filename, - width) + width, height, mode=ThumbnailMode.CROP) -class ImageResizePlugin(Plugin): +class ImageCropPlugin(Plugin): def on_setup_env(self, **extra): - self.env.add_build_program(Image, ResizeBuildProgram) + self.env.add_build_program(Image, ImageCropBuildProgram) ``` diff --git a/content/docs/templates/imageops/contents.lr b/content/docs/templates/imageops/contents.lr index 642d9ec7..b224d855 100644 --- a/content/docs/templates/imageops/contents.lr +++ b/content/docs/templates/imageops/contents.lr @@ -81,8 +81,8 @@ still need to transmit the entire image. When you want smaller images it often makes sense to generate thumbnails automatically. In Lektor each image provides the [thumbnail :ref](../../api/db/record/thumbnail/) method. -It accepts the width and height of the target image. If the height is not -provided it will be scaled proportionally. The return value can be converted +It accepts the width and height of the target image. If either of these is not +provided, it will be computed automatically. The return value can be converted into a URL with the `|url` filter: ```html+jinja