Laces - Django UI Components

0.1.2 · active · verified Thu Apr 09

Laces is a Python library that provides a simple way to create self-rendering UI components for Django applications. It combines Python objects (data) with their corresponding Django templates, allowing components to be easily rendered in any parent template using a custom template tag. This approach helps in avoiding redundant data structuring and is particularly useful for nested components. The current version is 0.1.2, and releases occur semi-regularly, often driven by feature additions or bug fixes, with some significant gaps between versions.

Warnings

gotcha The `laces` library (PyPI package `laces`) is listed with a 'Development Status :: 3 - Alpha' classifier on PyPI. While it is used internally by Wagtail, this status technically implies that the API might not be fully stable and could undergo breaking changes in minor releases.
Fix: Refer to the GitHub changelog before upgrading to new minor versions for potential breaking changes. Test upgrades thoroughly.
gotcha You must explicitly add `'laces'` to your `INSTALLED_APPS` setting in Django for the component template tag and other features to be discovered and registered.
Fix: In your `settings.py`, add `INSTALLED_APPS = ['laces', ...]`.
gotcha The `{% component %}` template tag requires `{% load laces %}` at the top of any Django template where it is used.
Fix: Add `{% load laces %}` at the beginning of your Django template files that render Laces components.
deprecated For projects using Wagtail versions *prior* to 6.0, it is recommended to continue using Wagtail's native component imports (`wagtail.admin.ui.components` and `wagtail.admin.templatetags.wagtailadmin_tags`). While Laces components are now integrated into Wagtail 6.0+, using Laces directly in older Wagtail versions could lead to conflicts or unexpected behavior.
Fix: If on Wagtail < 6.0, continue using `wagtail.admin.ui.components.Component` and `{% load wagtailadmin_tags %}`. If migrating to Wagtail 6.0+, you can safely switch to or use `laces` imports interchangeably.

Install

pip install laces Install with pip

Imports

Component
```
from laces.components import Component
```
MediaContainer
```
from laces.components import MediaContainer
```
Useful for combining JavaScript and CSS assets from multiple components.

Quickstart

This quickstart demonstrates how to set up and render a basic Laces component within a Django project. It includes the necessary Django settings configuration, component definition, and template usage with the `{% component %}` tag.

import os
import django
from django.conf import settings
from django.template.backends.django import DjangoTemplates
from django.urls import path
from django.http import HttpResponse
from django.shortcuts import render

# Minimal Django setup (for demonstration purposes)
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
settings.configure(
    INSTALLED_APPS=[
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        'laces' # Crucial: add 'laces' to INSTALLED_APPS
    ],
    TEMPLATES=[
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [os.path.join(os.path.dirname(__file__), 'templates')],
            'APP_DIRS': True,
            'OPTIONS': {
                'context_processors': [
                    'django.template.context_processors.debug',
                    'django.template.context_processors.request',
                    'django.contrib.auth.context_processors.auth',
                    'django.contrib.messages.context_processors.messages',
                ],
            },
        },
    ],
    ROOT_URLCONF=__name__,
    DEBUG=True,
    SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-dev'),
    STATIC_URL='/static/'
)
django.setup()

# 1. Define your component
from laces.components import Component

class GreetingComponent(Component):
    template_name = "components/greeting_component.html"

    def get_context_data(self, parent_context=None):
        # You can access parent_context if rendering within another component/template
        return {"name": self.name, "greeting_message": f"Hello, {self.name}!"}

    def __init__(self, name="World", **kwargs):
        super().__init__(**kwargs)
        self.name = name

# 2. Create Django template files
# Save this as 'templates/components/greeting_component.html'
# <p>{{ greeting_message }}</p>

# Save this as 'templates/home.html'
# {% load laces %}
# <!DOCTYPE html>
# <html>
# <head><title>Laces Quickstart</title></head>
# <body>
#     <h1>Laces Example</h1>
#     {% component component_instance %}
#     {% component another_component_instance %}
# </body>
# </html>

# 3. Create a Django view
def home_view(request):
    component_1 = GreetingComponent(name="Alice")
    component_2 = GreetingComponent(name="Bob")
    return render(request, "home.html", {
        "component_instance": component_1,
        "another_component_instance": component_2
    })

# 4. Define URLs
urlpatterns = [
    path('', home_view, name='home'),
]

# To run this minimal example, you would typically save the templates
# and then run the Django development server.
# For an actual project:
# 1. Ensure 'templates/components/greeting_component.html' exists with content: <p>{{ greeting_message }}</p>
# 2. Ensure 'templates/home.html' exists with content as above.
# 3. Add 'laces' to INSTALLED_APPS in your project's settings.py.
# 4. Define your component in an app's components.py (e.g., myapp/components.py).
# 5. Use the component in a view and pass it to your template.

view raw JSON →