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:
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 ba76bf72..33685c80 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/hooks/index.html b/dev/concepts/advanced/hooks/index.html
index 985669d7..cc6acb12 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
Component hooks are functions that allow you to intercept the rendering process at specific positions.
Available hooks¤
on_render_before
def 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
def on_render_before(
self: Component,
context: Context,
template: Template
diff --git a/dev/concepts/advanced/html_tragments/index.html b/dev/concepts/advanced/html_tragments/index.html
index 0c5ce192..99c98023 100644
--- a/dev/concepts/advanced/html_tragments/index.html
+++ b/dev/concepts/advanced/html_tragments/index.html
@@ -1,4 +1,4 @@
- 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:
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:
MyTable.render(
kwargs={...},
)
diff --git a/dev/concepts/advanced/provide_inject/index.html b/dev/concepts/advanced/provide_inject/index.html
index b755925b..fc2dcf16 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 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 %}
+ 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 %}
diff --git a/dev/concepts/advanced/rendering_js_css/index.html b/dev/concepts/advanced/rendering_js_css/index.html
index 5284f138..ab51233f 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
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
+ 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.
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
diff --git a/dev/concepts/advanced/tag_formatter/index.html b/dev/concepts/advanced/tag_formatter/index.html
index 35b0e0f1..f6cffe65 100644
--- a/dev/concepts/advanced/tag_formatter/index.html
+++ b/dev/concepts/advanced/tag_formatter/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/typing_and_validation/index.html b/dev/concepts/advanced/typing_and_validation/index.html
index d2f3927b..b0aebfbc 100644
--- a/dev/concepts/advanced/typing_and_validation/index.html
+++ b/dev/concepts/advanced/typing_and_validation/index.html
@@ -1,4 +1,4 @@
- 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:
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:
from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
diff --git a/dev/concepts/fundamentals/access_component_input/index.html b/dev/concepts/fundamentals/access_component_input/index.html
index 2200b2ef..65fa94cc 100644
--- a/dev/concepts/fundamentals/access_component_input/index.html
+++ b/dev/concepts/fundamentals/access_component_input/index.html
@@ -1,4 +1,4 @@
- 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):
+ 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 7c2f5394..e2696075 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 767ce604..a66d7952 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 27acc657..064f5a1b 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:
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/components_in_python/index.html b/dev/concepts/fundamentals/components_in_python/index.html
index c52cef71..2fc83b19 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 8e314aa9..8b1c4dda 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
As you could have seen in the tutorial, there's multiple ways how you can associate HTML / JS / CSS with a component:
- You can set
Component.template, Component.css and Component.js to define the main HTML / CSS / JS for a component as inlined code. - You can set
Component.template_file, Component.css_file and Component.js_file to define the main HTML / CSS / JS for a component in separate files. - You can link additional CSS / JS files using
Component.Media.js and Component.Media.css.
Warning
You cannot use both inlined code and separate file for a single language type:
- You can only either set
Component.template or Component.template_file - You can only either set
Component.css or Component.css_file - You can only either set
Component.js or Component.js_file
However, you can freely mix these for different languages:
class MyTable(Component):
+ Defining HTML / JS / CSS files - Django-Components Defining HTML / JS / CSS files
As you could have seen in the tutorial, there's multiple ways how you can associate HTML / JS / CSS with a component:
- You can set
Component.template, Component.css and Component.js to define the main HTML / CSS / JS for a component as inlined code. - You can set
Component.template_file, Component.css_file and Component.js_file to define the main HTML / CSS / JS for a component in separate files. - You can link additional CSS / JS files using
Component.Media.js and Component.Media.css.
Warning
You cannot use both inlined code and separate file for a single language type:
- You can only either set
Component.template or Component.template_file - You can only either set
Component.css or Component.css_file - You can only either set
Component.js or Component.js_file
However, you can freely mix these for different languages:
class MyTable(Component):
template: types.django_html = """
<div class="welcome">
Hi there!
@@ -22,7 +22,7 @@
js_file = "calendar/script.js"
Important
File path resolution in-depth
At component class creation, django-components checks all file paths defined on the component (e.g. Component.template_file).
For each file path, it checks if the file path is relative to the component's directory. And such file exists, the component's file path is re-written to be defined relative to a first matching directory in COMPONENTS.dirs or COMPONENTS.app_dirs.
Example:
- Component
MyTable is defined in file [root]/components/mytable/mytable.py. - The component's directory is thus
[root]/components/mytable/. - Because
MyTable.template_file is mytable.html, django-components tries to resolve it as [root]/components/mytable/mytable.html. - django-components checks the filesystem. If there's no such file, nothing happens.
- If there IS such file, django-components tries to rewrite the path.
- django-components searches
COMPONENTS.dirs and COMPONENTS.app_dirs for a first directory that contains [root]/components/mytable/mytable.html. - It comes across
[root]/components/, which DOES contain the path to mytable.html. - Thus, it rewrites
template_file from mytable.html to mytable/mytable.html.
NOTE: In case of ambiguity, the preference goes to resolving the files relative to the component's directory.
Defining additional JS and CSS files¤
Each component can have only a single template, and single main JS and CSS. However, you can define additional JS or CSS using the nested Component.Media class.
This Media class behaves similarly to Django's Media class:
- Paths are generally handled as static file paths, and resolved URLs are rendered to HTML with
media_class.render_js() or media_class.render_css(). - A path that starts with
http, https, or / is considered a URL, skipping the static file resolution. This path is still rendered to HTML with media_class.render_js() or media_class.render_css(). - A
SafeString, or a function (with __html__ method) is considered an already-formatted HTML tag, skipping both static file resolution and rendering with media_class.render_js() or media_class.render_css().
However, there's a few differences from Django's Media class:
- Our Media class accepts various formats for the JS and CSS files: either a single file, a list, or (CSS-only) a dictonary (See
ComponentMediaInput). - Individual JS / CSS files can be any of
str, bytes, Path, SafeString, or a function (See ComponentMediaInputPath). - Our Media class does NOT support Django's
extend keyword
- Component
MyTable is defined in file [root]/components/mytable/mytable.py. - The component's directory is thus
[root]/components/mytable/. - Because
MyTable.template_file is mytable.html, django-components tries to resolve it as [root]/components/mytable/mytable.html. - django-components checks the filesystem. If there's no such file, nothing happens.
- If there IS such file, django-components tries to rewrite the path.
- django-components searches
COMPONENTS.dirs and COMPONENTS.app_dirs for a first directory that contains [root]/components/mytable/mytable.html. - It comes across
[root]/components/, which DOES contain the path to mytable.html. - Thus, it rewrites
template_file from mytable.html to mytable/mytable.html.
NOTE: In case of ambiguity, the preference goes to resolving the files relative to the component's directory.
Defining additional JS and CSS files¤
Each component can have only a single template, and single main JS and CSS. However, you can define additional JS or CSS using the nested Component.Media class.
This Media class behaves similarly to Django's Media class:
- Paths are generally handled as static file paths, and resolved URLs are rendered to HTML with
media_class.render_js() or media_class.render_css(). - A path that starts with
http, https, or / is considered a URL, skipping the static file resolution. This path is still rendered to HTML with media_class.render_js() or media_class.render_css(). - A
SafeString, or a function (with __html__ method) is considered an already-formatted HTML tag, skipping both static file resolution and rendering with media_class.render_js() or media_class.render_css(). - You can set
extend to configure whether to inherit JS / CSS from parent components. See Controlling Media Inheritance.
However, there's a few differences from Django's Media class:
- Our Media class accepts various formats for the JS and CSS files: either a single file, a list, or (CSS-only) a dictonary (See
ComponentMediaInput). - Individual JS / CSS files can be any of
str, bytes, Path, SafeString, or a function (See ComponentMediaInputPath).
class MyTable(Component):
class Media:
js = [
"path/to/script.js",
@@ -145,7 +145,7 @@
# width: 200px;
# background: pink;
# }
-
Warning
Do NOT modify HTML / CSS / JS after it has been loaded
django-components assumes that the component's media files like js_file or Media.js/css are static.
If you need to dynamically change these media files, consider instead defining multiple Components.
Modifying these files AFTER the component has been loaded at best does nothing. However, this is an untested behavior, which may lead to unexpected errors.
Accessing component's Media files¤
To access the files defined under Component.Media, you can access Component.media (lowercase). This is consistent behavior with Django's Media class.
Warning
Do NOT modify HTML / CSS / JS after it has been loaded
django-components assumes that the component's media files like js_file or Media.js/css are static.
If you need to dynamically change these media files, consider instead defining multiple Components.
Modifying these files AFTER the component has been loaded at best does nothing. However, this is an untested behavior, which may lead to unexpected errors.
Accessing component's Media files¤
To access the files that you defined under Component.Media, use Component.media (lowercase). This is consistent behavior with Django's Media class.
class MyComponent(Component):
class Media:
js = "path/to/script.js"
css = "path/to/style.css"
@@ -154,4 +154,48 @@
# Output:
# <script src="/static/path/to/script.js"></script>
# <link href="/static/path/to/style.css" media="all" rel="stylesheet">
-
If you want to modify the class that is instantiated for Component.media, you can configure Component.media_class (See example).
\ No newline at end of file
+
Component.Media vs Component.media¤
When working with component media files, there are a few important concepts to understand:
-
Component.Media
- Is the "raw" media definition, or the input, which holds only the component's own media definition
- This class is NOT instantiated, it merely holds the JS / CSS files.
-
Component.media
- Returns all resolved media files, including those inherited from parent components
- Is an instance of
Component.media_class
class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+class ChildComponent(ParentComponent):
+ class Media:
+ js = ["child.js"]
+
+# Access only this component's media
+print(ChildComponent.Media.js) # ["child.js"]
+
+# Access all inherited media
+print(ChildComponent.media._js) # ["parent.js", "child.js"]
+
Note
You should not manually modify Component.media or Component.Media after the component has been resolved, as this may lead to unexpected behavior.
If you want to modify the class that is instantiated for Component.media, you can configure Component.media_class (See example).
Controlling Media Inheritance¤
By default, the media files are inherited from the parent component.
class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+class MyComponent(ParentComponent):
+ class Media:
+ js = ["script.js"]
+
+print(MyComponent.media._js) # ["parent.js", "script.js"]
+
You can set the component NOT to inherit from the parent component by setting the extend attribute to False:
class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+class MyComponent(ParentComponent):
+ class Media:
+ extend = False # Don't inherit parent media
+ js = ["script.js"]
+
+print(MyComponent.media._js) # ["script.js"]
+
Alternatively, you can specify which components to inherit from. In such case, the media files are inherited ONLY from the specified components, and NOT from the original parent components:
class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+class MyComponent(ParentComponent):
+ class Media:
+ # Only inherit from these, ignoring the files from the parent
+ extend = [OtherComponent1, OtherComponent2]
+
+ js = ["script.js"]
+
+print(MyComponent.media._js) # ["script.js", "other1.js", "other2.js"]
+
Info
The extend behaves consistently with Django's Media class, with one exception:
- When you set
extend to a list, the list is expected to contain Component classes (or other classes that have a nested Media class).
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/html_attributes/index.html b/dev/concepts/fundamentals/html_attributes/index.html
index 20f837eb..75ce5817 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 4efaae04..0dccf0c1 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 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_file, js_file, and css_file.
For example, here's the calendar component from the Getting started tutorial, defined in a single file:
[project root]/components/calendar.pyfrom django_components import Component, register, types
+ Single-file components - Django-Components Single-file components
Components can 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_file, js_file, and css_file.
For example, here's the calendar component from the Getting started tutorial, defined in a single file:
[project root]/components/calendar.pyfrom django_components import Component, register, types
@register("calendar")
class Calendar(Component):
diff --git a/dev/concepts/fundamentals/slots/index.html b/dev/concepts/fundamentals/slots/index.html
index 63315895..d15849b2 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/subclassing_components/index.html b/dev/concepts/fundamentals/subclassing_components/index.html
new file mode 100644
index 00000000..0081b9e5
--- /dev/null
+++ b/dev/concepts/fundamentals/subclassing_components/index.html
@@ -0,0 +1,82 @@
+ Subclassing components - Django-Components Subclassing components
In larger projects, you might need to write multiple components with similar behavior. In such cases, you can extract shared behavior into a standalone component class to keep things DRY.
When subclassing a component, there's a couple of things to keep in mind:
Template, JS, and CSS Inheritance¤
When it comes to the pairs:
Component.template/Component.template_fileComponent.js/Component.js_fileComponent.css/Component.css_file
inheritance follows these rules:
- If a child component class defines either member of a pair (e.g., either
template or template_file), it takes precedence and the parent's definition is ignored completely. - For example, if a child component defines
template_file, the parent's template or template_file will be ignored. - This applies independently to each pair - you can inherit the JS while overriding the template, for instance.
For example:
class BaseCard(Component):
+ template = """
+ <div class="card">
+ <div class="card-content">{{ content }}</div>
+ </div>
+ """
+ css = """
+ .card {
+ border: 1px solid gray;
+ }
+ """
+ js = "console.log('Base card loaded');"
+
+# This class overrides parent's template, but inherits CSS and JS
+class SpecialCard(BaseCard):
+ template = """
+ <div class="card special">
+ <div class="card-content">✨ {{ content }} ✨</div>
+ </div>
+ """
+
+# This class overrides parent's template and CSS, but inherits JS
+class CustomCard(BaseCard):
+ template_file = "custom_card.html"
+ css = """
+ .card {
+ border: 2px solid gold;
+ }
+ """
+
Media Class Inheritance¤
The Component.Media nested class follows Django's media inheritance rules:
- If both parent and child define a
Media class, the child's media will automatically include both its own and the parent's JS and CSS files. - This behavior can be configured using the
extend attribute in the Media class, similar to Django's forms. Read more on this in Controlling Media Inheritance.
For example:
class BaseModal(Component):
+ template = "<div>Modal content</div>"
+
+ class Media:
+ css = ["base_modal.css"]
+ js = ["base_modal.js"] # Contains core modal functionality
+
+class FancyModal(BaseModal):
+ class Media:
+ # Will include both base_modal.css/js AND fancy_modal.css/js
+ css = ["fancy_modal.css"] # Additional styling
+ js = ["fancy_modal.js"] # Additional animations
+
+class SimpleModal(BaseModal):
+ class Media:
+ extend = False # Don't inherit parent's media
+ css = ["simple_modal.css"] # Only this CSS will be included
+ js = ["simple_modal.js"] # Only this JS will be included
+
Regular Python Inheritance¤
All other attributes and methods (including the Component.View class and its methods) follow standard Python inheritance rules.
For example:
class BaseForm(Component):
+ template = """
+ <form>
+ {{ form_content }}
+ <button type="submit">
+ {{ submit_text }}
+ </button>
+ </form>
+ """
+
+ def get_context_data(self, **kwargs):
+ return {
+ "form_content": self.get_form_content(),
+ "submit_text": "Submit"
+ }
+
+ def get_form_content(self):
+ return "<input type='text' name='data'>"
+
+class ContactForm(BaseForm):
+ # Extend parent's "context"
+ # but override "submit_text"
+ def get_context_data(self, **kwargs):
+ context = super().get_context_data(**kwargs)
+ context["submit_text"] = "Send Message"
+ return context
+
+ # Completely override parent's get_form_content
+ def get_form_content(self):
+ return """
+ <input type='text' name='name' placeholder='Your Name'>
+ <input type='email' name='email' placeholder='Your Email'>
+ <textarea name='message' placeholder='Your Message'></textarea>
+ """
+
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/template_tag_syntax/index.html b/dev/concepts/fundamentals/template_tag_syntax/index.html
index ec7fbc5d..6319d57d 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: