dj-angles 0.1.0

Add some more bracket angles to your Django templates

dj-angles 🎧

Add some more bracket angles to your Django templates 🎧

This code is experimental -- use with caution! Or maybe not at all! 🤷

📦 Package located at https://pypi.org/project/dj-angles/.

⭐ Features

• Use HTML-like elements in Django templates instead of {% %}
• Can be sprinkled in as needed, but does not remove existing Django functionality
• Pretend like you are writing React components, but without dealing with JavaScript at all
• Tell all your friends how neat the Shadow DOM is

⚡ Installation

1. Create a new Django project or cd to an existing project
2. pip install dj-angles to install the dj-angles package
3. Edit settings.py TEMPLATES and add "dj_angles.template_loader.Loader", as the first loader. Note: you might need to add the "loaders" key since it is not there by default: https://docs.djangoproject.com/en/stable/ref/templates/api/#django.template.loaders.cached.Loader.

TEMPLATES = [
  "BACKEND": "django.template.backends.django.DjangoTemplates",
  # "APP_DIRS": True,  # this cannot be specified if loaders are explicitly set
  "DIRS": [],
  "OPTIONS": {
      "builtins": builtins,
      "context_processors": [
          "django.template.context_processors.request",
          "django.template.context_processors.debug",
          "django.template.context_processors.static",
      ],
      "loaders": [
          (
              "django.template.loaders.cached.Loader",
              [
                  "dj_angles.template_loader.Loader",  # this is required for `dj-angles`
                  "django.template.loaders.filesystem.Loader",
                  "django.template.loaders.app_directories.Loader",
              ],
          )
      ],
  },
]

Example templates

base.html

<dj-block 'content'>
</dj-block 'content'>

index.html

<dj-extends 'base.html' />  <!-- {% extends 'base.html' %} -->

<dj-block 'content'>  <!-- {% block 'content' %} -->
  <div>
    <h2>Including partials</h2>

    <div>
      <dj-include 'partial.html' />  <!-- {% include 'partial.html' %} -->
    </div>
  </div>

  <dj-verbatim>  <!-- {% verbatim %} -->
    This is verbatim: {% include %}
  </dj-verbatim>  <!-- {% endverbatim %} -->

  <dj-comment>  <!-- {% comment %} -->
    this is a comment
  </dj-comment>  <!-- {% endcomment %} -->

  <dj-#>this is another comment</dj-#>    <!-- {# this is another comment #} -->

  <dj-autoescape-on>  <!-- {% autoescape-on %} -->
    This is escaped
  </dj-autoescape-on>  <!-- {% endautoescape %} -->

  <dj-autoescape-off>  <!-- {% autoescape off %} -->
    This is not escaped
  </dj-autoescape-off>  <!-- {% endautoescape %} -->

  <dj-csrf />  <!-- {% csrf_token %} -->
  
  <dj-debug />  <!-- {% debug %} -->
</dj-block 'content'>  <!-- {% endblock 'content' %} -->

partial.html

<div style="border: 1px solid red;">
  <p>
    This is a partial: {{ now|date:"c" }}
  </p>
</div>

<style>
  p {
    color: green;
  }
</style>

Include tags

<p>These are all equivalent ways to include partials.</p>

<dj-include 'partial.html' />
<dj-partial />
<$partial />

They all compile to the following Django template syntax.

{% include 'partial.html' %}

Directories are also supported.

<dj-include 'directory/partial.html' />
<dj-directory/partial />
<$directory/partial />

CSS scoping

To encapsulate component styles, enable the Shadow DOM for the partial. This will ensure that any style element in the partial will be contained to that partial.

<p>These are all equivalent ways to include partials.</p>

<dj-include 'partial.html' shadow />
<dj-partial shadow />
<dj-partial! />
<$partial! />

They all compile to the following Django template syntax.

<template shadowrootmode='open'>{% include 'partial.html' %}</template>

• More details about declaratively creating shadow root: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template#shadowrootmode
• More details about using the Shadow DOM: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM

Other tags

extends

<dj-extends 'base.html' />

{% extends 'base.html' %}

block

<dj-block 'content'>
  ...
</dj-block 'content'>

{% block 'content' %}
  ...
{% endblock 'content' %}

verbatim

<dj-verbatim>
  ...
</dj-verbatim>

{% verbatim %}
  ...
{% endverbatim %}

comment

<dj-comment>
  ...
</dj-comment>

{% comment %}
  ...
{% endcomment %}

#

<dj-#>...</dj-#>

{# ... #}

autoescape-on

<dj-autoescape-on>
  ...
</dj-autoescape-on>

{% autoescape on %}
{% endautoescape %}

autoescape-off

<dj-autoescape-off>
  ...
</dj-autoescape-off>

{% autoescape off %}
{% endautoescape %}

csrf, csrf-token

<dj-csrf />

{% csrf_token %}

csrf-input

<dj-csrf-input />

<input type='hidden' value='{% csrf_token %}'></input>

debug

<dj-debug />

{% debug %}

filter

<dj-filter ... />

{% filter ... %}

lorem

<dj-lorem />

{% lorem %}

now

<dj-now />

{% now %}

spaceless

<dj-spaceless>
  ...
</dj-spaceless>

{% spaceless %}
  ...
{% endspaceless %}

templatetag

<dj-templatetag ... />

{% templatetag ... %}