Skip to main content

High-flying components for perfectionists with deadlines

Project description

django-bird

PyPI PyPI - Python Version Django Version

High-flying components for perfectionists with deadlines.

[!CAUTION] This is an experimental, alpha attempt at a different approach to defining components in Django templates. It is not suitable for production use yet.

Requirements

  • Python 3.10, 3.11, 3.12, 3.13
  • Django 4.2, 5.0, 5.1

Installation

  1. Install the package from PyPI:

    python -m pip install django-bird
    
    # or if you like the new hotness
    
    uv add django-bird
    uv sync
    
  2. Add the app to your Django project's INSTALLED_APPS:

    INSTALLED_APPS = [
        ...,
        "django_bird",
        ...,
    ]
    
  3. django-bird will automatically configure the necessary settings in your project.

    If you need to customize the configuration or prefer to set up django-bird manually, you can set DJANGO_BIRD["ENABLE_AUTO_CONFIG"] = False in your settings.

    For detailed instructions, please refer to the Manual Setup section within the Configuration documentation.

Getting Started

django-bird is a library for creating reusable components in Django. Let's create a simple button component to show the basics of how to use the library.

Create a new directory named bird in your project's main templates directory. This will be the primary location for your components.

templates/
└── bird/

Inside the bird directory, create a new file named button.html. The filename determines the component's name.

templates/
└── bird/
    └── button.html

In button.html, create a simple HTML button. Use {{ slot }} to indicate where the main content will go. We will also define a component property via the {% bird:prop %} templatetag and add {{ attrs }} for passing in arbitrary HTML attributes.

{# templates/bird/button.html #}
{% bird:prop class="btn" %}
{% bird:prop data_attr="button" %}

<button class="{{ props.class }}" data-attr="{{ props.data_attr }}" {{ attrs }}>
    {{ slot }}
</button>

To use your component in a Django template, use the {% bird %} templatetag. The content between {% bird %} and {% endbird %} becomes the {{ slot }} content. Properties and attributes are set as parameters on the {% bird %} tag itself.

{% bird button class="btn-primary" disabled=True %}
    Click me!
{% endbird %}

django-bird automatically recognizes components in the bird directory, so no manual registration is needed. When Django processes the template, django-bird replaces the {% bird %} tag with the component's HTML, inserting the provided content into the slot, resulting in:

<button class="btn-primary" data-attr="button" disabled>
    Click me!
</button>

You now have a button component that can be easily reused across your Django project.

Documentation

django-bird offers features for creating flexible components, such as:

For a full overview of the features and configuration options, please refer to the documentation.

Motivation

Several excellent libraries for creating components in Django exist:

[!NOTE] Also worth mentioning is django-template-partials from Carlton Gibson. While not a full component library, it allows defining reusable chunks in a Django template, providing a lightweight approach to reusability.

These libraries are excellent in their own right, each solving specific problems in innovative ways: django-components is full-featured and will take most people far with custom components, django-unicorn offers a novel approach to adding interactivity without a full JavaScript framework, and django-cotton has a new way of defining custom components that has me very excited.

So, why another Django component library?

Most of the ones above focus on defining components on the Python side, which works for many use cases. For those focusing on the HTML and Django template side, they have made significant strides in improving the developer experience. However, as a developer with strong opinions (sometimes loosely held 😄) about API design, I wanted a different approach.

After watching Caleb Porzio's 2024 Laracon US talk introducing Flux, I could not shake the desire to bring something similar to Django. While there are plenty of libraries such as Shoelace or UI kits designed for use in any web application, and tools like SaaS Pegasus for whole Django project generation, I couldn't find a well-polished component library solely dedicated to Django templates with the level of polish that Flux has for Laravel.

Initially, I considered contributing to existing libraries or wrapping one to add the functionality I wanted. However, I decided to create a new library for several reasons:

  1. I wanted to respect the hard work of existing maintainers and avoid burdening them with features that may not align with their project's goals.
  2. While wrapping an existing library might have been technically feasible and okay license-wise, it didn't feel right to build an entire component system on top of someone else's work, especially for a project I might want to develop independently in the future.
  3. Building something new gives me the freedom to fully control the direction and architecture, without being constrained by design choices made in other libraries.
  4. Healthy competition among libraries helps drive innovation, and I see this as an opportunity to contribute to the broader Django ecosystem.
  5. Recent libraries like django-cotton and dj-angles are pushing Django templates in new and exciting directions and I wanted to join in on the fun. 😄

It's very early days for django-bird. What you see here is laying the foundation for a template-centric approach to Django components. The current implementation focuses on core functionality, setting the stage for future features and enhancements.

See the ROADMAP for planned features and the future direction of django-bird.

License

django-bird is licensed under the MIT license. See the LICENSE file for more information.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_bird-0.6.0.tar.gz (111.4 kB view details)

Uploaded Source

Built Distribution

django_bird-0.6.0-py3-none-any.whl (18.4 kB view details)

Uploaded Python 3

File details

Details for the file django_bird-0.6.0.tar.gz.

File metadata

  • Download URL: django_bird-0.6.0.tar.gz
  • Upload date:
  • Size: 111.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.4.30

File hashes

Hashes for django_bird-0.6.0.tar.gz
Algorithm Hash digest
SHA256 c218c0c16cb64f0da0453f23a9e7680087c365b86702f8196c5a366fcf6215ca
MD5 bd10b4fd6f9c38d22fa17ef36d6f3df1
BLAKE2b-256 aa1de3b4e6550e5c7d1b3ec1202fb1daeb5d6bc85b973a83a1beab0cffdf99ad

See more details on using hashes here.

File details

Details for the file django_bird-0.6.0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_bird-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 086a8ecf6fc90792f1b54b51ba1a258dc8ed4e367363826b7f55d9bbfb95ff9f
MD5 dd02de621ad073fc67ec2b029927de68
BLAKE2b-256 44dd57be27cfed190a76d6f0b85b49ecf5502c1042dc4895007c5f8c420450d7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page