{
"info": {
"author": "Canonical webteam",
"author_email": "webteam@canonical.com",
"bugtrack_url": null,
"classifiers": [],
"description": "# 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/) if it's available\n- Output markup compatible with [lazysizes `noscript` plugin](https://github.com/aFarkas/lazysizes/tree/gh-pages/plugins/noscript)\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- `width` (mandatory integer): The number of pixels wide the image should be\n- `height` (mandatory integer): The number of pixels high the image should be\n- `hi_def` (mandatory boolean): Has an image been uploaded 2x the width and height of the desired size\n- `loading` (optional string, default: \"lazy\"): Set to [\"auto\" or \"eager\"](https://addyosmani.com/blog/lazy-loading/) to disable lazyloading\n- `attrs` (optional dictionary): Extra `` attributes (e.g. `class` or `id`) can be passed as additional arguments\n\n## Usage\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 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### Add lazysizes\n\nAt the time of writing, the `loading` attribute [is only natively supported](https://caniuse.com/#search=loading) in Chrome. Therefore we use [lazysizes](https://github.com/aFarkas/lazysizes) to enable loading in other browsers while still taking advantage of the native functionality when it's available.\n\nIf `loading` is set to \"lazy\" (the default) we will output [the Markup](#generated-markup) in a format supported by [lazysizes](https://github.com/aFarkas/lazysizes), with the [`noscript`](https://github.com/aFarkas/lazysizes/tree/gh-pages/plugins/noscript) and [`native-loading`](https://github.com/aFarkas/lazysizes/tree/gh-pages/plugins/native-loading) plugins enabled.\n\nTo support this in your site you need to add the following script to the `` of each page, *above* any `` attributes:\n\n``` html\n\n```\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 %}\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 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\n```\n\nIf `loading` is set to \"lazy\" (the default), the output markup will be wrapped in markup for lazysizes support:\n\n``` html\n