accompanying documentation updates to lektor/#551

This commit is contained in:
Ionuț Ciocîrlan 2018-10-18 22:34:43 +03:00
parent b0df51ccdf
commit 12317785d3
3 changed files with 41 additions and 19 deletions

View File

@ -4,7 +4,7 @@ summary: Creates a thumbnail for an image.
--- ---
type: method type: method
--- ---
signature: width, height=None, crop=False, quality=None signature: width=None, height=None, mode=None, upscale=None, quality=None
--- ---
body: body:
@ -12,10 +12,25 @@ 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 automatically generate a thumbnail. The return value is a thumbnail proxy
that can be either used directly or with the `|url` filter. 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 The outcome differs depending on the operation mode, which can be one of "fit"
given reactangle of width and height. If height is not specified it will (the default), "crop" or "stretch".
match the width and the height is set accordingly. If cropping is enabled
it's cropped around the edges to fit into the center. 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. 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 +41,6 @@ It provides the following attributes:
* `url_path` the URL path of the thumbnail. This is absolute and needs to * `url_path` the URL path of the thumbnail. This is absolute and needs to
be made relative with the `|url` filter. 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 ## Example
```html+jinja ```html+jinja
@ -38,5 +50,11 @@ to the exact dimensions provided instead of scaling it uncropped.
``` ```
```html+jinja ```html+jinja
<img src="{{ image.thumbnail(1920, 1080, crop=True, quality=40)|url }}"> {% for image in this.attachments.images %}
<img src="{{ image.thumbnail(height=64)|url }}">
{% endfor %}
```
```html+jinja
<img src="{{ image.thumbnail(1920, 1080, mode="crop", quality=40)|url }}">
``` ```

View File

@ -2,7 +2,7 @@ title: process_image
--- ---
module: lektor.imagetools 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. summary: Build an image from a source image, optionally compressing and resizing.
--- ---
@ -12,7 +12,11 @@ version_added: 2.0
--- ---
body: 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. 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.build_programs import AttachmentBuildProgram
from lektor.context import get_ctx from lektor.context import get_ctx
from lektor.db import Image from lektor.db import Image
from lektor.imagetools import process_image from lektor.imagetools import process_image, ThumbnailMode
from lektor.pluginsystem import Plugin from lektor.pluginsystem import Plugin
class ResizeBuildProgram(AttachmentBuildProgram): class ImageCropBuildProgram(AttachmentBuildProgram):
def build_artifact(self, artifact): def build_artifact(self, artifact):
ctx = get_ctx() ctx = get_ctx()
width = 1024 width, height = 600, 400
source_img = artifact.source_obj.attachment_filename source_img = artifact.source_obj.attachment_filename
artifact.ensure_dir() artifact.ensure_dir()
process_image(ctx, process_image(ctx,
source_img, source_img,
artifact.dst_filename, artifact.dst_filename,
width) width, height, mode=ThumbnailMode.CROP)
class ImageResizePlugin(Plugin): class ImageCropPlugin(Plugin):
def on_setup_env(self, **extra): def on_setup_env(self, **extra):
self.env.add_build_program(Image, ResizeBuildProgram) self.env.add_build_program(Image, ImageCropBuildProgram)
``` ```

View File

@ -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 often makes sense to generate thumbnails automatically. In Lektor each
image provides the [thumbnail :ref](../../api/db/record/thumbnail/) method. 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 It accepts the width and height of the target image. If either of these is not
provided it will be scaled proportionally. The return value can be converted provided, it will be computed automatically. The return value can be converted
into a URL with the `|url` filter: into a URL with the `|url` filter:
```html+jinja ```html+jinja