Quickstart

This guide will get you up and running with django-brick-astley in minutes.

Installation

Install the package using pip:

pip install django-brick-astley

Configuration

Add brickastley to your INSTALLED_APPS in your Django settings:

INSTALLED_APPS = [
    # ... other apps
    "brickastley",
    # ... your apps
]

That’s it! The package will automatically discover bricks.py modules in all your installed apps and register them as template tags.

Creating Your First Brick

  1. Create a bricks.py file in one of your Django apps:

# myapp/bricks.py
from brickastley import Brick, register

@register
class Button(Brick):
    """A simple button component."""
    label: str
    variant: str = "primary"
    disabled: bool = False

  1. Create a template for your brick at myapp/templates/bricks/button.html:

<button class="btn btn-{{ variant }}"{% if disabled %} disabled{% endif %}>
    {{ label }}
</button>

  1. Use the brick in your templates:

{% load brickastley %}

{% button label="Click me" %}
{% button label="Secondary" variant="secondary" %}
{% button label="Disabled" disabled=True %}

Understanding Brick Names

By default, brick names are derived from the class name using snake_case conversion:

  • Button → {% button %}

  • MyFancyButton → {% my_fancy_button %}

  • AlertBox → {% alert_box %}

You can customize the name using the name parameter:

@register(name="btn")
class Button(Brick):
    label: str

Now use it as {% btn label="Click" %}.

Template Paths

By default, brick templates are located at bricks/<brick_name>.html. For example:

  • Button → bricks/button.html

  • AlertBox → bricks/alert_box.html

You can customize the template path:

@register
class Button(Brick):
    label: str
    template_name = "components/ui/button.html"

Required vs Optional Kwargs

Kwargs without default values are required:

@register
class Button(Brick):
    label: str        # Required - must be provided
    variant: str = "primary"  # Optional - defaults to "primary"
    size: str | None = None   # Optional - defaults to None

Using required kwargs without providing them raises an error:

{# This will raise BrickValidationError #}
{% button variant="secondary" %}

{# This works #}
{% button label="Click me" variant="secondary" %}

Block Bricks

Block bricks can wrap content. Use BlockBrick as your base class:

from brickastley import BlockBrick, register

@register
class Card(BlockBrick):
    title: str
    subtitle: str | None = None

Create the template with a {{ children }} variable:

{# bricks/card.html #}
<div class="card">
    <div class="card-header">
        <h2>{{ title }}</h2>
        {% if subtitle %}<h3>{{ subtitle }}</h3>{% endif %}
    </div>
    <div class="card-body">
        {{ children }}
    </div>
</div>

Use it with an end tag:

{% card title="Welcome" subtitle="Getting started" %}
    <p>This is the card content.</p>
    <p>You can include any HTML here.</p>
    {% button label="Learn more" %}
{% endcard %}

Next Steps