Add documentation and source

Added documentation, source and extra files.

source/templating/.idea/Templating.iml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="FacetManager">
+    <facet type="django" name="Django">
+      <configuration>
+        <option name="rootFolder" value="$MODULE_DIR$" />
+        <option name="settingsModule" value="templating/settings.py" />
+        <option name="manageScript" value="manage.py" />
+        <option name="environment" value="&lt;map/&gt;" />
+        <option name="doNotUseTestRunner" value="false" />
+        <option name="trackFilePattern" value="" />
+      </configuration>
+    </facet>
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.idea" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3 (training)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PackageRequirementsSettings">
+    <option name="requirementsPath" value="$MODULE_DIR$/../../requirements.pip" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="GOOGLE" />
+    <option name="myDocStringFormat" value="Google" />
+  </component>
+  <component name="TemplatesService">
+    <option name="TEMPLATE_CONFIGURATION" value="Django" />
+  </component>
+</module>

source/templating/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,12 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="GrazieInspection" enabled="false" level="TYPO" enabled_by_default="false" />
+    <inspection_tool class="LanguageDetectionInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="SpellCheckingInspection" enabled="false" level="TYPO" enabled_by_default="false">
+      <option name="processCode" value="true" />
+      <option name="processLiterals" value="true" />
+      <option name="processComments" value="true" />
+    </inspection_tool>
+  </profile>
+</component>

source/templating/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

source/templating/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/templating.iml" filepath="$PROJECT_DIR$/.idea/templating.iml" />
+    </modules>
+  </component>
+</project>

source/templating/.idea/workspace.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showExcludedFiles" value="false" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+</project>

source/templating/demonstration/__init__.py

@@ -0,0 +1,9 @@
+from django.apps import AppConfig
+
+
+class DemonstrationConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'demonstration'
+
+
+default_app_config = "demonstration.DemonstrationConfig"

source/templating/demonstration/static/demonstration/demonstration.css

@@ -0,0 +1,48 @@
+:root {
+    --head-bg-color: #222;
+    --head-fg-color: #fff;
+    --head-ln-color: #3cf;
+}
+
+html, body {
+    height: 100%;
+    min-height: 100%;
+    width: 100%;
+}
+
+body {
+    margin: 0;
+    display: grid;
+    grid-template-areas: "header" "content" "footer";
+    grid-template-rows: auto 1fr auto;
+    grid-template-columns: 100%;
+    font-family: "Roboto", "Lucida Grande", "DejaVu Sans", "Bitstream Vera Sans", Verdana, Arial, sans-serif;
+}
+
+section#header {
+    grid-area: header;
+}
+
+section#content {
+    grid-area: content;
+}
+
+section#footer {
+    grid-area: footer;
+}
+
+
+section#header, section#footer {
+    background-color: var(--head-bg-color);
+    color: var(--head-fg-color);
+}
+
+section#header a, section#footer a {
+    color: var(--head-ln-color);
+    text-decoration: none;
+}
+
+div.body {
+    width: 1024px;
+    margin: 1.5em auto;
+}

