You can publish and share your components for others to use. Here are the steps to do so:
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. Here are the steps to do so:
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):
@@ -53,4 +53,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.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(
+ kwargs={...},
+)
+
+# or
+
+MyTable.render(
+ kwargs={...},
+ type="document",
+)
+Fragment mode assumes that the main HTML has already been rendered and loaded on the page. The component renders HTML that will be inserted into the page as a fragment, at a LATER time:
{% component_js_dependencies %} inside of fragments are ignored.<script> to trigger a call to its asset manager JS script, which will load the JS and CSS smartly.A component is rendered as "fragment" when:
Component.render() or Component.render_to_response() with the type kwarg set to "fragment"Example:
For live interactive examples, start our demo project (sampleproject).
Then navigate to these URLs:
/fragment/base/alpine/fragment/base/htmx/fragment/base/jsfrom django_components import Component, types
+
+# HTML into which a fragment will be loaded using HTMX
+class MyPage(Component):
+ def get(self, request):
+ return self.render_to_response()
+
+ template = """
+ {% load component_tags %}
+ <!DOCTYPE html>
+ <html>
+ <head>
+ {% component_css_dependencies %}
+ <script src="https://unpkg.com/htmx.org@1.9.12"></script>
+ </head>
+ <body>
+ <div id="target">OLD</div>
+
+ <button
+ hx-get="/mypage/frag"
+ hx-swap="outerHTML"
+ hx-target="#target"
+ >
+ Click me!
+ </button>
+
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
+class Frag(Component):
+ def get(self, request):
+ return self.render_to_response(
+ # IMPORTANT: Don't forget `type="fragment"`
+ type="fragment",
+ )
+
+ template = """
+ <div class="frag">
+ 123
+ <span id="frag-text"></span>
+ </div>
+ """
+
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+from django.urls import path
+
+from components.demo import MyPage, Frag
+
+urlpatterns = [
+ path("mypage/", MyPage.as_view())
+ path("mypage/frag", Frag.as_view()),
+]
+from django_components import Component, types
+
+# HTML into which a fragment will be loaded using AlpineJS
+class MyPage(Component):
+ def get(self, request):
+ return self.render_to_response()
+
+ template = """
+ {% load component_tags %}
+ <!DOCTYPE html>
+ <html>
+ <head>
+ {% component_css_dependencies %}
+ <script defer src="https://unpkg.com/alpinejs"></script>
+ </head>
+ <body x-data="{
+ htmlVar: 'OLD',
+ loadFragment: function () {
+ const url = '/mypage/frag';
+ fetch(url)
+ .then(response => response.text())
+ .then(html => {
+ this.htmlVar = html;
+ });
+ }
+ }">
+ <div id="target" x-html="htmlVar">OLD</div>
+
+ <button @click="loadFragment">
+ Click me!
+ </button>
+
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
+class Frag(Component):
+ def get(self, request):
+ # IMPORTANT: Don't forget `type="fragment"`
+ return self.render_to_response(
+ type="fragment",
+ )
+
+ # NOTE: We wrap the actual fragment in a template tag with x-if="false" to prevent it
+ # from being rendered until we have registered the component with AlpineJS.
+ template = """
+ <template x-if="false" data-name="frag">
+ <div class="frag">
+ 123
+ <span x-data="frag" x-text="fragVal">
+ </span>
+ </div>
+ </template>
+ """
+
+ js = """
+ Alpine.data('frag', () => ({
+ fragVal: 'xxx',
+ }));
+
+ // Now that the component has been defined in AlpineJS, we can "activate"
+ // all instances where we use the `x-data="frag"` directive.
+ document.querySelectorAll('[data-name="frag"]').forEach((el) => {
+ el.setAttribute('x-if', 'true');
+ });
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+from django.urls import path
+
+from components.demo import MyPage, Frag
+
+urlpatterns = [
+ path("mypage/", MyPage.as_view())
+ path("mypage/frag", Frag.as_view()),
+]
+from django_components import Component, types
+
+# HTML into which a fragment will be loaded using JS
+class MyPage(Component):
+ def get(self, request):
+ return self.render_to_response()
+
+ template = """
+ {% load component_tags %}
+ <!DOCTYPE html>
+ <html>
+ <head>
+ {% component_css_dependencies %}
+ </head>
+ <body>
+ <div id="target">OLD</div>
+
+ <button>
+ Click me!
+ </button>
+ <script>
+ const url = `/mypage/frag`;
+ document.querySelector('#loader').addEventListener('click', function () {
+ fetch(url)
+ .then(response => response.text())
+ .then(html => {
+ document.querySelector('#target').outerHTML = html;
+ });
+ });
+ </script>
+
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
+class Frag(Component):
+ def get(self, request):
+ return self.render_to_response(
+ # IMPORTANT: Don't forget `type="fragment"`
+ type="fragment",
+ )
+
+ template = """
+ <div class="frag">
+ 123
+ <span id="frag-text"></span>
+ </div>
+ """
+
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+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!
New in version 0.92
The Component class optionally accepts type parameters that allow you to specify the types of args, kwargs, slots, and data:
class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
+ Typing and validation - Django-Components Typing and validation
Adding type hints with Generics¤
New in version 0.92
The Component class optionally accepts type parameters that allow you to specify the types of args, kwargs, slots, and data:
Args - Must be a Tuple or AnyKwargs - Must be a TypedDict or AnyData - Must be a TypedDict or AnySlots - Must be a TypedDict or Any
Here's a full example:
Or you can replace Args with Any altogether, to skip the validation of args:
# Replaced `Args` with `Any`
class Button(Component[Any, Kwargs, Slots, Data, JsData, CssData]):
...
-
Same applies to kwargs, data, and slots.
\ No newline at end of file
+Same applies to kwargs, data, and slots.
When you call Component.render or Component.render_to_response, the inputs to these methods can be accessed from within the instance under self.input.
This means that you can use self.input inside:
get_context_dataget_template_nameget_templateon_render_beforeon_render_afterself.input is only defined during the execution of Component.render, and raises a RuntimeError when called outside of this context.
self.input has the same fields as the input to Component.render:
class TestComponent(Component):
+ Accessing component inputs - Django-Components Accessing component inputs
When you call Component.render or Component.render_to_response, the inputs to these methods can be accessed from within the instance under self.input.
This means that you can use self.input inside:
get_context_dataget_template_nameget_templateon_render_beforeon_render_after
self.input is only defined during the execution of Component.render, and raises a RuntimeError when called outside of this context.
self.input has the same fields as the input to Component.render:
class TestComponent(Component):
def get_context_data(self, var1, var2, variable, another, **attrs):
assert self.input.args == (123, "str")
assert self.input.kwargs == {"variable": "test", "another": 1}
diff --git a/dev/concepts/fundamentals/autodiscovery/index.html b/dev/concepts/fundamentals/autodiscovery/index.html
index 60dfddc4..3b806446 100644
--- a/dev/concepts/fundamentals/autodiscovery/index.html
+++ b/dev/concepts/fundamentals/autodiscovery/index.html
@@ -1,4 +1,4 @@
- Autodiscovery - Django-Components Autodiscovery
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry. Normally, we use the @register decorator for that:
from django_components import Component, register
+ Autodiscovery - Django-Components Autodiscovery
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry. Normally, 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_context_scope/index.html b/dev/concepts/fundamentals/component_context_scope/index.html
index 996f1243..8d9b06af 100644
--- a/dev/concepts/fundamentals/component_context_scope/index.html
+++ b/dev/concepts/fundamentals/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_context_data by accessing the property self.outer_context.
Example of Accessing Outer Context¤
<div>
{% component "calender" / %}
</div>
diff --git a/dev/concepts/fundamentals/components_as_views/index.html b/dev/concepts/fundamentals/components_as_views/index.html
index 38de9ba5..02eb0922 100644
--- a/dev/concepts/fundamentals/components_as_views/index.html
+++ b/dev/concepts/fundamentals/components_as_views/index.html
@@ -1,4 +1,4 @@
- Components as views - Django-Components Components as views
New in version 0.34
Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested Component.View class
Components can now be used as views:
-
Components define the Component.as_view() class method that can be used the same as View.as_view().
-
By default, you can define GET, POST or other HTTP handlers directly on the Component, same as you do with View. For example, you can override get and post to handle GET and POST requests, respectively.
-
In addition, Component now has a render_to_response method that renders the component template based on the provided context and slots' data and returns an HttpResponse object.
Component as view example¤
Here's an example of a calendar component defined as a view:
# In a file called [project root]/components/calendar.py
+ Components as views - Django-Components Components as views
New in version 0.34
Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested Component.View class
Components can now be used as views:
-
Components define the Component.as_view() class method that can be used the same as View.as_view().
-
By default, you can define GET, POST or other HTTP handlers directly on the Component, same as you do with View. For example, you can override get and post to handle GET and POST requests, respectively.
-
In addition, Component now has a render_to_response method that renders the component template based on the provided context and slots' data and returns an HttpResponse object.
Component as view example¤
Here's an example of a calendar component defined as a view:
# In a file called [project root]/components/calendar.py
from django_components import Component, ComponentView, register
@register("calendar")
diff --git a/dev/concepts/fundamentals/components_in_python/index.html b/dev/concepts/fundamentals/components_in_python/index.html
index 72683cd2..c9cadd2e 100644
--- a/dev/concepts/fundamentals/components_in_python/index.html
+++ b/dev/concepts/fundamentals/components_in_python/index.html
@@ -1,4 +1,4 @@
- Components in Python - Django-Components Components in Python
New in version 0.81
Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
The component class defines render and render_to_response class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the {% component %} tag:
class SimpleComponent(Component):
+ Components in Python - Django-Components Components in Python
New in version 0.81
Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
The component class defines render and render_to_response class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the {% component %} tag:
class SimpleComponent(Component):
template = """
{% load component_tags %}
hello: {{ hello }}
diff --git a/dev/concepts/fundamentals/defining_js_css_html_files/index.html b/dev/concepts/fundamentals/defining_js_css_html_files/index.html
index 4c06a727..ed96c3ee 100644
--- a/dev/concepts/fundamentals/defining_js_css_html_files/index.html
+++ b/dev/concepts/fundamentals/defining_js_css_html_files/index.html
@@ -1,4 +1,4 @@
- Defining HTML / JS / CSS files - Django-Components Defining HTML / JS / CSS files
django_component's management of files builds on top of Django's Media class.
To be familiar with how Django handles static files, we recommend reading also:
Defining file paths relative to component or static dirs¤
As seen in the getting started example, to associate HTML/JS/CSS files with a component, you set them as template_name, Media.js and Media.css respectively:
# In a file [project root]/components/calendar/calendar.py
+ Defining HTML / JS / CSS files - Django-Components Defining HTML / JS / CSS files
django_component's management of files builds on top of Django's Media class.
To be familiar with how Django handles static files, we recommend reading also:
Defining file paths relative to component or static dirs¤
As seen in the getting started example, to associate HTML/JS/CSS files with a component, you set them as template_name, Media.js and Media.css respectively:
# In a file [project root]/components/calendar/calendar.py
from django_components import Component, register
@register("calendar")
diff --git a/dev/concepts/fundamentals/html_attributes/index.html b/dev/concepts/fundamentals/html_attributes/index.html
index 119abfe5..19e03f17 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 HTML attributes
New in version 0.74:
You can use the html_attrs tag to render HTML attributes, given a dictionary of values.
So if you have a template:
<div class="{{ classes }}" data-id="{{ my_id }}">
+ HTML attributes - Django-Components HTML attributes
New in version 0.74:
You can use the html_attrs tag to render HTML attributes, given a dictionary of values.
So if you have a template:
You can simplify it with html_attrs tag:
<div {% html_attrs attrs %}>
</div>
diff --git a/dev/concepts/fundamentals/single_file_components/index.html b/dev/concepts/fundamentals/single_file_components/index.html
index b05857bd..931dd81c 100644
--- a/dev/concepts/fundamentals/single_file_components/index.html
+++ b/dev/concepts/fundamentals/single_file_components/index.html
@@ -1,4 +1,4 @@
- Single-file components - Django-Components Single-file components
Components can also be defined in a single file, which is useful for small components. To do this, you can use the template, js, and css class attributes instead of the template_name and Media. For example, here's the calendar component from above, defined in a single file:
[project root]/components/calendar.py# In a file called [project root]/components/calendar.py
+ Single-file components - Django-Components Single-file components
Components can also be defined in a single file, which is useful for small components. To do this, you can use the template, js, and css class attributes instead of the template_name and Media. For example, here's the calendar component from above, defined in a single file:
[project root]/components/calendar.py# In a file called [project root]/components/calendar.py
from django_components import Component, register, types
@register("calendar")
diff --git a/dev/concepts/fundamentals/slots/index.html b/dev/concepts/fundamentals/slots/index.html
index bcbd6327..20d2e78a 100644
--- a/dev/concepts/fundamentals/slots/index.html
+++ b/dev/concepts/fundamentals/slots/index.html
@@ -1,4 +1,4 @@
- Slots - Django-Components Slots
New in version 0.26:
- The
slot tag now serves only to declare new slots inside the component template. - To override the content of a declared slot, use the newly introduced
fill tag instead. - Whereas unfilled slots used to raise a warning, filling a slot is now optional by default.
- To indicate that a slot must be filled, the new
required option should be added at the end of the slot tag.
Components support something called 'slots'. When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content. This mechanism makes components more reusable and composable. This behavior is similar to slots in Vue.
In the example below we introduce two block tags that work hand in hand to make this work. These are...
{% slot <name> %}/{% endslot %}: Declares a new slot in the component template.{% fill <name> %}/{% endfill %}: (Used inside a {% component %} tag pair.) Fills a declared slot with the specified content.
Let's update our calendar component to support more customization. We'll add slot tag pairs to its template, template.html.
<div class="calendar-component">
+ Slots - Django-Components Slots
New in version 0.26:
- The
slot tag now serves only to declare new slots inside the component template. - To override the content of a declared slot, use the newly introduced
fill tag instead. - Whereas unfilled slots used to raise a warning, filling a slot is now optional by default.
- To indicate that a slot must be filled, the new
required option should be added at the end of the slot tag.
Components support something called 'slots'. When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content. This mechanism makes components more reusable and composable. This behavior is similar to slots in Vue.
In the example below we introduce two block tags that work hand in hand to make this work. These are...
{% slot <name> %}/{% endslot %}: Declares a new slot in the component template.{% fill <name> %}/{% endfill %}: (Used inside a {% component %} tag pair.) Fills a declared slot with the specified content.
Let's update our calendar component to support more customization. We'll add slot tag pairs to its template, template.html.
<div class="calendar-component">
<div class="header">
{% slot "header" %}Calendar header{% endslot %}
</div>
diff --git a/dev/concepts/fundamentals/template_tag_syntax/index.html b/dev/concepts/fundamentals/template_tag_syntax/index.html
index 49c0559d..4d76996b 100644
--- a/dev/concepts/fundamentals/template_tag_syntax/index.html
+++ b/dev/concepts/fundamentals/template_tag_syntax/index.html
@@ -1,4 +1,4 @@
- Template tag syntax - Django-Components Template tag syntax
All template tags in django_component, like {% component %} or {% slot %}, and so on, support extra syntax that makes it possible to write components like in Vue or React (JSX).
Self-closing tags¤
When you have a tag like {% component %} or {% slot %}, but it has no content, you can simply append a forward slash / at the end, instead of writing out the closing tags like {% endcomponent %} or {% endslot %}:
So this:
{% component "button" %}{% endcomponent %}
+ Template tag syntax - Django-Components Template tag syntax
All template tags in django_component, like {% component %} or {% slot %}, and so on, support extra syntax that makes it possible to write components like in Vue or React (JSX).
Self-closing tags¤
When you have a tag like {% component %} or {% slot %}, but it has no content, you can simply append a forward slash / at the end, instead of writing out the closing tags like {% endcomponent %} or {% endslot %}:
So this:
becomes
Special characters¤
New in version 0.71:
Keyword arguments can contain special characters # @ . - _, so keywords like so are still valid:
<body>
{% component "calendar" my-date="2015-06-19" @click.native=do_something #some_id=True / %}
diff --git a/dev/concepts/getting_started/adding_js_and_css/index.html b/dev/concepts/getting_started/adding_js_and_css/index.html
index bc427017..466c11ba 100644
--- a/dev/concepts/getting_started/adding_js_and_css/index.html
+++ b/dev/concepts/getting_started/adding_js_and_css/index.html
@@ -1,4 +1,4 @@
- Adding JS and CSS - Django-Components Adding JS and CSS
Next we will add CSS and JavaScript to our template.
Info
In django-components, using JS and CSS is as simple as defining them on the Component class. You don't have to insert the <script> and <link> tags into the HTML manually.
Behind the scenes, django-components keeps track of which components use which JS and CSS files. Thus, when a component is rendered on the page, the page will contain only the JS and CSS used by the components, and nothing more!
1. Update project structure¤
Start by creating empty calendar.js and calendar.css files:
sampleproject/
+ Adding JS and CSS - Django-Components Adding JS and CSS
Next we will add CSS and JavaScript to our template.
Info
In django-components, using JS and CSS is as simple as defining them on the Component class. You don't have to insert the <script> and <link> tags into the HTML manually.
Behind the scenes, django-components keeps track of which components use which JS and CSS files. Thus, when a component is rendered on the page, the page will contain only the JS and CSS used by the components, and nothing more!
1. Update project structure¤
Start by creating empty calendar.js and calendar.css files:
sampleproject/
├── calendarapp/
├── components/
│ └── calendar/
diff --git a/dev/concepts/getting_started/adding_slots/index.html b/dev/concepts/getting_started/adding_slots/index.html
index bbb4e0e5..1d31966f 100644
--- a/dev/concepts/getting_started/adding_slots/index.html
+++ b/dev/concepts/getting_started/adding_slots/index.html
@@ -1,4 +1,4 @@
- Adding slots - Django-Components Adding slots
Our calendar component's looking great! But we just got a new assignment from our colleague - The calendar date needs to be shown on 3 different pages:
- On one page, it needs to be shown as is
- On the second, the date needs to be bold
- On the third, the date needs to be in italics
As a reminder, this is what the component's template looks like:
<div class="calendar">
+ Adding slots - Django-Components Adding slots
Our calendar component's looking great! But we just got a new assignment from our colleague - The calendar date needs to be shown on 3 different pages:
- On one page, it needs to be shown as is
- On the second, the date needs to be bold
- On the third, the date needs to be in italics
As a reminder, this is what the component's template looks like:
There's many ways we could approach this:
- Expose the date in a slot
- Style
.calendar > span differently on different pages - Pass a variable to the component that decides how the date is rendered
- Create a new component
First two options are more flexible, because the custom styling is not baked into a component's implementation. And for the sake of demonstration, we'll solve this challenge with slots.
1. What are slots¤
Components support something called Slots.
When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content.
This mechanism makes components more reusable and composable.
This behavior is similar to slots in Vue.
In the example below we introduce two tags that work hand in hand to make this work. These are...
{% slot <name> %}/{% endslot %}: Declares a new slot in the component template.{% fill <name> %}/{% endfill %}: (Used inside a {% component %} tag pair.) Fills a declared slot with the specified content.
2. Add a slot tag¤
Let's update our calendar component to support more customization. We'll add {% slot %} tag to the template:
<div class="calendar">
diff --git a/dev/concepts/getting_started/components_in_templates/index.html b/dev/concepts/getting_started/components_in_templates/index.html
index 5926110b..9429ab75 100644
--- a/dev/concepts/getting_started/components_in_templates/index.html
+++ b/dev/concepts/getting_started/components_in_templates/index.html
@@ -1,4 +1,4 @@
- Components in templates - Django-Components Components in templates
By the end of this section, we want to be able to use our components in Django templates like so:
{% load component_tags %}
+ Components in templates - Django-Components Components in templates
By the end of this section, we want to be able to use our components in Django templates like so:
{% load component_tags %}
<!DOCTYPE html>
<html>
<head>
diff --git a/dev/concepts/getting_started/parametrising_components/index.html b/dev/concepts/getting_started/parametrising_components/index.html
index 6919509e..fd0a84fb 100644
--- a/dev/concepts/getting_started/parametrising_components/index.html
+++ b/dev/concepts/getting_started/parametrising_components/index.html
@@ -1,4 +1,4 @@
- Parametrising components - Django-Components Parametrising components
So far, our Calendar component will always render the date 1970-01-01. Let's make it more useful and flexible by being able to pass in custom date.
What we want is to be able to use the Calendar component within the template like so:
{% component "calendar" date="2024-12-13" extra_class="text-red" / %}
+ Parametrising components - Django-Components Parametrising components
So far, our Calendar component will always render the date 1970-01-01. Let's make it more useful and flexible by being able to pass in custom date.
What we want is to be able to use the Calendar component within the template like so:
1. Understading component inputs¤
In section Create your first component, we defined the get_context_data() method that defines what variables will be available within the template:
[project root]/components/calendar/calendar.pyfrom django_components import Component, register
@register("calendar")
diff --git a/dev/concepts/getting_started/your_first_component/index.html b/dev/concepts/getting_started/your_first_component/index.html
index ba2185e4..ab5168ab 100644
--- a/dev/concepts/getting_started/your_first_component/index.html
+++ b/dev/concepts/getting_started/your_first_component/index.html
@@ -1,4 +1,4 @@
- Create your first component - Django-Components Create your first component
A component in django-components can be as simple as a Django template and Python code to declare the component:
from django_components import Component
+ Create your first component - Django-Components Create your first component
A component in django-components can be as simple as a Django template and Python code to declare the component:
from django_components import Component
class Calendar(Component):
template = """
diff --git a/dev/guides/devguides/dependency_mgmt/index.html b/dev/guides/devguides/dependency_mgmt/index.html
index c1716ef5..58f954e0 100644
--- a/dev/guides/devguides/dependency_mgmt/index.html
+++ b/dev/guides/devguides/dependency_mgmt/index.html
@@ -1,4 +1,4 @@
- JS and CSS rendering - Django-Components