From 0e04177837d5061616f7fb626d21bff088e3922d Mon Sep 17 00:00:00 2001 From: Andy Babic Date: Fri, 5 Jul 2024 13:20:52 +0100 Subject: [PATCH] Update docs --- README.md | 48 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 9e972ac..75cda30 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,16 @@ To sync images updated within the last three days: $ python manage.py update_stale_images --days=3 ``` +### Automatic conversion and downsizing of images + +When the `BYNDER_IMAGE_SOURCE_THUMBNAIL_NAME` derivative for an image is successfully downloaded by Wagtail, it is passed to the `convert_downloaded_image()` method of your custom image model in order to convert it into something more suitable for Wagtail. + +Firstly, downloaded images are converted to the most appropriate type, according to your project's `WAGTAILIMAGES_FORMAT_CONVERSIONS` setting and Wagtail's default preferences. For example, by default, `BMP` and `WebP` are converted to `PNG`. + +Secondly, downloaded image are downsized according to the `BYNDER_MAX_IMAGE_WIDTH` and `BYNDER_MAX_IMAGE_HEIGHT` setting values, in a way that preserves their original aspect ratio. Whilst Bynder is expected to address this on their side by generating appropriately-sized derivatives, that isn't always possible, and monitoring it can be time-consuming and impractical. + +Ensuring source images only have enough pixels to meet the rendition-generation requirements of your project has an enormous long-term benefit for Wagtail project (especially one with image-heavy content pages), as it provides efficiency gains **every single time** a new rendition is generated. + ## What to ask of Bynder When communicating with Bynder about configuring a new instance for compatibility with Wagtail, there are a few things you'll want to be clear about: @@ -241,17 +251,6 @@ An API token for Bynder's JavaScript 'compact view' to use. The value is injecte for the JavaScript to pick up, exposing it to Wagtail users. Because of this, it should be different to `BYNDER_API_TOKEN` and only needs to have basic read permissions. -### `BYNDER_IMAGE_SOURCE_THUMBNAIL_NAME` - -Default: `"WagtailSource"` - -The name of the automatically generated derivative that should be downloaded and used as the `file` value for the -representative Wagtail image (as it appears in `thumbnails` in the API representation). - -WARNING: It's important to get this right, because if the specified derivative is NOT present in the response for an -image for any reason, the ORIGINAL will be downloaded - which will lead to slow chooser response times and higher memory -usage when generating renditions. - ### `BYNDER_MAX_DOCUMENT_FILE_SIZE` Example: `10485760` @@ -264,6 +263,17 @@ The maximum acceptable file size (in Bytes) when downloading a 'Document' asset - How large the documents are that editors want to feature in content - Whether you are doing anything particularly memory intensive with document files (e.g. text/content analysis) +### `BYNDER_IMAGE_SOURCE_THUMBNAIL_NAME` + +Default: `"WagtailSource"` + +The name of the automatically generated derivative that should be downloaded and used as the `file` value for the +representative Wagtail image (as it appears in `thumbnails` in the API representation). + +WARNING: It's important to get this right, because if the specified derivative is NOT present in the response for an +image for any reason, the ORIGINAL will be downloaded - which will lead to slow chooser response times and higher memory +usage when generating renditions. + ### `BYNDER_MAX_IMAGE_FILE_SIZE` Example: `10485760` @@ -276,6 +286,22 @@ This setting is provided separately to `BYNDER_MAX_DOCUMENT_FILE_SIZE`, because As with `BYNDER_MAX_DOCUMENT_FILE_SIZE`, this can be tweaked for individual environments to reflect how much RAM is available in the host infrastructure. +### `BYNDER_MAX_IMAGE_WIDTH` + +Example: `5000` + +Default: `3500` + +Used to restrict the **width** of images downloaded from Bynder before they are used as source images for objects in Wagtail's image library. + +### `BYNDER_MAX_IMAGE_HEIGHT` + +Example: `5000` + +Default: `3500` + +Used to restrict the **height** of images downloaded from Bynder before they are used as source images for objects in Wagtail's image library. + ### `BYNDER_VIDEO_MODEL` Example: `"video.Video"`