Design

Todo

Review

This section is dated and needs to be reviewed and rewritten.

Base Files

Todo

These base files are named base.ENGINE.html; this should be applied for all of the base frameworks. It frees the user up to migrate from some base.html to base.ENGINE.html until they can adopt web templates across their entire site and revert back to base.html. The “Sphinx in Django” section of the documentation also illustrates the utility in having the sphinx_ENGINE themes compile ones documentation to depends upon a base.ENGINE.html template rather then a base.html.

I believe these templates were measnt to ‘passivate’; that is setup the base functionality for the website for a given template engine e.g. include boostrap/material design react etc.

In the package root there are a set of base.ENGINE.html files. i have forgotten their purpose to be honest but i believe they are meant to generate the skeleton files that are ready to be processed by the Django Template Engine (DTE) after the other template engine has processed the file.

base.ENGINE.html > FRAMEWORK/ENGINE > TEMPLATE.html(DTE) > Django Template Engine > PAGE.html

Consider a document generated by Sphinx, the base.sphinx.html template, creates a PAGE.html(DTE) page that can then be processed by the Django template engine to produce the final output. This allows both template engines to process the page in its usual manner but the content flows “upstream” until the final production.

Todo

Specifically for sphinx the file E:Pythonweb-templatesweb_templatessphinxdjangolayout.html, a copy of E:Pythonweb-templatesweb_templatesbasiclayout.html, may be sued by sphinx to compile documentation that depends upon a base.sphinx.html file; based upon the users base.html which in turn subclasses web-teplates/../skeleton.html. The current E:Pythonweb-templatesweb_templatesbase.sphinx.html seems to duplicate the E:Pythonsphinxsphinxthemesbasiclayout.html from the Sphinx base theme more then anything else; I believe this was to be merged with E:Pythonweb-templatesweb_templatessphinxdjangolayout.html. E:Pythonweb-templatesweb_templatesbase.sphinx.html was probably meant to serve as a bridging template for users to simply copy or extend as necessary.

Structure

The templates are organized within the project as follows

Naming

The skeleton templates provided by Web-Templates for the base templates of other projects to inherit are named accordingly to the following scheme

BACKEND_FRAMEWORK[/EXTENTION(S)][/FRONTEND_FRAMEWORK][/EXTENTION(S)]/skeleton.TEMPLATE_ENGINE.html

Django

Name Spaced Packages

Django does not pick up templates within a namespaced package, like templates, especially when there are multiple paths as is common with 3rd parties adding additional functionality. Providing templates through the following structure

templates/
 base.html

resulted in the following message, for example

django.core.exceptions.ImproperlyConfigured: The app module <module 'templates' (namespace)> has multiple filesystem locations (['..\\web-templates\\templates', '..\\other\\templates']); you must configure this app with an AppConfig subclass with a 'path' class attribute.

This implies one might select a preferred package by specifying a preferred root package within AppConfig.

A work around is to nest the template one level deeper, removing the ambiguity and appeasing Django accordingly. Consequently web-tamples has been refactored from the original structure to the following one

templates/
 django/
  base.html

resolving the issue. Under the hood Python is selecting the unique subpackage, django, from the multi-targeted namespace package, templates, that contains it; eliminating the ambiguity and finding the template accordingly.

Hence the need to use templates.django within the middleware of a projects settings.py file.