Component caching allows you to store the rendered output of a component. Next time the component is rendered with the same input, the cached output is returned instead of re-rendering the component.
This is particularly useful for components that are expensive to render or do not change frequently.
Info
Component caching uses Django's cache framework, so you can use any cache backend that is supported by Django.
Caching is disabled by default.
To enable caching for a component, set Component.Cache.enabled to True:
from django_components import Component
+ Component caching - Django-Components Component caching
Component caching allows you to store the rendered output of a component. Next time the component is rendered with the same input, the cached output is returned instead of re-rendering the component.
This is particularly useful for components that are expensive to render or do not change frequently.
Info
Component caching uses Django's cache framework, so you can use any cache backend that is supported by Django.
Enabling caching¤
Caching is disabled by default.
To enable caching for a component, set Component.Cache.enabled to True:
from django_components import Component
class MyComponent(Component):
class Cache:
diff --git a/dev/concepts/advanced/component_context_scope/index.html b/dev/concepts/advanced/component_context_scope/index.html
index 7afcebd5..c5041d86 100644
--- a/dev/concepts/advanced/component_context_scope/index.html
+++ b/dev/concepts/advanced/component_context_scope/index.html
@@ -1,4 +1,4 @@
- Component context and scope - Django-Components Component context and scope
By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
With this in mind, the {% component %} tag behaves similarly to {% include %} tag - inside the component tag, you can access all variables that were defined outside of it.
And just like with {% include %}, if you don't want a specific component template to have access to the parent context, add only to the {% component %} tag:
{% component "calendar" date="2015-06-19" only / %}
+ Component context and scope - Django-Components Component context and scope
By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
With this in mind, the {% component %} tag behaves similarly to {% include %} tag - inside the component tag, you can access all variables that were defined outside of it.
And just like with {% include %}, if you don't want a specific component template to have access to the parent context, add only to the {% component %} tag:
NOTE: {% csrf_token %} tags need access to the top-level context, and they will not function properly if they are rendered in a component that is called with the only modifier.
If you find yourself using the only modifier often, you can set the context_behavior option to "isolated", which automatically applies the only modifier. This is useful if you want to make sure that components don't accidentally access the outer context.
Components can also access the outer context in their context methods like get_template_data by accessing the property self.outer_context.
Example of Accessing Outer Context¤
<div>
{% component "calender" / %}
</div>
diff --git a/dev/concepts/advanced/component_libraries/index.html b/dev/concepts/advanced/component_libraries/index.html
index fe43dc78..d9c37658 100644
--- a/dev/concepts/advanced/component_libraries/index.html
+++ b/dev/concepts/advanced/component_libraries/index.html
@@ -1,4 +1,4 @@
- Component libraries - Django-Components 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:
project/
+ Component libraries - Django-Components 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:
project/
|-- myapp/
|-- __init__.py
|-- apps.py
diff --git a/dev/concepts/advanced/component_registry/index.html b/dev/concepts/advanced/component_registry/index.html
index e6c874cf..7a251bc8 100644
--- a/dev/concepts/advanced/component_registry/index.html
+++ b/dev/concepts/advanced/component_registry/index.html
@@ -1,4 +1,4 @@
- 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
+ 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):
diff --git a/dev/concepts/advanced/extensions/index.html b/dev/concepts/advanced/extensions/index.html
index a765da56..715210d6 100644
--- a/dev/concepts/advanced/extensions/index.html
+++ b/dev/concepts/advanced/extensions/index.html
@@ -1,4 +1,4 @@
- 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.
Live examples¤
Install 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:
# 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.
Live examples¤
Install 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:
# settings.py
class MyExtension(ComponentExtension):
name = "my_extension"
diff --git a/dev/concepts/advanced/hooks/index.html b/dev/concepts/advanced/hooks/index.html
index 648a3612..c58ccf96 100644
--- a/dev/concepts/advanced/hooks/index.html
+++ b/dev/concepts/advanced/hooks/index.html
@@ -1,4 +1,4 @@
- Lifecycle hooks - Django-Components Lifecycle hooks
New in version 0.96
Intercept the rendering lifecycle with Component hooks.
Unlike the extension hooks, these are defined directly on the Component class.
Available hooks¤
on_render_before¤
def on_render_before(
+ Lifecycle hooks - Django-Components Lifecycle hooks
New in version 0.96
Intercept the rendering lifecycle with Component hooks.
Unlike the extension hooks, these are defined directly on the Component class.
Available hooks¤
on_render_before¤
def on_render_before(
self: Component,
context: Context,
template: Optional[Template],
diff --git a/dev/concepts/advanced/html_fragments/index.html b/dev/concepts/advanced/html_fragments/index.html
index e00c72ed..64948a92 100644
--- a/dev/concepts/advanced/html_fragments/index.html
+++ b/dev/concepts/advanced/html_fragments/index.html
@@ -1,4 +1,4 @@
- HTML fragments - Django-Components HTML fragments
Django-components provides a seamless integration with HTML fragments with AJAX (HTML over the wire), whether you're using jQuery, HTMX, AlpineJS, vanilla JavaScript, or other.
If the fragment component has any JS or CSS, 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 strategies¤
Components support different "strategies" for rendering JS and CSS.
Two of them are used to enable HTML fragments - "document" and "fragment".
What's the difference?
Document strategy¤
Document strategy 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 Default JS / CSS 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 deps_strategy kwarg set to "document" (default)
Example:
MyTable.render(
+ HTML fragments - Django-Components HTML fragments
Django-components provides a seamless integration with HTML fragments with AJAX (HTML over the wire), whether you're using jQuery, HTMX, AlpineJS, vanilla JavaScript, or other.
If the fragment component has any JS or CSS, 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 strategies¤
Components support different "strategies" for rendering JS and CSS.
Two of them are used to enable HTML fragments - "document" and "fragment".
What's the difference?
Document strategy¤
Document strategy 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 Default JS / CSS 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 deps_strategy kwarg set to "document" (default)
Example:
MyTable.render(
kwargs={...},
)
diff --git a/dev/concepts/advanced/provide_inject/index.html b/dev/concepts/advanced/provide_inject/index.html
index 6c89417a..120f2155 100644
--- a/dev/concepts/advanced/provide_inject/index.html
+++ b/dev/concepts/advanced/provide_inject/index.html
@@ -1,4 +1,4 @@
- Prop drilling and provide / inject - Django-Components Prop drilling and provide / inject
New in version 0.80:
django-components supports the provide / inject pattern, similarly to React's Context Providers or Vue's provide / inject.
This is achieved with the combination of:
{% provide %} tagComponent.inject() method
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.
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.
Providing data¤
First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" hello="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 pattern, similarly to React's Context Providers or Vue's provide / inject.
This is achieved with the combination of:
{% provide %} tagComponent.inject() method
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.
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.
Providing data¤
First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" hello="hi" another=123 %}
{% component "child" / %} <--- Can access "my_data"
{% endprovide %}
diff --git a/dev/concepts/advanced/rendering_js_css/index.html b/dev/concepts/advanced/rendering_js_css/index.html
index 7e8c3f48..ca68ac6f 100644
--- a/dev/concepts/advanced/rendering_js_css/index.html
+++ b/dev/concepts/advanced/rendering_js_css/index.html
@@ -1,4 +1,4 @@
- Rendering JS / CSS - Django-Components Rendering JS / CSS
Introduction¤
Components consist of 3 parts - HTML, JS and CSS.
Handling of HTML is straightforward - it is rendered as is, and inserted where the {% component %} tag is.
However, handling of JS and CSS is more complex:
- JS and CSS is are inserted elsewhere in the HTML. As a best practice, JS is placed in the
<body> HTML tag, and CSS in the <head>. - Multiple components may use the same JS and CSS files. We don't want to load the same files multiple times.
- Fetching of JS and CSS may block the page, so the JS / CSS should be embedded in the HTML.
- Components inserted as HTML fragments need different handling for JS and CSS.
Default JS / CSS locations¤
If your components use JS and CSS then, by default, the 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
+ Rendering JS / CSS - Django-Components Rendering JS / CSS
Introduction¤
Components consist of 3 parts - HTML, JS and CSS.
Handling of HTML is straightforward - it is rendered as is, and inserted where the {% component %} tag is.
However, handling of JS and CSS is more complex:
- JS and CSS is are inserted elsewhere in the HTML. As a best practice, JS is placed in the
<body> HTML tag, and CSS in the <head>. - Multiple components may use the same JS and CSS files. We don't want to load the same files multiple times.
- Fetching of JS and CSS may block the page, so the JS / CSS should be embedded in the HTML.
- Components inserted as HTML fragments need different handling for JS and CSS.
Default JS / CSS locations¤
If your components use JS and CSS then, by default, the 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 = """
diff --git a/dev/concepts/advanced/tag_formatters/index.html b/dev/concepts/advanced/tag_formatters/index.html
index a65221a9..ae472bbd 100644
--- a/dev/concepts/advanced/tag_formatters/index.html
+++ b/dev/concepts/advanced/tag_formatters/index.html
@@ -1,4 +1,4 @@
- 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 %}
+ 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 %}
diff --git a/dev/concepts/advanced/template_tags/index.html b/dev/concepts/advanced/template_tags/index.html
index caaf8d69..ed02f2af 100644
--- a/dev/concepts/advanced/template_tags/index.html
+++ b/dev/concepts/advanced/template_tags/index.html
@@ -1,4 +1,4 @@
- Custom template tags - Django-Components Custom template tags
Template tags introduced by django-components, such as {% component %} and {% slot %}, offer additional features over the default Django template tags:
django-components/django-components Custom template tags
Template tags introduced by django-components, such as {% component %} and {% slot %}, offer additional features over the default Django template tags:
- Self-closing tags
{% mytag / %} - Allowing the use of
:, - (and more) in keys - Spread operator
... - Using template tags as inputs to other template tags
- Flat definition of dictionaries
attr:key=val - Function-like input validation
You too can easily create custom template tags that use the above features.
Defining template tags with @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.
from django.template import Context, Library
diff --git a/dev/concepts/advanced/testing/index.html b/dev/concepts/advanced/testing/index.html
index 9a5fd552..79067eec 100644
--- a/dev/concepts/advanced/testing/index.html
+++ b/dev/concepts/advanced/testing/index.html
@@ -1,4 +1,4 @@
- Testing - Django-Components Testing
New in version 0.131
The @djc_test decorator is a powerful tool for testing components created with django-components. It ensures that each test is properly isolated, preventing components registered in one test from affecting others.
Usage¤
The @djc_test decorator can be applied to functions, methods, or classes.
When applied to a class, it decorates all methods starting with test_, and all nested classes starting with Test, recursively.
Applying to a Function¤
To apply djc_test to a function, simply decorate the function as shown below:
import django
+ Testing - Django-Components Testing
New in version 0.131
The @djc_test decorator is a powerful tool for testing components created with django-components. It ensures that each test is properly isolated, preventing components registered in one test from affecting others.
Usage¤
The @djc_test decorator can be applied to functions, methods, or classes.
When applied to a class, it decorates all methods starting with test_, and all nested classes starting with Test, recursively.
Applying to a Function¤
To apply djc_test to a function, simply decorate the function as shown below:
import django
from django_components.testing import djc_test
@djc_test
diff --git a/dev/concepts/fundamentals/autodiscovery/index.html b/dev/concepts/fundamentals/autodiscovery/index.html
index fa21a07d..2edaa14d 100644
--- a/dev/concepts/fundamentals/autodiscovery/index.html
+++ b/dev/concepts/fundamentals/autodiscovery/index.html
@@ -1,4 +1,4 @@
- Autodiscovery - Django-Components Autodiscovery
django-components automatically searches for files containing components in the COMPONENTS.dirs and COMPONENTS.app_dirs directories.
Manually register components¤
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry.
We use the @register decorator for that:
from django_components import Component, register
+ Autodiscovery - Django-Components Autodiscovery
django-components automatically searches for files containing components in the COMPONENTS.dirs and COMPONENTS.app_dirs directories.
Manually register components¤
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry.
We use the @register decorator for that:
from django_components import Component, register
@register("calendar")
class Calendar(Component):
diff --git a/dev/concepts/fundamentals/component_defaults/index.html b/dev/concepts/fundamentals/component_defaults/index.html
index e85b9631..50158b6f 100644
--- a/dev/concepts/fundamentals/component_defaults/index.html
+++ b/dev/concepts/fundamentals/component_defaults/index.html
@@ -1,4 +1,4 @@
- Component defaults - Django-Components Component defaults
When a component is being rendered, the component inputs are passed to various methods like get_template_data(), get_js_data(), or get_css_data().
It can be cumbersome to specify default values for each input in each method.
To make things easier, Components can specify their defaults. Defaults are used when no value is provided, or when the value is set to None for a particular input.
Defining defaults¤
To define defaults for a component, you create a nested Defaults class within your Component class. Each attribute in the Defaults class represents a default value for a corresponding input.
from django_components import Component, Default, register
+ Component defaults - Django-Components Component defaults
When a component is being rendered, the component inputs are passed to various methods like get_template_data(), get_js_data(), or get_css_data().
It can be cumbersome to specify default values for each input in each method.
To make things easier, Components can specify their defaults. Defaults are used when no value is provided, or when the value is set to None for a particular input.
Defining defaults¤
To define defaults for a component, you create a nested Defaults class within your Component class. Each attribute in the Defaults class represents a default value for a corresponding input.
from django_components import Component, Default, register
@register("my_table")
class MyTable(Component):
diff --git a/dev/concepts/fundamentals/component_views_urls/index.html b/dev/concepts/fundamentals/component_views_urls/index.html
index fa42d8dc..83197506 100644
--- a/dev/concepts/fundamentals/component_views_urls/index.html
+++ b/dev/concepts/fundamentals/component_views_urls/index.html
@@ -1,4 +1,4 @@
- Component views and URLs - Django-Components Component views and URLs
New in version 0.34
Note: Since 0.92, Component is no longer a subclass of Django's View. Instead, the nested Component.View class is a subclass of Django's View.
For web applications, it's common to define endpoints that serve HTML content (AKA views).
django-components has a suite of features that help you write and manage views and their URLs:
-
For each component, you can define methods for handling HTTP requests (GET, POST, etc.) - get(), post(), etc.
-
Use Component.as_view() to be able to use your Components with Django's urlpatterns. This works the same way as View.as_view().
-
To avoid having to manually define the endpoints for each component, you can set the component to be "public" with Component.View.public = True. This will automatically create a URL for the component. To retrieve the component URL, use get_component_url().
-
In addition, Component has a render_to_response() method that renders the component template based on the provided input and returns an HttpResponse object.
Define handlers¤
Here's an example of a calendar component defined as a view. Simply define a View class with your custom get() method to handle GET requests:
[project root]/components/calendar.pyfrom django_components import Component, ComponentView, register
+ Component views and URLs - Django-Components Component views and URLs
New in version 0.34
Note: Since 0.92, Component is no longer a subclass of Django's View. Instead, the nested Component.View class is a subclass of Django's View.
For web applications, it's common to define endpoints that serve HTML content (AKA views).
django-components has a suite of features that help you write and manage views and their URLs:
-
For each component, you can define methods for handling HTTP requests (GET, POST, etc.) - get(), post(), etc.
-
Use Component.as_view() to be able to use your Components with Django's urlpatterns. This works the same way as View.as_view().
-
To avoid having to manually define the endpoints for each component, you can set the component to be "public" with Component.View.public = True. This will automatically create a URL for the component. To retrieve the component URL, use get_component_url().
-
In addition, Component has a render_to_response() method that renders the component template based on the provided input and returns an HttpResponse object.
Define handlers¤
Here's an example of a calendar component defined as a view. Simply define a View class with your custom get() method to handle GET requests:
[project root]/components/calendar.pyfrom django_components import Component, ComponentView, register
@register("calendar")
class Calendar(Component):
diff --git a/dev/concepts/fundamentals/html_attributes/index.html b/dev/concepts/fundamentals/html_attributes/index.html
index 7aff3fe7..6fb5f630 100644
--- a/dev/concepts/fundamentals/html_attributes/index.html
+++ b/dev/concepts/fundamentals/html_attributes/index.html
@@ -1,4 +1,4 @@
- HTML attributes - Django-Components