Templating of Upload Results

Templating Introduction

As mentioned earlier, after uploading image files, the resulting links are fed into a Jinja2 template.

To list all the currently defined templates, use the hypershot templates command.

Template file names always end with a .j2 extension. Built-in ones can be overridden by placing a file with the same name in the configuration directory.

You can also pass the path of an existing file with the -t option, then the template can be located anywhere.

If you want to write your own templates, or have some error in an existing one, the yaml and json templates come in handy. They dump all the keys and values available to a template as a YAML or JSON document, so you can see what’s where.

Writing Custom Templates

See the Jinja homepage for the full documentation of the template engine. You might not need it at all, if the available built-in templates serve your needs – then just skip this section.

Here’s the built-in bbcode.j2 template as an example:

{# Simple BBcode Template [built-in] #}
{%- for image in images -%}
[img]{{ image.hypershot.link }}[/img]
{% endfor %}

Start your own templates with a comment line like shown, so they get a proper description in hypershot templates.

These additional utility functions are available:

  • u.context – The Jinja2 context object, make sure you understand what you’re doing when accessing this.
  • u.namespace – A shallow copy of the Jinja2 template namespace, without helper functions.

And these are the custom filters:

  • json – Dump the value as JSON document.
  • mask_secrets – Replace any secret values (passwords) with question marks.
  • re_sub(pattern, repl) – Substitute regular expression matches with the text in repl.
  • repr – Apply Python’s repr.
  • yaml – Dump the value as YAML document.