source/templating/demonstration/templates/demonstration/basic/control.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Template with control structures</title>
+</head>
+<body>
+Use of a control structure to parse a list of values:
+<ul>
+    {% for item in values %}
+        {% if item != 3 %} {# Do not show the item with a value of 3 #}
+            <li>Item n.{{ forloop.counter }}: {{ item }}</li>
+        {% endif %}
+    {% endfor %}
+</ul>
+</body>
+</html>

source/templating/demonstration/templates/demonstration/basic/filters.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Template with filtering</title>
+</head>
+<body>
+<p>Use different filters on values:</p>
+{# Filter for strings #}
+<ul>
+    {% for item in strings %}
+        <li>{{ item|title }}</li>
+    {% endfor %}
+</ul>
+{# Filter for dates #}
+<p>{{ moment|date:"Y m d" }}</p>
+</body>
+</html>

source/templating/demonstration/templates/demonstration/basic/plain.txt

@@ -0,0 +1,7 @@
+This is a plain text file rendered as a template.
+Django can use any text file to render a template, whether it's an XML, HTML, RST or TXT file.
+
+The only specificity in rendering a template is that we can use values, control structures and
+a few tricks to make the rendering more dynamic.
+
+Templates are generally used in Django to render HTML, text and custom email bodies.

source/templating/demonstration/templates/demonstration/basic/variables.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Template with variables</title>
+</head>
+<body>
+This is an HTML file rendered as a template, with interpolated variables.
+Django can use any text file to render a template, whether it's an XML, HTML, RST or TXT file.
+
+The only specificity in rendering a template is that we can use values, control structures and
+a few tricks to make the rendering more dynamic.
+
+Templates are generally used in Django to render HTML, text and custom email bodies.
+
+Variables passed to the template context:
+<ul>
+    <li>Variable1: {{ variable1 }}</li>
+    <li>Variable2: {{ variable2 }}</li>
+</ul>
+</body>
+</html>

source/templating/demonstration/templates/demonstration/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Templating demonstration</title>
+</head>
+<body>
+<h1>Sections of templating</h1>
+<ul>
+    <li><a href="{% url "untemplated" %}">No template, just an HttpResponse</a></li>
+    <li><a href="{% url "basic-plain" %}">Basic: plain text</a></li>
+    <li><a href="{% url "basic-variables" %}">Basic: HTML with variables</a></li>
+    <li><a href="{% url "basic-control" %}">Basic: HTML with control structures</a></li>
+    <li><a href="{% url "basic-control-class" %}">Basic: HTML with control structures (class-based)</a></li>
+    <li><a href="{% url "basic-filters" %}">Basic: HTML with template filters</a></li>
+    <li><a href="{% url "inheritance-base" %}">Inheritance: Base template with overridable blocks</a></li>
+</ul>
+</body>
+</html>

source/templating/demonstration/templates/demonstration/inheritance/base.html

@@ -0,0 +1,33 @@
+{% load static %} {# The load tag enables template tags from other Django apps #}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>{% block title %} | Django Demonstration{% endblock title %}</title>
+    <link rel="stylesheet" href="{% static "demonstration/demonstration.css" %}">
+</head>
+<body>
+<section id="header">
+    <div class="body">
+        <nav>
+            <a href="{% url "index" %}">Home page</a>
+        </nav>
+    </div>
+</section>
+<section id="content">
+    <div class="body">
+        {% block body %}
+            Base content in a overridable block.
+        {% endblock body %}
+    </div>
+</section>
+<section id="footer">
+    <div class="body">
+        {% block footer %}
+            ©2021 Steve Kossouho, <strong>Dawan</strong>
+        {% endblock footer %}
+    </div>
+</section>
+
+</body>
+</html>

source/templating/demonstration/templates/demonstration/inheritance/inherited.html

@@ -0,0 +1,8 @@
+{% extends "demonstration/inheritance/base.html" %}
+{% load static %} {# The load tag enables template tags from other Django apps #}
+
+{% block title %}Inherited page{{ block.super }}{% endblock title %}
+
+{% block body %}
+Change body block from the original in the overridden block.
+{% endblock body %}

source/templating/demonstration/templates/demonstration/translation/translated.html

@@ -0,0 +1,9 @@
+{% extends "demonstration/inheritance/base.html" %}
+{% load i18n %} {# The i18n tag enables template tags for internationalization #}
+
+{% block title %}{% translate "Inherited page" %}{{ block.super }}{% endblock title %}
+
+{% block body %}
+    <p>{% translate "First string for translation." %}</p>
+    <p>{% blocktranslate %}Second string with placeholder: {{ value }}{% endblocktranslate %}</p>
+{% endblock body %}

source/templating/demonstration/templatetags/demonstration.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+
+from django import template
+from django.template.defaultfilters import stringfilter
+from pytz import UTC
+
+register = template.Library()
+
+
+@register.filter
+@stringfilter
+def decorate(value, _arg=None):
+    """
+    Template filter to decorate the value with hyphens.
+
+    Args:
+        value: Any value that can be displayed and filtered.
+        _arg: Option passed for the filter, if any
+
+    Returns:
+        Decorated value, like --<value>--
+
+    """
+    return f"--{value}--"
+
+
+@register.simple_tag
+def current_time():
+    """
+    Template tag that returns the current time, with the UTC timezone.
+
+    Returns:
+        Now in UTC.
+
+    """
+    return datetime.now(tz=UTC)

source/templating/demonstration/urls.py

@@ -0,0 +1,14 @@
+from django.urls import path
+
+from demonstration.views import *
+
+
+urlpatterns = [
+    path("untemplated/", view_untemplated, name="untemplated"),
+    path("basic/plain/", view_basic_plain, name="basic-plain"),
+    path("basic/variables/", view_basic_variables, name="basic-variables"),
+    path("basic/control/", view_basic_control, name="basic-control"),
+    path("basic/control/class/", BasicTemplateView.as_view(), name="basic-control-class"),
+    path("basic/filters/", view_basic_filters, name="basic-filters"),
+    path("inheritance/base/", view_inheritance_base, name="inheritance-base"),
+]

source/templating/demonstration/views/__init__.py

@@ -0,0 +1,3 @@
+from .index import *
+from .basic import *
+from .inheritance import *

source/templating/demonstration/views/basic.py

@@ -0,0 +1,55 @@
+from annoying.decorators import render_to
+from django.http import HttpRequest, HttpResponse
+from django.views.generic import TemplateView
+from pytz import UTC
+
+
+def view_untemplated(request: HttpRequest) -> HttpResponse:
+    """Return a base view for demonstration purposes."""
+    return HttpResponse("Page content returned")
+
+
+@render_to("demonstration/basic/plain.txt")
+def view_basic_plain(request: HttpRequest) -> dict:
+    """Show a plain text rendered as a template."""
+    return {}
+
+
+@render_to("demonstration/basic/variables.html")
+def view_basic_variables(request: HttpRequest) -> dict:
+    """Show a template using variable interpolation."""
+    return {"variable1": "Text number 1.", "variable2": 599.31}
+
+
+@render_to("demonstration/basic/control.html")
+def view_basic_control(request: HttpRequest) -> dict:
+    """Use control structures."""
+    return {"values": [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]}
+
+
+@render_to("demonstration/basic/filters.html")
+def view_basic_filters(request: HttpRequest) -> dict:
+    """Use template filters."""
+    from datetime import datetime
+
+    return {"strings": ["text in lowercase", "basic text."], "moment": datetime(2020, 1, 1, tzinfo=UTC)}
+
+
+@render_to("demonstration/basic/tags.html")
+def view_basic_tags(request: HttpRequest) -> dict:
+    """Use template tags."""
+    return {"numbers": [1, 2, 3, 4, 5, 6, 7, 8]}
+
+
+class BasicTemplateView(TemplateView):
+    """
+    Equivalent of the `view_basic_control` view.
+
+    See Also:
+        Documentation to know how to use class-based views:
+        - https://docs.djangoproject.com/fr/3.2/topics/class-based-views/
+
+    """
+
+    template_name = "demonstration/basic/control.html"
+    extra_context = {"values": [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]}

source/templating/demonstration/views/index.py

@@ -0,0 +1,8 @@
+from annoying.decorators import render_to
+from django.http import HttpRequest
+
+
+@render_to("demonstration/index.html")
+def view_index(request: HttpRequest) -> dict:
+    """Show the list of all sections."""
+    return {}

source/templating/demonstration/views/inheritance.py

@@ -0,0 +1,8 @@
+from annoying.decorators import render_to
+from django.http import HttpRequest
+
+
+@render_to("demonstration/inheritance/base.html")
+def view_inheritance_base(request: HttpRequest) -> dict:
+    """Show the list of all sections."""
+    return {}

source/templating/manage.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+
+def main():
+    """Run administrative tasks."""
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'templating.settings')
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == '__main__':
+    main()

source/templating/templating/asgi.py

@@ -0,0 +1,16 @@
+"""
+ASGI config for templating project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/3.2/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'templating.settings')
+
+application = get_asgi_application()

source/templating/templating/settings.py

@@ -0,0 +1,83 @@
+"""
+Django settings for templating project.
+
+Generated by 'django-admin startproject' using Django 3.2.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/3.2/topics/settings/
+
+For the full list of settings and their values, see
+https://docs.djangoproject.com/en/3.2/ref/settings/
+"""
+
+from pathlib import Path
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+# Quick-start development settings - unsuitable for production
+# See https://docs.djangoproject.com/en/3.2/howto/deployment/checklist/
+
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = "django-insecure-e08sa^6gqf-m!z5jmgt(hba^tg25+ce^6f#qx41o*2$q0=h+6%"
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = True
+
+ALLOWED_HOSTS = []
+
+
+# Application definition
+
+INSTALLED_APPS = [
+    "django.contrib.staticfiles",
+    "demonstration",
+]
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ROOT_URLCONF = "templating.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = "templating.wsgi.application"
+
+
+# Database
+# https://docs.djangoproject.com/en/3.2/ref/settings/#databases
+
+DATABASES = {}
+
+
+# Internationalization
+# https://docs.djangoproject.com/en/3.2/topics/i18n/
+
+LANGUAGE_CODE = "en-us"
+TIME_ZONE = "UTC"
+USE_I18N = True
+USE_L10N = True
+USE_TZ = True
+
+
+# Static files (CSS, JavaScript, Images)
+# https://docs.djangoproject.com/en/3.2/howto/static-files/
+
+STATIC_URL = "/static/"

source/templating/templating/urls.py

@@ -0,0 +1,23 @@
+"""templating URL Configuration
+
+The `urlpatterns` list routes URLs to views. For more information please see:
+    https://docs.djangoproject.com/en/3.2/topics/http/urls/
+Examples:
+Function views
+    1. Add an import:  from my_app import views
+    2. Add a URL to urlpatterns:  path('', views.home, name='home')
+Class-based views
+    1. Add an import:  from other_app.views import Home
+    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
+Including another URLconf
+    1. Import the include() function: from django.urls import include, path
+    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
+"""
+from django.urls import path, include
+
+from demonstration.views import view_index
+
+urlpatterns = [
+    path("demonstration/", include("demonstration.urls")),
+    path("", view_index, name="index"),
+]

source/templating/templating/wsgi.py

@@ -0,0 +1,16 @@
+"""
+WSGI config for templating project.
+
+It exposes the WSGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'templating.settings')
+
+application = get_wsgi_application()