Description

# Laces 👟 [](https://github.com/tbrlpld/laces/blob/main/LICENSE) [](https://pypi.org/project/laces/) [](https://github.com/tbrlpld/laces/actions/workflows/test.yml) [](https://codecov.io/gh/tbrlpld/laces) --- Django components that know how to render themselves. Laces components provide a simple way to combine data (in the form of Python objects) with the Django templates that are meant to render that data. The components can then be simply rendered in any other template using the `{% component %}` template tag. That parent template does not need to know anything about the component's template or data. No need to receive, filter, restructure or pass any data to the component's template. Just let the component render itself. Template and data are tied together (sorry, not sorry 😅) in the component, and they can be passed around together. This becomes especially useful when components are nested — it allows us to avoid building the same nested structure twice (once in the data and again in the templates). Working with objects that know how to render themselves as HTML elements is a common pattern found in complex Django applications, such as the [Wagtail](https://github.com/wagtail/wagtail) admin interface. The Wagtail admin is also where the APIs provided in this package have previously been discovered, developed and solidified. The purpose of this package is to make these tools available to other Django projects outside the Wagtail ecosystem. ## Links - [Getting started](#getting-started) - [Installation](#installation) - [Creating components](#creating-components) - [Passing context to the component template](#passing-context-to-the-component-template) - [Using components in other templates](#using-components-in-other-templates) - [Adding JavaScript and CSS assets to a component](#adding-javascript-and-css-assets-to-a-component) - [Patterns for using components](#patterns-for-using-components) - [Nesting components](#nesting-components) - [Nested groups of components](#nested-groups-of-components) - [Container components](#container-components) - [Using dataclasses](#using-dataclasses) - [About Laces](#about-laces) - [Contributing](#contributing) - [Changelog](https://github.com/tbrlpld/laces/blob/main/CHANGELOG.md) - [Discussions](https://github.com/tbrlpld/laces/discussions) - [Security](https://github.com/tbrlpld/laces/security) ## Getting started ### Installation First, install with pip: ```sh $ python -m pip install laces ``` Then, add to your installed apps: ```python # settings.py INSTALLED_APPS = ["laces", ...] ``` That's it. ### Creating components The simplest way to create a component is to define a subclass of `laces.components.Component` and specify a `template_name` attribute on it. ```python # my_app/components.py from laces.components import Component class WelcomePanel(Component): template_name = "my_app/components/welcome.html" ``` ```html+django {# my_app/templates/my_app/components/welcome.html #} <h1>Hello World!</h1> ``` With the above in place, you then instantiate the component (e.g., in a view) and pass it to another template for rendering. ```python # my_app/views.py from django.shortcuts import render from my_app.components import WelcomePanel def home(request): welcome = WelcomePanel() # <-- Instantiates the component return render( request, "my_app/home.html", {"welcome": welcome}, # <-- Passes the component to the view template ) ``` In the view template, we `load` the `laces` tag library and use the `{% component %}` tag to render the component. ```html+django {# my_app/templates/my_app/home.html #} {% load laces %} {% component welcome %} {# <-- Renders the component #} ``` That's it! The component's template will be rendered right there in the view template. Of course, this is a very simple example and not much more useful than using a simple `include`. We will go into some more useful use cases below. ### Without a template Before we dig deeper into the component use cases, just a quick note that components don't have to have a template. For simple cases that don't require a template, the `render_html` method can be overridden instead. If the return value contains HTML, it should be marked as safe using `django.utils.html.format_html` or `django.utils.safestring.mark_safe`. ```python # my_app/components.py from django.utils.html import format_html from laces.components import Component class WelcomePanel(Component): def render_html(self, parent_context=None): return format_html("<h1>Hello World!</h1>") ``` ### Passing context to the component template Now back to