Extensions

Global variables

The following variables are available to jinja2 templating expressions:

year: current year

Local extensions

A template project may extend the jinja2 environment with local extensions. It can add extra filters, tests, globals or even extend the parser.

To do so, an author must specify the required extensions in scaffold.yml as follows:

---
extensions:
  - "extensions.FoobarExtension"

On invocation mk-scaffold tries to import the extensions and add them to its environment respectively.

This example uses a simple module local_extensions.py which exists in the template project extensions` direcotory, containing the following (for instance):

from jinja2.ext import Extension


class FoobarExtension(Extension):
    def __init__(self, environment):
        super(FoobarExtension, self).__init__(environment)
        environment.filters["foobar"] = lambda v: v * 2

This will register the foobar filter for the template.

Built-in Extensions

By default mk-scaffold includes the following extensions:

jinja2_time.TimeExtension
scaffold.extensions.JsonifyExtension
scaffold.extensions.RandomStringExtension
scaffold.extensions.SlugifyExtension
scaffold.extensions.StringExtension
scaffold.extensions.UUIDExtension

Jsonify extension

The scaffold.extensions.JsonifyExtension extension provides a jsonify filter in templates that converts a Python object to JSON:

{% {'a': True} | jsonify %}

Would output:

{"a": true}

Random string extension

The scaffold.extensions.RandomStringExtension extension provides a random_ascii_string method in templates that generates a random fixed-length string, optionally with punctuation.

Generate a random n-size character string. Example for n=12:

{{ random_ascii_string(12) }}

Outputs:

bIIUczoNvswh

The second argument controls if punctuation and special characters !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ should be present in the result:

{{ random_ascii_string(12, punctuation=True) }}

Outputs:

fQupUkY}W!)!

Slugify extension

The scaffold.extensions.SlugifyExtension extension provides a slugify filter in templates that converts string into its dashed (“slugified”) version:

{% "It's a random version" | slugify %}

Would output:

it-s-a-random-version

It is different from a mere replace of spaces since it also treats some special characters differently such as ' in the example above. The function accepts all arguments that can be passed to the slugify function of python-slugify. For example to change the output from it-s-a-random-version` to it_s_a_random_version, the separator parameter would be passed: slugify(separator='_').

UUID4 extension

The scaffold.extensions.UUIDExtension extension provides a uuid() method in templates that generates a uuid4.

Generate a uuid string:

{{ uuid() }}

Outputs:

83b5de62-31b4-4a1e-83fa-8c548de65a11

String extension

The scaffold.extensions.StringExtension extension provides string methods.

Get the length, and repeat character for length of string:

{{ repeat("=", len(uuid())) }}

Outputs:

====================================