From acb0a0df59d746a587dc94a0c5b1606a93259f54 Mon Sep 17 00:00:00 2001
From: Jannis Vajen <jvajen@gmail.com>
Date: Tue, 25 Oct 2022 15:10:56 +0200
Subject: [PATCH] Document img_url template tag (#59)

* Allow img_url tag to take width as string
* Mention img_url template tag in README
---
 README.md                         | 19 +++++++++++++++++++
 pictures/templatetags/pictures.py |  2 +-
 tests/test_templatetags.py        |  2 +-
 3 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e1eaac0..77da3c5 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,25 @@ if get_settings().USE_PLACEHOLDERS:
     ]
 ```
 
+### Legacy use-cases (email)
+
+Although the `picture`-tag is [adequate for most use-cases][caniuse-picture],
+some remain, where a single `img` tag is necessary. Notably in email, where
+[most clients do support WebP][caniemail-webp] but not [srcset][caniemail-srcset].
+The template tag `img_url` returns a single size image URL.
+In addition to the ratio you will need to define the `file_type`
+as well as the `width` (absolute width in pixels).
+
+
+```html
+{% load pictures %}
+<img src="{% img_url profile.picture ratio="3/2" file_type="webp" width=800 %}" alt="profile picture">
+```
+
+[caniuse-picture]: https://caniuse.com/picture
+[caniemail-webp]: https://www.caniemail.com/features/image-webp/
+[caniemail-srcset]: https://www.caniemail.com/features/html-srcset/
+
 ## Config
 
 ### Aspect ratios
diff --git a/pictures/templatetags/pictures.py b/pictures/templatetags/pictures.py
index 26fa73c..601a44c 100644
--- a/pictures/templatetags/pictures.py
+++ b/pictures/templatetags/pictures.py
@@ -59,6 +59,6 @@ def img_url(field_file, file_type, width, ratio=None) -> str:
         ) from e
     for w, img in sorted(sizes.items()):
         url = img.url
-        if w >= width:
+        if w >= int(width):
             break
     return url
diff --git a/tests/test_templatetags.py b/tests/test_templatetags.py
index 0f7b913..e36f8cb 100644
--- a/tests/test_templatetags.py
+++ b/tests/test_templatetags.py
@@ -67,7 +67,7 @@ def test_picture__additional_attrs(image_upload_file):
 def test_img_url(image_upload_file):
     profile = Profile.objects.create(name="Spiderman", picture=image_upload_file)
     assert (
-        img_url(profile.picture, ratio="3/2", file_type="webp", width=800)
+        img_url(profile.picture, ratio="3/2", file_type="webp", width="800")
         == "/_pictures/image/3x2/800w.WEBP"
     )