django-component 0.1.1

Django template tags to create composable components

The readme is outaded and will be updated only for the first release. Until then refer to the tests

Better components for Django templates. Inspired by javascript front-end frameworks like Svelte, React, etc

Supports Python 3.6+ and Django 1.11, 2.0+, and 3.0+

Describe your components in templatetags/mycomponents.py

from django_component import Library, Component

register = Library()

@register.component
class Card(Component):
    template = "mycomponents/card.html"
    css = ["mycomponents/card.css"]
    js = ["mycomponents/card.js"]

    def context(title, author='Me'):
        # By default all arguments are passed to the context,
        # But you can do some context processing if needed
        return {
            'short_title': title[:20],
            'author': author
        }

Create it’s template in template/mycomponents/card.html

<section class="card">
    <header>{{ slots.header }}</header>
    <h1>{{ short_title }}</h1>
    <div class="content">{{ children }}</div>
    <footer>
        Written by {{ author }}
        {{ slots.footer }}
    </footer>
</section>

Use it in template/homepage.html

{% load mycomponents %}

{% components.use_components_media %}
{% components.css %}

{% Card title="My card's title" %}
    <div>
        This will be accessible as the `children` variable.
        It's just django template, {{ variable }} !
    </div>

    {% slot header %}
        This <img src="foo.jpg" />
        will be in the header of the card
    {% endslot %}

    {% slot footer %}
        This <span class="bar">slots</span>
        will be in the footer of the card
    {% endslot %}
{% end_Card %}

{% components.js %}

Why django_component?

django_component make it easy to create reusable template components. Django already has some features to address this, but they all come with some limitations. django_component unify what’s great from all of these features (block, includes, inclusion_tag) under an unique api. In addition django_component address one of my greatest frustration with reusable components in django: tracking css and js dependencies for each component and automatically include them when necessary.

django_component api is influenced by javascript frameworks like Svelte, Vue, React, etc

Installation

pip install git+https://gitlab.com/Mojeer/django_component.git#egg=django_component

Then add django_component to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django_component",
    ...
]

Usage

The example at the begining of the readme describe most of the api of django_component. Bellow is a detailed explanation.

Create your component’s class

A component is describe by it’s class. This is where you define it’s name, template, css, js, and context processor. It’s then registered similarly to how you register classic django tags, by instanciating Library, and then calling it’s component method.

from django_component import Library, Component

register = Library()

@register.component
class MyComponent(Component):
    template = 'components/my_component.html'
    css = ['components/my_component.css']
    js = ['components/my_component.js']

    def context(foo=5):
        return {'foo2': foo * 2}

Because django_component.Library inherit from django.template.Library you can also register regular tags with it.

Use it in your templates

The opening tag of a component is the same as it’s class name, the closing tag is the same prefixed by end_

If your component contains css or js you will need to use {% components.use_components_media %} before using your components. You can put it in your base.html template once and then forget about it.

TODO For more examples look into tests/templatetags/test_components.py