# canonicalwebteam.image-template
[](https://pypi.org/project/canonicalwebteam.image-template/)
[](https://github.com/canonical-web-and-design/canonicalwebteam.image-template/actions?query=workflow%3ATests)
[](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.image-template)
A module to generate performant HTML image markup for images. The markup
will:
- Use [native lazyloading](https://addyosmani.com/blog/lazy-loading/)
- Explicitly define `width` and `height` attributes to avoid the page jumping effect
- Prefix all image URLs with cloudinary CDN proxy URLs, to transform the image to the optimal size
- Use predefined (2x) `srcset` break points for hidef screens
## Parameters
- `url` (mandatory string): The url to an image (e.g. `https://assets.ubuntu.com/v1/9f6916dd-k8s-prometheus-light.png`)
- `alt` (mandatory string): Alt text to describe the image
- `hi_def` (mandatory boolean): Has an image been uploaded 2x the width and height of the desired size
- `width` (mandatory integer): The number of pixels wide the image should be
- `height` (optional integer): The number of pixels high the image should be
- `fill` (optional boolean): Set the crop mode to ["fill"](https://cloudinary.com/documentation/image_transformation_reference#crop_parameter)
- `loading` (optional string, default: "lazy"): Set to ["auto" or "eager"](https://addyosmani.com/blog/lazy-loading/) to disable lazyloading
- `fmt` (optional string, default: "auto"): Define the file format (e.g. `fmt="jpg"`)
- `attrs` (optional dictionary): Extra `<img>` attributes (e.g. `class` or `id`) can be passed as additional arguments
- `output_mode` (optional string, default: "html"): The output mode can be set to either `html` or `attrs`. If set to `attrs`, the function will return an object with the image attributes instead of HTML markup.
## Usage
### Local development
For local development, it's best to test this module with one of our website projects like [ubuntu.com](https://github.com/canonical-web-and-design/ubuntu.com/). For more information, follow [this guide (internal only)](https://discourse.canonical.com/t/how-to-run-our-python-modules-for-local-development/308).
### Application code
The `image_template` function can be used directly to generate image Markup.
``` python3
from canonicalwebteam import image_template
image_markup = image_template(
url="https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg",
alt="",
width="534",
height="319",
hi_def=True,
loading="auto",
fill=True,
attrs={"class": "hero", "id": "openstack-hero"},
)
```
However, the most common usage is to add it to Django or Flask template contexts, as an `image` function.
### Django usage
Add it as a template tag:
``` python3
# myapp/templatetags.py
from canonicalwebteam import image_template
from django import template
from django.utils.safestring import mark_safe
register = template.Library()
@register.simple_tag
def image(*args, **kwargs):
return mark_safe(image_template(*args, **kwargs))
# settings.py
TEMPLATES[0]["OPTIONS"]["builtins"].append("myapp.templatetags")
```
Use it in templates:
``` html
# templates/mytemplate.html
{% image url="https://assets.ubuntu.com/v1/9f6916dd-k8s-prometheus-light.png" alt="Operational dashboard" width="1040" height="585" hi_def=True fill=True %}
```
### Flask usage
Add it as a template tag:
``` python3
# app.py
from canonicalwebteam import image_template
from flask import Flask
app = Flask(__name__)
@app.context_processor
def utility_processor():
return {"image": image_template}
```
Use it in templates, e.g.::
``` html
# templates/mytemplate.html
{{
image(
url="https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg",
alt="",
width="534",
height="319",
hi_def=True,
fill=True,
loading="auto",
attrs={"class": "hero", "id": "openstack-hero"},
) | safe
}}
```
## Generated markup
The output image markup will be e.g.:
``` html
<img
src="https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_534,h_319,c_fill/https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg"
srcset="https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_1068,h_638,c_fill/https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg 2x"
alt=""
width="534"
height="319"
loading="auto"
class="hero"
id="openstack hero"
/>
```
## Attribute output
In some cases, you may want to use the image attributes generated by this utility, rather than directly rendering its markup.
This allows you to add the image attributes to an existing `<img>` tag, or to use them in a different context.
To do this, you can set the `output_mode` parameter to `attrs` when calling the `image_template` function.
For example, some Vanilla patterns may require image attributes to be passed as a dictionary, in order to allow the pattern itself to construct the image element.
```html
{%-
call(slot) vf_tiered_list(
# other params...
img_attrs=image(
url="https://assets.ubuntu.com/v1/3f63a18c-data-center.png",
alt="",
width="2464",
height="1028",
hi_def=True,
loading="auto",
attrs={"class": "my-class-name"},
output_mode="attrs"
)
) -%}
```
Result:
```json
{
'src': 'https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_2464,h_1028/https://assets.ubuntu.com/v1/3f63a18c-data-center.png',
'srcset': 'https://res.cloudinary.com/canonical/image/fetch/c_limit,f_auto,q_auto,fl_sanitize,w_4928,h_2056/https://assets.ubuntu.com/v1/3f63a18c-data-center.png 2x',
'class': 'my-class-name',
'alt': '',
'width': 2464,
'height': '1028',
'hi_def': True,
'loading': 'auto'
}
```
## VS Code Snippet
To add the required markup for this template as a User Snippet, add the following as a HTML snippet (User Snippets under File > Preferences, or Code > Preferences on macOS):
```
"Image module": {
"prefix": "image-module",
"body": [
"{{",
" image_template(",
" url=\"$1\",",
" alt=\"$2\",",
" height=\"$3\",",
" width=\"$4\",",
" hi_def=$5True,",
" loading=\"auto|lazy$6\",",
" attrs={\"class\": \"$7\"}",
" ) | safe",
"}}"
],
"description": "Image module include"
}"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/canonical-web-and-design/canonicalwebteam.image-template",
"name": "canonicalwebteam.image-template",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Canonical webteam",
"author_email": "webteam@canonical.com",
"download_url": "https://files.pythonhosted.org/packages/0a/6a/38e942861983ded00355d09340d3cd6237849f6641e53235097650ec7b22/canonicalwebteam_image_template-1.8.0.tar.gz",
"platform": null,
"description": "# canonicalwebteam.image-template\n\n[](https://pypi.org/project/canonicalwebteam.image-template/)\n[](https://github.com/canonical-web-and-design/canonicalwebteam.image-template/actions?query=workflow%3ATests)\n[](https://codecov.io/gh/canonical-web-and-design/canonicalwebteam.image-template)\n\nA module to generate performant HTML image markup for images. The markup\nwill:\n\n- Use [native lazyloading](https://addyosmani.com/blog/lazy-loading/)\n- Explicitly define `width` and `height` attributes to avoid the page jumping effect\n- Prefix all image URLs with cloudinary CDN proxy URLs, to transform the image to the optimal size\n- Use predefined (2x) `srcset` break points for hidef screens\n\n## Parameters\n\n- `url` (mandatory string): The url to an image (e.g. `https://assets.ubuntu.com/v1/9f6916dd-k8s-prometheus-light.png`)\n- `alt` (mandatory string): Alt text to describe the image\n- `hi_def` (mandatory boolean): Has an image been uploaded 2x the width and height of the desired size\n- `width` (mandatory integer): The number of pixels wide the image should be\n- `height` (optional integer): The number of pixels high the image should be\n- `fill` (optional boolean): Set the crop mode to [\"fill\"](https://cloudinary.com/documentation/image_transformation_reference#crop_parameter)\n- `loading` (optional string, default: \"lazy\"): Set to [\"auto\" or \"eager\"](https://addyosmani.com/blog/lazy-loading/) to disable lazyloading\n- `fmt` (optional string, default: \"auto\"): Define the file format (e.g. `fmt=\"jpg\"`)\n- `attrs` (optional dictionary): Extra `<img>` attributes (e.g. `class` or `id`) can be passed as additional arguments\n- `output_mode` (optional string, default: \"html\"): The output mode can be set to either `html` or `attrs`. If set to `attrs`, the function will return an object with the image attributes instead of HTML markup.\n\n## Usage\n\n### Local development\n\nFor local development, it's best to test this module with one of our website projects like [ubuntu.com](https://github.com/canonical-web-and-design/ubuntu.com/). For more information, follow [this guide (internal only)](https://discourse.canonical.com/t/how-to-run-our-python-modules-for-local-development/308).\n\n### Application code\n\nThe `image_template` function can be used directly to generate image Markup.\n\n``` python3\nfrom canonicalwebteam import image_template\n\nimage_markup = image_template(\n url=\"https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg\",\n alt=\"\",\n width=\"534\",\n height=\"319\",\n hi_def=True,\n loading=\"auto\",\n\tfill=True,\n attrs={\"class\": \"hero\", \"id\": \"openstack-hero\"},\n)\n```\n\nHowever, the most common usage is to add it to Django or Flask template contexts, as an `image` function.\n\n### Django usage\n\nAdd it as a template tag:\n\n``` python3\n# myapp/templatetags.py\n\nfrom canonicalwebteam import image_template\nfrom django import template\nfrom django.utils.safestring import mark_safe\n\n\nregister = template.Library()\n\n@register.simple_tag\ndef image(*args, **kwargs):\n return mark_safe(image_template(*args, **kwargs))\n\n\n# settings.py\n\nTEMPLATES[0][\"OPTIONS\"][\"builtins\"].append(\"myapp.templatetags\")\n```\n\nUse it in templates:\n\n``` html\n# templates/mytemplate.html\n\n{% image url=\"https://assets.ubuntu.com/v1/9f6916dd-k8s-prometheus-light.png\" alt=\"Operational dashboard\" width=\"1040\" height=\"585\" hi_def=True fill=True %}\n```\n\n### Flask usage\n\nAdd it as a template tag:\n\n``` python3\n# app.py\n\nfrom canonicalwebteam import image_template\nfrom flask import Flask\n\napp = Flask(__name__)\n\n@app.context_processor\ndef utility_processor():\n return {\"image\": image_template}\n```\n\nUse it in templates, e.g.::\n\n``` html\n# templates/mytemplate.html\n\n{{\n image(\n url=\"https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg\",\n alt=\"\",\n width=\"534\",\n height=\"319\",\n hi_def=True,\n\tfill=True,\n loading=\"auto\",\n attrs={\"class\": \"hero\", \"id\": \"openstack-hero\"},\n ) | safe\n}}\n```\n\n## Generated markup\n\nThe output image markup will be e.g.:\n\n``` html\n<img\n src=\"https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_534,h_319,c_fill/https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg\"\n srcset=\"https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_1068,h_638,c_fill/https://assets.ubuntu.com/v1/450d7c2f-openstack-hero.svg 2x\"\n alt=\"\"\n width=\"534\"\n height=\"319\"\n loading=\"auto\"\n class=\"hero\"\n id=\"openstack hero\"\n/>\n```\n\n## Attribute output\n\nIn some cases, you may want to use the image attributes generated by this utility, rather than directly rendering its markup.\nThis allows you to add the image attributes to an existing `<img>` tag, or to use them in a different context.\nTo do this, you can set the `output_mode` parameter to `attrs` when calling the `image_template` function.\n\nFor example, some Vanilla patterns may require image attributes to be passed as a dictionary, in order to allow the pattern itself to construct the image element. \n\n```html\n{%-\n call(slot) vf_tiered_list(\n # other params...\n img_attrs=image(\n url=\"https://assets.ubuntu.com/v1/3f63a18c-data-center.png\",\n alt=\"\",\n width=\"2464\",\n height=\"1028\",\n hi_def=True,\n loading=\"auto\",\n attrs={\"class\": \"my-class-name\"},\n output_mode=\"attrs\"\n )\n) -%}\n```\n\nResult: \n\n```json\n{\n 'src': 'https://res.cloudinary.com/canonical/image/fetch/f_auto,q_auto,fl_sanitize,w_2464,h_1028/https://assets.ubuntu.com/v1/3f63a18c-data-center.png', \n 'srcset': 'https://res.cloudinary.com/canonical/image/fetch/c_limit,f_auto,q_auto,fl_sanitize,w_4928,h_2056/https://assets.ubuntu.com/v1/3f63a18c-data-center.png 2x', \n 'class': 'my-class-name',\n 'alt': '', \n 'width': 2464, \n 'height': '1028', \n 'hi_def': True, \n 'loading': 'auto'\n} \n```\n\n## VS Code Snippet\n\nTo add the required markup for this template as a User Snippet, add the following as a HTML snippet (User Snippets under File > Preferences, or Code > Preferences on macOS):\n\n```\n\"Image module\": {\n\t\"prefix\": \"image-module\",\n\t\"body\": [\n\t\t\"{{\",\n\t\t\"\timage_template(\",\n\t\t\"\t\turl=\\\"$1\\\",\",\n\t\t\"\t\talt=\\\"$2\\\",\",\n\t\t\"\t\theight=\\\"$3\\\",\",\n\t\t\"\t\twidth=\\\"$4\\\",\",\n\t\t\"\t\thi_def=$5True,\",\n\t\t\"\t\tloading=\\\"auto|lazy$6\\\",\",\n\t\t\"\t\tattrs={\\\"class\\\": \\\"$7\\\"}\",\n\t\t\"\t) | safe\",\n\t\t\"}}\"\n\t],\n\t\"description\": \"Image module include\"\n}\"\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Generate <img> markup block for an image.",
"version": "1.8.0",
"project_urls": {
"Homepage": "https://github.com/canonical-web-and-design/canonicalwebteam.image-template"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6e6f2f0818d0ec6a31c54650325b45452b949c78f1de0bec469650f7f9b35141",
"md5": "0f1879d57626bdcbc87614b7f581eadb",
"sha256": "a4b92702f8c389b03b81237033b8f16dc3069754ceaad38a0ebed2357dd54d39"
},
"downloads": -1,
"filename": "canonicalwebteam_image_template-1.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f1879d57626bdcbc87614b7f581eadb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6374,
"upload_time": "2025-07-31T13:24:32",
"upload_time_iso_8601": "2025-07-31T13:24:32.773292Z",
"url": "https://files.pythonhosted.org/packages/6e/6f/2f0818d0ec6a31c54650325b45452b949c78f1de0bec469650f7f9b35141/canonicalwebteam_image_template-1.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0a6a38e942861983ded00355d09340d3cd6237849f6641e53235097650ec7b22",
"md5": "80c6d1cd42cac54ecda83cc19302d5ed",
"sha256": "5e4b7d374d1e647e62f9d74387ed59dfba17b80e852fe0638a9b51edbfe8dd89"
},
"downloads": -1,
"filename": "canonicalwebteam_image_template-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "80c6d1cd42cac54ecda83cc19302d5ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7453,
"upload_time": "2025-07-31T13:24:33",
"upload_time_iso_8601": "2025-07-31T13:24:33.871816Z",
"url": "https://files.pythonhosted.org/packages/0a/6a/38e942861983ded00355d09340d3cd6237849f6641e53235097650ec7b22/canonicalwebteam_image_template-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 13:24:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "canonical-web-and-design",
"github_project": "canonicalwebteam.image-template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "canonicalwebteam.image-template"
}
JSON
