You can publish and share your components for others to use. Below you will find the steps to do so.
For live examples, see the Community examples.
Create a Django project with a similar structure:
project/
+ Authoring component libraries - Django-Components Authoring component libraries
You can publish and share your components for others to use. Below you will find the steps to do so.
For live examples, see the Community examples.
Writing component libraries¤
-
Create a Django project with a similar structure:
-
And, at last, you can use the components in your own project!
\ No newline at end of file
+In previous examples you could repeatedly see us using @register() to "register" the components. In this section we dive deeper into what it actually means and how you can manage (add or remove) components.
As a reminder, we may have a component like this:
from django_components import Component, register
+ Registering components - Django-Components Registering components
In previous examples you could repeatedly see us using @register() to "register" the components. In this section we dive deeper into what it actually means and how you can manage (add or remove) components.
As a reminder, we may have a component like this:
from django_components import Component, register
@register("calendar")
class Calendar(Component):
@@ -56,4 +56,4 @@
tag_formatter="django_components.component_formatter",
),
)
-
These settings are the same as the ones you can set for django_components.
In fact, when you set COMPONENT.tag_formatter or COMPONENT.context_behavior, these are forwarded to the default ComponentRegistry.
This makes it possible to have multiple registries with different settings in one projects, and makes sharing of component libraries possible.
\ No newline at end of file
+These settings are the same as the ones you can set for django_components.
In fact, when you set COMPONENT.tag_formatter or COMPONENT.context_behavior, these are forwarded to the default ComponentRegistry.
This makes it possible to have multiple registries with different settings in one projects, and makes sharing of component libraries possible.
New in version 0.131
Django-components functionality can be extended with "extensions". Extensions allow for powerful customization and integrations. They can:
Extensions are configured in the Django settings under COMPONENTS.extensions.
Extensions can be set by either as an import string or by passing in a class:
# settings.py
+ Extensions - Django-Components Extensions
New in version 0.131
Django-components functionality can be extended with "extensions". Extensions allow for powerful customization and integrations. They can:
- Tap into lifecycle events, such as when a component is created, deleted, registered, or unregistered.
- Add new attributes and methods to the components under an extension-specific nested class.
- Define custom commands that can be executed via the Django management command interface.
Setting up extensions¤
Extensions are configured in the Django settings under COMPONENTS.extensions.
Extensions can be set by either as an import string or by passing in a class:
\ No newline at end of file
+New in version 0.96
Component hooks are functions that allow you to intercept the rendering process at specific positions.
on_render_beforedef on_render_before(
+ Lifecycle hooks - Django-Components Lifecycle hooks
New in version 0.96
Component hooks are functions that allow you to intercept the rendering process at specific positions.
Available hooks¤
on_render_before
\ No newline at end of file
+Django-components provides a seamless integration with HTML fragments (HTML over the wire), whether you're using HTMX, AlpineJS, or vanilla JavaScript.
When you define a component that has extra JS or CSS, and you use django-components to render the fragment, django-components will:
Info
What are HTML fragments and "HTML over the wire"?
It is one of the methods for updating the state in the browser UI upon user interaction.
How it works is that:
Components support two modes of rendering - As a "document" or as a "fragment".
What's the difference?
Document mode assumes that the rendered components will be embedded into the HTML of the initial page load. This means that:
<script> and <style> tags (see JS and CSS output locations)A component is rendered as a "document" when:
{% component %}Component.render() or Component.render_to_response() with the type kwarg set to "document" (default)Example:
MyTable.render(
+ HTML fragments - Django-Components HTML fragments
Django-components provides a seamless integration with HTML fragments (HTML over the wire), whether you're using HTMX, AlpineJS, or vanilla JavaScript.
When you define a component that has extra JS or CSS, and you use django-components to render the fragment, django-components will:
- Automatically load the associated JS and CSS
- Ensure that JS is loaded and executed only once even if the fragment is inserted multiple times
Info
What are HTML fragments and "HTML over the wire"?
It is one of the methods for updating the state in the browser UI upon user interaction.
How it works is that:
- User makes an action - clicks a button or submits a form
- The action causes a request to be made from the client to the server.
- Server processes the request (e.g. form submission), and responds with HTML of some part of the UI (e.g. a new entry in a table).
- A library like HTMX, AlpineJS, or custom function inserts the new HTML into the correct place.
Document and fragment types¤
Components support two modes of rendering - As a "document" or as a "fragment".
What's the difference?
Document mode¤
Document mode assumes that the rendered components will be embedded into the HTML of the initial page load. This means that:
- The JS and CSS is embedded into the HTML as
<script> and <style> tags (see JS and CSS output locations) - Django-components injects a JS script for managing JS and CSS assets
A component is rendered as a "document" when:
- It is embedded inside a template as
{% component %} - It is rendered with
Component.render() or Component.render_to_response() with the type kwarg set to "document" (default)
Example:
\ No newline at end of file
+New in version 0.80:
Django components supports the provide / inject or ContextProvider pattern with the combination of:
{% provide %} taginject() method of the Component classProp drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
A neat solution to avoid prop drilling is using the "provide and inject" technique.
With provide / inject, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
This feature is inspired by Vue's Provide / Inject and React's Context / useContext.
As the name suggest, using provide / inject consists of 2 steps
For examples of advanced uses of provide / inject, see this discussion.
{% provide %} tag¤First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" key="hi" another=123 %}
+ Prop drilling and provide / inject - Django-Components Prop drilling and provide / inject
New in version 0.80:
Django components supports the provide / inject or ContextProvider pattern with the combination of:
{% provide %} taginject() method of the Component class
What is "prop drilling"?¤
Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
A neat solution to avoid prop drilling is using the "provide and inject" technique.
With provide / inject, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
This feature is inspired by Vue's Provide / Inject and React's Context / useContext.
How to use provide / inject¤
As the name suggest, using provide / inject consists of 2 steps
- Providing data
- Injecting provided data
For examples of advanced uses of provide / inject, see this discussion.
Using {% provide %} tag¤
First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" key="hi" another=123 %}
{% component "child" / %} <--- Can access "my_data"
{% endprovide %}
@@ -40,4 +40,4 @@
"""
renders:
\ No newline at end of file
+If:
ComponentDependencyMiddleware middlewareThen, by default, the components' JS and CSS will be automatically inserted into the HTML:
<head><body>If you want to place the dependencies elsewhere in the HTML, you can override the locations by inserting following Django template tags:
{% component_js_dependencies %} - Set new location(s) for JS scripts{% component_css_dependencies %} - Set new location(s) for CSS stylesSo if you have a component with JS and CSS:
from django_components import Component, types
+ Rendering JS / CSS - Django-Components Rendering JS / CSS
JS and CSS output locations¤
If:
- Your components use JS and CSS via any of:
- And you use the
ComponentDependencyMiddleware middleware
Then, by default, the components' JS and CSS will be automatically inserted into the HTML:
- CSS styles will be inserted at the end of the
<head> - JS scripts will be inserted at the end of the
<body>
If you want to place the dependencies elsewhere in the HTML, you can override the locations by inserting following Django template tags:
{% component_js_dependencies %} - Set new location(s) for JS scripts{% component_css_dependencies %} - Set new location(s) for CSS styles
So if you have a component with JS and CSS:
from django_components import Component, types
class MyButton(Component):
template: types.django_html = """
@@ -90,4 +90,4 @@
page = MyPage.render(
slots={"card": card},
)
-
Why is render_dependencies=False required?
This is a technical limitation of the current implementation.
As mentioned earlier, each time we call Component.render(), we also call render_dependencies().
However, there is a problem here - When we call render_dependencies() inside CardActions.render(), we extract and REMOVE the info on components' JS and CSS from the HTML. But the template of CardActions contains no {% component_depedencies %} tags, and nor <head> nor <body> HTML tags. So the component's JS and CSS will NOT be inserted, and will be lost.
To work around this, you must set render_dependencies=False when rendering pieces of HTML with Component.render() and inserting them into larger structures.
Summary¤
- Every time you render HTML that contained components, you have to call
render_dependencies() on the rendered output. - There are several ways to call
render_dependencies(): - Using the
ComponentDependencyMiddleware middleware - Rendering the HTML by calling
Component.render() with render_dependencies=True (default) - Rendering the HTML by calling
Component.render_to_response() (always renders dependencies) - Directly passing rendered HTML to
render_dependencies()
- If you pre-render one component to pass it into another, the pre-rendered component must be rendered with
render_dependencies=False.
\ No newline at end of file
+Why is render_dependencies=False required?
This is a technical limitation of the current implementation.
As mentioned earlier, each time we call Component.render(), we also call render_dependencies().
However, there is a problem here - When we call render_dependencies() inside CardActions.render(), we extract and REMOVE the info on components' JS and CSS from the HTML. But the template of CardActions contains no {% component_depedencies %} tags, and nor <head> nor <body> HTML tags. So the component's JS and CSS will NOT be inserted, and will be lost.
To work around this, you must set render_dependencies=False when rendering pieces of HTML with Component.render() and inserting them into larger structures.
render_dependencies() on the rendered output.render_dependencies():ComponentDependencyMiddleware middlewareComponent.render() with render_dependencies=True (default)Component.render_to_response() (always renders dependencies)render_dependencies()render_dependencies=False.New in version 0.89
By default, components are rendered using the pair of {% component %} / {% endcomponent %} template tags:
{% component "button" href="..." disabled %}
+ Tag formatters - Django-Components Tag formatters
Customizing component tags with TagFormatter¤
New in version 0.89
By default, components are rendered using the pair of {% component %} / {% endcomponent %} template tags:
{% component "button" href="..." disabled %}
Click me!
{% endcomponent %}
@@ -51,4 +51,4 @@
name, # e.g. 'button'
tokens # e.g. ['href="..."', 'disabled']
)
-
That's it! And once your TagFormatter is ready, don't forget to update the settings!
\ No newline at end of file
+That's it! And once your TagFormatter is ready, don't forget to update the settings!
Template tags introduced by django-components, such as {% component %} and {% slot %}, offer additional features over the default Django template tags:
Template tags introduced by django-components, such as {% component %} and {% slot %}, offer additional features over the default Django template tags:
{% mytag / %}:, - (and more) in keys...attr:key=valYou too can easily create custom template tags that use the above features.
@template_tag¤The simplest way to create a custom template tag is using the template_tag decorator. This decorator allows you to define a template tag by just writing a function that returns the rendered content.
You can unregister a node from a library using the unregister method:
This is particularly useful in testing when you want to clean up after registering temporary tags.
This is particularly useful in testing when you want to clean up after registering temporary tags.