Set of helpers for Django used at PHAC-ASPC
Project description
Django Helpers
Provides a series of helpers to provide a consistent experience across PHAC-ASPC's Django based projects.
Quick start
pip install django-phac_aspc-helpers
Start by adding phac_aspc.django.helpers to your INSTALLED_APPS
setting like this:
# settings.py
INSTALLED_APPS = [
...
'phac_aspc.django.helpers',
]
Note: The
phac_aspc.django.helpersmust appear after any application that will be using it. Consider placing it as the last application in the list.
To use all recommended default settings, add this line to your project's settings file:
#settings.py
from phac_aspc.django.settings import *
There are also a number of views available that provide additional functionality for things like renewing sessions. Add them to your project's configuration.
# urls.py
from phac_aspc.django.helpers.urls import urlpatterns as phac_aspc_helper_urls
urlpatterns = [
...
*phac_aspc_helper_urls,
]
Jinja
If you are using jinja you can use django template tags by adding them to the global environment like this:
import phac_aspc.django.helpers.templatetags as phac_aspc def environment(**options): env = Environment(**options) env.globals.update({ "phac_aspc": phac_aspc, }) return envFor more information, refer to the Jinja documentation.
Environment variables
Several settings or behaviours implemented by this library can be controlled via
environment variables. This is done via the
django-environ library.
(Refer to their documentation on how to format special data types like lists)
If your project root has a .env file, those values will be used.
If you want to use environment variables in your project's configuration, you can simply reference django-environ directly as it will automatically be installed. For example:
import environ
env = environ.Env(DEBUG=(bool, False))
environ.Env.read_env()
DEBUG = env('DEBUG')
This library also provides a utility that automatically declares a module level global while checking the environment. It is particularly useful when declaring django settings.
from .utils import global_from_env
global_from_env(
SESSION_COOKIE_AGE=(int, 1200),
)
The example above creates the module level global SESSION_COOKIE_AGE with a
default value of 1200, unless there is an environment variable (or .env file
entry) PHAC_ASPC_SESSION_COOKIE_AGE. By default the declared variable name is
prefixed with PHAC_ASPC_. The prefix can be changed by providing a custom
prefix.
from .utils import global_from_env
global_from_env(
prefix='MY_PREFIX_',
SESSION_COOKIE_AGE=(int, 1200),
)
Environment variable list
All variables are prefixed with PHAC_ASPC_ to avoid name conflicts.
| Variable | Type | Purpose |
|---|---|---|
| PHAC_ASPC_SESSION_COOKIE_AGE | int | Session expiry in seconds |
| PHAC_ASPC_SESSION_COOKIE_SECURE | bool | Use secure cookies (HTTPS only) |
| PHAC_ASPC_LANGUAGE_CODE | str | Default language |
Features
Web Experience Toolkit (WET)
The Web Experience Toolkit is bundled with the helpers, and can easily be added to your templates.
Your base template should be modified to:
- Specify the current language in the lang attribute of the HTML element
- Include the WET CSS files inside the HEAD element
- Include the WET script files at the end of your BODY element
A minimum base template may look like this:
{% load phac_aspc_wet %}
{% load phac_aspc_localization %}
<html lang="{% phac_aspc_localization_lang %}">
<head>
{% phac_aspc_wet_css %}
</head>
<body>
<h1>Minimum base template</h1>
{% block content %}{% endblock %}
{% phac_aspc_wet_scripts %}
</body>
</html>
or if you're using Jinja:
<html lang="{{ phac_aspc.phac_aspc_localization_lang() }}">
<head>
{{ phac_aspc.phac_aspc_wet_css() }}
</head>
<body>
<h1>Minimum base template</h1>
{% block content %}{% endblock %}
{{ phac_aspc.phac_aspc_wet_scripts() }}
</body>
</html>
Bundled releases
| Product | Version |
|---|---|
| Web Experience Toolkit (WET) | v4.0.56.4 |
| Canada.ca (GCWeb) | v12.5.0 |
Security Controls
AC-11 Session Timeouts
The default configuration makes the following configuration changes to django:
- Sessions timeout in 20 minutes,
- Sessions cookies are marked as secure,
- Sessions cookies are discarded when the browser is closed,
- Any requests to the server automatically extends the session.
You can override any of these settings by adding them below the settings import line. For example to use 30 minutes sessions:
#settings.py
from phac_aspc.django.settings import *
SESSION_COOKIE_AGE=1800
Configuration parameters can also be overridden using environment variables. For example here is a .env file that achieves the same result as above.
# .env
PHAC_ASPC_SESSION_COOKIE_AGE=1800
For more information on sessions, refer to Django's documentation
Additionally the Session Timeout UI control is available to warn users their session is about to expire, and provide mechanisms to automatically renew the session by clicking anywhere on the page, or by clicking on the "extend session" button when less than 3 minutes remain.
To use it, make sure your base template has WET setup as described above, and add the following line somewhere in your body tag.
{% phac_aspc_wet_session_timeout_dialog 'logout' %}
or if you're using Jinja
{{ phac_aspc.phac_aspc_wet_session_timeout_dialog(
dict(request=request),
'logout'
)
}}
Make sure the above is included on every page where a user can be signed in, preferably in the base template for the entire site.
For more information on session timeout, visit the documentation.
Localization
Django will be configured to support English (en-ca) and French (fr-ca). This
can be changed in your projects settings using LANGUAGES and LANGUAGE_CODE.
For more information on Django's localization, see their documentation.
lang template tag
In your templates, retrieve the current language code using the lang tag.
{% load localization %}
<html lang="{% lang %}">
Or in you're using Jinja
<html lang="{{ phac_aspc.localization.lang() }}">
translate decorator
Use this decorator on your models to add translations via
django-modeltranslation. The example below adds translations for the
title field.
from django.db import models
from phac_aspc.django.localization.decorators import translate
@translate('title')
class Person(models.Model):
name = models.CharField(max_length=255)
title = models.CharField(max_length=255)
add_admin decorator
Use this decorator on your model to quickly add it to Django's admin interface.
from django.db import models
from phac_aspc.django.admin.decorators import add_admin
@add_admin()
class Person(models.Model):
...
You can also specify inline models as well as additional ModelAdmin
parameters via inlines and admin_options respectively.
class SignalLocation(models.Model):
signal = models.ForeignKey("Signal", on_delete=models.CASCADE)
location = models.String()
@add_admin(
admin_options={'filter_horizontal': ('source',)},
inlines=[SignalLocation]
)
class Signal(models.Model):
title = models.CharField(max_length=400)
location = models.ManyToManyField("Location", through='SignalLocation')
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for django-phac_aspc-helpers-0.3.0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3985974688822d7a0d0ead669a2ec4a04e65a0dd8ba2c3cea2bed9f493f31a46 |
|
| MD5 | a37b52896bcea3ade5c4ebb3940a37d4 |
|
| BLAKE2b-256 | 8ea801562a9b334808a2a1433503575f7efc7af2d755ebc0a3bfc5e43acc6a3c |
