A module to generate performant HTML image markup for images. The markup will:
- Use native lazyloading if it's available
- Output markup compatible with lazysizes
noscriptplugin - Explicitly define
widthandheightattributes 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)
srcsetbreak points for hidef screens
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 imagehi_def(mandatory boolean): Has an image been uploaded 2x the width and height of the desired sizewidth(mandatory integer): The number of pixels wide the image should beheight(optional integer): The number of pixels high the image should befill(optional boolean): Set the crop mode to "fill"loading(optional string, default: "lazy"): Set to "auto" or "eager" to disable lazyloadingattrs(optional dictionary): Extra<img>attributes (e.g.classorid) can be passed as additional arguments
For local development, it's best to test this module with one of our website projects like ubuntu.com. For more information, follow this guide (internal only).
The image_template function can be used directly to generate image Markup.
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.
At the time of writing, the loading attribute is only natively supported in Chrome. Therefore we use lazysizes to enable loading in other browsers while still taking advantage of the native functionality when it's available.
If loading is set to "lazy" (the default) we will output the Markup in a format supported by lazysizes, with the noscript and native-loading plugins enabled.
To support this in your site you need to add the following script to the <head> of each page, above any <link> attributes:
<script src="https://assets.ubuntu.com/v1/703e23c9-lazysizes+noscript+native-loading.5.1.2.min.js" defer></script>Add it as a template tag:
# 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:
# 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 %}Add it as a template tag:
# 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.::
# 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
}}The output image markup will be e.g.:
<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"
/>If loading is set to "lazy" (the default), the output markup will be wrapped in markup for lazysizes support:
<div class="lazyload" data-noscript>
<noscript>
<img ...>
</noscript>
</div>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"
}"