You can publish and share your components for others to use. Below you will find the steps to do so.
For live examples, see the Community examples.
Create a Django project with a similar structure:
project/
+ Authoring component libraries - Django-Components Authoring component libraries
You can publish and share your components for others to use. Below you will find the steps to do so.
For live examples, see the Community examples.
Writing component libraries¤
-
Create a Django project with a similar structure:
project/
|-- myapp/
|-- __init__.py
|-- apps.py
@@ -69,16 +69,16 @@
"attrs": attrs,
}
- template: types.django_html = """
- {# Load django_components template tags #}
- {% load component_tags %}
+ template: types.django_html = """
+ {# Load django_components template tags #}
+ {% load component_tags %}
- <div {% html_attrs attrs class="my-menu" %}>
- <div class="my-menu__content">
- {% slot "default" default / %}
- </div>
- </div>
- """
+ <div {% html_attrs attrs class="my-menu" %}>
+ <div class="my-menu__content">
+ {% slot "default" default / %}
+ </div>
+ </div>
+ """
-
Import the components in apps.py
Normally, users rely on autodiscovery and COMPONENTS.dirs to load the component files.
Since you, as the library author, are not in control of the file system, it is recommended to load the components manually.
We recommend doing this in the AppConfig.ready() hook of your apps.py:
-
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):
diff --git a/dev/concepts/advanced/hooks/index.html b/dev/concepts/advanced/hooks/index.html
index be090572..85a4ee1c 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 0ff097ea..0791b1cb 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={...},
)
@@ -19,29 +19,29 @@
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>
+ 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>
+ <button
+ hx-get="/mypage/frag"
+ hx-swap="outerHTML"
+ hx-target="#target"
+ >
+ Click me!
+ </button>
- {% component_js_dependencies %}
- </body>
- </html>
- """
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
2. Define fragment HTML¤
[root]/components/demo.pyclass Frag(Component):
def get(self, request):
return self.render_to_response(
@@ -49,22 +49,22 @@
type="fragment",
)
- template = """
- <div class="frag">
- 123
- <span id="frag-text"></span>
- </div>
- """
+ template = """
+ <div class="frag">
+ 123
+ <span id="frag-text"></span>
+ </div>
+ """
- js = """
- document.querySelector('#frag-text').textContent = 'xxx';
- """
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
- css = """
- .frag {
- background: blue;
- }
- """
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
3. Create view and URLs¤
[app]/urls.pyfrom django.urls import path
from components.demo import MyPage, Frag
@@ -80,35 +80,35 @@
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>
+ 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>
+ <button @click="loadFragment">
+ Click me!
+ </button>
- {% component_js_dependencies %}
- </body>
- </html>
- """
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
2. Define fragment HTML¤
[root]/components/demo.pyclass Frag(Component):
def get(self, request):
# IMPORTANT: Don't forget `type="fragment"`
@@ -118,33 +118,33 @@
# 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>
- """
+ 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',
- }));
+ 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');
- });
- """
+ // 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;
- }
- """
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
3. Create view and URLs¤
[app]/urls.pyfrom django.urls import path
from components.demo import MyPage, Frag
@@ -160,34 +160,34 @@
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>
+ 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>
+ <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>
- """
+ {% component_js_dependencies %}
+ </body>
+ </html>
+ """
2. Define fragment HTML¤
[root]/components/demo.pyclass Frag(Component):
def get(self, request):
return self.render_to_response(
@@ -195,22 +195,22 @@
type="fragment",
)
- template = """
- <div class="frag">
- 123
- <span id="frag-text"></span>
- </div>
- """
+ template = """
+ <div class="frag">
+ 123
+ <span id="frag-text"></span>
+ </div>
+ """
- js = """
- document.querySelector('#frag-text').textContent = 'xxx';
- """
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
- css = """
- .frag {
- background: blue;
- }
- """
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
3. Create view and URLs¤
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/concepts/advanced/provide_inject/index.html b/dev/concepts/advanced/provide_inject/index.html
index 2fd0d70d..67d33d66 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 %}
@@ -23,10 +23,10 @@
return {}
The instance returned from inject() is a subclass of NamedTuple, so the instance is immutable. This ensures that the data returned from inject will always have all the keys that were passed to the provide tag.
NOTE: inject() works strictly only in get_context_data. If you try to call it from elsewhere, it will raise an error.
Full example¤
@register("child")
class ChildComponent(Component):
- template = """
- <div> {{ my_data.key }} </div>
- <div> {{ my_data.another }} </div>
- """
+ template = """
+ <div> {{ my_data.key }} </div>
+ <div> {{ my_data.another }} </div>
+ """
def get_context_data(self):
my_data = self.inject("my_data", "default")
@@ -40,4 +40,4 @@
"""
renders:
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/concepts/advanced/rendering_js_css/index.html b/dev/concepts/advanced/rendering_js_css/index.html
index a5549aa2..bdf89d6f 100644
--- a/dev/concepts/advanced/rendering_js_css/index.html
+++ b/dev/concepts/advanced/rendering_js_css/index.html
@@ -1,18 +1,18 @@
- 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 = """
- <button class="my-button">
- Click me!
- </button>
- """
- js: types.js = """
- for (const btnEl of document.querySelectorAll(".my-button")) {
- btnEl.addEventListener("click", () => {
- console.log("BUTTON CLICKED!");
- });
- }
- """
+ template: types.django_html = """
+ <button class="my-button">
+ Click me!
+ </button>
+ """
+ js: types.js = """
+ for (const btnEl of document.querySelectorAll(".my-button")) {
+ btnEl.addEventListener("click", () => {
+ console.log("BUTTON CLICKED!");
+ });
+ }
+ """
css: types.css """
.my-button {
background: green;
@@ -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 919a619c..462f2558 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/template_tags/index.html b/dev/concepts/advanced/template_tags/index.html
index c93e5bc1..e8fd542b 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/typing_and_validation/index.html b/dev/concepts/advanced/typing_and_validation/index.html
index 12917fea..0c2da15a 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 48845f7e..1b89ad07 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 b7fde16f..65c695fc 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 f0097604..e86a4cc5 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¤
However, as a best practice, it’s recommended not to rely on accessing the outer context directly through self.outer_context. Instead, explicitly pass the variables to the component. For instance, continue passing the variables in the component tag as shown in the previous examples.
Context behavior¤
django_components supports both Django and Vue-like behavior when it comes to passing data to and through components. This can be configured in context_behavior.
This has two modes:
-
"django"
The default Django template behavior.
Inside the {% fill %} tag, the context variables you can access are a union of:
- All the variables that were OUTSIDE the fill tag, including any\
{% with %} tags. - Any loops (
{% for ... %}) that the {% fill %} tag is part of. - Data returned from
Component.get_context_data() of the component that owns the fill tag.
-
"isolated"
Similar behavior to Vue or React, this is useful if you want to make sure that components don't accidentally access variables defined outside of the component.
Inside the {% fill %} tag, you can ONLY access variables from 2 places:
- Any loops (
{% for ... %}) that the {% fill %} tag is part of. Component.get_context_data() of the component which defined the template (AKA the "root" component).
Warning
Notice that the component whose get_context_data() we use inside {% fill %} is NOT the same across the two modes!
Consider this example:
class Outer(Component):
- template = \"\"\"
- <div>
- {% component "inner" %}
- {% fill "content" %}
- {{ my_var }}
- {% endfill %}
- {% endcomponent %}
- </div>
- \"\"\"
+ template = """
+ <div>
+ {% component "inner" %}
+ {% fill "content" %}
+ {{ my_var }}
+ {% endfill %}
+ {% endcomponent %}
+ </div>
+ """
-
"django" - my_var has access to data from get_context_data() of both Inner and Outer. If there are variables defined in both, then Inner overshadows Outer.
-
"isolated" - my_var has access to data from get_context_data() of ONLY Outer.
Example "django"¤
Given this template:
@register("root_comp")
class RootComp(Component):
- template = """
- {% with cheese="feta" %}
- {% component 'my_comp' %}
- {{ my_var }} # my_var
- {{ cheese }} # cheese
- {% endcomponent %}
- {% endwith %}
- """
+ template = """
+ {% with cheese="feta" %}
+ {% component 'my_comp' %}
+ {{ my_var }} # my_var
+ {{ cheese }} # cheese
+ {% endcomponent %}
+ {% endwith %}
+ """
def get_context_data(self):
return { "my_var": 123 }
@@ -38,18 +38,18 @@
Then the template will be rendered as:
Because "my_comp" overshadows the outer variable "my_var", so {{ my_var }} equals 456.
And variable "cheese" equals feta, because the fill CAN access all the data defined in the outer layers, like the {% with %} tag.
Example "isolated"¤
Given this template:
class RootComp(Component):
- template = """
- {% with cheese="feta" %}
- {% component 'my_comp' %}
- {{ my_var }} # my_var
- {{ cheese }} # cheese
- {% endcomponent %}
- {% endwith %}
- """
+ template = """
+ {% with cheese="feta" %}
+ {% component 'my_comp' %}
+ {{ my_var }} # my_var
+ {{ cheese }} # cheese
+ {% endcomponent %}
+ {% endwith %}
+ """
def get_context_data(self):
return { "my_var": 123 }
Then if get_context_data() of the component "my_comp" returns following data:
Then the template will be rendered as:
Because variables "my_var" and "cheese" are searched only inside RootComponent.get_context_data(). But since "cheese" is not defined there, it's empty.
Info
Notice that the variables defined with the {% with %} tag are ignored inside the {% fill %} tag with the "isolated" mode.
\ No newline at end of file
+
Because variables "my_var" and "cheese" are searched only inside RootComponent.get_context_data(). But since "cheese" is not defined there, it's empty.
Info
Notice that the variables defined with the {% with %} tag are ignored inside the {% fill %} tag with the "isolated" mode.
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/components_as_views/index.html b/dev/concepts/fundamentals/components_as_views/index.html
index cffca4de..8fa8b27e 100644
--- a/dev/concepts/fundamentals/components_as_views/index.html
+++ b/dev/concepts/fundamentals/components_as_views/index.html
@@ -1,19 +1,19 @@
- 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")
class Calendar(Component):
- template = """
- <div class="calendar-component">
- <div class="header">
- {% slot "header" / %}
- </div>
- <div class="body">
- Today's date is <span>{{ date }}</span>
- </div>
- </div>
- """
+ template = """
+ <div class="calendar-component">
+ <div class="header">
+ {% slot "header" / %}
+ </div>
+ <div class="body">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ </div>
+ """
# Handle GET requests
def get(self, request, *args, **kwargs):
@@ -80,4 +80,4 @@
super(request, *args, **kwargs)
do_something_extra(request, *args, **kwargs)
-
\ 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 2bc5554f..596eb5bf 100644
--- a/dev/concepts/fundamentals/components_in_python/index.html
+++ b/dev/concepts/fundamentals/components_in_python/index.html
@@ -1,11 +1,11 @@
- 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 }}
- foo: {{ foo }}
- kwargs: {{ kwargs|safe }}
- slot_first: {% slot "first" required / %}
- """
+ 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 }}
+ foo: {{ foo }}
+ kwargs: {{ kwargs|safe }}
+ slot_first: {% slot "first" required / %}
+ """
def get_context_data(self, arg1, arg2, **kwargs):
return {
@@ -61,4 +61,4 @@
response = SimpleComponent.render_to_response()
assert isinstance(response, MyResponse)
-
\ No newline at end of file
+
\ No newline at end of file
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 8bbf1404..1292bc73 100644
--- a/dev/concepts/fundamentals/defining_js_css_html_files/index.html
+++ b/dev/concepts/fundamentals/defining_js_css_html_files/index.html
@@ -1,9 +1,9 @@
- 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!
- </div>
- """
+ 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:
Note
django-component's management of files is inspired by Django's Media class.
To be familiar with how Django handles static files, we recommend reading also:
Defining file paths relative to component¤
As seen in the getting started example, to associate HTML / JS / CSS files with a component, you can set them as Component.template_file, Component.js_file and Component.css_file respectively:
[project root]/components/calendar/calendar.pyfrom django_components import Component, register
@@ -198,4 +198,4 @@
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
+
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 722e577c..12b7532c 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:
Then:
- Empty tag
{% html_attr %}
renders (empty string):
- Only kwargs
{% html_attr class="some-class" class=class_from_var data-id="123" %}
renders:
class="some-class from-var" data-id="123"
- Only attrs
{% html_attr attrs %}
renders:
class="from-attrs" type="submit"
- Attrs as kwarg
{% html_attr attrs=attrs %}
renders:
class="from-attrs" type="submit"
- Only defaults (as kwarg)
{% html_attr defaults=defaults %}
renders:
class="from-defaults" role="button"
- Attrs using the
prefix:key=value construct
{% html_attr attrs:class="from-attrs" attrs:type="submit" %}
renders:
class="from-attrs" type="submit"
- Defaults using the
prefix:key=value construct
{% html_attr defaults:class="from-defaults" %}
renders:
class="from-defaults" role="button"
- All together (1) - attrs and defaults as positional args:
{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}
renders:
class="from-attrs added_class from-var" type="submit" role="button" data-id=123
- All together (2) - attrs and defaults as kwargs args:
{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}
renders:
class="from-attrs added_class from-var" type="submit" role="button" data-id=123
- All together (3) - mixed:
{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}
renders:
class="from-attrs added_class from-var" type="submit" data-id=123
Full example for html_attrs¤
@register("my_comp")
class MyComp(Component):
- template: t.django_html = """
- <div
- {% html_attrs attrs
- defaults:class="pa-4 text-red"
- class="my-comp-date"
- class=class_from_var
- data-id="123"
- %}
- >
- Today's date is <span>{{ date }}</span>
- </div>
- """
+ template: t.django_html = """
+ <div
+ {% html_attrs attrs
+ defaults:class="pa-4 text-red"
+ class="my-comp-date"
+ class=class_from_var
+ data-id="123"
+ %}
+ >
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
def get_context_data(self, date: Date, attrs: dict):
return {
@@ -72,14 +72,14 @@
@register("parent")
class Parent(Component):
- template: t.django_html = """
- {% component "my_comp"
- date=date
- attrs:class="pa-0 border-solid border-red"
- attrs:data-json=json_data
- attrs:@click="(e) => onClick(e, 'from_parent')"
- / %}
- """
+ template: t.django_html = """
+ {% component "my_comp"
+ date=date
+ attrs:class="pa-0 border-solid border-red"
+ attrs:data-json=json_data
+ attrs:@click="(e) => onClick(e, 'from_parent')"
+ / %}
+ """
def get_context_data(self, date: Date):
return {
@@ -115,4 +115,4 @@
attributes_to_string(attrs)
# 'class="my-class text-red pa-4" data-id="123" required'
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/http_request/index.html b/dev/concepts/fundamentals/http_request/index.html
index 513a5e72..561b0b2c 100644
--- a/dev/concepts/fundamentals/http_request/index.html
+++ b/dev/concepts/fundamentals/http_request/index.html
@@ -1,4 +1,4 @@
- HTTP Request - Django-Components HTTP Request
The most common use of django-components is to render HTML for a given request. As such, there are a few features that are dependent on the request object.
Passing and accessing HttpRequest¤
In regular Django templates, the request object is available only within the RequestContext.
In Components, you can either use RequestContext, or pass the request object explicitly to Component.render() and Component.render_to_response().
When a component is nested in another, the child component uses parent's request object.
You can access the request object under Component.request:
class MyComponent(Component):
+ HTTP Request - Django-Components HTTP Request
The most common use of django-components is to render HTML for a given request. As such, there are a few features that are dependent on the request object.
Passing and accessing HttpRequest¤
In regular Django templates, the request object is available only within the RequestContext.
In Components, you can either use RequestContext, or pass the request object explicitly to Component.render() and Component.render_to_response().
When a component is nested in another, the child component uses parent's request object.
You can access the request object under Component.request:
class MyComponent(Component):
def get_context_data(self):
return {
'user_id': self.request.GET['user_id'],
@@ -31,11 +31,11 @@
# ✅ With context processors
rendered = template.render(RequestContext(request, {}))
Accessing context processors data¤
The data from context processors is automatically available within the component's template.
class MyComponent(Component):
- template = """
- <div>
- {{ csrf_token }}
- </div>
- """
+ template = """
+ <div>
+ {{ csrf_token }}
+ </div>
+ """
MyComponent.render(request=request)
You can also access the context processors data from within get_context_data() and other methods under Component.context_processors_data.
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/single_file_components/index.html b/dev/concepts/fundamentals/single_file_components/index.html
index 6f5fe51c..05d3a955 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):
@@ -7,29 +7,29 @@
"date": date,
}
- template: types.django_html = """
- <div class="calendar">
- Today's date is <span>{{ date }}</span>
- </div>
- """
+ template: types.django_html = """
+ <div class="calendar">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
- css: types.css = """
- .calendar {
- width: 200px;
- background: pink;
- }
- .calendar span {
- font-weight: bold;
- }
- """
+ css: types.css = """
+ .calendar {
+ width: 200px;
+ background: pink;
+ }
+ .calendar span {
+ font-weight: bold;
+ }
+ """
- js: types.js = """
- (function(){
- if (document.querySelector(".calendar")) {
- document.querySelector(".calendar").onclick = () => {
- alert("Clicked calendar!");
- };
- }
- })()
- """
-
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
To add syntax highlighting to these snippets, head over to Syntax highlighting.
\ No newline at end of file
+ js: types.js = """
+ (function(){
+ if (document.querySelector(".calendar")) {
+ document.querySelector(".calendar").onclick = () => {
+ alert("Clicked calendar!");
+ };
+ }
+ })()
+ """
+
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
To add syntax highlighting to these snippets, head over to Syntax highlighting.
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/slots/index.html b/dev/concepts/fundamentals/slots/index.html
index 60a26717..d02c37ef 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>
@@ -214,26 +214,26 @@
{% endcomponent %}
Scoped slots¤
Added in version 0.76:
Consider a component with slot(s). This component may do some processing on the inputs, and then use the processed variable in the slot's default template:
@register("my_comp")
class MyComp(Component):
- template = """
- <div>
- {% slot "content" default %}
- input: {{ input }}
- {% endslot %}
- </div>
- """
+ template = """
+ <div>
+ {% slot "content" default %}
+ input: {{ input }}
+ {% endslot %}
+ </div>
+ """
def get_context_data(self, input):
processed_input = do_something(input)
return {"input": processed_input}
You may want to design a component so that users of your component can still access the input variable, so they don't have to recompute it.
This behavior is called "scoped slots". This is inspired by Vue scoped slots and scoped slots of django-web-components.
Using scoped slots consists of two steps:
- Passing data to
slot tag - Accessing data in
fill tag
Passing data to slots¤
To pass the data to the slot tag, simply pass them as keyword attributes (key=value):
@register("my_comp")
class MyComp(Component):
- template = """
- <div>
- {% slot "content" default input=input %}
- input: {{ input }}
- {% endslot %}
- </div>
- """
+ template = """
+ <div>
+ {% slot "content" default input=input %}
+ input: {{ input }}
+ {% endslot %}
+ </div>
+ """
def get_context_data(self, input):
processed_input = do_something(input)
@@ -296,15 +296,15 @@
"slots": self.input.slots,
}
- template: """
- <div>
- {% component "child" %}
- {% for slot_name in slots %}
- {% fill name=slot_name data="data" %}
- {% slot name=slot_name ...data / %}
- {% endfill %}
- {% endfor %}
- {% endcomponent %}
- </div>
- """
-
\ No newline at end of file
+ template = """
+ <div>
+ {% component "child" %}
+ {% for slot_name in slots %}
+ {% fill name=slot_name data="data" %}
+ {% slot name=slot_name ...data / %}
+ {% endfill %}
+ {% endfor %}
+ {% endcomponent %}
+ </div>
+ """
+
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/subclassing_components/index.html b/dev/concepts/fundamentals/subclassing_components/index.html
index 477f0e4d..286f6471 100644
--- a/dev/concepts/fundamentals/subclassing_components/index.html
+++ b/dev/concepts/fundamentals/subclassing_components/index.html
@@ -1,32 +1,32 @@
- 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');"
+ 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>
- """
+ 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;
- }
- """
+ 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>"
@@ -46,14 +46,14 @@
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>
- """
+ template = """
+ <form>
+ {{ form_content }}
+ <button type="submit">
+ {{ submit_text }}
+ </button>
+ </form>
+ """
def get_context_data(self, **kwargs):
return {
@@ -79,4 +79,4 @@
<input type='email' name='email' placeholder='Your Email'>
<textarea name='message' placeholder='Your Message'></textarea>
"""
-
\ No newline at end of file
+
\ 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 568b375d..dda0b772 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 / %}
@@ -48,9 +48,9 @@
/ %}
Note: Never use this feature to mix business logic and template logic. Business logic should still be in the view!
Pass dictonary by its key-value pairs¤
New in version 0.74:
Sometimes, a component may expect a dictionary as one of its inputs.
Most commonly, this happens when a component accepts a dictionary of HTML attributes (usually called attrs) to pass to the underlying template.
In such cases, we may want to define some HTML attributes statically, and other dynamically. But for that, we need to define this dictionary on Python side:
@register("my_comp")
class MyComp(Component):
- template = """
- {% component "other" attrs=attrs / %}
- """
+ template = """
+ {% component "other" attrs=attrs / %}
+ """
def get_context_data(self, some_id: str):
attrs = {
@@ -61,13 +61,13 @@
return {"attrs": attrs}
But as you can see in the case above, the event handler @click.stop and styling pa-4 flex are disconnected from the template. If the component grew in size and we moved the HTML to a separate file, we would have hard time reasoning about the component's template.
Luckily, there's a better way.
When we want to pass a dictionary to a component, we can define individual key-value pairs as component kwargs, so we can keep all the relevant information in the template. For that, we prefix the key with the name of the dict and :. So key class of input attrs becomes attrs:class. And our example becomes:
@register("my_comp")
class MyComp(Component):
- template = """
- {% component "other"
- attrs:class="pa-4 flex"
- attrs:data-some-id=some_id
- attrs:@click.stop="onClickHandler"
- / %}
- """
+ template = """
+ {% component "other"
+ attrs:class="pa-4 flex"
+ attrs:data-some-id=some_id
+ attrs:@click.stop="onClickHandler"
+ / %}
+ """
def get_context_data(self, some_id: str):
return {"some_id": some_id}
@@ -84,4 +84,4 @@
date_last_active="2024-09-03"
...
%}
-
Much better!
To disable this behavior, set COMPONENTS.multiline_tag to False
\ No newline at end of file
+
Much better!
To disable this behavior, set COMPONENTS.multiline_tag to False
\ No newline at end of file
diff --git a/dev/getting_started/adding_js_and_css/index.html b/dev/getting_started/adding_js_and_css/index.html
index 8871c54c..5f5a5eb5 100644
--- a/dev/getting_started/adding_js_and_css/index.html
+++ b/dev/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/getting_started/adding_slots/index.html b/dev/getting_started/adding_slots/index.html
index 7cd3f6fe..2ce46d41 100644
--- a/dev/getting_started/adding_slots/index.html
+++ b/dev/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/getting_started/components_in_templates/index.html b/dev/getting_started/components_in_templates/index.html
index 385ffadb..d2211a3f 100644
--- a/dev/getting_started/components_in_templates/index.html
+++ b/dev/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/getting_started/parametrising_components/index.html b/dev/getting_started/parametrising_components/index.html
index c6d5e373..1d6173a0 100644
--- a/dev/getting_started/parametrising_components/index.html
+++ b/dev/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/getting_started/your_first_component/index.html b/dev/getting_started/your_first_component/index.html
index 42cde2e6..07eb8504 100644
--- a/dev/getting_started/your_first_component/index.html
+++ b/dev/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:
calendar.html<div class="calendar">
+ 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:
Alternatively, you can "inline" HTML, JS, and CSS right into the component class:
from django_components import Component
class Calendar(Component):
- template = """
- <div class="calendar">
- Today's date is <span>{{ date }}</span>
- </div>
- """
+ template = """
+ <div class="calendar">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
- css = """
- .calendar {
- width: 200px;
- background: pink;
- }
- """
+ css = """
+ .calendar {
+ width: 200px;
+ background: pink;
+ }
+ """
- js = """
- document.querySelector(".calendar").onclick = function () {
- alert("Clicked calendar!");
- };
- """
+ js = """
+ document.querySelector(".calendar").onclick = function () {
+ alert("Clicked calendar!");
+ };
+ """
Note
If you "inline" the HTML, JS and CSS code into the Python class, you can set up syntax highlighting for better experience. However, autocompletion / intellisense does not work with syntax highlighting.
We'll start by creating a component that defines only a Django template:
1. Create project structure¤
Start by creating empty calendar.py and calendar.html files:
It will output
And voilá!! We've created our first component.
\ No newline at end of file
+
And voilá!! We've created our first component.
\ No newline at end of file
diff --git a/dev/guides/devguides/dependency_mgmt/index.html b/dev/guides/devguides/dependency_mgmt/index.html
index 2a79ced2..46556a34 100644
--- a/dev/guides/devguides/dependency_mgmt/index.html
+++ b/dev/guides/devguides/dependency_mgmt/index.html
@@ -1,17 +1,17 @@
- JS and CSS rendering - Django-Components JS and CSS rendering¤
Aim of this doc is to share the intuition on how we manage the JS and CSS ("dependencies") associated with components, and how we render them.
Starting conditions¤
-
First of all, when we consider a component, it has two kind of dependencies - the "inlined" JS and CSS, and additional linked JS and CSS via Media.js/css:
from django_components import Component, types
+ JS and CSS rendering - Django-Components JS and CSS rendering¤
Aim of this doc is to share the intuition on how we manage the JS and CSS ("dependencies") associated with components, and how we render them.
Starting conditions¤
-
First of all, when we consider a component, it has two kind of dependencies - the "inlined" JS and CSS, and additional linked JS and CSS via Media.js/css:
from django_components import Component, types
class MyTable(Component):
# Inlined JS
- js: types.js = """
- console.log(123);
- """
+ js: types.js = """
+ console.log(123);
+ """
# Inlined CSS
- css: types.css = """
- .my-table {
- color: red;
- }
- """
+ css: types.css = """
+ .my-table {
+ color: red;
+ }
+ """
# Linked JS / CSS
class Media:
@@ -80,4 +80,4 @@
// Or mark one as already-loaded, so it is ignored when
// we call `loadJs`
Components.markScriptLoaded("js", "/abc/def");
-
Note that loadJs() / loadCss() receive whole <script> / <link> tags, not just the URL. This is because when Django's Media class renders JS and CSS, it formats it as <script> and <link> tags. And we allow users to modify how the JS and CSS should be rendered into the <script> and <link> tags.
So, if users decided to add an extra attribute to their <script> tags, e.g. <script defer src="http://..."></script>, then this way we make sure that the defer attribute will be present on the <script> tag when it is inserted into the DOM at the time of loading the JS script.
-
To be able to fetch component's inlined JS and CSS, django-components adds a URL path under:
/components/cache/<str:comp_cls_hash>.<str:script_type>/
E.g. /components/cache/my_table_10bc2c.js/
This endpoint takes the component's unique hash, e.g. my_table_10bc2c, and looks up the component's inlined JS or CSS.
Thus, with this approach, we ensure that:
- All JS / CSS dependencies are loaded / executed only once.
- The approach is compatible with HTML fragments
- The approach is compatible with JS / CSS variables.
- Inlined JS / CSS may be post-processed by plugins
\ No newline at end of file
+
Note that loadJs() / loadCss() receive whole <script> / <link> tags, not just the URL. This is because when Django's Media class renders JS and CSS, it formats it as <script> and <link> tags. And we allow users to modify how the JS and CSS should be rendered into the <script> and <link> tags.
So, if users decided to add an extra attribute to their <script> tags, e.g. <script defer src="http://..."></script>, then this way we make sure that the defer attribute will be present on the <script> tag when it is inserted into the DOM at the time of loading the JS script.
-
To be able to fetch component's inlined JS and CSS, django-components adds a URL path under:
/components/cache/<str:comp_cls_hash>.<str:script_type>/
E.g. /components/cache/my_table_10bc2c.js/
This endpoint takes the component's unique hash, e.g. my_table_10bc2c, and looks up the component's inlined JS or CSS.
Thus, with this approach, we ensure that:
- All JS / CSS dependencies are loaded / executed only once.
- The approach is compatible with HTML fragments
- The approach is compatible with JS / CSS variables.
- Inlined JS / CSS may be post-processed by plugins
\ No newline at end of file
diff --git a/dev/guides/devguides/slot_rendering/index.html b/dev/guides/devguides/slot_rendering/index.html
index 4891cbc5..a936619d 100644
--- a/dev/guides/devguides/slot_rendering/index.html
+++ b/dev/guides/devguides/slot_rendering/index.html
@@ -1,4 +1,4 @@
- Slot rendering - Django-Components Slot rendering¤
This doc serves as a primer on how component slots and fills are resolved.
Flow¤
-
Imagine you have a template. Some kind of text, maybe HTML:
| ------
+ Slot rendering - Django-Components Slot rendering¤
This doc serves as a primer on how component slots and fills are resolved.
Flow¤
-
Imagine you have a template. Some kind of text, maybe HTML:
| ------
| ---------
| ----
| -------
diff --git a/dev/guides/devguides/slots_and_blocks/index.html b/dev/guides/devguides/slots_and_blocks/index.html
index 162a01da..c498a9a8 100644
--- a/dev/guides/devguides/slots_and_blocks/index.html
+++ b/dev/guides/devguides/slots_and_blocks/index.html
@@ -1,4 +1,4 @@
- Using slot and block tags - Django-Components Using slot and block tags¤
-
First let's clarify how include and extends tags work inside components.
When component template includes include or extends tags, it's as if the "included" template was inlined. So if the "included" template contains slot tags, then the component uses those slots.
If you have a template abc.html:
<div>
+ Using slot and block tags - Django-Components Using slot and block tags¤
-
First let's clarify how include and extends tags work inside components.
When component template includes include or extends tags, it's as if the "included" template was inlined. So if the "included" template contains slot tags, then the component uses those slots.
If you have a template abc.html:
<div>
hello
{% slot "body" %}{% endslot %}
</div>
@@ -6,11 +6,11 @@
@register("my_comp_extends")
class MyCompWithExtends(Component):
- template = """{% extends "abc.html" %}"""
+ template = """{% extends "abc.html" %}"""
@register("my_comp_include")
class MyCompWithInclude(Component):
- template = """{% include "abc.html" %}"""
+ template = """{% include "abc.html" %}"""
Then you can set slot fill for the slot imported via include/extends:
Will still render the component content just the same:
-
You CAN override the block tags of abc.html if the component template uses extends. In that case, just as you would expect, the block inner inside abc.html will render OVERRIDEN:
-
This is where it gets interesting (but still intuitive). You can insert even new slots inside these "overriding" blocks:
@register("my_comp")
class MyComp(Component):
- template_file = """
- {% extends "abc.html" %}
+ template = """
+ {% extends "abc.html" %}
- {% load component_tags %}
- {% block "inner" %}
- OVERRIDEN
- {% slot "new_slot" %}
- hello
- {% endslot %}
- {% endblock %}
- """
+ {% load component_tags %}
+ {% block "inner" %}
+ OVERRIDEN
+ {% slot "new_slot" %}
+ hello
+ {% endslot %}
+ {% endblock %}
+ """
And you can then pass fill for this new_slot when rendering the component:
\ No newline at end of file
+
\ No newline at end of file
diff --git a/dev/guides/other/troubleshooting/index.html b/dev/guides/other/troubleshooting/index.html
index caaa217c..01f4f03a 100644
--- a/dev/guides/other/troubleshooting/index.html
+++ b/dev/guides/other/troubleshooting/index.html
@@ -1,4 +1,4 @@
- Troubleshooting - Django-Components Troubleshooting
As larger projects get more complex, it can be hard to debug issues. Django Components provides a number of tools and approaches that can help you with that.
Component and slot highlighting¤
Django Components provides a visual debugging feature that helps you understand the structure and boundaries of your components and slots. When enabled, it adds a colored border and a label around each component and slot on your rendered page.
To enable component and slot highlighting, set debug_highlight_components and/or debug_highlight_slots to True in your settings.py file:
from django_components import ComponentsSettings
+ Troubleshooting - Django-Components Troubleshooting
As larger projects get more complex, it can be hard to debug issues. Django Components provides a number of tools and approaches that can help you with that.
Component and slot highlighting¤
Django Components provides a visual debugging feature that helps you understand the structure and boundaries of your components and slots. When enabled, it adds a colored border and a label around each component and slot on your rendered page.
To enable component and slot highlighting, set debug_highlight_components and/or debug_highlight_slots to True in your settings.py file:
from django_components import ComponentsSettings
COMPONENTS = ComponentsSettings(
debug_highlight_components=True,
diff --git a/dev/guides/setup/caching/index.html b/dev/guides/setup/caching/index.html
index 40f4093b..d3b69acf 100644
--- a/dev/guides/setup/caching/index.html
+++ b/dev/guides/setup/caching/index.html
@@ -1,4 +1,4 @@
- Caching - Django-Components Caching
This page describes the kinds of assets that django-components caches and how to configure the cache backends.
Component's JS and CSS files¤
django-components caches the JS and CSS files associated with your components. This enables components to be rendered as HTML fragments and still having the associated JS and CSS files loaded with them.
This includes:
- Inlined JS/CSS defined via
Component.js and Component.css - JS/CSS variables generated from
get_js_data() and get_css_data()
By default, django-components uses Django's local memory cache backend to store these assets. You can configure it to use any of your Django cache backends by setting the COMPONENTS.cache option in your settings:
COMPONENTS = {
+ Caching - Django-Components Caching
This page describes the kinds of assets that django-components caches and how to configure the cache backends.
Component's JS and CSS files¤
django-components caches the JS and CSS files associated with your components. This enables components to be rendered as HTML fragments and still having the associated JS and CSS files loaded with them.
This includes:
- Inlined JS/CSS defined via
Component.js and Component.css - JS/CSS variables generated from
get_js_data() and get_css_data()
By default, django-components uses Django's local memory cache backend to store these assets. You can configure it to use any of your Django cache backends by setting the COMPONENTS.cache option in your settings:
COMPONENTS = {
# Name of the cache backend to use
"cache": "my-cache-backend",
}
diff --git a/dev/guides/setup/development_server/index.html b/dev/guides/setup/development_server/index.html
index 38d07a78..a3408e47 100644
--- a/dev/guides/setup/development_server/index.html
+++ b/dev/guides/setup/development_server/index.html
@@ -1 +1 @@
- Development server - Django-Components Development server
Reload dev server on component file changes¤
This is relevant if you are using the project structure as shown in our examples, where HTML, JS, CSS and Python are in separate files and nested in a directory.
In this case you may notice that when you are running a development server, the server sometimes does not reload when you change component files.
From relevant StackOverflow thread:
TL;DR is that the server won't reload if it thinks the changed file is in a templates directory, or in a nested sub directory of a templates directory. This is by design.
To make the dev server reload on all component files, set reload_on_file_change to True. This configures Django to watch for component files too.
Note
This setting should be enabled only for the dev environment!
\ No newline at end of file
+ Development server - Django-Components Development server
Reload dev server on component file changes¤
This is relevant if you are using the project structure as shown in our examples, where HTML, JS, CSS and Python are in separate files and nested in a directory.
In this case you may notice that when you are running a development server, the server sometimes does not reload when you change component files.
From relevant StackOverflow thread:
TL;DR is that the server won't reload if it thinks the changed file is in a templates directory, or in a nested sub directory of a templates directory. This is by design.
To make the dev server reload on all component files, set reload_on_file_change to True. This configures Django to watch for component files too.
Note
This setting should be enabled only for the dev environment!
\ No newline at end of file
diff --git a/dev/guides/setup/syntax_highlight/index.html b/dev/guides/setup/syntax_highlight/index.html
index 2804ca22..ef656221 100644
--- a/dev/guides/setup/syntax_highlight/index.html
+++ b/dev/guides/setup/syntax_highlight/index.html
@@ -1,4 +1,4 @@
- Syntax highlighting - Django-Components Syntax highlighting
VSCode¤
-
First install Python Inline Source Syntax Highlighting extension, it will give you syntax highlighting for the template, CSS, and JS.
-
Next, in your component, set typings of Component.template/css/js to types.django_html, types.css, and types.js respectively. The extension will recognize these and will activate syntax highlighting.
[project root]/components/calendar.py# In a file called [project root]/components/calendar.py
+ Syntax highlighting - Django-Components Syntax highlighting
VSCode¤
-
First install Python Inline Source Syntax Highlighting extension, it will give you syntax highlighting for the template, CSS, and JS.
-
Next, in your component, set typings of Component.template/css/js to types.django_html, types.css, and types.js respectively. The extension will recognize these and will activate syntax highlighting.
[project root]/components/calendar.py# In a file called [project root]/components/calendar.py
from django_components import Component, register, types
@register("calendar")
@@ -8,22 +8,29 @@
"date": date,
}
- template: types.django_html = """
- <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
- """
-
- css: types.css = """
- .calendar-component { width: 200px; background: pink; }
- .calendar-component span { font-weight: bold; }
- """
-
- js: types.js = """
- (function(){
- if (document.querySelector(".calendar-component")) {
- document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
- }
- })()
- """
+ template: types.django_html = """
+ <div class="calendar-component">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
+
+ css: types.css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+
+ js: types.js = """
+ (function(){
+ if (document.querySelector(".calendar-component")) {
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
+ }
+ })()
+ """
Pycharm (or other Jetbrains IDEs)¤
With PyCharm (or any other editor from Jetbrains), you don't need to use types.django_html, types.css, types.js since Pycharm uses language injections. You only need to write the comments # language=<lang> above the variables.
from django_components import Component, register
@register("calendar")
@@ -34,22 +41,52 @@
}
# language=HTML
- template= """
- <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
- """
-
- # language=CSS
- css = """
- .calendar-component { width: 200px; background: pink; }
- .calendar-component span { font-weight: bold; }
- """
-
- # language=JS
- js = """
- (function(){
- if (document.querySelector(".calendar-component")) {
- document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
- }
- })()
- """
-
\ No newline at end of file
+ template= """
+ <div class="calendar-component">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
+
+ # language=CSS
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+
+ # language=JS
+ js = """
+ (function(){
+ if (document.querySelector(".calendar-component")) {
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
+ }
+ })()
+ """
+
Pygments¤
Pygments is a syntax highlighting library written in Python. It's also what's used by this documentation site (mkdocs-material) to highlight code blocks.
To write code blocks with syntax highlighting, you need to install the pygments-djc package.
And then initialize it by importing pygments_djc:
Now you can write code blocks with syntax highlighting.
\```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template= """
+ <div class="calendar-component">
+ Today's date is <span>{{ date }}</span>
+ </div>
+ """
+
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+\```
+
\ No newline at end of file
diff --git a/dev/migrating_from_safer_staticfiles/index.html b/dev/migrating_from_safer_staticfiles/index.html
index ac6af1cb..d2d906d3 100644
--- a/dev/migrating_from_safer_staticfiles/index.html
+++ b/dev/migrating_from_safer_staticfiles/index.html
@@ -1,4 +1,4 @@
- Migrating from safer_staticfiles - Django-Components Migrating from safer_staticfiles¤
This guide is for you if you're upgrating django_components to v0.100 or later from older versions.
In version 0.100, we changed how components' static JS and CSS files are handled. See more in the "Static files" section.
Migration steps:
- Remove
django_components.safer_staticfiles from INSTALLED_APPS in your settings.py, and replace it with django.contrib.staticfiles.
Before:
INSTALLED_APPS = [
+ Migrating from safer_staticfiles - Django-Components Migrating from safer_staticfiles¤
This guide is for you if you're upgrating django_components to v0.100 or later from older versions.
In version 0.100, we changed how components' static JS and CSS files are handled. See more in the "Static files" section.
Migration steps:
- Remove
django_components.safer_staticfiles from INSTALLED_APPS in your settings.py, and replace it with django.contrib.staticfiles.
Before:
INSTALLED_APPS = [
"django.contrib.admin",
...
# "django.contrib.staticfiles", # <-- ADD
diff --git a/dev/overview/code_of_conduct/index.html b/dev/overview/code_of_conduct/index.html
index c9fd0d48..7c23c1da 100644
--- a/dev/overview/code_of_conduct/index.html
+++ b/dev/overview/code_of_conduct/index.html
@@ -1 +1 @@
- Code of Conduct - Django-Components