Components¶

dj-angles provides component-like functionality by enhancing Django’s built-in include template tag.

Includes¶

These are equivalent ways to include HTML files.

<dj-partial />
<dj-include template='partial.html' />
<dj-include template='partial' />
<dj-include 'partial.html' />
<dj-include 'partial' />

Note

The self-closing element is used in most examples, but explicit closing elements for all examples, e.g. <dj-partial></dj-partial>, also works.

They all compile to the following Django template.

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

The wrapping element, e.g. dj-partial, is a custom element which browsers will ignore. It allows for easier debugging when looking at the source code and also allows for targeted CSS styling.

Warning

The built-in tags are considered reserved words. Template file names that conflict will not get loaded because reserved words take precedence. For example, if there is a template named “extends.html” <dj-extends /> could not be used to include it; <dj-include 'extends.html' /> would need to be used instead.

Wrapping element key¶

Adding a colon and an identifier to the end of a template name allows for even more specific CSS styling.

<dj-partial:1 />

Would get compiled to the following Django template.

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

Directories¶

Accessing templates in directories is supported even though technically forward-slashes aren’t permitted in a custom element. It might confound HTML syntax highlighters.

<dj-directory/partial />
<dj-include template='directory/partial.html' />
<dj-include template='directory/partial' />
<dj-include 'directory/partial.html' />
<dj-include 'directory/partial' />

They all compile to the following Django template.

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

CSS scoping¶

To encapsulate component styles, the dj-angles can use the Shadow DOM. This will ensure that any style element in the include will be contained. The downside is that the Shadow DOM does not allow outside styles in (other than CSS variables).

These are all equivalent ways to use the Shadow DOM with an include.

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

They all compile to the following Django template syntax.

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

More information about the Shadow DOM

Shadow DOM styling: https://javascript.info/shadow-dom-style
Declaratively creating a shadow root: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template#shadowrootmode
Using the Shadow DOM: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM

Slots¶

Note

Currently in beta and disabled by default. Can be enabled by setting slots_enabled to True.

Slots designate certain sections of an include template as placeholders. Those placeholders can then be “filled-in” with HTML when the component is rendered.

<!-- index.html -->
<dj-include template="profile.html">
    <span slot="username">User One</span>
</dj-include>

<dj-include template="profile.html"></dj-include>

<!-- profile.html -->
<h1>Profile</h1>

<ul>
    <li>Username: <slot name="username">n/a</slot></li>
</ul>

Would be rendered as the following.

<dj-profile>
    <h1>Profile</h1>

    <ul>
        <li>Username: <slot name="username"><span slot="username">User One</span></slot></li>
    </ul>
</dj-profile>

<dj-profile>
    <h1>Profile</h1>

    <ul>
        <li>Username: <slot name="username">n/a</slot></li>
    </ul>
</dj-profile>

Integrations¶

For other approaches to components in Django, dj-angles integrates with other Django component libraries. The currently supported external libraries include:

django-bird