Templates

The Jinja template backend is extended with features that are generally missing from Django’s built-in Jinja template backend.

Note

The extended Jinja backend uses .j as a file extension by default, therefore you should make sure to name your template files accordingly.

Note

The jinja2.ext.i18n extension is added to the list of extensions by default.

Bases

Standard HTML

We provide a standard HTML base template that can be used as follows:

{% extends 'django_logikal/base.html.j' %}

{% block title %}Page Title{% endblock %}
{% block description %}Page description.{% endblock %}
{% block head %}
  <link rel="icon" href="{{ static('favicon.png') }}">
  <link rel="stylesheet" href="{{ static('style.css') }}">
{% endblock %}

{% block body %}
  <h1>Header</h1>
{% endblock %}

Note that the title, description and body blocks are required, the head block is optional.

Optionally, you can override the lang global HTML attribute (it defaults to the value provided by django.utils.translation.get_language()):

{% block language %}en-GB{% endblock %}

You may also add attributes to the body element via the bodyattributes tag:

{% block bodyattributes %}class="flex-cards"{% endblock %}

Email

We provide a standard email base template (which extends the standard HTML template) that can be used as follows:

{% extends 'django_logikal/email/base.html.j' %}

{% block subject %}Email Subject{% endblock %}
{% block description %}Email description.{% endblock %}
{% block head %}
  <style>
    {{ include_static('email/style.css') }}
  </style>
{% endblock %}

{% block body %}
  <h1>Header</h1>
{% endblock %}

Note that the subject, description and body blocks are required, the head block is optional.

Tags

language

Override the current language inside the block.

{% language 'en-gb' %}
  British English: {{ _('localized') }}
{% endlanguage %}

timezone

Override the current time zone inside the block.

{% timezone 'Europe/London' %}
  London time: {{ timestamp }}
{% endtimezone %}

Objects

messages: django.contrib.messages.storage.base.BaseStorage

The current message storage backend instance.

You may simply iterate over it to get the currently available messages:

{% for message in messages %}
  {{ message }}
{% endfor %}

settings: django.conf.LazySettings: The current Django settings object.

filters: Dict[str, Any]: The currently available filters.

tests: Dict[str, Any]: The currently available tests.

Libraries

re: Python regular expression operations.

Filters

The following Python built-in objects are exposed as filters:

Functions: dir(), getattr(), hasattr(), repr(), type()
Types: str

upper_first(text: str) → str: Change the first letter of a string to uppercase.

join_lines(text: str, spacer: bool = False) → str

Replace new lines with spaces.

Parameters:

text – The text to use.
spacer – Whether to add a space to the beginning when the text is not empty.

slugify(text: str, use_underscore: bool = False) → str: Convert a string to a URL slug.

unslugify(text: str) → str: Convert a URL slug to a string.

wrap(text: str) → SafeString: Replace spaces with line breaks.

nowrap(text: str) → SafeString: Replace spaces with non-breaking spaces.

Tests

startswith(text: str, prefix: str) → bool: Return True when the provided text starts with the given prefix.

Functions

context(): Return the current template context.

static(path: str) → str: Return the absolute server URL path to a static asset.

static_path(path: str) → Path: Return the local path to a static asset.

include_static(path: str) → SafeString

Insert the contents of the given static file into the template.

Useful for inlining CSS, SVG or JavaScript content.

Danger

Security risk: the contents of the referenced file are inserted unescaped.

Do not use this function to include non-trusted, user-generated or user-uploaded content, or content that can be in any way influenced by users.

url(*args: Any, request: HttpRequest | None = None, request_get_update: dict[str, Any] | None = None, **kwargs: Any) → str

Return the absolute server URL path associated with the given view name.

HTTP GET parameters are automatically appended when the request is provided.

url_name(request: HttpRequest) → str: Return the view name associated with the current request.

language() → str: Return the current language code.

format(locale: Locale | None = None, language_code: str | None = None, tzinfo: tzinfo | None = None) → Format

Return a locale-aware and time zone-aware formatter.

Defaults to deriving the locale from the current language and using the current time zone.

Tip

Often times you can use a single formatter instance in a template as follows:

{% set fmt = format() %}

... {{ fmt.decimal(number) }} ...
... {{ fmt.datetime(timestamp) }} ...

Note that the current locale can be influenced with the language tag, while the current time zone can be influenced with the timezone tag:

{% language 'en-us' %}
{% timezone 'Europe/London' %}

{{ format().datetime(timestamp, format='long') }}
<!-- if timestamp is datetime(2023, 7, 1, 14, 34, 56, tzinfo=timezone.utc) -->
<!-- displays 1 July 2023, 15:34:56 BST -->

{% endtimezone %}
{% endlanguage %}

cwd() → Path: Return the current working directory.

now() → datetime: Return the current date and time.

bibliography(name: str) → django_logikal.bibliography.Bibliography

Return a Bibliography instance.

Parameters:: name – The name of the bibliography configuration to use.

Note

Requires the bibliography extra.

Usage

First, make sure that your bibliographies are in the appropriate template folders and that their paths are added to the Django settings file as follows:

BIBLIOGRAPHIES = {'references': 'website/references.bib'}

Once configured, you can use this function in templates as follows:

{% set bib = bibliography('references') %}
{% set cite = bib.cite %}

... {{ cite('entry') }} ...

{{ bib.references() }}

Bibliography

class django_logikal.bibliography.Bibliography(name: str)

Render bibliography citations and references.

Parameters:: name – The name of the bibliography configuration to use.

classmethod add_bibliographies(bibliographies: dict[str, str]) → None

Parse and store the provided bibliographies.

Parameters:: bibliographies – A name to path mapping of the bibliographies to read.

cite(name: str) → SafeString

Render a citation to the given entry and store it in the references.

Parameters:: name – The name of the entry.

references(classes: Sequence[str] = ('references',)) → SafeString

Render the stored references as an ordered, numbered list.

Parameters:: classes – The classes to add to the ordered list element.