+
+ """
+
+ class View:
+ # Handle GET requests
+ def get(self, request, *args, **kwargs):
+ # Return HttpResponse with the rendered content
+ return Calendar.render_to_response(
+ request=request,
+ kwargs={
+ "date": request.GET.get("date", "2020-06-06"),
+ },
+ slots={
+ "header": "Calendar header",
+ },
+ )
+```
+
+!!! info
+
+ The View class supports all the same HTTP methods as Django's [`View`](https://docs.djangoproject.com/en/5.2/ref/class-based-views/base/#django.views.generic.base.View) class. These are:
+
+ `get()`, `post()`, `put()`, `patch()`, `delete()`, `head()`, `options()`, `trace()`
+
+ Each of these receive the [`HttpRequest`](https://docs.djangoproject.com/en/5.2/ref/request-response/#django.http.HttpRequest) object as the first argument.
+
+
+
+
+!!! warning
+
+ **Deprecation warning:**
+
+ Previously, the handler methods such as `get()` and `post()` could be defined directly on the `Component` class:
+
+ ```py
+ class Calendar(Component):
+ def get(self, request, *args, **kwargs):
+ return self.render_to_response(
+ kwargs={
+ "date": request.GET.get("date", "2020-06-06"),
+ }
+ )
+ ```
+
+ This is deprecated from v0.137 onwards, and will be removed in v1.0.
+
+### Acccessing component class
+
+You can access the component class from within the View methods by using the [`View.component_cls`](../../../reference/api#django_components.ComponentView.component_cls) attribute:
+
+```py
+class Calendar(Component):
+ ...
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+```
+
+## Register URLs manually
+
+To register the component as a route / endpoint in Django, add an entry to your
+[`urlpatterns`](https://docs.djangoproject.com/en/5.2/topics/http/urls/).
+In place of the view function, create a view object with [`Component.as_view()`](../../../reference/api#django_components.Component.as_view):
+
+```python title="[project root]/urls.py"
+from django.urls import path
+from components.calendar.calendar import Calendar
+
+urlpatterns = [
+ path("calendar/", Calendar.as_view()),
+]
+```
+
+[`Component.as_view()`](../../../reference/api#django_components.Component.as_view)
+internally calls [`View.as_view()`](https://docs.djangoproject.com/en/5.2/ref/class-based-views/base/#django.views.generic.base.View.as_view), passing the component
+instance as one of the arguments.
+
+## Register URLs automatically
+
+If you don't care about the exact URL of the component, you can let django-components manage the URLs for you by setting the [`Component.View.public`](../../../reference/api#django_components.ComponentView.public) attribute to `True`:
+
+```py
+class MyComponent(Component):
+ class View:
+ public = True
+
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+ ...
+```
+
+Then, to get the URL for the component, use [`get_component_url()`](../../../reference/api#django_components.get_component_url):
+
+```py
+from django_components import get_component_url
+
+url = get_component_url(MyComponent)
+```
+
+This way you don't have to mix your app URLs with component URLs.
+
+!!! info
+
+ If you need to pass query parameters or a fragment to the component URL, you can do so by passing the `query` and `fragment` arguments to [`get_component_url()`](../../../reference/api#django_components.get_component_url):
+
+ ```py
+ url = get_component_url(
+ MyComponent,
+ query={"foo": "bar"},
+ fragment="baz",
+ )
+ # /components/ext/view/components/c1ab2c3?foo=bar#baz
+ ```
diff --git a/docs/concepts/fundamentals/components_as_views.md b/docs/concepts/fundamentals/components_as_views.md
deleted file mode 100644
index a9f66042..00000000
--- a/docs/concepts/fundamentals/components_as_views.md
+++ /dev/null
@@ -1,148 +0,0 @@
-_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()`](https://docs.djangoproject.com/en/5.1/ref/class-based-views/base/#django.views.generic.base.View.as_view).
-
-- By default, you can define GET, POST or other HTTP handlers directly on the Component, same as you do with [View](https://docs.djangoproject.com/en/5.1/ref/class-based-views/base/#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`](#inputs-of-render-and-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:
-
-```djc_py
-# In a file called [project root]/components/calendar.py
-from django_components import Component, ComponentView, register
-
-@register("calendar")
-class Calendar(Component):
-
- template = """
-
+ {% slot "header" / %}
+
+
+ Today's date is {{ date }}
+
+
-
- """
-
- # Handle GET requests
- def get(self, request, *args, **kwargs):
- context = {
- "date": request.GET.get("date", "2020-06-06"),
- }
- slots = {
- "header": "Calendar header",
- }
- # Return HttpResponse with the rendered content
- return self.render_to_response(
- context=context,
- slots=slots,
- )
-```
-
-Then, to use this component as a view, you should create a `urls.py` file in your components directory, and add a path to the component's view:
-
-```python
-# In a file called [project root]/components/urls.py
-from django.urls import path
-from components.calendar.calendar import Calendar
-
-urlpatterns = [
- path("calendar/", Calendar.as_view()),
-]
-```
-
-`Component.as_view()` is a shorthand for calling [`View.as_view()`](https://docs.djangoproject.com/en/5.1/ref/class-based-views/base/#django.views.generic.base.View.as_view) and passing the component
-instance as one of the arguments.
-
-Remember to add `__init__.py` to your components directory, so that Django can find the `urls.py` file.
-
-Finally, include the component's urls in your project's `urls.py` file:
-
-```python
-# In a file called [project root]/urls.py
-from django.urls import include, path
-
-urlpatterns = [
- path("components/", include("components.urls")),
-]
-```
-
-Note: Slots content are automatically escaped by default to prevent XSS attacks. To disable escaping, set `escape_slots_content=False` in the `render_to_response` method. If you do so, you should make sure that any content you pass to the slots is safe, especially if it comes from user input.
-
-If you're planning on passing an HTML string, check Django's use of [`format_html`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.html.format_html) and [`mark_safe`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.safestring.mark_safe).
-
-## Modifying the View class
-
-The View class that handles the requests is defined on `Component.View`.
-
-When you define a GET or POST handlers on the `Component` class, like so:
-
-```py
-class MyComponent(Component):
- def get(self, request, *args, **kwargs):
- return self.render_to_response(
- context={
- "date": request.GET.get("date", "2020-06-06"),
- },
- )
-
- def post(self, request, *args, **kwargs) -> HttpResponse:
- variable = request.POST.get("variable")
- return self.render_to_response(
- kwargs={"variable": variable}
- )
-```
-
-Then the request is still handled by `Component.View.get()` or `Component.View.post()`
-methods. However, by default, `Component.View.get()` points to `Component.get()`, and so on.
-
-```py
-class ComponentView(View):
- component: Component = None
- ...
-
- def get(self, request, *args, **kwargs):
- return self.component.get(request, *args, **kwargs)
-
- def post(self, request, *args, **kwargs):
- return self.component.post(request, *args, **kwargs)
-
- ...
-```
-
-If you want to define your own `View` class, you need to:
-
-1. Set the class as `Component.View`
-2. Subclass from `ComponentView`, so the View instance has access to the component instance.
-
-In the example below, we added extra logic into `View.setup()`.
-
-Note that the POST handler is still defined at the top. This is because `View` subclasses `ComponentView`, which defines the `post()` method that calls `Component.post()`.
-
-If you were to overwrite the `View.post()` method, then `Component.post()` would be ignored.
-
-```py
-from django_components import Component, ComponentView
-
-class MyComponent(Component):
-
- def post(self, request, *args, **kwargs) -> HttpResponse:
- variable = request.POST.get("variable")
- return self.component.render_to_response(
- kwargs={"variable": variable}
- )
-
- class View(ComponentView):
- def setup(self, request, *args, **kwargs):
- super(request, *args, **kwargs)
-
- do_something_extra(request, *args, **kwargs)
-```
diff --git a/docs/concepts/fundamentals/components_in_python.md b/docs/concepts/fundamentals/components_in_python.md
deleted file mode 100644
index 1cf569f1..00000000
--- a/docs/concepts/fundamentals/components_in_python.md
+++ /dev/null
@@ -1,134 +0,0 @@
-_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:
-
-```djc_py
-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 {
- "hello": arg1,
- "foo": arg2,
- "kwargs": kwargs,
- }
-
-rendered = SimpleComponent.render(
- args=["world", "bar"],
- kwargs={"kw1": "test", "kw2": "ooo"},
- slots={"first": "FIRST_SLOT"},
- context={"from_context": 98},
-)
-```
-
-Renders:
-
-```
-hello: world
-foo: bar
-kwargs: {'kw1': 'test', 'kw2': 'ooo'}
-slot_first: FIRST_SLOT
-```
-
-## Inputs of `render` and `render_to_response`
-
-Both `render` and `render_to_response` accept the same input:
-
-```py
-Component.render(
- context: Mapping | django.template.Context | None = None,
- args: List[Any] | None = None,
- kwargs: Dict[str, Any] | None = None,
- slots: Dict[str, str | SafeString | SlotFunc] | None = None,
- escape_slots_content: bool = True
-) -> str:
-```
-
-- _`args`_ - Positional args for the component. This is the same as calling the component
- as `{% component "my_comp" arg1 arg2 ... %}`
-
-- _`kwargs`_ - Keyword args for the component. This is the same as calling the component
- as `{% component "my_comp" key1=val1 key2=val2 ... %}`
-
-- _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
- Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
- or [`SlotFunc`](#slotfunc).
-
-- _`escape_slots_content`_ - Whether the content from `slots` should be escaped. `True` by default to prevent XSS attacks. If you disable escaping, you should make sure that any content you pass to the slots is safe, especially if it comes from user input.
-
-- _`context`_ - A context (dictionary or Django's Context) within which the component
- is rendered. The keys on the context can be accessed from within the template.
- - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
- component's args and kwargs.
-
-- _`request`_ - A Django request object. This is used to enable Django template `context_processors` to run,
- allowing for template tags like `{% csrf_token %}` and variables like `{{ debug }}`.
- - Similar behavior can be achieved with [provide / inject](#how-to-use-provide--inject).
- - This is used internally to convert `context` to a RequestContext. It does nothing if `context` is already
- a `Context` instance.
-
-### `SlotFunc`
-
-When rendering components with slots in `render` or `render_to_response`, you can pass either a string or a function.
-
-The function has following signature:
-
-```py
-def render_func(
- context: Context,
- data: Dict[str, Any],
- slot_ref: SlotRef,
-) -> str | SafeString:
- return nodelist.render(ctx)
-```
-
-- _`context`_ - Django's Context available to the Slot Node.
-- _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
-- _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
- - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
-
-Example:
-
-```py
-def footer_slot(ctx, data, slot_ref):
- return f"""
- SLOT_DATA: {data['abc']}
- ORIGINAL: {slot_ref}
- """
-
-MyComponent.render_to_response(
- slots={
- "footer": footer_slot,
- },
-)
-```
-
-## Response class of `render_to_response`
-
-While `render` method returns a plain string, `render_to_response` wraps the rendered content in a "Response" class. By default, this is `django.http.HttpResponse`.
-
-If you want to use a different Response class in `render_to_response`, set the `Component.response_class` attribute:
-
-```py
-class MyResponse(HttpResponse):
- def __init__(self, *args, **kwargs) -> None:
- super().__init__(*args, **kwargs)
- # Configure response
- self.headers = ...
- self.status = ...
-
-class SimpleComponent(Component):
- response_class = MyResponse
- template: types.django_html = "HELLO"
-
-response = SimpleComponent.render_to_response()
-assert isinstance(response, MyResponse)
-```
diff --git a/docs/concepts/fundamentals/html_attributes.md b/docs/concepts/fundamentals/html_attributes.md
index 8cde6912..22b111d3 100644
--- a/docs/concepts/fundamentals/html_attributes.md
+++ b/docs/concepts/fundamentals/html_attributes.md
@@ -47,10 +47,10 @@ You can use this for example to allow users of your component to add extra attri
```djc_py
@register("my_comp")
class MyComp(Component):
- # Capture extra kwargs in `attrs`
- def get_context_data(self, **attrs):
+ # Pass all kwargs as `attrs`
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs,
"classes": "text-red",
"my_id": 123,
}
@@ -329,7 +329,7 @@ Renders:
```
-### Merging `style` Attributes
+### Merging `style` attributes
The `style` attribute can be specified as a string of style properties as usual.
@@ -364,8 +364,8 @@ If you want granular control over individual style properties, you can use a dic
If a style property is specified multiple times, the last value is used.
-- If the last time the property is set is `False`, the property is removed.
- Properties set to `None` are ignored.
+- If the last non-`None` instance of the property is set to `False`, the property is removed.
**Example:**
@@ -607,10 +607,11 @@ class MyComp(Component):
"""
- def get_context_data(self, date: Date, attrs: dict):
+ def get_template_data(self, args, kwargs, slots, context):
+ date = kwargs.pop("date")
return {
"date": date,
- "attrs": attrs,
+ "attrs": kwargs,
"class_from_var": "extra-class"
}
@@ -625,7 +626,7 @@ class Parent(Component):
/ %}
"""
- def get_context_data(self, date: Date):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"date": datetime.now(),
"json_data": json.dumps({"value": 456})
@@ -669,7 +670,7 @@ So all kwargs that start with `attrs:` will be collected into an `attrs` dict.
attrs:@click="(e) => onClick(e, 'from_parent')"
```
-And `get_context_data` of `MyComp` will receive `attrs` input with following keys:
+And `get_template_data` of `MyComp` will receive a kwarg named `attrs` with following keys:
```py
attrs = {
diff --git a/docs/concepts/fundamentals/html_js_css_files.md b/docs/concepts/fundamentals/html_js_css_files.md
new file mode 100644
index 00000000..296f02e1
--- /dev/null
+++ b/docs/concepts/fundamentals/html_js_css_files.md
@@ -0,0 +1,441 @@
+## Overview
+
+Each component can have single "primary" HTML, CSS and JS file associated with them.
+
+Each of these can be either defined inline, or in a separate file:
+
+- HTML files are defined using [`Component.template`](../../reference/api.md#django_components.Component.template) or [`Component.template_file`](../../reference/api.md#django_components.Component.template_file)
+- CSS files are defined using [`Component.css`](../../reference/api.md#django_components.Component.css) or [`Component.css_file`](../../reference/api.md#django_components.Component.css_file)
+- JS files are defined using [`Component.js`](../../reference/api.md#django_components.Component.js) or [`Component.js_file`](../../reference/api.md#django_components.Component.js_file)
+
+```py
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+ css_file = "calendar.css"
+ js_file = "calendar.js"
+```
+
+or
+
+```djc_py
+@register("calendar")
+class Calendar(Component):
+ template = """
+
- {% slot "header" / %}
-
-
- Today's date is {{ date }}
-
-
+ Hi there!
+
+ """
+ css = """
+ .welcome {
+ color: red;
+ }
+ """
+ js = """
+ console.log("Hello, world!");
+ """
+```
+
+These "primary" files will have special behavior. For example, each will receive variables from the component's data methods.
+Read more about each file type below:
+
+- [HTML](#html)
+- [CSS](#css)
+- [JS](#js)
+
+In addition, you can define extra "secondary" CSS / JS files using the nested [`Component.Media`](../../reference/api.md#django_components.Component.Media) class,
+by setting [`Component.Media.js`](../../reference/api.md#django_components.ComponentMediaInput.js) and [`Component.Media.css`](../../reference/api.md#django_components.ComponentMediaInput.css).
+
+Single component can have many secondary files. There is no special behavior for them.
+
+You can use these for third-party libraries, or for shared CSS / JS files.
+
+Read more about [Secondary JS / CSS files](../secondary_js_css_files).
+
+!!! warning
+
+ You **cannot** use both inlined code **and** separate file for a single language type (HTML, CSS, JS).
+
+ However, you can freely mix these for different languages:
+
+ ```djc_py
+ class MyTable(Component):
+ template: types.django_html = """
+
+ Hi there!
+
+ """
+ js_file = "my_table.js"
+ css_file = "my_table.css"
+ ```
+
+## HTML
+
+Components use Django's template system to define their HTML.
+This means that you can use [Django's template syntax](https://docs.djangoproject.com/en/5.2/ref/templates/language/) to define your HTML.
+
+Inside the template, you can access the data returned from the [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data) method.
+
+You can define the HTML directly in your Python code using the [`template`](../../reference/api.md#django_components.Component.template) attribute:
+
+```djc_py
+class Button(Component):
+ template = """
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "text": kwargs.get("text", "Click me"),
+ "icon": kwargs.get("icon", None),
+ }
+```
+
+Or you can define the HTML in a separate file and reference it using [`template_file`](../../reference/api.md#django_components.Component.template_file):
+
+```python
+class Button(Component):
+ template_file = "button.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "text": kwargs.get("text", "Click me"),
+ "icon": kwargs.get("icon", None),
+ }
+```
+
+```django title="button.html"
+
+```
+
+### Dynamic templates
+
+Each component has only a single template associated with it.
+
+However, whether it's for A/B testing or for preserving public API
+when sharing your components, sometimes you may need to render different templates
+based on the input to your component.
+
+You can use [`Component.on_render()`](../../reference/api.md#django_components.Component.on_render)
+to dynamically override what template gets rendered.
+
+By default, the component's template is rendered as-is.
+
+```py
+class Table(Component):
+ def on_render(self, context: Context, template: Optional[Template]):
+ if template is not None:
+ return template.render(context)
+```
+
+If you want to render a different template in its place,
+we recommended you to:
+
+1. Wrap the substitute templates as new Components
+2. Then render those Components inside [`Component.on_render()`](../../reference/api.md#django_components.Component.on_render):
+
+```py
+class TableNew(Component):
+ template_file = "table_new.html"
+
+class TableOld(Component):
+ template_file = "table_old.html"
+
+class Table(Component):
+ def on_render(self, context, template):
+ if self.kwargs.get("feat_table_new_ui"):
+ return TableNew.render(
+ args=self.args,
+ kwargs=self.kwargs,
+ slots=self.slots,
+ )
+ else:
+ return TableOld.render(
+ args=self.args,
+ kwargs=self.kwargs,
+ slots=self.slots,
+ )
+```
+
+!!! warning
+
+ If you do not wrap the templates as Components,
+ there is a risk that some [extensions](../../advanced/extensions) will not work as expected.
+
+ ```py
+ new_template = Template("""
+ {% load django_components %}
+
+ {% slot "content" %}
+ Other template
+ {% endslot %}
+
+ """)
+
+ class Table(Component):
+ def on_render(self, context, template):
+ if self.kwargs.get("feat_table_new_ui"):
+ return new_template.render(context)
+ else:
+ return template.render(context)
+ ```
+
+### Template-less components
+
+Since you can use [`Component.on_render()`](../../reference/api.md#django_components.Component.on_render)
+to render *other* components, there is no need to define a template for the component.
+
+So even an empty component like this is valid:
+
+```py
+class MyComponent(Component):
+ pass
+```
+
+These "template-less" components can be useful as base classes for other components, or as mixins.
+
+### HTML processing
+
+Django Components expects the rendered template to be a valid HTML. This is needed to enable features like [CSS / JS variables](../html_js_css_variables).
+
+Here is how the HTML is post-processed:
+
+1. **Insert component ID**: Each root element in the rendered HTML automatically receives a `data-djc-id-cxxxxxx` attribute containing a unique component instance ID.
+
+ ```html
+
+
+ ...
+
+
+ ...
+
+ ```
+
+2. **Insert CSS ID**: If the component defines CSS variables through [`get_css_data()`](../../../reference/api/#django_components.Component.get_css_data), the root elements also receive a `data-djc-css-xxxxxx` attribute. This attribute links the element to its specific CSS variables.
+
+ ```html
+
+
+
+
+ ```
+
+3. **Insert JS and CSS**: After the HTML is rendered, Django Components handles inserting JS and CSS dependencies into the page based on the [dependencies rendering strategy](../rendering_components/#dependencies-rendering) (document, fragment, or inline).
+
+ For example, if your component contains the
+ [`{% component_js_dependencies %}`](../../reference/template_tags.md#component_js_dependencies)
+ or
+ [`{% component_css_dependencies %}`](../../reference/template_tags.md#component_css_dependencies)
+ tags, or the `` and `` elements, the JS and CSS scripts will be inserted into the HTML.
+
+ For more information on how JS and CSS dependencies are rendered, see [Rendering JS / CSS](../../advanced/rendering_js_css).
+
+## JS
+
+The component's JS script is executed in the browser:
+
+- It is executed AFTER the "secondary" JS files from [`Component.Media.js`](../../reference/api.md#django_components.ComponentMediaInput.js) are loaded.
+- The script is only executed once, even if there are multiple instances of the component on the page.
+- Component JS scripts are executed in the order how they appeared in the template / HTML (top to bottom).
+
+You can define the JS directly in your Python code using the [`js`](../../reference/api.md#django_components.Component.js) attribute:
+
+```djc_py
+class Button(Component):
+ js = """
+ console.log("Hello, world!");
+ """
+
+ def get_js_data(self, args, kwargs, slots, context):
+ return {
+ "text": kwargs.get("text", "Click me"),
+ }
+```
+
+Or you can define the JS in a separate file and reference it using [`js_file`](../../reference/api.md#django_components.Component.js_file):
+
+```python
+class Button(Component):
+ js_file = "button.js"
+
+ def get_js_data(self, args, kwargs, slots, context):
+ return {
+ "text": kwargs.get("text", "Click me"),
+ }
+```
+
+```django title="button.js"
+console.log("Hello, world!");
+```
+
+## CSS
+
+You can define the CSS directly in your Python code using the [`css`](../../reference/api.md#django_components.Component.css) attribute:
+
+```djc_py
+class Button(Component):
+ css = """
+ .btn {
+ width: 100px;
+ color: var(--color);
+ }
+ """
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return {
+ "color": kwargs.get("color", "red"),
+ }
+```
+
+Or you can define the CSS in a separate file and reference it using [`css_file`](../../reference/api.md#django_components.Component.css_file):
+
+```python
+class Button(Component):
+ css_file = "button.css"
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return {
+ "text": kwargs.get("text", "Click me"),
+ }
+```
+
+```django title="button.css"
+.btn {
+ color: red;
+}
+```
+
+## File paths
+
+Compared to the [secondary JS / CSS files](../secondary_js_css_files), the definition of file paths for the main HTML / JS / CSS files is quite simple - just strings, without any lists, objects, or globs.
+
+However, similar to the secondary JS / CSS files, you can specify the file paths [relative to the component's directory](../secondary_js_css_files/#relative-to-component).
+
+So if you have a directory with following files:
+
+```
+[project root]/components/calendar/
+├── calendar.html
+├── calendar.css
+├── calendar.js
+└── calendar.py
+```
+
+You can define the component like this:
+
+```py title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+ css_file = "calendar.css"
+ js_file = "calendar.js"
+```
+
+Assuming that
+[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
+contains path `[project root]/components`, the example above is the same as writing out:
+
+```py title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar/template.html"
+ css_file = "calendar/style.css"
+ js_file = "calendar/script.js"
+```
+
+If the path cannot be resolved relative to the component, django-components will attempt
+to resolve the path relative to the component directories, as set in
+[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
+or
+[`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs).
+
+Read more about [file path resolution](../secondary_js_css_files/#relative-to-component).
+
+## Access component definition
+
+Component's HTML / CSS / JS is resolved and loaded lazily.
+
+This means that, when you specify any of
+[`template_file`](../../reference/api.md#django_components.Component.template_file),
+[`js_file`](../../reference/api.md#django_components.Component.js_file),
+[`css_file`](../../reference/api.md#django_components.Component.css_file),
+or [`Media.js/css`](../../reference/api.md#django_components.Component.Media),
+these file paths will be resolved only once you either:
+
+1. Access any of the following attributes on the component:
+
+ - [`media`](../../reference/api.md#django_components.Component.media),
+ [`template`](../../reference/api.md#django_components.Component.template),
+ [`template_file`](../../reference/api.md#django_components.Component.template_file),
+ [`js`](../../reference/api.md#django_components.Component.js),
+ [`js_file`](../../reference/api.md#django_components.Component.js_file),
+ [`css`](../../reference/api.md#django_components.Component.css),
+ [`css_file`](../../reference/api.md#django_components.Component.css_file)
+
+2. Render the component.
+
+Once the component's media files have been loaded once, they will remain in-memory
+on the Component class:
+
+- HTML from [`Component.template_file`](../../reference/api.md#django_components.Component.template_file)
+ will be available under [`Component.template`](../../reference/api.md#django_components.Component.template)
+- CSS from [`Component.css_file`](../../reference/api.md#django_components.Component.css_file)
+ will be available under [`Component.css`](../../reference/api.md#django_components.Component.css)
+- JS from [`Component.js_file`](../../reference/api.md#django_components.Component.js_file)
+ will be available under [`Component.js`](../../reference/api.md#django_components.Component.js)
+
+Thus, whether you define HTML via
+[`Component.template_file`](../../reference/api.md#django_components.Component.template_file)
+or [`Component.template`](../../reference/api.md#django_components.Component.template),
+you can always access the HTML content under [`Component.template`](../../reference/api.md#django_components.Component.template).
+And the same applies for JS and CSS.
+
+**Example:**
+
+```py
+# When we create Calendar component, the files like `calendar/template.html`
+# are not yet loaded!
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar/template.html"
+ css_file = "calendar/style.css"
+ js_file = "calendar/script.js"
+
+ class Media:
+ css = "calendar/style1.css"
+ js = "calendar/script2.js"
+
+# It's only at this moment that django-components reads the files like `calendar/template.html`
+print(Calendar.css)
+# Output:
+# .calendar {
+# 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.
diff --git a/docs/concepts/fundamentals/html_js_css_variables.md b/docs/concepts/fundamentals/html_js_css_variables.md
new file mode 100644
index 00000000..b7164e06
--- /dev/null
+++ b/docs/concepts/fundamentals/html_js_css_variables.md
@@ -0,0 +1,496 @@
+When a component recieves input through [`{% component %}`](../../../reference/template_tags/#component) tag,
+or the [`Component.render()`](../../../reference/api/#django_components.Component.render) or [`Component.render_to_response()`](../../../reference/api/#django_components.Component.render_to_response) methods, you can define how the input is handled, and what variables will be available to the template, JavaScript and CSS.
+
+## Overview
+
+Django Components offers three key methods for passing variables to different parts of your component:
+
+- [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data) - Provides variables to your HTML template
+- [`get_js_data()`](../../../reference/api/#django_components.Component.get_js_data) - Provides variables to your JavaScript code
+- [`get_css_data()`](../../../reference/api/#django_components.Component.get_css_data) - Provides variables to your CSS styles
+
+These methods let you pre-process inputs before they're used in rendering.
+
+Each method handles the data independently - you can define different data for the template, JS, and CSS.
+
+```python
+class ProfileCard(Component):
+ class Kwargs(NamedTuple):
+ user_id: int
+ show_details: bool
+
+ class Defaults:
+ show_details = True
+
+ def get_template_data(self, args, kwargs: Kwargs, slots, context):
+ user = User.objects.get(id=kwargs.user_id)
+ return {
+ "user": user,
+ "show_details": kwargs.show_details,
+ }
+
+ def get_js_data(self, args, kwargs: Kwargs, slots, context):
+ return {
+ "user_id": kwargs.user_id,
+ }
+
+ def get_css_data(self, args, kwargs: Kwargs, slots, context):
+ text_color = "red" if kwargs.show_details else "blue"
+ return {
+ "text_color": text_color,
+ }
+```
+
+## Template variables
+
+The [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data) method is the primary way to provide variables to your HTML template. It receives the component inputs and returns a dictionary of data that will be available in the template.
+
+If [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data) returns `None`, an empty dictionary will be used.
+
+```python
+class ProfileCard(Component):
+ template_file = "profile_card.html"
+
+ class Kwargs(NamedTuple):
+ user_id: int
+ show_details: bool
+
+ def get_template_data(self, args, kwargs: Kwargs, slots, context):
+ user = User.objects.get(id=kwargs.user_id)
+
+ # Process and transform inputs
+ return {
+ "user": user,
+ "show_details": kwargs.show_details,
+ "user_joined_days": (timezone.now() - user.date_joined).days,
+ }
+```
+
+In your template, you can then use these variables:
+
+```django
+
+
+```
+
+### Legacy `get_context_data()`
+
+The [`get_context_data()`](../../../reference/api/#django_components.Component.get_context_data) method is the legacy way to provide variables to your HTML template. It serves the same purpose as [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data) - it receives the component inputs and returns a dictionary of data that will be available in the template.
+
+However, [`get_context_data()`](../../../reference/api/#django_components.Component.get_context_data) has a few drawbacks:
+
+- It does NOT receive the `slots` and `context` parameters.
+- The `args` and `kwargs` parameters are given as variadic `*args` and `**kwargs` parameters. As such, they cannot be typed.
+
+```python
+class ProfileCard(Component):
+ template_file = "profile_card.html"
+
+ def get_context_data(self, user_id, show_details=False, *args, **kwargs):
+ user = User.objects.get(id=user_id)
+ return {
+ "user": user,
+ "show_details": show_details,
+ }
+```
+
+There is a slight difference between [`get_context_data()`](../../../reference/api/#django_components.Component.get_context_data) and [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data)
+when rendering a component with the [`{% component %}`](../../../reference/template_tags/#component) tag.
+
+For example if you have component that accepts kwarg `date`:
+
+```py
+class MyComponent(Component):
+ def get_context_data(self, date, *args, **kwargs):
+ return {
+ "date": date,
+ }
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"],
+ }
+```
+
+The difference is that:
+
+- With [`get_context_data()`](../../../reference/api/#django_components.Component.get_context_data), you can pass `date` either as arg or kwarg:
+
+ ```django
+ ✅
+ {% component "my_component" date=some_date %}
+ {% component "my_component" some_date %}
+ ```
+
+- But with [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data), `date` MUST be passed as kwarg:
+
+ ```django
+ ✅
+ {% component "my_component" date=some_date %}
+
+ ❌
+ {% component "my_component" some_date %}
+ ```
+
+!!! warning
+
+ [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data)
+ and [`get_context_data()`](../../../reference/api/#django_components.Component.get_context_data)
+ are mutually exclusive.
+
+ If both methods return non-empty dictionaries, an error will be raised.
+
+!!! note
+
+ The `get_context_data()` method will be removed in v2.
+
+## Accessing component inputs
+
+The component inputs are available in 3 ways:
+
+### Function arguments
+
+The data methods receive the inputs as parameters directly.
+
+```python
+class ProfileCard(Component):
+ # Access inputs directly as parameters
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "user_id": args[0],
+ "show_details": kwargs["show_details"],
+ }
+```
+
+!!! info
+
+ By default, the `args` parameter is a list, while `kwargs` and `slots` are dictionaries.
+
+ If you add typing to your component with
+ [`Args`](../../../reference/api/#django_components.Component.Args),
+ [`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+ or [`Slots`](../../../reference/api/#django_components.Component.Slots) classes,
+ the respective inputs will be given as instances of these classes.
+
+ Learn more about [Component typing](../../fundamentals/typing_and_validation).
+
+ ```py
+ class ProfileCard(Component):
+ class Args(NamedTuple):
+ user_id: int
+
+ class Kwargs(NamedTuple):
+ show_details: bool
+
+ # Access inputs directly as parameters
+ def get_template_data(self, args: Args, kwargs: Kwargs, slots, context):
+ return {
+ "user_id": args.user_id,
+ "show_details": kwargs.show_details,
+ }
+ ```
+
+### `args`, `kwargs`, `slots` properties
+
+In other methods, you can access the inputs via
+[`self.args`](../../../reference/api/#django_components.Component.args),
+[`self.kwargs`](../../../reference/api/#django_components.Component.kwargs),
+and [`self.slots`](../../../reference/api/#django_components.Component.slots) properties:
+
+```py
+class ProfileCard(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]):
+ # Access inputs via self.args, self.kwargs, self.slots
+ self.args[0]
+ self.kwargs.get("show_details", False)
+ self.slots["footer"]
+```
+
+!!! info
+
+ These properties work the same way as `args`, `kwargs`, and `slots` parameters in the data methods:
+
+ By default, the `args` property is a list, while `kwargs` and `slots` are dictionaries.
+
+ If you add typing to your component with
+ [`Args`](../../../reference/api/#django_components.Component.Args),
+ [`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+ or [`Slots`](../../../reference/api/#django_components.Component.Slots) classes,
+ the respective inputs will be given as instances of these classes.
+
+ Learn more about [Component typing](../../fundamentals/typing_and_validation).
+
+ ```py
+ class ProfileCard(Component):
+ class Args(NamedTuple):
+ user_id: int
+
+ class Kwargs(NamedTuple):
+ show_details: bool
+
+ def get_template_data(self, args: Args, kwargs: Kwargs, slots, context):
+ return {
+ "user_id": self.args.user_id,
+ "show_details": self.kwargs.show_details,
+ }
+ ```
+
+
+
+### `input` property (low-level)
+
+!!! warning
+
+ The `input` property is deprecated and will be removed in v1.
+
+ Instead, use properties defined on the
+ [`Component`](../../../reference/api/#django_components.Component) class
+ directly like
+ [`self.context`](../../../reference/api/#django_components.Component.context).
+
+ To access the unmodified inputs, use
+ [`self.raw_args`](../../../reference/api/#django_components.Component.raw_args),
+ [`self.raw_kwargs`](../../../reference/api/#django_components.Component.raw_kwargs),
+ and [`self.raw_slots`](../../../reference/api/#django_components.Component.raw_slots) properties.
+
+The previous two approaches allow you to access only the most important inputs.
+
+There are additional settings that may be passed to components.
+If you need to access these, you can use [`self.input`](../../../reference/api/#django_components.Component.input) property
+for a low-level access to all the inputs.
+
+The `input` property contains all the inputs passed to the component (instance of [`ComponentInput`](../../../reference/api/#django_components.ComponentInput)).
+
+This includes:
+
+- [`input.args`](../../../reference/api/#django_components.ComponentInput.args) - List of positional arguments
+- [`input.kwargs`](../../../reference/api/#django_components.ComponentInput.kwargs) - Dictionary of keyword arguments
+- [`input.slots`](../../../reference/api/#django_components.ComponentInput.slots) - Dictionary of slots. Values are normalized to [`Slot`](../../../reference/api/#django_components.Slot) instances
+- [`input.context`](../../../reference/api/#django_components.ComponentInput.context) - [`Context`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context) object that should be used to render the component
+- [`input.type`](../../../reference/api/#django_components.ComponentInput.type) - The type of the component (document, fragment)
+- [`input.render_dependencies`](../../../reference/api/#django_components.ComponentInput.render_dependencies) - Whether to render dependencies (CSS, JS)
+
+```python
+class ProfileCard(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access positional arguments
+ user_id = self.input.args[0] if self.input.args else None
+
+ # Access keyword arguments
+ show_details = self.input.kwargs.get("show_details", False)
+
+ # Render component differently depending on the type
+ if self.input.type == "fragment":
+ ...
+
+ return {
+ "user_id": user_id,
+ "show_details": show_details,
+ }
+```
+
+!!! info
+
+ Unlike the parameters passed to the data methods, the `args`, `kwargs`, and `slots` in `self.input` property are always lists and dictionaries,
+ regardless of whether you added typing classes to your component (like [`Args`](../../../reference/api/#django_components.Component.Args),
+ [`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+ or [`Slots`](../../../reference/api/#django_components.Component.Slots)).
+
+## Default values
+
+You can use [`Defaults`](../../../reference/api/#django_components.Component.Defaults) class to provide default values for your inputs.
+
+These defaults will be applied either when:
+
+- The input is not provided at rendering time
+- The input is provided as `None`
+
+When you then access the inputs in your data methods, the default values will be already applied.
+
+Read more about [Component Defaults](./component_defaults.md).
+
+```py
+from django_components import Component, Default, register
+
+@register("profile_card")
+class ProfileCard(Component):
+ class Kwargs(NamedTuple):
+ show_details: bool
+
+ class Defaults:
+ show_details = True
+
+ # show_details will be set to True if `None` or missing
+ def get_template_data(self, args, kwargs: Kwargs, slots, context):
+ return {
+ "show_details": kwargs.show_details,
+ }
+
+ ...
+```
+
+!!! warning
+
+ When typing your components with [`Args`](../../../reference/api/#django_components.Component.Args),
+ [`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+ or [`Slots`](../../../reference/api/#django_components.Component.Slots) classes,
+ you may be inclined to define the defaults in the classes.
+
+ ```py
+ class ProfileCard(Component):
+ class Kwargs(NamedTuple):
+ show_details: bool = True
+ ```
+
+ This is **NOT recommended**, because:
+
+ - The defaults will NOT be applied to inputs when using [`self.raw_kwargs`](../../../reference/api/#django_components.Component.raw_kwargs) property.
+ - The defaults will NOT be applied when a field is given but set to `None`.
+
+ Instead, define the defaults in the [`Defaults`](../../../reference/api/#django_components.Component.Defaults) class.
+
+## Accessing Render API
+
+All three data methods have access to the Component's [Render API](../render_api), which includes:
+
+- [`self.args`](../render_api/#args) - The positional arguments for the current render call
+- [`self.kwargs`](../render_api/#kwargs) - The keyword arguments for the current render call
+- [`self.slots`](../render_api/#slots) - The slots for the current render call
+- [`self.raw_args`](../render_api/#args) - Unmodified positional arguments for the current render call
+- [`self.raw_kwargs`](../render_api/#kwargs) - Unmodified keyword arguments for the current render call
+- [`self.raw_slots`](../render_api/#slots) - Unmodified slots for the current render call
+- [`self.context`](../render_api/#context) - The context for the current render call
+- [`self.id`](../render_api/#component-id) - The unique ID for the current render call
+- [`self.request`](../render_api/#request-and-context-processors) - The request object
+- [`self.context_processors_data`](../render_api/#request-and-context-processors) - Data from Django's context processors
+- [`self.inject()`](../render_api/#provide-inject) - Inject data into the component
+- [`self.registry`](../render_api/#template-tag-metadata) - The [`ComponentRegistry`](../../../reference/api/#django_components.ComponentRegistry) instance
+- [`self.registered_name`](../render_api/#template-tag-metadata) - The name under which the component was registered
+- [`self.outer_context`](../render_api/#template-tag-metadata) - The context outside of the [`{% component %}`](../../../reference/template_tags#component) tag
+- `self.deps_strategy` - The strategy for rendering dependencies
+
+## Type hints
+
+### Typing inputs
+
+You can add type hints for the component inputs to ensure that the component logic is correct.
+
+For this, define the [`Args`](../../../reference/api/#django_components.Component.Args),
+[`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+and [`Slots`](../../../reference/api/#django_components.Component.Slots) classes,
+and then add type hints to the data methods.
+
+This will also validate the inputs at runtime, as the type classes will be instantiated with the inputs.
+
+Read more about [Component typing](../../fundamentals/typing_and_validation).
+
+```python
+from typing import NamedTuple, Optional
+from django_components import Component, SlotInput
+
+class Button(Component):
+ class Args(NamedTuple):
+ name: str
+
+ class Kwargs(NamedTuple):
+ surname: str
+ maybe_var: Optional[int] = None # May be omitted
+
+ class Slots(NamedTuple):
+ my_slot: Optional[SlotInput] = None
+ footer: SlotInput
+
+ # Use the above classes to add type hints to the data method
+ def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
+ # The parameters are instances of the classes we defined
+ assert isinstance(args, Button.Args)
+ assert isinstance(kwargs, Button.Kwargs)
+ assert isinstance(slots, Button.Slots)
+```
+
+!!! note
+
+ To access "untyped" inputs, use [`self.raw_args`](../../../reference/api/#django_components.Component.raw_args),
+ [`self.raw_kwargs`](../../../reference/api/#django_components.Component.raw_kwargs),
+ and [`self.raw_slots`](../../../reference/api/#django_components.Component.raw_slots) properties.
+
+ These are plain lists and dictionaries, even when you added typing to your component.
+
+### Typing data
+
+In the same fashion, you can add types and validation for the data that should be RETURNED from each data method.
+
+For this, set the [`TemplateData`](../../../reference/api/#django_components.Component.TemplateData),
+[`JsData`](../../../reference/api/#django_components.Component.JsData),
+and [`CssData`](../../../reference/api/#django_components.Component.CssData) classes on the component class.
+
+For each data method, you can either return a plain dictionary with the data, or an instance of the respective data class.
+
+```python
+from typing import NamedTuple
+from django_components import Component
+
+class Button(Component):
+ class TemplateData(NamedTuple):
+ data1: str
+ data2: int
+
+ class JsData(NamedTuple):
+ js_data1: str
+ js_data2: int
+
+ class CssData(NamedTuple):
+ css_data1: str
+ css_data2: int
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return Button.TemplateData(
+ data1="...",
+ data2=123,
+ )
+
+ def get_js_data(self, args, kwargs, slots, context):
+ return Button.JsData(
+ js_data1="...",
+ js_data2=123,
+ )
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return Button.CssData(
+ css_data1="...",
+ css_data2=123,
+ )
+```
+
+## Pass-through kwargs
+
+It's best practice to explicitly define what args and kwargs a component accepts.
+
+However, if you want a looser setup, you can easily write components that accept any number
+of kwargs, and pass them all to the template
+(similar to [django-cotton](https://github.com/wrabit/django-cotton)).
+
+To do that, simply return the `kwargs` dictionary itself from [`get_template_data()`](../../../reference/api/#django_components.Component.get_template_data):
+
+```py
+class MyComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return kwargs
+```
+
+You can do the same for [`get_js_data()`](../../../reference/api/#django_components.Component.get_js_data) and [`get_css_data()`](../../../reference/api/#django_components.Component.get_css_data), if needed:
+
+```py
+class MyComponent(Component):
+ def get_js_data(self, args, kwargs, slots, context):
+ return kwargs
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return kwargs
+```
diff --git a/docs/concepts/fundamentals/http_request.md b/docs/concepts/fundamentals/http_request.md
index 06c9d586..148fdc7b 100644
--- a/docs/concepts/fundamentals/http_request.md
+++ b/docs/concepts/fundamentals/http_request.md
@@ -1,25 +1,22 @@
-The most common use of django-components is to render HTML for a given request. As such,
+The most common use of django-components is to render HTML when the server receives a request. As such,
there are a few features that are dependent on the request object.
-## Passing and accessing HttpRequest
+## Passing the HttpRequest object
-In regular Django templates, the request object is available only within the `RequestContext`.
+In regular Django templates, the request object is available only within the [`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext).
-In Components, you can either use `RequestContext`, or pass the `request` object
+In Components, you can either use [`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext), or pass the `request` object
explicitly to [`Component.render()`](../../../reference/api#django_components.Component.render) and
[`Component.render_to_response()`](../../../reference/api#django_components.Component.render_to_response).
-When a component is nested in another, the child component uses parent's `request` object.
+So the request object is available to components either when:
-You can access the request object under [`Component.request`](../../../reference/api#django_components.Component.request):
+- The component is rendered with [`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext) (Regular Django behavior)
+- The component is rendered with a regular [`Context`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context) (or none), but you set the `request` kwarg
+ of [`Component.render()`](../../../reference/api#django_components.Component.render).
+- The component is nested and the parent has access to the request object.
```python
-class MyComponent(Component):
- def get_context_data(self):
- return {
- 'user_id': self.request.GET['user_id'],
- }
-
# ✅ With request
MyComponent.render(request=request)
MyComponent.render(context=RequestContext(request, {}))
@@ -29,31 +26,7 @@ MyComponent.render()
MyComponent.render(context=Context({}))
```
-## Context Processors
-
-Components support Django's [context processors](https://docs.djangoproject.com/en/5.1/ref/templates/api/#using-requestcontext).
-
-In regular Django templates, the context processors are applied only when the template is rendered with `RequestContext`.
-
-Components allow you to pass the `request` object explicitly. Thus, the context processors are applied to components either when:
-
-- The component is rendered with `RequestContext` (Regular Django behavior)
-- The component is rendered with a regular `Context` (or none), but you set the `request` kwarg
- of [`Component.render()`](../../../reference/api#django_components.Component.render).
-- The component is nested in another component that matches one of the two conditions above.
-
-```python
-# ❌ No context processors
-rendered = MyComponent.render()
-rendered = MyComponent.render(Context({}))
-
-# ✅ With context processors
-rendered = MyComponent.render(request=request)
-rendered = MyComponent.render(Context({}), request=request)
-rendered = MyComponent.render(RequestContext(request, {}))
-```
-
-When a component is rendered within a template with [`{% component %}`](../../../reference/template_tags#component) tag, context processors are available depending on whether the template is rendered with `RequestContext` or not.
+When a component is rendered within a template with [`{% component %}`](../../../reference/template_tags#component) tag, the request object is available depending on whether the template is rendered with [`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext) or not.
```python
template = Template("""
@@ -62,13 +35,33 @@ template = Template("""
""")
-# ❌ No context processors
+# ❌ No request
rendered = template.render(Context({}))
-# ✅ With context processors
+# ✅ With request
rendered = template.render(RequestContext(request, {}))
```
+## Accessing the HttpRequest object
+
+When the component has access to the `request` object, the request object will be available in [`Component.request`](../../../reference/api/#django_components.Component.request).
+
+```python
+class MyComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ 'user_id': self.request.GET['user_id'],
+ }
+```
+
+## Context Processors
+
+Components support Django's [context processors](https://docs.djangoproject.com/en/5.2/ref/templates/api/#using-requestcontext).
+
+In regular Django templates, the context processors are applied only when the template is rendered with [`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext).
+
+In Components, the context processors are applied when the component has access to the `request` object.
+
### Accessing context processors data
The data from context processors is automatically available within the component's template.
@@ -84,13 +77,21 @@ class MyComponent(Component):
MyComponent.render(request=request)
```
-You can also access the context processors data from within [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) and other methods under [`Component.context_processors_data`](../../../reference/api#django_components.Component.context_processors_data).
+You can also access the context processors data from within [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data) and other methods under [`Component.context_processors_data`](../../../reference/api#django_components.Component.context_processors_data).
```python
class MyComponent(Component):
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
csrf_token = self.context_processors_data['csrf_token']
return {
'csrf_token': csrf_token,
}
```
+
+This is a dictionary with the context processors data.
+
+If the request object is not available, then [`self.context_processors_data`](../../../reference/api/#django_components.Component.context_processors_data) will be an empty dictionary.
+
+!!! warning
+
+ The [`self.context_processors_data`](../../../reference/api/#django_components.Component.context_processors_data) object is generated dynamically, so changes to it are not persisted.
diff --git a/docs/concepts/fundamentals/render_api.md b/docs/concepts/fundamentals/render_api.md
new file mode 100644
index 00000000..d41708d4
--- /dev/null
+++ b/docs/concepts/fundamentals/render_api.md
@@ -0,0 +1,376 @@
+When a component is being rendered, whether with [`Component.render()`](../../../reference/api#django_components.Component.render)
+or [`{% component %}`](../../../reference/template_tags#component), a component instance is populated with the current inputs and context. This allows you to access things like component inputs.
+
+We refer to these render-time-only methods and attributes as the "Render API".
+
+Render API is available inside these [`Component`](../../../reference/api#django_components.Component) methods:
+
+- [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+- [`get_js_data()`](../../../reference/api#django_components.Component.get_js_data)
+- [`get_css_data()`](../../../reference/api#django_components.Component.get_css_data)
+- [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data)
+- [`on_render_before()`](../../../reference/api#django_components.Component.on_render_before)
+- [`on_render()`](../../../reference/api#django_components.Component.on_render)
+- [`on_render_after()`](../../../reference/api#django_components.Component.on_render_after)
+
+Example:
+
+```python
+class Table(Component):
+ def on_render_before(self, context, template):
+ # Access component's ID
+ assert self.id == "c1A2b3c"
+
+ # Access component's inputs, slots and context
+ assert self.args == [123, "str"]
+ assert self.kwargs == {"variable": "test", "another": 1}
+ footer_slot = self.slots["footer"]
+ some_var = self.context["some_var"]
+
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access the request object and Django's context processors, if available
+ assert self.request.GET == {"query": "something"}
+ assert self.context_processors_data['user'].username == "admin"
+
+rendered = Table.render(
+ kwargs={"variable": "test", "another": 1},
+ args=(123, "str"),
+ slots={"footer": "MY_SLOT"},
+)
+```
+
+## Overview
+
+The Render API includes:
+
+- Component inputs:
+ - [`self.args`](../render_api/#args) - The positional arguments for the current render call
+ - [`self.kwargs`](../render_api/#kwargs) - The keyword arguments for the current render call
+ - [`self.slots`](../render_api/#slots) - The slots for the current render call
+ - [`self.raw_args`](../render_api/#args) - Unmodified positional arguments for the current render call
+ - [`self.raw_kwargs`](../render_api/#kwargs) - Unmodified keyword arguments for the current render call
+ - [`self.raw_slots`](../render_api/#slots) - Unmodified slots for the current render call
+ - [`self.context`](../render_api/#context) - The context for the current render call
+ - [`self.deps_strategy`](../../advanced/rendering_js_css#dependencies-strategies) - The strategy for rendering dependencies
+
+- Request-related:
+ - [`self.request`](../render_api/#request-and-context-processors) - The request object (if available)
+ - [`self.context_processors_data`](../render_api/#request-and-context-processors) - Data from Django's context processors
+
+- Provide / inject:
+ - [`self.inject()`](../render_api/#provide-inject) - Inject data into the component
+
+- Template tag metadata:
+ - [`self.node`](../render_api/#template-tag-metadata) - The [`ComponentNode`](../../../reference/api/#django_components.ComponentNode) instance
+ - [`self.registry`](../render_api/#template-tag-metadata) - The [`ComponentRegistry`](../../../reference/api/#django_components.ComponentRegistry) instance
+ - [`self.registered_name`](../render_api/#template-tag-metadata) - The name under which the component was registered
+ - [`self.outer_context`](../render_api/#template-tag-metadata) - The context outside of the [`{% component %}`](../../../reference/template_tags#component) tag
+
+- Other metadata:
+ - [`self.id`](../render_api/#component-id) - The unique ID for the current render call
+
+## Component inputs
+
+### Args
+
+The `args` argument as passed to
+[`Component.get_template_data()`](../../../reference/api/#django_components.Component.get_template_data).
+
+If you defined the [`Component.Args`](../../../reference/api/#django_components.Component.Args) class,
+then the [`Component.args`](../../../reference/api/#django_components.Component.args) property will return an instance of that class.
+
+Otherwise, `args` will be a plain list.
+
+Use [`self.raw_args`](../../../reference/api/#django_components.Component.raw_args)
+to access the positional arguments as a plain list irrespective of [`Component.Args`](../../../reference/api/#django_components.Component.Args).
+
+**Example:**
+
+With `Args` class:
+
+```python
+from django_components import Component
+
+class Table(Component):
+ class Args(NamedTuple):
+ page: int
+ per_page: int
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert self.args.page == 123
+ assert self.args.per_page == 10
+
+rendered = Table.render(
+ args=[123, 10],
+)
+```
+
+Without `Args` class:
+
+```python
+from django_components import Component
+
+class Table(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert self.args[0] == 123
+ assert self.args[1] == 10
+```
+
+### Kwargs
+
+The `kwargs` argument as passed to
+[`Component.get_template_data()`](../../../reference/api/#django_components.Component.get_template_data).
+
+If you defined the [`Component.Kwargs`](../../../reference/api/#django_components.Component.Kwargs) class,
+then the [`Component.kwargs`](../../../reference/api/#django_components.Component.kwargs) property will return an instance of that class.
+
+Otherwise, `kwargs` will be a plain dictionary.
+
+Use [`self.raw_kwargs`](../../../reference/api/#django_components.Component.raw_kwargs)
+to access the keyword arguments as a plain dictionary irrespective of [`Component.Kwargs`](../../../reference/api/#django_components.Component.Kwargs).
+
+**Example:**
+
+With `Kwargs` class:
+
+```python
+from django_components import Component
+
+class Table(Component):
+ class Kwargs(NamedTuple):
+ page: int
+ per_page: int
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert self.kwargs.page == 123
+ assert self.kwargs.per_page == 10
+
+rendered = Table.render(
+ kwargs={"page": 123, "per_page": 10},
+)
+```
+
+Without `Kwargs` class:
+
+```python
+from django_components import Component
+
+class Table(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert self.kwargs["page"] == 123
+ assert self.kwargs["per_page"] == 10
+```
+
+### Slots
+
+The `slots` argument as passed to
+[`Component.get_template_data()`](../../../reference/api/#django_components.Component.get_template_data).
+
+If you defined the [`Component.Slots`](../../../reference/api/#django_components.Component.Slots) class,
+then the [`Component.slots`](../../../reference/api/#django_components.Component.slots) property will return an instance of that class.
+
+Otherwise, `slots` will be a plain dictionary.
+
+Use [`self.raw_slots`](../../../reference/api/#django_components.Component.raw_slots)
+to access the slots as a plain dictionary irrespective of [`Component.Slots`](../../../reference/api/#django_components.Component.Slots).
+
+**Example:**
+
+With `Slots` class:
+
+```python
+from django_components import Component, Slot, SlotInput
+
+class Table(Component):
+ class Slots(NamedTuple):
+ header: SlotInput
+ footer: SlotInput
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert isinstance(self.slots.header, Slot)
+ assert isinstance(self.slots.footer, Slot)
+
+rendered = Table.render(
+ slots={
+ "header": "MY_HEADER",
+ "footer": lambda ctx: "FOOTER: " + ctx.data["user_id"],
+ },
+)
+```
+
+Without `Slots` class:
+
+```python
+from django_components import Component, Slot, SlotInput
+
+class Table(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ assert isinstance(self.slots["header"], Slot)
+ assert isinstance(self.slots["footer"], Slot)
+```
+
+### Context
+
+The `context` argument as passed to
+[`Component.get_template_data()`](../../../reference/api/#django_components.Component.get_template_data).
+
+This is Django's [Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context)
+with which the component template is rendered.
+
+If the root component or template was rendered with
+[`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext)
+then this will be an instance of `RequestContext`.
+
+Whether the context variables defined in `context` are available to the template depends on the
+[context behavior mode](../../../reference/settings#django_components.app_settings.ComponentsSettings.context_behavior):
+
+- In `"django"` context behavior mode, the template will have access to the keys of this context.
+
+- In `"isolated"` context behavior mode, the template will NOT have access to this context,
+ and data MUST be passed via component's args and kwargs.
+
+## Component ID
+
+Component ID (or render ID) is a unique identifier for the current render call.
+
+That means that if you call [`Component.render()`](../../../reference/api#django_components.Component.render)
+multiple times, the ID will be different for each call.
+
+It is available as [`self.id`](../../../reference/api#django_components.Component.id).
+
+The ID is a 7-letter alphanumeric string in the format `cXXXXXX`,
+where `XXXXXX` is a random string of 6 alphanumeric characters (case-sensitive).
+
+E.g. `c1a2b3c`.
+
+A single render ID has a chance of collision 1 in 57 billion. However, due to birthday paradox, the chance of collision increases to 1% when approaching ~33K render IDs.
+
+Thus, there is currently a soft-cap of ~30K components rendered on a single page.
+
+If you need to expand this limit, please open an issue on GitHub.
+
+```python
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access component's ID
+ assert self.id == "c1A2b3c"
+```
+
+## Request and context processors
+
+Components have access to the request object and context processors data if the component was:
+
+- Given a [`request`](../../../reference/api/#django_components.Component.render) kwarg directly
+- Rendered with [`RenderContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext)
+- Nested in another component for which any of these conditions is true
+
+Then the request object will be available in [`self.request`](../../../reference/api/#django_components.Component.request).
+
+If the request object is available, you will also be able to access the [`context processors`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#configuring-an-engine) data in [`self.context_processors_data`](../../../reference/api/#django_components.Component.context_processors_data).
+
+This is a dictionary with the context processors data.
+
+If the request object is not available, then [`self.context_processors_data`](../../../reference/api/#django_components.Component.context_processors_data) will be an empty dictionary.
+
+Read more about the request object and context processors in the [HTTP Request](./http_request.md) section.
+
+```python
+from django.http import HttpRequest
+
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access the request object and Django's context processors
+ assert self.request.GET == {"query": "something"}
+ assert self.context_processors_data['user'].username == "admin"
+
+rendered = Table.render(
+ request=HttpRequest(),
+)
+```
+
+## Provide / Inject
+
+Components support a provide / inject system as known from Vue or React.
+
+When rendering the component, you can call [`self.inject()`](../../../reference/api/#django_components.Component.inject) with the key of the data you want to inject.
+
+The object returned by [`self.inject()`](../../../reference/api/#django_components.Component.inject)
+
+To provide data to components, use the [`{% provide %}`](../../../reference/template_tags#provide) template tag.
+
+Read more about [Provide / Inject](../advanced/provide_inject.md).
+
+```python
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access provided data
+ data = self.inject("some_data")
+ assert data.some_data == "some_data"
+```
+
+## Template tag metadata
+
+If the component is rendered with [`{% component %}`](../../../reference/template_tags#component) template tag,
+the following metadata is available:
+
+- [`self.node`](../../../reference/api/#django_components.Component.node) - The [`ComponentNode`](../../../reference/api/#django_components.ComponentNode) instance
+- [`self.registry`](../../../reference/api/#django_components.Component.registry) - The [`ComponentRegistry`](../../../reference/api/#django_components.ComponentRegistry) instance
+ that was used to render the component
+- [`self.registered_name`](../../../reference/api/#django_components.Component.registered_name) - The name under which the component was registered
+- [`self.outer_context`](../../../reference/api/#django_components.Component.outer_context) - The context outside of the [`{% component %}`](../../../reference/template_tags#component) tag
+
+ ```django
+ {% with abc=123 %}
+ {{ abc }} {# <--- This is in outer context #}
+ {% component "my_component" / %}
+ {% endwith %}
+ ```
+
+You can use these to check whether the component was rendered inside a template with [`{% component %}`](../../../reference/template_tags#component) tag
+or in Python with [`Component.render()`](../../../reference/api/#django_components.Component.render).
+
+```python
+class MyComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ if self.registered_name is None:
+ # Do something for the render() function
+ else:
+ # Do something for the {% component %} template tag
+```
+
+You can access the [`ComponentNode`](../../../reference/api/#django_components.ComponentNode) under [`Component.node`](../../../reference/api/#django_components.Component.node):
+
+```py
+class MyComponent(Component):
+ def get_template_data(self, context, template):
+ if self.node is not None:
+ assert self.node.name == "my_component"
+```
+
+Accessing the [`ComponentNode`](../../../reference/api/#django_components.ComponentNode) is mostly useful for extensions, which can modify their behaviour based on the source of the Component.
+
+For example, if `MyComponent` was used in another component - that is,
+with a `{% component "my_component" %}` tag
+in a template that belongs to another component - then you can use
+[`self.node.template_component`](../../../reference/api/#django_components.ComponentNode.template_component)
+to access the owner [`Component`](../../../reference/api/#django_components.Component) class.
+
+```djc_py
+class Parent(Component):
+ template: types.django_html = """
+ {{ user.username }}
+ + {% if show_details %} +Member for {{ user_joined_days }} days
+Email: {{ user.email }}
+ {% endif %} +
+ {% component "my_component" / %}
+
+ """
+
+@register("my_component")
+class MyComponent(Component):
+ def get_template_data(self, context, template):
+ if self.node is not None:
+ assert self.node.template_component == Parent
+```
+
+!!! info
+
+ `Component.node` is `None` if the component is created by [`Component.render()`](../../../reference/api/#django_components.Component.render)
+ (but you can pass in the `node` kwarg yourself).
diff --git a/docs/concepts/fundamentals/rendering_components.md b/docs/concepts/fundamentals/rendering_components.md
new file mode 100644
index 00000000..38883204
--- /dev/null
+++ b/docs/concepts/fundamentals/rendering_components.md
@@ -0,0 +1,627 @@
+Your components can be rendered either within your Django templates, or directly in Python code.
+
+## Overview
+
+Django Components provides three main methods to render components:
+
+- [`{% component %}` tag](#component-tag) - Renders the component within your Django templates
+- [`Component.render()` method](#render-method) - Renders the component to a string
+- [`Component.render_to_response()` method](#render-to-response-method) - Renders the component and wraps it in an HTTP response
+
+## `{% component %}` tag
+
+Use the [`{% component %}`](../../../reference/template_tags#component) tag to render a component within your Django templates.
+
+The [`{% component %}`](../../../reference/template_tags#component) tag takes:
+
+- Component's registered name as the first positional argument,
+- Followed by any number of positional and keyword arguments.
+
+```django
+{% load component_tags %}
+
+ {% component "button" name="John" job="Developer" / %}
+
+```
+
+To pass in slots content, you can insert [`{% fill %}`](../../../reference/template_tags#fill) tags,
+directly within the [`{% component %}`](../../../reference/template_tags#component) tag to "fill" the slots:
+
+```django
+{% component "my_table" rows=rows headers=headers %}
+ {% fill "pagination" %}
+ < 1 | 2 | 3 >
+ {% endfill %}
+{% endcomponent %}
+```
+
+You can even nest [`{% fill %}`](../../../reference/template_tags#fill) tags within
+[`{% if %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#if),
+[`{% for %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#for)
+and other tags:
+
+```django
+{% component "my_table" rows=rows headers=headers %}
+ {% if rows %}
+ {% fill "pagination" %}
+ < 1 | 2 | 3 >
+ {% endfill %}
+ {% endif %}
+{% endcomponent %}
+```
+
+!!! info "Omitting the `component` keyword"
+
+ If you would like to omit the `component` keyword, and simply refer to your
+ components by their registered names:
+
+ ```django
+ {% button name="John" job="Developer" / %}
+ ```
+
+ You can do so by setting the "shorthand" [Tag formatter](../../advanced/tag_formatters) in the settings:
+
+ ```python
+ # settings.py
+ COMPONENTS = {
+ "tag_formatter": "django_components.component_shorthand_formatter",
+ }
+ ```
+
+!!! info "Extended template tag syntax"
+
+ Unlike regular Django template tags, django-components' tags offer extra features like
+ defining literal lists and dicts, and more. Read more about [Template tag syntax](../template_tag_syntax).
+
+### Registering components
+
+For a component to be renderable with the [`{% component %}`](../../../reference/template_tags#component) tag, it must be first registered with the [`@register()`](../../../reference/api/#django_components.register) decorator.
+
+For example, if you register a component under the name `"button"`:
+
+```python
+from typing import NamedTuple
+from django_components import Component, register
+
+@register("button")
+class Button(Component):
+ template_file = "button.html"
+
+ class Kwargs(NamedTuple):
+ name: str
+ job: str
+
+ def get_template_data(self, args, kwargs, slots, context):
+ ...
+```
+
+Then you can render this component by using its registered name `"button"` in the template:
+
+```django
+{% component "button" name="John" job="Developer" / %}
+```
+
+As you can see above, the args and kwargs passed to the [`{% component %}`](../../../reference/template_tags#component) tag correspond
+to the component's input.
+
+For more details, read [Registering components](../../advanced/component_registry).
+
+!!! note "Why do I need to register components?"
+
+ TL;DR: To be able to share components as libraries, and because components can be registed with multiple registries / libraries.
+
+ Django-components allows to [share components across projects](../../advanced/component_libraries).
+
+ However, different projects may use different settings. For example, one project may prefer the "long" format:
+
+ ```django
+ {% component "button" name="John" job="Developer" / %}
+ ```
+
+ While the other may use the "short" format:
+
+ ```django
+ {% button name="John" job="Developer" / %}
+ ```
+
+ Both approaches are supported simultaneously for backwards compatibility, because django-components
+ started out with only the "long" format.
+
+ To avoid ambiguity, when you use a 3rd party library, it uses the syntax that the author
+ had configured for it.
+
+ So when you are creating a component, django-components need to know which registry the component
+ belongs to, so it knows which syntax to use.
+
+### Rendering templates
+
+If you have embedded the component in a Django template using the
+[`{% component %}`](../../reference/template_tags#component) tag:
+
+```django title="[project root]/templates/my_template.html"
+{% load component_tags %}
+
+ {% component "calendar" date="2024-12-13" / %}
+
+```
+
+You can simply render the template with the Django's API:
+
+- [`django.shortcuts.render()`](https://docs.djangoproject.com/en/5.2/topics/http/shortcuts/#render)
+
+ ```python
+ from django.shortcuts import render
+
+ context = {"date": "2024-12-13"}
+ rendered_template = render(request, "my_template.html", context)
+ ```
+
+- [`Template.render()`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template.render)
+
+ ```python
+ from django.template import Template
+ from django.template.loader import get_template
+
+ # Either from a file
+ template = get_template("my_template.html")
+
+ # or inlined
+ template = Template("""
+ {% load component_tags %}
+
+ {% component "calendar" date="2024-12-13" / %}
+
+ """)
+
+ rendered_template = template.render()
+ ```
+
+### Isolating components
+
+By default, components behave similarly to Django's
+[`{% include %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#include),
+and the template inside the component has access to the variables defined in the outer template.
+
+You can selectively isolate a component, using the `only` flag, so that the inner template
+can access only the data that was explicitly passed to it:
+
+```django
+{% component "name" positional_arg keyword_arg=value ... only / %}
+```
+
+Alternatively, you can set all components to be isolated by default, by setting
+[`context_behavior`](../../../reference/settings#django_components.app_settings.ComponentsSettings.context_behavior)
+to `"isolated"` in your settings:
+
+```python
+# settings.py
+COMPONENTS = {
+ "context_behavior": "isolated",
+}
+```
+
+## `render()` method
+
+The [`Component.render()`](../../../reference/api/#django_components.Component.render) method renders a component to a string.
+
+This is the equivalent of calling the [`{% component %}`](../template_tags#component) tag.
+
+```python
+from typing import NamedTuple, Optional
+from django_components import Component, SlotInput
+
+class Button(Component):
+ template_file = "button.html"
+
+ class Args(NamedTuple):
+ name: str
+
+ class Kwargs(NamedTuple):
+ surname: str
+ age: int
+
+ class Slots(NamedTuple):
+ footer: Optional[SlotInput] = None
+
+ def get_template_data(self, args, kwargs, slots, context):
+ ...
+
+Button.render(
+ args=["John"],
+ kwargs={
+ "surname": "Doe",
+ "age": 30,
+ },
+ slots={
+ "footer": "i AM A SLOT",
+ },
+)
+```
+
+[`Component.render()`](../../../reference/api/#django_components.Component.render) accepts the following arguments:
+
+- `args` - Positional arguments to pass to the component (as a list or tuple)
+- `kwargs` - Keyword arguments to pass to the component (as a dictionary)
+- `slots` - Slot content to pass to the component (as a dictionary)
+- `context` - Django context for rendering (can be a dictionary or a `Context` object)
+- `deps_strategy` - [Dependencies rendering strategy](#dependencies-rendering) (default: `"document"`)
+- `request` - [HTTP request object](../http_request), used for context processors (optional)
+
+All arguments are optional. If not provided, they default to empty values or sensible defaults.
+
+See the API reference for [`Component.render()`](../../../reference/api/#django_components.Component.render)
+for more details on the arguments.
+
+## `render_to_response()` method
+
+The [`Component.render_to_response()`](../../../reference/api/#django_components.Component.render_to_response)
+method works just like [`Component.render()`](../../../reference/api/#django_components.Component.render),
+but wraps the result in an HTTP response.
+
+It accepts all the same arguments as [`Component.render()`](../../../reference/api/#django_components.Component.render).
+
+Any extra arguments are passed to the [`HttpResponse`](https://docs.djangoproject.com/en/5.2/ref/request-response/#django.http.HttpResponse)
+constructor.
+
+```python
+from typing import NamedTuple, Optional
+from django_components import Component, SlotInput
+
+class Button(Component):
+ template_file = "button.html"
+
+ class Args(NamedTuple):
+ name: str
+
+ class Kwargs(NamedTuple):
+ surname: str
+ age: int
+
+ class Slots(NamedTuple):
+ footer: Optional[SlotInput] = None
+
+ def get_template_data(self, args, kwargs, slots, context):
+ ...
+
+# Render the component to an HttpResponse
+response = Button.render_to_response(
+ args=["John"],
+ kwargs={
+ "surname": "Doe",
+ "age": 30,
+ },
+ slots={
+ "footer": "i AM A SLOT",
+ },
+ # Additional response arguments
+ status=200,
+ headers={"X-Custom-Header": "Value"},
+)
+```
+
+This method is particularly useful in view functions, as you can return the result of the component directly:
+
+```python
+def profile_view(request, user_id):
+ return Button.render_to_response(
+ kwargs={
+ "surname": "Doe",
+ "age": 30,
+ },
+ request=request,
+ )
+```
+
+### Custom response classes
+
+By default, [`Component.render_to_response()`](../../../reference/api/#django_components.Component.render_to_response)
+returns a standard Django [`HttpResponse`](https://docs.djangoproject.com/en/5.2/ref/request-response/#django.http.HttpResponse).
+
+You can customize this by setting the [`response_class`](../../../reference/api/#django_components.Component.response_class)
+attribute on your component:
+
+```python
+from django.http import HttpResponse
+from django_components import Component
+
+class MyHttpResponse(HttpResponse):
+ ...
+
+class MyComponent(Component):
+ response_class = MyHttpResponse
+
+response = MyComponent.render_to_response()
+assert isinstance(response, MyHttpResponse)
+```
+
+## Dependencies rendering
+
+The rendered HTML may be used in different contexts (browser, email, etc), and each may need different handling of JS and CSS scripts.
+
+[`render()`](../../../reference/api/#django_components.Component.render) and [`render_to_response()`](../../../reference/api/#django_components.Component.render_to_response)
+accept a `deps_strategy` parameter, which controls where and how the JS / CSS are inserted into the HTML.
+
+The `deps_strategy` parameter is ultimately passed to [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies).
+
+Learn more about [Rendering JS / CSS](../../advanced/rendering_js_css).
+
+There are six dependencies rendering strategies:
+
+- [`document`](../../advanced/rendering_js_css#document) (default)
+ - Smartly inserts JS / CSS into placeholders ([`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies)) or into `` and `` tags.
+ - Inserts extra script to allow `fragment` components to work.
+ - Assumes the HTML will be rendered in a JS-enabled browser.
+- [`fragment`](../../advanced/rendering_js_css#fragment)
+ - A lightweight HTML fragment to be inserted into a document with AJAX.
+ - Assumes the page was already rendered with `"document"` strategy.
+ - No JS / CSS included.
+- [`simple`](../../advanced/rendering_js_css#simple)
+ - Smartly insert JS / CSS into placeholders ([`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies)) or into `` and `` tags.
+ - No extra script loaded.
+- [`prepend`](../../advanced/rendering_js_css#prepend)
+ - Insert JS / CSS before the rendered HTML.
+ - Ignores the placeholders ([`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies)) and any ``/`` HTML tags.
+ - No extra script loaded.
+- [`append`](../../advanced/rendering_js_css#append)
+ - Insert JS / CSS after the rendered HTML.
+ - Ignores the placeholders ([`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies)) and any ``/`` HTML tags.
+ - No extra script loaded.
+- [`ignore`](../../advanced/rendering_js_css#ignore)
+ - HTML is left as-is. You can still process it with a different strategy later with
+ [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies).
+ - Used for inserting rendered HTML into other components.
+
+!!! info
+
+ You can use the `"prepend"` and `"append"` strategies to force to output JS / CSS for components
+ that don't have neither the placeholders like [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies), nor any ``/`` HTML tags:
+
+ ```py
+ rendered = Calendar.render_to_response(
+ request=request,
+ kwargs={
+ "date": request.GET.get("date", ""),
+ },
+ deps_strategy="append",
+ )
+ ```
+
+ Renders something like this:
+
+ ```html
+
+
+ ...
+
+
+
+
+ ```
+
+## Passing context
+
+The [`render()`](../../../reference/api/#django_components.Component.render) and [`render_to_response()`](../../../reference/api/#django_components.Component.render_to_response) methods accept an optional `context` argument.
+This sets the context within which the component is rendered.
+
+When a component is rendered within a template with the [`{% component %}`](../../../reference/template_tags#component)
+tag, this will be automatically set to the
+[Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context)
+instance that is used for rendering the template.
+
+When you call [`Component.render()`](../../../reference/api/#django_components.Component.render) directly from Python,
+there is no context object, so you can ignore this input most of the time.
+Instead, use `args`, `kwargs`, and `slots` to pass data to the component.
+
+However, you can pass
+[`RequestContext`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.RequestContext)
+to the `context` argument, so that the component will gain access to the request object and will use
+[context processors](https://docs.djangoproject.com/en/5.2/ref/templates/api/#using-requestcontext).
+Read more on [Working with HTTP requests](../http_request).
+
+```py
+Button.render(
+ context=RequestContext(request),
+)
+```
+
+For advanced use cases, you can use `context` argument to "pre-render" the component in Python, and then
+pass the rendered output as plain string to the template. With this, the inner component is rendered as if
+it was within the template with [`{% component %}`](../../../reference/template_tags#component).
+
+```py
+class Button(Component):
+ def render(self, context, template):
+ # Pass `context` to Icon component so it is rendered
+ # as if nested within Button.
+ icon = Icon.render(
+ context=context,
+ args=["icon-name"],
+ deps_strategy="ignore",
+ )
+ # Update context with icon
+ with context.update({"icon": icon}):
+ return template.render(context)
+```
+
+!!! warning
+
+ Whether the variables defined in `context` are actually available in the template depends on the
+ [context behavior mode](../../../reference/settings#django_components.app_settings.ComponentsSettings.context_behavior):
+
+ - In `"django"` context behavior mode, the template will have access to the keys of this context.
+
+ - In `"isolated"` context behavior mode, the template will NOT have access to this context,
+ and data MUST be passed via component's args and kwargs.
+
+ Therefore, it's **strongly recommended** to not rely on defining variables on the context object,
+ but instead passing them through as `args` and `kwargs`
+
+ ❌ Don't do this:
+
+ ```python
+ html = ProfileCard.render(
+ context={"name": "John"},
+ )
+ ```
+
+ ✅ Do this:
+
+ ```python
+ html = ProfileCard.render(
+ kwargs={"name": "John"},
+ )
+ ```
+
+## Typing render methods
+
+Neither [`Component.render()`](../../../reference/api/#django_components.Component.render)
+nor [`Component.render_to_response()`](../../../reference/api/#django_components.Component.render_to_response)
+are typed, due to limitations of Python's type system.
+
+To add type hints, you can wrap the inputs
+in component's [`Args`](../../../reference/api/#django_components.Component.Args),
+[`Kwargs`](../../../reference/api/#django_components.Component.Kwargs),
+and [`Slots`](../../../reference/api/#django_components.Component.Slots) classes.
+
+Read more on [Typing and validation](../../fundamentals/typing_and_validation).
+
+```python
+from typing import NamedTuple, Optional
+from django_components import Component, Slot, SlotInput
+
+# Define the component with the types
+class Button(Component):
+ class Args(NamedTuple):
+ name: str
+
+ class Kwargs(NamedTuple):
+ surname: str
+ age: int
+
+ class Slots(NamedTuple):
+ my_slot: Optional[SlotInput] = None
+ footer: SlotInput
+
+# Add type hints to the render call
+Button.render(
+ args=Button.Args(
+ name="John",
+ ),
+ kwargs=Button.Kwargs(
+ surname="Doe",
+ age=30,
+ ),
+ slots=Button.Slots(
+ footer=Slot(lambda ctx: "Click me!"),
+ ),
+)
+```
+
+## Components as input
+
+django_components makes it possible to compose components in a "React-like" way,
+where you can render one component and use its output as input to another component:
+
+```python
+from django.utils.safestring import mark_safe
+
+# Render the inner component
+inner_html = InnerComponent.render(
+ kwargs={"some_data": "value"},
+ deps_strategy="ignore", # Important for nesting!
+)
+
+# Use inner component's output in the outer component
+outer_html = OuterComponent.render(
+ kwargs={
+ "content": mark_safe(inner_html), # Mark as safe to prevent escaping
+ },
+)
+```
+
+The key here is setting [`deps_strategy="ignore"`](../../advanced/rendering_js_css#ignore) for the inner component. This prevents duplicate
+rendering of JS / CSS dependencies when the outer component is rendered.
+
+When `deps_strategy="ignore"`:
+
+- No JS or CSS dependencies will be added to the output HTML
+- The component's content is rendered as-is
+- The outer component will take care of including all needed dependencies
+
+Read more about [Rendering JS / CSS](../../advanced/rendering_js_css).
+
+## Dynamic components
+
+Django components defines a special "dynamic" component ([`DynamicComponent`](../../../reference/components#django_components.components.dynamic.DynamicComponent)).
+
+Normally, you have to hard-code the component name in the template:
+
+```django
+{% component "button" / %}
+```
+
+The dynamic component allows you to dynamically render any component based on the `is` kwarg. This is similar
+to [Vue's dynamic components](https://vuejs.org/guide/essentials/component-basics#dynamic-components) (`
- Hi there!
-
- """
- js_file = "my_table.js"
- css_file = "my_table.css"
- ```
+```py
+@register("calendar")
+class Calendar(Component):
+ class Media:
+ js = [
+ "https://unpkg.com/alpinejs@3.14.7/dist/cdn.min.js",
+ "calendar/script.js",
+ ]
+ css = [
+ "https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css",
+ "calendar/style.css",
+ ]
+```
!!! note
- django-component's management of files is inspired by [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
+ django-component's management of files is inspired by [Django's `Media` class](https://docs.djangoproject.com/en/5.2/topics/forms/media/).
To be familiar with how Django handles static files, we recommend reading also:
- - [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
+ - [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.2/howto/static-files/)
-## Defining file paths relative to component
+## `Media` class
+
+
+
+Use the `Media` class to define secondary JS / CSS files for a component.
+
+This `Media` class behaves similarly to
+[Django's Media class](https://docs.djangoproject.com/en/5.2/topics/forms/media/#assets-as-a-static-definition):
+
+- **Static paths** - Paths are handled as static file paths, and are resolved to URLs with Django's
+ [`{% static %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#static) template tag.
+- **URLs** - A path that starts with `http`, `https`, or `/` is considered a URL. URLs are NOT resolved with [`{% static %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#static).
+- **HTML tags** - Both static paths and URLs are rendered to `
+#
+```
+
+When working with component media files, it is important to understand the difference:
+
+- `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`](../../reference/api.md#django_components.Component.media_class)
+
+```python
+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`](../../reference/api.md#django_components.Component.media),
+you can configure [`Component.media_class`](../../reference/api.md#django_components.Component.media_class)
+([See example](#rendering-paths)).
+
+## File paths
+
+Unlike the [main HTML / JS / CSS files](../html_js_css_files), the path definition for the secondary files are quite ergonomic.
+
+### Relative to component
As seen in the [getting started example](../../getting_started/your_first_component.md), to associate HTML / JS / CSS
files with a component, you can set them as
@@ -117,93 +335,30 @@ class Calendar(Component):
NOTE: In case of ambiguity, the preference goes to resolving the files relative to the component's directory.
-## Defining additional JS and CSS files
+### Globs
-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](../../../reference/api#django_components.Component.Media).
+Components can have many secondary files. To simplify their declaration, you can use globs.
-This `Media` class behaves similarly to
-[Django's Media class](https://docs.djangoproject.com/en/5.1/topics/forms/media/#assets-as-a-static-definition):
+Globs MUST be relative to the component's directory.
-- 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`](https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.safestring.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`](../../../reference/api#django_components.ComponentMediaInput.extend) to configure
- whether to inherit JS / CSS from parent components. See
- [Controlling Media Inheritance](../../fundamentals/defining_js_css_html_files/#controlling-media-inheritance).
+```py title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register
-However, there's a few differences from Django's Media class:
-
-1. 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`](../../../reference/api#django_components.ComponentMediaInput)).
-2. Individual JS / CSS files can be any of `str`, `bytes`, `Path`,
- [`SafeString`](https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.safestring.SafeString), or a function
- (See [`ComponentMediaInputPath`](../../../reference/api#django_components.ComponentMediaInputPath)).
-3. Individual JS / CSS files can be glob patterns, e.g. `*.js` or `styles/**/*.css`.
-4. If you set [`Media.extend`](../../../reference/api/#django_components.ComponentMediaInput.extend) to a list,
- it should be a list of [`Component`](../../../reference/api/#django_components.Component) classes.
-
-```py
-class MyTable(Component):
+@register("calendar")
+class Calendar(Component):
class Media:
js = [
- "path/to/script.js",
- "path/to/*.js", # Or as a glob
- "https://unpkg.com/alpinejs@3.14.7/dist/cdn.min.js", # AlpineJS
+ "path/to/*.js",
+ "another/path/*.js",
]
- css = {
- "all": [
- "path/to/style.css",
- "path/to/*.css", # Or as a glob
- "https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css", # TailwindCSS
- ],
- "print": ["path/to/style2.css"],
- }
+ css = "*.css"
```
-## Configuring CSS Media Types
+How this works is that django-components will detect that the path is a glob, and will try to resolve all files matching the glob pattern relative to the component's directory.
-You can define which stylesheets will be associated with which
-[CSS Media types](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#targeting_media_types). You do so by defining CSS files as a dictionary.
+After that, the file paths are handled the same way as if you defined them explicitly.
-See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5.0/topics/forms/media/#css).
-
-Again, you can set either a single file or a list of files per media type:
-
-```py
-class MyComponent(Component):
- class Media:
- css = {
- "all": "path/to/style1.css",
- "print": ["path/to/style2.css", "path/to/style3.css"],
- }
-```
-
-!!! note
-
- When you define CSS as a string or a list, the `all` media type is implied.
-
- So these two examples are the same:
-
- ```py
- class MyComponent(Component):
- class Media:
- css = "path/to/style1.css"
- ```
-
- ```py
- class MyComponent(Component):
- class Media:
- css = {
- "all": ["path/to/style1.css"],
- }
- ```
-
-## Supported types for file paths
+### Supported types
File paths can be any of:
@@ -213,7 +368,7 @@ File paths can be any of:
- `SafeData` (`__html__` method)
- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
-See [`ComponentMediaInputPath`](../../../reference/api#django_components.ComponentMediaInputPath).
+To help with typing the union, use [`ComponentMediaInputPath`](../../../reference/api#django_components.ComponentMediaInputPath).
```py
from pathlib import Path
@@ -238,18 +393,18 @@ class SimpleComponent(Component):
]
```
-## Paths as objects
+### Paths as objects
-In the example [above](#supported-types-for-file-paths), you can see that when we used Django's
-[`mark_safe()`](https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.safestring.mark_safe)
-to mark a string as a [`SafeString`](https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.safestring.SafeString),
-we had to define the full `
-#
-```
-
-### `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`](../../reference/api.md#django_components.Component.media_class)
-
-```python
-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`](../../reference/api.md#django_components.Component.media),
-you can configure [`Component.media_class`](../../reference/api.md#django_components.Component.media_class)
-([See example](#customize-how-paths-are-rendered-into-html-tags)).
-
-## Controlling Media Inheritance
-
-By default, the media files are inherited from the parent component.
-
-```python
-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`](../../reference/api.md#django_components.ComponentMediaInput.extend) attribute to `False`:
-
-```python
-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:
-
-```python
-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](https://docs.djangoproject.com/en/5.1/topics/forms/media/#extend),
- 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).
diff --git a/docs/concepts/fundamentals/single_file_components.md b/docs/concepts/fundamentals/single_file_components.md
index d380dca2..6f9b0765 100644
--- a/docs/concepts/fundamentals/single_file_components.md
+++ b/docs/concepts/fundamentals/single_file_components.md
@@ -1,17 +1,38 @@
-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`.
+Components can be defined in a single file, inlining the HTML, JS and CSS within the Python code.
+
+## Writing single file components
+
+To do this, you can use the
+[`template`](../../../reference/api#django_components.Component.template),
+[`js`](../../../reference/api#django_components.Component.js),
+and [`css`](../../../reference/api#django_components.Component.css)
+class attributes instead of the
+[`template_file`](../../../reference/api#django_components.Component.template_file),
+[`js_file`](../../../reference/api#django_components.Component.js_file),
+and [`css_file`](../../../reference/api#django_components.Component.css_file).
For example, here's the calendar component from
-the [Getting started](../../getting_started/your_first_component.md) tutorial,
-defined in a single file:
+the [Getting started](../../getting_started/your_first_component.md) tutorial:
+
+```py title="calendar.py"
+from django_components import Component
+
+class Calendar(Component):
+ template_file = "calendar.html"
+ js_file = "calendar.js"
+ css_file = "calendar.css"
+```
+
+And here is the same component, rewritten in a single file:
```djc_py title="[project root]/components/calendar.py"
from django_components import Component, register, types
@register("calendar")
class Calendar(Component):
- def get_context_data(self, date):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "date": date,
+ "date": kwargs["date"],
}
template: types.django_html = """
@@ -41,6 +62,194 @@ class Calendar(Component):
"""
```
-This makes it easy to create small components without having to create a separate template, CSS, and JS file.
+You can mix and match, so you can have a component with inlined HTML,
+while the JS and CSS are in separate files:
-To add syntax highlighting to these snippets, head over to [Syntax highlighting](../../guides/setup/syntax_highlight.md).
+```djc_py title="[project root]/components/calendar.py"
+from django_components import Component, register, types
+
+@register("calendar")
+class Calendar(Component):
+ js_file = "calendar.js"
+ css_file = "calendar.css"
+
+ template: types.django_html = """
+
+ Today's date is {{ date }}
+
+ """
+```
+
+## Syntax highlighting
+
+If you "inline" the HTML, JS and CSS code into the Python class, you should set up
+syntax highlighting to let your code editor know that the inlined code is HTML, JS and CSS.
+
+In the examples above, we've annotated the
+[`template`](../../../reference/api#django_components.Component.template),
+[`js`](../../../reference/api#django_components.Component.js),
+and [`css`](../../../reference/api#django_components.Component.css)
+attributes with
+the `types.django_html`, `types.js` and `types.css` types. These are used for syntax highlighting in VSCode.
+
+!!! warning
+
+ Autocompletion / intellisense does not work in the inlined code.
+
+ Help us add support for intellisense in the inlined code! Start a conversation in the
+ [GitHub Discussions](https://github.com/django-components/django-components/discussions).
+
+### VSCode
+
+1. First install [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
+
+2. Next, in your component, set typings of
+[`Component.template`](../../../reference/api#django_components.Component.template),
+[`Component.js`](../../../reference/api#django_components.Component.js),
+[`Component.css`](../../../reference/api#django_components.Component.css)
+to `types.django_html`, `types.css`, and `types.js` respectively. The extension will recognize these and will activate syntax highlighting.
+
+```djc_py title="[project root]/components/calendar.py"
+from django_components import Component, register, types
+
+@register("calendar")
+class Calendar(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"],
+ }
+
+ template: types.django_html = """
+
+ Today's date is {{ date }}
+
+ """
+
+ 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](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
+
+You only need to write the comments `# language=
+ Today's date is {{ date }}
+
+ """
+
+ # 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!"); };
+ }
+ })()
+ """
+```
+
+### Markdown code blocks with Pygments
+
+[Pygments](https://pygments.org/) is a syntax highlighting library written in Python. It's also what's used by this documentation site ([mkdocs-material](https://squidfunk.github.io/mkdocs-material/)) to highlight code blocks.
+
+To write code blocks with syntax highlighting, you need to install the [`pygments-djc`](https://pypi.org/project/pygments-djc/) package.
+
+```bash
+pip install pygments-djc
+```
+
+And then initialize it by importing `pygments_djc` somewhere in your project:
+
+```python
+import pygments_djc
+```
+
+Now you can use the `djc_py` code block to write code blocks with syntax highlighting for components.
+
+```txt
+\```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template = """
+
+ Today's date is {{ date }}
+
+ """
+
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+\```
+```
+
+Will be rendered as below. Notice that the CSS and HTML are highlighted correctly:
+
+```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template= """
+
+ Today's date is {{ date }}
+
+ """
+
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+```
diff --git a/docs/concepts/fundamentals/slots.md b/docs/concepts/fundamentals/slots.md
index fd757694..7a65dcc4 100644
--- a/docs/concepts/fundamentals/slots.md
+++ b/docs/concepts/fundamentals/slots.md
@@ -1,46 +1,74 @@
-_New in version 0.26_:
+django-components has the most extensive slot system of all the popular Python templating engines.
-- 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.
+The slot system is based on [Vue](https://vuejs.org/guide/components/slots.html), and works across both Django templates and Python code.
----
+## 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](https://vuejs.org/guide/components/slots.html).
-In the example below we introduce two block tags that work hand in hand to make this work. These are...
+When you write a component, you define its template. The template will always be
+the same each time you render the component.
-- `{% slot
- {% slot "header" %}Calendar header{% endslot %}
-
-
- {% slot "body" %}Today's date is {{ date }}{% endslot %}
+ {# This is where the component will insert the content #}
+ {% slot "header" / %}
+
+```
+
+Next, when using the component, we can insert our own content into the slots. It looks like this:
```htmldjango
{% component "calendar" date="2020-06-06" %}
{% fill "body" %}
- Can you believe it's already {{ date }}??
+ Can you believe it's already
+ {{ date }}??
{% endfill %}
{% endcomponent %}
```
-Since the 'header' fill is unspecified, it's taken from the base template. If you put this in a template, and pass in `date=2020-06-06`, this is what gets rendered:
+Since the `'header'` fill is unspecified, it's [default value](#default-slot) is used.
+
+When rendered, notice that:
+
+- The body is filled with the content we specified,
+- The header is still the default value we defined in the component template.
```htmldjango
+ {% slot "header" %}
+ Calendar header
+ {% endslot %}
+
+
+ {% slot "body" %}
+ Today's date is {{ date }}
+ {% endslot %}
+
+
@@ -53,205 +81,825 @@ Since the 'header' fill is unspecified, it's taken from the base template. If yo
```
-### Named slots
+## Slots overview
-As seen in the previouse section, you can use `{% fill slot_name %}` to insert content into a specific
-slot.
+### Slot definition
-You can define fills for multiple slot simply by defining them all within the `{% component %} {% endcomponent %}`
-tags:
+Slots are defined with the [`{% slot %}`](../../../reference/template_tags#slot) tag:
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "header" %}
- Hi this is header!
+```django
+{% slot "name" %}
+ Default content
+{% endslot %}
+```
+
+Single component can have multiple slots:
+
+```django
+{% slot "name" %}
+ Default content
+{% endslot %}
+
+{% slot "other_name" / %}
+```
+
+And you can even define the same slot in multiple places:
+
+```django
+
+ {% slot "name" %}
+ First content
+ {% endslot %}
+
+
+ {% slot "name" %}
+ Second content
+ {% endslot %}
+
+```
+
+!!! info
+
+ If you define the same slot in multiple places, you must mark each slot individually
+ when setting `default` or `required` flags, e.g.:
+
+ ```htmldjango
+
+
+ ```
+
+### Slot filling
+
+Fill can be defined with the [`{% fill %}`](../../../reference/template_tags#fill) tag:
+
+```django
+{% component "calendar" %}
+ {% fill "name" %}
+ Filled content
{% endfill %}
- {% fill "body" %}
- Can you believe it's already {{ date }}??
+ {% fill "other_name" %}
+ Filled content
{% endfill %}
{% endcomponent %}
```
-You can also use `{% for %}`, `{% with %}`, or other non-component tags (even `{% include %}`)
-to construct the `{% fill %}` tags, **as long as these other tags do not leave any text behind!**
+Or in Python with the [`slots`](../../../reference/api#django_components.Component.render) argument:
-```django
-{% component "table" %}
- {% for slot_name in slots %}
- {% fill name=slot_name %}
- {{ slot_name }}
- {% endfill %}
- {% endfor %}
-
- {% with slot_name="abc" %}
- {% fill name=slot_name %}
- {{ slot_name }}
- {% endfill %}
- {% endwith %}
-{% endcomponent %}
+```py
+Calendar.render(
+ slots={
+ "name": "Filled content",
+ "other_name": "Filled content",
+ },
+)
```
### Default slot
-_Added in version 0.28_
+You can make the syntax shorter by marking the slot as [`default`](../../../reference/template_tags#slot):
-As you can see, component slots lets you write reusable containers that you fill in when you use a component. This makes for highly reusable components that can be used in different circumstances.
-
-It can become tedious to use `fill` tags everywhere, especially when you're using a component that declares only one slot. To make things easier, `slot` tags can be marked with an optional keyword: `default`.
-
-When added to the tag (as shown below), this option lets you pass filling content directly in the body of a `component` tag pair – without using a `fill` tag. Choose carefully, though: a component template may contain at most one slot that is marked as `default`. The `default` option can be combined with other slot options, e.g. `required`.
-
-Here's the same example as before, except with default slots and implicit filling.
-
-The template:
-
-```htmldjango
-
+ {% slot "image" default required %}Image here{% endslot %}
+
+
+ {% slot "image" default required %}Image here{% endslot %}
+
+
-
+```django
+{% slot "name" default %}
+ Default content
+{% endslot %}
```
-Including the component (notice how the `fill` tag is omitted):
+This allows you to fill the slot directly in the [`{% component %}`](../../../reference/template_tags#component) tag,
+omitting the `{% fill %}` tag:
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- Can you believe it's already {{ date }}??
+```django
+{% component "calendar" %}
+ Filled content
{% endcomponent %}
```
-The rendered result (exactly the same as before):
+To target the default slot in Python, you can use the `"default"` slot name:
-```html
-
- {% slot "header" %}Calendar header{% endslot %}
-
-
- {% slot "body" default %}Today's date is {{ date }}{% endslot %}
-
-
-
+```py
+Calendar.render(
+ slots={"default": "Filled content"},
+)
```
-You may be tempted to combine implicit fills with explicit `fill` tags. This will not work. The following component template will raise an error when rendered.
+!!! info "Accessing default slot in Python"
-```htmldjango
-{# DON'T DO THIS #}
-{% component "calendar" date="2020-06-06" %}
- {% fill "header" %}Totally new header!{% endfill %}
- Can you believe it's already {{ date }}??
-{% endcomponent %}
-```
+ Since the default slot is stored under the slot name `default`, you can access the default slot
+ in Python under the `"default"` key:
-Instead, you can use a named fill with name `default` to target the default fill:
+ ```py
+ class MyTable(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ default_slot = slots["default"]
+ return {
+ "default_slot": default_slot,
+ }
+ ```
-```htmldjango
-{# THIS WORKS #}
-{% component "calendar" date="2020-06-06" %}
- {% fill "header" %}Totally new header!{% endfill %}
- {% fill "default" %}
+!!! warning
+
+ Only one [`{% slot %}`](../../../reference/template_tags#slot) can be marked as `default`.
+ But you can have multiple slots with the same name all marked as `default`.
+
+ If you define multiple **different** slots as `default`, this will raise an error.
+
+ ❌ Don't do this
+
+ ```django
+ {% slot "name" default %}
+ Default content
+ {% endslot %}
+ {% slot "other_name" default %}
+ Default content
+ {% endslot %}
+ ```
+
+ ✅ Do this instead
+
+ ```django
+ {% slot "name" default %}
+ Default content
+ {% endslot %}
+ {% slot "name" default %}
+ Default content
+ {% endslot %}
+ ```
+
+!!! warning
+
+ Do NOT combine default fills with explicit named [`{% fill %}`](../../../reference/template_tags#fill) tags.
+
+ The following component template will raise an error when rendered:
+
+ ❌ Don't do this
+
+ ```django
+ {% component "calendar" date="2020-06-06" %}
+ {% fill "header" %}Totally new header!{% endfill %}
Can you believe it's already {{ date }}??
+ {% endcomponent %}
+ ```
+
+ ✅ Do this instead
+
+ ```django
+ {% component "calendar" date="2020-06-06" %}
+ {% fill "header" %}Totally new header!{% endfill %}
+ {% fill "default" %}
+ Can you believe it's already {{ date }}??
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+!!! warning
+
+ You cannot double-fill a slot.
+
+ That is, if both `{% fill "default" %}` and `{% fill "header" %}` point to the same slot,
+ this will raise an error when rendered.
+
+### Required slot
+
+You can make the slot required by adding the [`required`](../../../reference/template_tags#slot) keyword:
+
+```django
+{% slot "name" required %}
+ Default content
+{% endslot %}
+```
+
+This will raise an error if the slot is not filled.
+
+### Access fills
+
+You can access the fills with the
+[`{{ component_vars.slots.Calendar header
- Can you believe it's already 2020-06-06??
-
+ {% fill "my_slot" %}
+ Filled content
+ {% endfill %}
+
+{% endif %}
+```
+
+And in Python with the [`Component.slots`](../../../reference/api#django_components.Component.slots) property:
+
+```py
+class Calendar(Component):
+ # `get_template_data` receives the `slots` argument directly
+ def get_template_data(self, args, kwargs, slots, context):
+ if "my_slot" in slots:
+ content = "Filled content"
+ else:
+ content = "Default content"
+
+ return {
+ "my_slot": content,
+ }
+
+ # In other methods you can still access the slots with `Component.slots`
+ def on_render_before(self, context, template):
+ if "my_slot" in self.slots:
+ # Do something
+```
+
+### Dynamic fills
+
+The slot and fill names can be set as variables. This way you can fill slots dynamically:
+
+```django
+{% with "body" as slot_name %}
+ {% component "calendar" %}
+ {% fill slot_name %}
+ Filled content
+ {% endfill %}
+ {% endcomponent %}
+{% endwith %}
+```
+
+You can even use [`{% if %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#std-templatetag-if)
+and [`{% for %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#std-templatetag-for)
+tags inside the [`{% component %}`](../../../reference/template_tags#component) tag to fill slots with more control:
+
+```django
+{% component "calendar" %}
+ {% if condition %}
+ {% fill "name" %}
+ Filled content
+ {% endfill %}
+ {% endif %}
+
+ {% for item in items %}
+ {% fill item.name %}
+ Item: {{ item.value }}
+ {% endfill %}
+ {% endfor %}
+{% endcomponent %}
+```
+
+You can also use [`{% with %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#std-templatetag-with)
+or even custom tags to generate the fills dynamically:
+
+```django
+{% component "calendar" %}
+ {% with item.name as name %}
+ {% fill name %}
+ Item: {{ item.value }}
+ {% endfill %}
+ {% endwith %}
+{% endcomponent %}
+```
+
+!!! warning
+
+ If you dynamically generate `{% fill %}` tags, be careful to render text only inside the `{% fill %}` tags.
+
+ Any text rendered outside `{% fill %}` tags will be considered a default fill and will raise an error
+ if combined with explicit fills. (See [Default slot](#default-slot))
+
+### Slot data
+
+Sometimes the slots need to access data from the component. Imagine an HTML table component
+which has a slot to configure how to render the rows. Each row has a different data, so you need
+to pass the data to the slot.
+
+Similarly to [Vue's scoped slots](https://vuejs.org/guide/components/slots#scoped-slots),
+you can pass data to the slot, and then access it in the fill.
+
+This consists of two steps:
+
+1. Passing data to [`{% slot %}`](../../../reference/template_tags#slot) tag
+2. Accessing data in [`{% fill %}`](../../../reference/template_tags#fill) tag
+
+The data is passed to the slot as extra keyword arguments. Below we set two extra arguments: `first_name` and `job`.
+
+```django
+{# Pass data to the slot #}
+{% slot "name" first_name="John" job="Developer" %}
+ {# Fallback implementation #}
+ Name: {{ first_name }}
+ Job: {{ job }}
+{% endslot %}
+```
+
+!!! note
+
+ `name` kwarg is already used for slot name, so you cannot pass it as slot data.
+
+To access the slot's data in the fill, use the [`data`](../../../reference/template_tags#fill) keyword. This sets the name
+of the variable that holds the data in the fill:
+
+```django
+{# Access data in the fill #}
+{% component "profile" %}
+ {% fill "name" data="d" %}
+ Hello, my name is {{ d.first_name }}
+ and I'm a{{ d.job }}
{% endfill %} {% endcomponent %} ``` -NOTE: If you doubly-fill a slot, that is, that both `{% fill "default" %}` and `{% fill "header" %}` -would point to the same slot, this will raise an error when rendered. - -#### Accessing default slot in Python - -Since the default slot is stored under the slot name `default`, you can access the default slot -like so: +To access the slot data in Python, use the `data` attribute in [slot functions](#slot-functions). ```py -class MyTable(Component): - def get_context_data(self, *args, **kwargs): - default_slot = self.input.slots["default"] +def my_slot(ctx): + return f""" + Hello, my name is{ctx.data["first_name"]}
+ and I'm a{ctx.data["job"]}
+ """ + +Profile.render( + slots={ + "name": my_slot, + }, +) +``` + +Slot data can be set also when rendering a slot in Python: + +```py +slot = Slot(lambda ctx: f"Hello, {ctx.data['name']}!") + +# Render the slot +html = slot({"name": "John"}) +``` + +!!! info + + To access slot data on a [default slot](#default-slot), you have to explictly define the `{% fill %}` tags + with name `"default"`. + + ```django + {% component "my_comp" %} + {% fill "default" data="slot_data" %} + {{ slot_data.input }} + {% endfill %} + {% endcomponent %} + ``` + +!!! warning + + You cannot set the `data` attribute and + [`fallback` attribute](#slot-fallback) + to the same name. This raises an error: + + ```django + {% component "my_comp" %} + {% fill "content" data="slot_var" fallback="slot_var" %} + {{ slot_var.input }} + {% endfill %} + {% endcomponent %} + ``` + +### Slot fallback + +The content between the `{% slot %}..{% endslot %}` tags is the *fallback* content that +will be rendered if no fill is given for the slot. + +```django +{% slot "name" %} + Hello, my name is {{ name }} +{% endslot %} +``` + +Sometimes you may want to keep the fallback content, but only wrap it in some other content. + +To do so, you can access the fallback content via the [`fallback`](../../../reference/template_tags#fill) kwarg. +This sets the name of the variable that holds the fallback content in the fill: + +```django +{% component "profile" %} + {% fill "name" fallback="fb" %} + Original content: +
+ {{ fb }}
+
+ {% endfill %}
+{% endcomponent %}
+```
+
+To access the fallback content in Python, use the [`fallback`](../../../reference/api#django_components.SlotContext.fallback)
+attribute in [slot functions](#slot-functions).
+
+The fallback value is rendered lazily. Coerce the fallback to a string to render it.
+
+```py
+def my_slot(ctx):
+ # Coerce the fallback to a string
+ fallback = str(ctx.fallback)
+ return f"Original content: " + fallback
+
+Profile.render(
+ slots={
+ "name": my_slot,
+ },
+)
+```
+
+Fallback can be set also when rendering a slot in Python:
+
+```py
+slot = Slot(lambda ctx: f"Hello, {ctx.data['name']}!")
+
+# Render the slot
+html = slot({"name": "John"}, fallback="Hello, world!")
+```
+
+!!! info
+
+ To access slot fallback on a [default slot](#default-slot), you have to explictly define the `{% fill %}` tags
+ with name `"default"`.
+
+ ```django
+ {% component "my_comp" %}
+ {% fill "default" fallback="fallback" %}
+ {{ fallback }}
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+!!! warning
+
+ You cannot set the [`data`](#slot-data) attribute and
+ `fallback` attribute
+ to the same name. This raises an error:
+
+ ```django
+ {% component "my_comp" %}
+ {% fill "content" data="slot_var" fallback="slot_var" %}
+ {{ slot_var.input }}
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+### Slot functions
+
+In Python code, slot fills can be defined as strings, functions, or
+[`Slot`](../../../reference/api#django_components.Slot) instances that wrap the two.
+Slot functions have access to slot [`data`](../../../reference/api#django_components.SlotContext.data),
+[`fallback`](../../../reference/api#django_components.SlotContext.fallback),
+and [`context`](../../../reference/api#django_components.SlotContext.context).
+
+```py
+def row_slot(ctx):
+ if ctx.data["disabled"]:
+ return ctx.fallback
+
+ item = ctx.data["item"]
+ if ctx.data["type"] == "table":
+ return f"
-
+ return {
+ "my_fill": Slot(my_fill),
+ }
```
-So if used like:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "image" %}
-
- {% slot "image" %}Image here{% endslot %}
-
-
- {% slot "image" %}Image here{% endslot %}
-
-
-
+ Django automatically executes functions when it comes across them in templates.
+
+ Because of this you MUST wrap the function in [`Slot`](../../../reference/api#django_components.Slot)
+ instance to prevent it from being called.
+
+ Read more about Django's [`do_not_call_in_templates`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#variables-and-lookups).
+
+## Slot class
+
+The [`Slot`](../../../reference/api#django_components.Slot) class is a wrapper around a function that can be used to fill a slot.
+
+```py
+from django_components import Component, Slot
+
+def footer(ctx):
+ return f"Hello, {ctx.data['name']}!"
+
+Table.render(
+ slots={
+ "footer": Slot(footer),
+ },
+)
```
-#### Default and required slots
+Slot class can be instantiated with a function or a string:
-If you use a slot multiple times, you can still mark the slot as `default` or `required`.
-For that, you must mark each slot individually, e.g.:
-
-```htmldjango
-
- 
-
-
-
-
-
-
+```py
+slot1 = Slot(lambda ctx: f"Hello, {ctx.data['name']}!")
+slot2 = Slot("Hello, world!")
```
-Which you can then use as regular default slot:
+!!! warning
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
-
- {% slot "image" default required %}Image here{% endslot %}
-
-
- {% slot "image" default required %}Image here{% endslot %}
-
-
+ {% slot "date" default date=date / %}
+
+ """
+
+Calendar.render(
+ slots={
+ "date": escape("Hello"),
+ }
+)
+```
+
+To disable escaping, you can wrap the slot string or slot result in Django's [`mark_safe()`](https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.safestring.mark_safe):
+
+```py
+Calendar.render(
+ slots={
+ # string
+ "date": mark_safe("Hello"),
+
+ # function
+ "date": lambda ctx: mark_safe("Hello"),
+ }
+)
+```
+
+!!! info
+
+ Read more about Django's
+ [`format_html`](https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.html.format_html)
+ and [`mark_safe`](https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.safestring.mark_safe).
+
+## Examples
+
+### Pass through all the slots
+
+You can dynamically pass all slots to a child component. This is similar to
+[passing all slots in Vue](https://vue-land.github.io/faq/forwarding-slots#passing-all-slots):
+
+```djc_py
+class MyTable(Component):
+ template = """
+
+ {% component "child" %}
+ {% for slot_name, slot in component_vars.slots.items %}
+ {% fill name=slot_name body=slot / %}
+ {% endfor %}
+ {% endcomponent %}
+
+ """
+```
+
+### Required and default slots
+
+Since each [`{% slot %}`](../../../reference/template_tags#slot) is tagged
+with [`required`](#required-slot) and [`default`](#default-slot) individually, you can have multiple slots
with the same name but different conditions.
-E.g. in this example, we have a component that renders a user avatar - a small circular image with a profile picture or name initials.
+In this example, we have a component that renders a user avatar - a small circular image with a profile picture or name initials.
If the component is given `image_src` or `name_initials` variables,
-the `image` slot is optional. But if neither of those are provided,
-you MUST fill the `image` slot.
+the `image` slot is optional.
+
+But if neither of those are provided, you MUST fill the `image` slot.
```htmldjango
+ {# Image given, so slot is optional #}
{% if image_src %}
{% slot "image" default %}
{% endslot %}
+
+ {# Image not given, but we can make image from initials, so slot is optional #}
{% elif name_initials %}
{% slot "image" default %}
```
-### Accessing original content of slots
+### Dynamic slots in table component
-_Added in version 0.26_
+Sometimes you may want to generate slots based on the given input. One example of this is [Vuetify's table component](https://vuetifyjs.com/en/api/v-data-table/), which creates a header and an item slots for each user-defined column.
-> NOTE: In version 0.77, the syntax was changed from
->
-> ```django
-> {% fill "my_slot" as "alias" %} {{ alias.default }}
-> ```
->
-> to
->
-> ```django
-> {% fill "my_slot" default="slot_default" %} {{ slot_default }}
-> ```
-
-Sometimes you may want to keep the original slot, but only wrap or prepend/append content to it. To do so, you can access the default slot via the `default` kwarg.
-
-Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
-
-For instance, let's say you're filling a slot called 'body'. To render the original slot, assign it to a variable using the `'default'` keyword. You then render this variable to insert the default content:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "body" default="body_default" %}
- {{ body_default }}. Have a great day!
- {% endfill %}
-{% endcomponent %}
-```
-
-This produces:
-
-```htmldjango
- }}` variable. You can use this together with Django's `{% if/elif/else/endif %}` tags to define a block whose contents will be rendered only if the component slot with
-the corresponding 'name' is filled.
-
-This is what our example looks like with `component_vars.is_filled`.
-
-```htmldjango
-
@@ -599,9 +964,9 @@ When using the component, you can either set the fill explicitly:
```django
{% component "table" headers=headers items=items %}
- {% fill "header-name" data="data" %}
- {{ data.value }}
- {% endfill %}
+ {% fill "header-name" data="data" %}
+ {{ data.value }}
+ {% endfill %}
{% endcomponent %}
```
@@ -609,16 +974,22 @@ Or also use a variable:
```django
{% component "table" headers=headers items=items %}
- {# Make only the active column bold #}
- {% fill "header-{{ active_header_name }}" data="data" %}
- {{ data.value }}
- {% endfill %}
+ {% fill "header-{{ active_header_name }}" data="data" %}
+ {{ data.value }}
+ {% endfill %}
{% endcomponent %}
```
-> NOTE: It's better to use static slot names whenever possible for clarity. The dynamic slot names should be reserved for advanced use only.
+!!! note
-Lastly, in rare cases, you can also pass the slot name via [the spread operator](#spread-operator). This is possible, because the slot name argument is actually a shortcut for a `name` keyword argument.
+ It's better to use literal slot names whenever possible for clarity.
+ The dynamic slot names should be reserved for advanced use only.
+
+### Spread operator
+
+Lastly, you can also pass the slot name through the [spread operator](../template_tag_syntax#spread-operator).
+
+When you define a slot name, it's actually a shortcut for a `name` keyword argument.
So this:
@@ -639,27 +1010,85 @@ So it's possible to define a `name` key on a dictionary, and then spread that on
{% slot ...slot_props / %}
```
-### Pass through all the slots
-
-You can dynamically pass all slots to a child component. This is similar to
-[passing all slots in Vue](https://vue-land.github.io/faq/forwarding-slots#passing-all-slots):
+Full example:
```djc_py
class MyTable(Component):
- def get_context_data(self, *args, **kwargs):
- return {
- "slots": self.input.slots,
- }
-
template = """
-
```
+ Fill:
+
```django
{% component "my_table" %}
- {% fill "pagination" default="default_pag" %}
+ {% fill "pagination" fallback="fallback" %}
+ # }
+ # ```
+ #
+ # Since our template is inlined, we will format as `filepath::ComponentName`
+ #
+ # ```
+ # /path/to/project/django-components/src/calendarapp/calendar.html::Calendar
+ # ```
+ #
+ # See https://docs.djangoproject.com/en/5.2/howto/custom-template-backend/#template-origin-api
+ _, _, module_filepath = get_module_info(component)
+ origin = Origin(
+ name=f"{module_filepath}::{component.__name__}",
+ template_name=None,
+ loader=None,
+ )
+
+ set_component_to_origin(origin, component)
+
+ if is_component_template:
+ template = Template(template_string, name=origin.template_name, origin=origin)
+ else:
+ # TODO_V1 - `cached_template()` won't be needed as there will be only 1 template per component
+ # so we will be able to instead use `template_cache` to store the template
+ template = cached_template(
+ template_string=template_string,
+ name=origin.template_name,
+ origin=origin,
+ )
+
+ return template
+
+
+# When loading a template, use Django's `get_template()` to ensure it triggers Django template loaders
+# See https://github.com/django-components/django-components/issues/901
+#
+# This may raise `TemplateDoesNotExist` if the template doesn't exist.
+# See https://docs.djangoproject.com/en/5.2/ref/templates/api/#template-loaders
+# And https://docs.djangoproject.com/en/5.2/ref/templates/api/#custom-template-loaders
+#
+# TODO_v3 - Instead of loading templates with Django's `get_template()`,
+# we should simply read the files directly (same as we do for JS and CSS).
+# This has the implications that:
+# - We would no longer support Django's template loaders
+# - Instead if users are using template loaders, they should re-create them as djc extensions
+# - We would no longer need to set `TEMPLATES.OPTIONS.loaders` to include
+# `django_components.template_loader.Loader`
+def _load_django_template(template_name: str) -> Template:
+ return django_get_template(template_name).template
+
+
+########################################################
+# ASSOCIATING COMPONENT CLASSES WITH TEMPLATES
+#
+# See https://github.com/django-components/django-components/pull/1222
+########################################################
+
+# NOTE: `ReferenceType` is NOT a generic pre-3.9
+if sys.version_info >= (3, 9):
+ ComponentRef = ReferenceType[Type["Component"]]
+else:
+ ComponentRef = ReferenceType
+
+
+# Remember which Component classes defined `template_file`. Since multiple Components may
+# define the same `template_file`, we store a list of weak references to the Component classes.
+component_template_file_cache: Dict[str, List[ComponentRef]] = {}
+component_template_file_cache_initialized = False
+
+
+# Remember the mapping of `Component.template_file` -> `Component` class, so that we can associate
+# the `Template` instances with the correct Component class in our monkepatched `Template.__init__()`.
+def cache_component_template_file(component_cls: Type["Component"]) -> None:
+ # When a Component class is created before Django is set up,
+ # then `component_template_file_cache_initialized` is False and we leave it for later.
+ # This is necessary because:
+ # 1. We might need to resolve the template_file as relative to the file where the Component class is defined.
+ # 2. To be able to resolve the template_file, Django needs to be set up, because we need to access Django settings.
+ # 3. Django settings may not be available at the time of Component class creation.
+ if not component_template_file_cache_initialized:
+ return
+
+ # NOTE: Avoids circular import
+ from django_components.component_media import ComponentMedia, Unset, _resolve_component_relative_files, is_set
+
+ # If we access the `Component.template_file` attribute, then this triggers media resolution if it was not done yet.
+ # The problem is that this also causes the loading of the Template, if Component has defined `template_file`.
+ # This triggers `Template.__init__()`, which then triggers another call to `cache_component_template_file()`.
+ #
+ # At the same time, at this point we don't need the media files to be loaded. But we DO need for the relative
+ # file path to be resolved.
+ #
+ # So for this reason, `ComponentMedia.resolved_relative_files` was added to track if the media files were resolved.
+ # Once relative files were resolved, we can safely access the template file from `ComponentMedia` instance
+ # directly, thus avoiding the triggering of the Template loading.
+ comp_media: ComponentMedia = component_cls._component_media # type: ignore[attr-defined]
+ if comp_media.resolved and comp_media.resolved_relative_files:
+ template_file: Union[str, Unset, None] = component_cls.template_file
+ else:
+ # NOTE: This block of code is based on `_resolve_media()` in `component_media.py`
+ if not comp_media.resolved_relative_files:
+ comp_dirs = get_component_dirs()
+ _resolve_component_relative_files(component_cls, comp_media, comp_dirs=comp_dirs)
+
+ template_file = comp_media.template_file
+
+ if not is_set(template_file):
+ return
+
+ if template_file not in component_template_file_cache:
+ component_template_file_cache[template_file] = []
+
+ component_template_file_cache[template_file].append(ref(component_cls))
+
+
+def get_component_by_template_file(template_file: str) -> Optional[Type["Component"]]:
+ # This function is called from within `Template.__init__()`. At that point, Django MUST be already set up,
+ # because Django's `Template.__init__()` accesses the templating engines.
+ #
+ # So at this point we want to call `cache_component_template_file()` for all Components for which
+ # we skipped it earlier.
+ global component_template_file_cache_initialized
+ if not component_template_file_cache_initialized:
+ component_template_file_cache_initialized = True
+
+ # NOTE: Avoids circular import
+ from django_components.component import all_components
+
+ components = all_components()
+ for component in components:
+ cache_component_template_file(component)
+
+ if template_file not in component_template_file_cache or not len(component_template_file_cache[template_file]):
+ return None
+
+ # There is at least one Component class that has this `template_file`.
+ matched_component_refs = component_template_file_cache[template_file]
+
+ # There may be multiple components that define the same `template_file`.
+ # So to find the correct one, we need to check if the currently loading component
+ # is one of the ones that define the `template_file`.
+ #
+ # If there are NO currently loading components, then `Template.__init__()` was NOT triggered by us,
+ # in which case we don't associate any Component class with this Template.
+ if not len(loading_components):
+ return None
+
+ loading_component = loading_components[-1]()
+ if loading_component is None:
+ return None
+
+ for component_ref in matched_component_refs:
+ comp_cls = component_ref()
+ if comp_cls is loading_component:
+ return comp_cls
+
+ return None
+
+
+# NOTE: Used by `@djc_test` to reset the component template file cache
+def _reset_component_template_file_cache() -> None:
+ global component_template_file_cache
+ component_template_file_cache = {}
+
+ global component_template_file_cache_initialized
+ component_template_file_cache_initialized = False
+
+
+# Helpers so we know where in the codebase we set / access the `Origin.component_cls` attribute
+def set_component_to_origin(origin: Origin, component_cls: Type["Component"]) -> None:
+ origin.component_cls = component_cls
+
+
+def get_component_from_origin(origin: Origin) -> Optional[Type["Component"]]:
+ return getattr(origin, "component_cls", None)
diff --git a/src/django_components/template_loader.py b/src/django_components/template_loader.py
index b6d48097..4545ffda 100644
--- a/src/django_components/template_loader.py
+++ b/src/django_components/template_loader.py
@@ -10,7 +10,7 @@ from django.template.loaders.filesystem import Loader as FilesystemLoader
from django_components.util.loader import get_component_dirs
-class Loader(FilesystemLoader):
+class DjcLoader(FilesystemLoader):
def get_dirs(self, include_apps: bool = True) -> List[Path]:
"""
Prepare directories that may contain component files:
@@ -26,3 +26,10 @@ class Loader(FilesystemLoader):
`BASE_DIR` setting is required.
"""
return get_component_dirs(include_apps)
+
+
+# NOTE: Django's template loaders have the pattern of using the `Loader` class name.
+# However, this then makes it harder to track and distinguish between different loaders.
+# So internally we use the name `DjcLoader` instead.
+# But for public API we use the name `Loader` to match Django.
+Loader = DjcLoader
diff --git a/src/django_components/templatetags/component_tags.py b/src/django_components/templatetags/component_tags.py
index bc4868d5..e3f2117e 100644
--- a/src/django_components/templatetags/component_tags.py
+++ b/src/django_components/templatetags/component_tags.py
@@ -7,7 +7,7 @@ from django_components.provide import ProvideNode
from django_components.slots import FillNode, SlotNode
# NOTE: Variable name `register` is required by Django to recognize this as a template tag library
-# See https://docs.djangoproject.com/en/dev/howto/custom-template-tags
+# See https://docs.djangoproject.com/en/5.2/howto/custom-template-tags
register = django.template.Library()
diff --git a/src/django_components/types.py b/src/django_components/types.py
index b7a55ab8..61e38ccb 100644
--- a/src/django_components/types.py
+++ b/src/django_components/types.py
@@ -1,6 +1,6 @@
"""Helper types for IDEs."""
-from django_components.util.types import Annotated
+from typing_extensions import Annotated
css = Annotated[str, "css"]
django_html = Annotated[str, "django_html"]
diff --git a/src/django_components/util/command.py b/src/django_components/util/command.py
index e04f8ac0..e4de943c 100644
--- a/src/django_components/util/command.py
+++ b/src/django_components/util/command.py
@@ -1,11 +1,35 @@
import sys
from argparse import Action, ArgumentParser
from dataclasses import asdict, dataclass
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Literal, Optional, Protocol, Sequence, Type, Union
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Callable,
+ Dict,
+ List,
+ Literal,
+ Optional,
+ Protocol,
+ Sequence,
+ Type,
+ TypeVar,
+ Union,
+)
if TYPE_CHECKING:
from argparse import _ArgumentGroup, _FormatterClass
+
+TClass = TypeVar("TClass", bound=Type[Any])
+
+
+# Mark object as related to extension commands so we can place these in
+# a separate documentation section
+def mark_extension_command_api(obj: TClass) -> TClass:
+ obj._extension_command_api = True
+ return obj
+
+
#############################
# Argparse typing
#############################
@@ -19,8 +43,10 @@ The basic type of action to be taken when this argument is encountered at the co
This is a subset of the values for `action` in
[`ArgumentParser.add_argument()`](https://docs.python.org/3/library/argparse.html#the-add-argument-method).
"""
+mark_extension_command_api(CommandLiteralAction) # type: ignore
+@mark_extension_command_api
@dataclass
class CommandArg:
"""
@@ -77,6 +103,7 @@ class CommandArg:
return _remove_none_values(asdict(self))
+@mark_extension_command_api
@dataclass
class CommandArgGroup:
"""
@@ -102,6 +129,7 @@ class CommandArgGroup:
return _remove_none_values(asdict(self))
+@mark_extension_command_api
@dataclass
class CommandSubcommand:
"""
@@ -158,6 +186,7 @@ class CommandSubcommand:
return _remove_none_values(asdict(self))
+@mark_extension_command_api
@dataclass
class CommandParserInput:
"""
@@ -203,16 +232,18 @@ class CommandParserInput:
#############################
+@mark_extension_command_api
class CommandHandler(Protocol):
def __call__(self, *args: Any, **kwargs: Any) -> None: ... # noqa: E704
+@mark_extension_command_api
class ComponentCommand:
"""
Definition of a CLI command.
This class is based on Python's [`argparse`](https://docs.python.org/3/library/argparse.html)
- module and Django's [`BaseCommand`](https://docs.djangoproject.com/en/5.1/howto/custom-management-commands/)
+ module and Django's [`BaseCommand`](https://docs.djangoproject.com/en/5.2/howto/custom-management-commands/)
class. `ComponentCommand` allows you to define:
- Command name, description, and help text
diff --git a/src/django_components/util/component_highlight.py b/src/django_components/util/component_highlight.py
deleted file mode 100644
index 7e9adae0..00000000
--- a/src/django_components/util/component_highlight.py
+++ /dev/null
@@ -1,43 +0,0 @@
-from typing import Literal, NamedTuple
-
-from django_components.util.misc import gen_id
-
-
-class HighlightColor(NamedTuple):
- text_color: str
- border_color: str
-
-
-COLORS = {
- "component": HighlightColor(text_color="#2f14bb", border_color="blue"),
- "slot": HighlightColor(text_color="#bb1414", border_color="#e40c0c"),
-}
-
-
-def apply_component_highlight(type: Literal["component", "slot"], output: str, name: str) -> str:
- """
- Wrap HTML (string) in a div with a border and a highlight color.
-
- This is part of the component / slot highlighting feature. User can toggle on
- to see the component / slot boundaries.
- """
- color = COLORS[type]
-
- # Because the component / slot name is set via styling as a `::before` pseudo-element,
- # we need to generate a unique ID for each component / slot to avoid conflicts.
- highlight_id = gen_id()
-
- output = f"""
-
- , got 123.5 of type ` # noqa: E501
- raise TypeError(
- f"{prefix} expected {kind} at index {index} to be {arg_type}, got {arg} of type {type(arg)}"
- )
-
-
-# NOTE:
-# - `dict_type` can be a `TypedDict` or `Any` as the types themselves
-# - `value` is expected to be TypedDict, the base `TypedDict` type cannot be used
-# in function signature (only its subclasses can), so we specify the type as Mapping.
-# See https://stackoverflow.com/questions/74412803
-def validate_typed_dict(value: Mapping[str, Any], dict_type: Any, prefix: str, kind: str) -> None:
- # `Any` type is the signal that we should skip validation
- if dict_type == Any:
- return
-
- # See https://stackoverflow.com/a/76527675
- # And https://stackoverflow.com/a/71231688
- required_kwargs = dict_type.__required_keys__
- unseen_keys = set(value.keys())
-
- # For each entry in the TypedDict, we do two kinds of validation:
- # 1. We check whether there are any extra / missing keys
- # 2. We look at the values of TypedDict entries (which are types themselves),
- # and check if our concrete dict has correct types under correct keys.
- for key, kwarg_type in get_type_hints(dict_type).items():
- if key not in value:
- if key in required_kwargs:
- # Generate errors like below (listed for searchability)
- # `Component 'name' is missing a required keyword argument 'key'`
- # `Component 'name' is missing a required slot argument 'key'`
- # `Component 'name' is missing a required data argument 'key'`
- raise TypeError(f"{prefix} is missing a required {kind} '{key}'")
- else:
- unseen_keys.remove(key)
- kwarg = value[key]
- kwarg_type = _prepare_type_for_validation(kwarg_type)
-
- # NOTE: `isinstance()` cannot be used with the version of TypedDict prior to 3.11.
- # So we do type validation for TypedDicts only in 3.11 and later.
- if sys.version_info >= (3, 11) and not isinstance(kwarg, kwarg_type):
- # Generate errors like below (listed for searchability)
- # `Component 'name' expected keyword argument 'key' to be , got 123.4 of type ` # noqa: E501
- # `Component 'name' expected slot 'key' to be , got 123.4 of type `
- # `Component 'name' expected data 'key' to be , got 123.4 of type `
- raise TypeError(
- f"{prefix} expected {kind} '{key}' to be {kwarg_type}, got {kwarg} of type {type(kwarg)}"
- )
-
- if unseen_keys:
- formatted_keys = ", ".join([f"'{key}'" for key in unseen_keys])
- # Generate errors like below (listed for searchability)
- # `Component 'name' got unexpected keyword argument keys 'invalid_key'`
- # `Component 'name' got unexpected slot keys 'invalid_key'`
- # `Component 'name' got unexpected data keys 'invalid_key'`
- raise TypeError(f"{prefix} got unexpected {kind} keys {formatted_keys}")
diff --git a/src/django_components_js/README.md b/src/django_components_js/README.md
index 5c7f0fff..f6eb3ad0 100644
--- a/src/django_components_js/README.md
+++ b/src/django_components_js/README.md
@@ -25,8 +25,8 @@ Components.registerComponentData(
// we can run component's init function
Components.callComponent(
"table", // Component name
- 12345, // Component ID - An HTML element with corresponding
- // attribute (`data-djc-id-12345`) MUST
+ "c123456", // Component ID - An HTML element with corresponding
+ // attribute (`data-djc-id-c123456`) MUST
// be present in the DOM.
"3d09cf", // Input ID
);
diff --git a/tests/__snapshots__/test_benchmark_djc.ambr b/tests/__snapshots__/test_benchmark_djc.ambr
index 52dc2801..4a23fe00 100644
--- a/tests/__snapshots__/test_benchmark_djc.ambr
+++ b/tests/__snapshots__/test_benchmark_djc.ambr
@@ -11,7 +11,7 @@
-
+
@@ -43,7 +43,7 @@
-
-```
-
-To access the original content of a default slot, set the name to `default`:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "default" default="slot_default" %}
- {{ slot_default }}. Have a great day!
- {% endfill %}
-{% endcomponent %}
-```
-
-### Conditional slots
-
-_Added in version 0.26._
-
-> NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section [Accessing `is_filled` of slot names with special characters](#accessing-is_filled-of-slot-names-with-special-characters).
-
-In certain circumstances, you may want the behavior of slot filling to depend on
-whether or not a particular slot is filled.
-
-For example, suppose we have the following component template:
-
-```htmldjango
-
- Calendar header
-
-
- Today's date is 2020-06-06. Have a great day!
-
-
-
-```
-
-By default the slot named 'subtitle' is empty. Yet when the component is used without
-explicit fills, the div containing the slot is still rendered, as shown below:
-
-```html
-
- {% slot "title" %}Title{% endslot %}
-
-
- {% slot "subtitle" %}{# Optional subtitle #}{% endslot %}
-
-
-
-```
-
-This may not be what you want. What if instead the outer 'subtitle' div should only
-be included when the inner slot is in fact filled?
-
-The answer is to use the `{{ component_vars.is_filled.Title
-
-
-
-```
-
-Here's our example with more complex branching.
-
-```htmldjango
-
- {% slot "title" %}Title{% endslot %}
-
- {% if component_vars.is_filled.subtitle %}
-
- {% slot "subtitle" %}{# Optional subtitle #}{% endslot %}
-
- {% endif %}
-
- %}
- ...
- {% endif %}
-
-```
-
-Sometimes you're not interested in whether a slot is filled, but rather that it _isn't_.
-To negate the meaning of `component_vars.is_filled`, simply treat it as boolean and negate it with `not`:
-
-```htmldjango
-{% if not component_vars.is_filled.subtitle %}
-
- {% slot "title" %}Title{% endslot %}
-
- {% if component_vars.is_filled.subtitle %}
-
- {% slot "subtitle" %}{# Optional subtitle #}{% endslot %}
-
- {% elif component_vars.is_filled.title %}
- ...
- {% elif component_vars.is_filled.
- {% slot "subtitle" / %}
-
-{% endif %}
-```
-
-#### Accessing `is_filled` of slot names with special characters
-
-To be able to access a slot name via `component_vars.is_filled`, the slot name needs to be composed of only alphanumeric characters and underscores (e.g. `this__isvalid_123`).
-
-However, you can still define slots with other special characters. In such case, the slot name in `component_vars.is_filled` is modified to replace all invalid characters into `_`.
-
-So a slot named `"my super-slot :)"` will be available as `component_vars.is_filled.my_super_slot___`.
-
-Same applies when you are accessing `is_filled` from within the Python, e.g.:
+So if you pass columns named `name` and `age` to the table component:
```py
-class MyTable(Component):
- def on_render_before(self, context, template) -> None:
- # ✅ Works
- if self.is_filled["my_super_slot___"]:
- # Do something
-
- # ❌ Does not work
- if self.is_filled["my super-slot :)"]:
- # Do something
+[
+ {"key": "name", "title": "Name"},
+ {"key": "age", "title": "Age"},
+]
```
-### Conditional fills
-
-Similarly, you can use `{% if %}` and `{% for %}` when defining the `{% fill %}` tags, to conditionally fill the slots when using the componnet:
-
-In the example below, the `{% fill "footer" %}` fill is used only if the condition is true. If falsy, the fill is ignored, and so the `my_table` component will use its default content for the `footer` slot.
-
-```django_html
-{% component "my_table" %}
- {% if editable %}
- {% fill "footer" %}
-
- {% endfill %}
- {% endif %}
-{% endcomponent %}
-```
-
-You can even combine `{% if %}` and `{% for %}`:
-
-```django_html
-{% component "my_table" %}
- {% for header in headers %}
- {% if header != "hyperlink" %}
- {# Generate fill name like `header.my_column` #}
- {% fill name="header."|add:header" %}
- {{ header }}
- {% endfill %}
- {% endif %}
- {% endfor %}
-{% 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:
-
-```djc_py
-@register("my_comp")
-class MyComp(Component):
- template = """
-
- {% slot "content" default %}
- input: {{ input }}
- {% endslot %}
-
- """
-
- 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](https://vuejs.org/guide/components/slots.html#scoped-slots) and [scoped slots of django-web-components](https://github.com/Xzya/django-web-components/tree/master?tab=readme-ov-file#scoped-slots).
-
-Using scoped slots consists of two steps:
-
-1. Passing data to `slot` tag
-2. 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`):
-
-```djc_py
-@register("my_comp")
-class MyComp(Component):
- template = """
-
- {% slot "content" default input=input %}
- input: {{ input }}
- {% endslot %}
-
- """
-
- def get_context_data(self, input):
- processed_input = do_something(input)
- return {
- "input": processed_input,
- }
-```
-
-#### Accessing slot data in fill
-
-Next, we head over to where we define a fill for this slot. Here, to access the slot data
-we set the `data` attribute to the name of the variable through which we want to access
-the slot data. In the example below, we set it to `data`:
+Then the component will accept fills named `header-name` and `header-age` (among others):
```django
-{% component "my_comp" %}
- {% fill "content" data="slot_data" %}
- {{ slot_data.input }}
- {% endfill %}
-{% endcomponent %}
+{% fill "header-name" data="data" %}
+ {{ data.value }}
+{% endfill %}
+
+{% fill "header-age" data="data" %}
+ {{ data.value }}
+{% endfill %}
```
-To access slot data on a default slot, you have to explictly define the `{% fill %}` tags.
-
-So this works:
-
-```django
-{% component "my_comp" %}
- {% fill "content" data="slot_data" %}
- {{ slot_data.input }}
- {% endfill %}
-{% endcomponent %}
-```
-
-While this does not:
-
-```django
-{% component "my_comp" data="data" %}
- {{ data.input }}
-{% endcomponent %}
-```
-
-Note: You cannot set the `data` attribute and
-[`default` attribute)](#accessing-original-content-of-slots)
-to the same name. This raises an error:
-
-```django
-{% component "my_comp" %}
- {% fill "content" data="slot_var" default="slot_var" %}
- {{ slot_var.input }}
- {% endfill %}
-{% endcomponent %}
-```
-
-#### Slot data of default slots
-
-To access data of a default slot, you can specify `{% fill name="default" %}`:
-
-```htmldjango
-{% component "my_comp" %}
- {% fill "default" data="slot_data" %}
- {{ slot_data.input }}
- {% endfill %}
-{% endcomponent %}
-```
-
-### Dynamic slots and fills
-
-Until now, we were declaring slot and fill names statically, as a string literal, e.g.
-
-```django
-{% slot "content" / %}
-```
-
-However, sometimes you may want to generate slots based on the given input. One example of this is [a table component like that of Vuetify](https://vuetifyjs.com/en/api/v-data-table/), which creates a header and an item slots for each user-defined column.
-
-In django_components you can achieve the same, simply by using a variable (or a [template expression](#use-template-tags-inside-component-inputs)) instead of a string literal:
+In django-components you can achieve the same, simply by using a variable or a [template expression](../template_tag_syntax#template-tags-inside-literal-strings) instead of a string literal:
```django
- {{ default_pag }}
+ {{ fallback }}
{% endfill %}
{% endcomponent %}
```
- ### Accessing slot's data with the `data` kwarg
+ ### Access slot data
+
+ Use the `data` kwarg to access the data passed to the slot.
+
+ The `data` kwarg defines the name of the variable that will contain the slot's data.
+
+ Read more about [Slot data](../../concepts/fundamentals/slots#slot-data).
+
+ Component template:
```django
{# my_table.html #}
@@ -674,6 +1065,8 @@ class FillNode(BaseNode):
```
+ Fill:
+
```django
{% component "my_table" %}
{% fill "pagination" data="slot_data" %}
@@ -686,26 +1079,85 @@ class FillNode(BaseNode):
{% endcomponent %}
```
- ### Accessing slot data and default content on the default slot
+ ### Using default slot
- To access slot data and the default slot content on the default slot,
- use `{% fill %}` with `name` set to `"default"`:
+ To access slot data and the fallback slot content on the default slot,
+ use [`{% fill %}`](../template_tags#fill) with `name` set to `"default"`:
```django
{% component "button" %}
- {% fill name="default" data="slot_data" default="default_slot" %}
+ {% fill name="default" data="slot_data" fallback="slot_fallback" %}
You clicked me {{ slot_data.count }} times!
- {{ default_slot }}
+ {{ slot_fallback }}
{% endfill %}
{% endcomponent %}
```
+
+ ### Slot fills from Python
+
+ You can pass a slot fill from Python to a component by setting the `body` kwarg
+ on the [`{% fill %}`](../template_tags#fill) tag.
+
+ First pass a [`Slot`](../api#django_components.Slot) instance to the template
+ with the [`get_template_data()`](../api#django_components.Component.get_template_data)
+ method:
+
+ ```python
+ from django_components import component, Slot
+
+ class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "my_slot": Slot(lambda ctx: "Hello, world!"),
+ }
+ ```
+
+ Then pass the slot to the [`{% fill %}`](../template_tags#fill) tag:
+
+ ```django
+ {% component "table" %}
+ {% fill "pagination" body=my_slot / %}
+ {% endcomponent %}
+ ```
+
+ !!! warning
+
+ If you define both the `body` kwarg and the [`{% fill %}`](../template_tags#fill) tag's body,
+ an error will be raised.
+
+ ```django
+ {% component "table" %}
+ {% fill "pagination" body=my_slot %}
+ ...
+ {% endfill %}
+ {% endcomponent %}
+ ```
"""
tag = "fill"
end_tag = "endfill"
allowed_flags = []
- def render(self, context: Context, name: str, *, data: Optional[str] = None, default: Optional[str] = None) -> str:
+ def render(
+ self,
+ context: Context,
+ name: str,
+ *,
+ data: Optional[str] = None,
+ fallback: Optional[str] = None,
+ body: Optional[SlotInput] = None,
+ # TODO_V1: Use `fallback` kwarg instead of `default`
+ default: Optional[str] = None,
+ ) -> str:
+ # TODO_V1: Use `fallback` kwarg instead of `default`
+ if fallback is not None and default is not None:
+ raise TemplateSyntaxError(
+ f"Fill tag received both 'default' and '{FILL_FALLBACK_KWARG}' kwargs. "
+ f"Use '{FILL_FALLBACK_KWARG}' instead."
+ )
+ elif fallback is None and default is not None:
+ fallback = default
+
if not _is_extracting_fill(context):
raise TemplateSyntaxError(
"FillNode.render() (AKA {% fill ... %} block) cannot be rendered outside of a Component context. "
@@ -718,36 +1170,43 @@ class FillNode(BaseNode):
if data is not None:
if not isinstance(data, str):
- raise TemplateSyntaxError(f"Fill tag '{SLOT_DATA_KWARG}' kwarg must resolve to a string, got {data}")
+ raise TemplateSyntaxError(f"Fill tag '{FILL_DATA_KWARG}' kwarg must resolve to a string, got {data}")
if not is_identifier(data):
raise RuntimeError(
- f"Fill tag kwarg '{SLOT_DATA_KWARG}' does not resolve to a valid Python identifier, got '{data}'"
+ f"Fill tag kwarg '{FILL_DATA_KWARG}' does not resolve to a valid Python identifier, got '{data}'"
)
- if default is not None:
- if not isinstance(default, str):
+ if fallback is not None:
+ if not isinstance(fallback, str):
raise TemplateSyntaxError(
- f"Fill tag '{SLOT_DEFAULT_KWARG}' kwarg must resolve to a string, got {default}"
+ f"Fill tag '{FILL_FALLBACK_KWARG}' kwarg must resolve to a string, got {fallback}"
)
- if not is_identifier(default):
+ if not is_identifier(fallback):
raise RuntimeError(
- f"Fill tag kwarg '{SLOT_DEFAULT_KWARG}' does not resolve to a valid Python identifier,"
- f" got '{default}'"
+ f"Fill tag kwarg '{FILL_FALLBACK_KWARG}' does not resolve to a valid Python identifier,"
+ f" got '{fallback}'"
)
- # data and default cannot be bound to the same variable
- if data and default and data == default:
+ # data and fallback cannot be bound to the same variable
+ if data and fallback and data == fallback:
raise RuntimeError(
- f"Fill '{name}' received the same string for slot default ({SLOT_DEFAULT_KWARG}=...)"
- f" and slot data ({SLOT_DATA_KWARG}=...)"
+ f"Fill '{name}' received the same string for slot fallback ({FILL_FALLBACK_KWARG}=...)"
+ f" and slot data ({FILL_DATA_KWARG}=...)"
+ )
+
+ if body is not None and self.contents:
+ raise TemplateSyntaxError(
+ f"Fill '{name}' received content both through '{FILL_BODY_KWARG}' kwarg and '{{% fill %}}' body. "
+ f"Use only one method."
)
fill_data = FillWithData(
fill=self,
name=name,
- default_var=default,
+ fallback_var=fallback,
data_var=data,
extra_context={},
+ body=body,
)
self._extract_fill(context, fill_data)
@@ -763,10 +1222,13 @@ class FillNode(BaseNode):
# ...
# {% endfill %}
# {% endfor %}
- collected_fills: List[FillWithData] = context.get(FILL_GEN_CONTEXT_KEY, None)
+ captured_fills: Optional[List[FillWithData]] = context.get(FILL_GEN_CONTEXT_KEY, None)
- if collected_fills is None:
- return
+ if captured_fills is None:
+ raise RuntimeError(
+ "FillNode.render() (AKA {% fill ... %} block) cannot be rendered outside of a Component context. "
+ "Make sure that the {% fill %} tags are nested within {% component %} tags."
+ )
# To allow using variables which were defined within the template and to which
# the `{% fill %}` tag has access, we need to capture those variables too.
@@ -786,7 +1248,8 @@ class FillNode(BaseNode):
# `{% component %} ... {% endcomponent %}`. Hence we search for the last
# index of `FILL_GEN_CONTEXT_KEY`.
index_of_new_layers = get_last_index(context.dicts, lambda d: FILL_GEN_CONTEXT_KEY in d)
- for dict_layer in context.dicts[index_of_new_layers:]:
+ context_dicts: List[Dict[str, Any]] = context.dicts
+ for dict_layer in context_dicts[index_of_new_layers:]:
for key, value in dict_layer.items():
if not key.startswith("_"):
data.extra_context[key] = value
@@ -821,25 +1284,61 @@ class FillNode(BaseNode):
layer["forloop"] = layer["forloop"].copy()
data.extra_context.update(layer)
- collected_fills.append(data)
+ captured_fills.append(data)
#######################################
# EXTRACTING {% fill %} FROM TEMPLATES
+# (internal)
#######################################
class FillWithData(NamedTuple):
fill: FillNode
name: str
- default_var: Optional[str]
+ """Name of the slot to be filled, as set on the `{% fill %}` tag."""
+ body: Optional[SlotInput]
+ """
+ Slot fill as set by the `body` kwarg on the `{% fill %}` tag.
+
+ E.g.
+ ```django
+ {% component "mycomponent" %}
+ {% fill "footer" body=my_slot / %}
+ {% endcomponent %}
+ ```
+ """
+ fallback_var: Optional[str]
+ """Name of the FALLBACK variable, as set on the `{% fill %}` tag."""
data_var: Optional[str]
+ """Name of the DATA variable, as set on the `{% fill %}` tag."""
extra_context: Dict[str, Any]
+ """
+ Extra context variables that will be available inside the `{% fill %}` tag.
+
+ For example, if the `{% fill %}` tags are nested within `{% with %}` or `{% for %}` tags,
+ then the variables defined within those tags will be available inside the `{% fill %}` tags:
+
+ ```django
+ {% component "mycomponent" %}
+ {% with extra_var="extra_value" %}
+ {% fill "my_fill" %}
+ {{ extra_var }}
+ {% endfill %}
+ {% endwith %}
+ {% for item in items %}
+ {% fill "my_fill" %}
+ {{ item }}
+ {% endfill %}
+ {% endfor %}
+ {% endcomponent %}
+ ```
+ """
def resolve_fills(
context: Context,
- nodelist: NodeList,
+ component_node: "ComponentNode",
component_name: str,
) -> Dict[SlotName, Slot]:
"""
@@ -890,6 +1389,9 @@ def resolve_fills(
"""
slots: Dict[SlotName, Slot] = {}
+ nodelist = component_node.nodelist
+ contents = component_node.contents
+
if not nodelist:
return slots
@@ -907,12 +1409,14 @@ def resolve_fills(
)
if not nodelist_is_empty:
- slots[DEFAULT_SLOT_KEY] = _nodelist_to_slot_render_func(
+ slots[DEFAULT_SLOT_KEY] = _nodelist_to_slot(
component_name=component_name,
slot_name=None, # Will be populated later
nodelist=nodelist,
+ contents=contents,
data_var=None,
- default_var=None,
+ fallback_var=None,
+ fill_node=component_node,
)
# The content has fills
@@ -920,14 +1424,30 @@ def resolve_fills(
# NOTE: If slot fills are explicitly defined, we use them even if they are empty (or only whitespace).
# This is different from the default slot, where we ignore empty content.
for fill in maybe_fills:
- slots[fill.name] = _nodelist_to_slot_render_func(
- component_name=component_name,
- slot_name=fill.name,
- nodelist=fill.fill.nodelist,
- data_var=fill.data_var,
- default_var=fill.default_var,
- extra_context=fill.extra_context,
- )
+ # Case: Slot fill was explicitly defined as `{% fill body=... / %}`
+ if fill.body is not None:
+ # Set `Slot.fill_node` so the slot fill behaves the same as if it was defined inside
+ # a `{% fill %}` tag.
+ # This for example allows CSS scoping to work even on slots that are defined
+ # as `{% fill ... body=... / %}`
+ if isinstance(fill.body, Slot):
+ # Make a copy of the Slot instance and set its `fill_node`.
+ slot_fill = dataclass_replace(fill.body, fill_node=fill.fill)
+ else:
+ slot_fill = Slot(fill.body, fill_node=fill.fill)
+ # Case: Slot fill was defined as the body of `{% fill / %}...{% endfill %}`
+ else:
+ slot_fill = _nodelist_to_slot(
+ component_name=component_name,
+ slot_name=fill.name,
+ nodelist=fill.fill.nodelist,
+ contents=fill.fill.contents,
+ data_var=fill.data_var,
+ fallback_var=fill.fallback_var,
+ extra_context=fill.extra_context,
+ fill_node=fill.fill,
+ )
+ slots[fill.name] = slot_fill
return slots
@@ -973,32 +1493,81 @@ def _extract_fill_content(
#######################################
-name_escape_re = re.compile(r"[^\w]")
+def normalize_slot_fills(
+ fills: Mapping[SlotName, SlotInput],
+ component_name: Optional[str] = None,
+) -> Dict[SlotName, Slot]:
+ norm_fills = {}
+
+ # NOTE: `copy_slot` is defined as a separate function, instead of being inlined within
+ # the forloop, because the value the forloop variable points to changes with each loop iteration.
+ def copy_slot(content: Union[SlotFunc, Slot], slot_name: str) -> Slot:
+ # Case: Already Slot and names assigned, so nothing to do.
+ if isinstance(content, Slot) and content.slot_name and content.component_name:
+ return content
+
+ # Otherwise, we create a new instance of Slot, whether we've been given Slot or not,
+ # so we can assign metadata to our internal copies without affecting the original.
+ if not isinstance(content, Slot):
+ content_func = content
+ else:
+ content_func = content.content_func
+
+ # Populate potentially missing fields so we can trace the component and slot
+ if isinstance(content, Slot):
+ used_component_name = content.component_name or component_name
+ used_slot_name = content.slot_name or slot_name
+ used_nodelist = content.nodelist
+ used_contents = content.contents if content.contents is not None else content_func
+ used_fill_node = content.fill_node
+ used_extra = content.extra.copy()
+ else:
+ used_component_name = component_name
+ used_slot_name = slot_name
+ used_nodelist = None
+ used_contents = content_func
+ used_fill_node = None
+ used_extra = {}
+
+ slot = Slot(
+ contents=used_contents,
+ content_func=content_func,
+ component_name=used_component_name,
+ slot_name=used_slot_name,
+ nodelist=used_nodelist,
+ fill_node=used_fill_node,
+ extra=used_extra,
+ )
+
+ return slot
+
+ for slot_name, content in fills.items():
+ # Case: No content, so nothing to do.
+ if content is None:
+ continue
+ # Case: Content is a string / non-slot / non-callable
+ elif not callable(content):
+ # NOTE: `Slot.content_func` and `Slot.nodelist` will be set in `Slot.__init__()`
+ slot: Slot = Slot(contents=content, component_name=component_name, slot_name=slot_name)
+ # Case: Content is a callable, so either a plain function or a `Slot` instance.
+ else:
+ slot = copy_slot(content, slot_name)
+
+ norm_fills[slot_name] = slot
+
+ return norm_fills
-def _escape_slot_name(name: str) -> str:
- """
- Users may define slots with names which are invalid identifiers like 'my slot'.
- But these cannot be used as keys in the template context, e.g. `{{ component_vars.is_filled.'my slot' }}`.
- So as workaround, we instead use these escaped names which are valid identifiers.
-
- So e.g. `my slot` should be escaped as `my_slot`.
- """
- # NOTE: Do a simple substitution where we replace all non-identifier characters with `_`.
- # Identifiers consist of alphanum (a-zA-Z0-9) and underscores.
- # We don't check if these escaped names conflict with other existing slots in the template,
- # we leave this obligation to the user.
- escaped_name = name_escape_re.sub("_", name)
- return escaped_name
-
-
-def _nodelist_to_slot_render_func(
+def _nodelist_to_slot(
component_name: str,
slot_name: Optional[str],
nodelist: NodeList,
+ contents: Optional[str] = None,
data_var: Optional[str] = None,
- default_var: Optional[str] = None,
+ fallback_var: Optional[str] = None,
extra_context: Optional[Dict[str, Any]] = None,
+ fill_node: Optional[Union[FillNode, "ComponentNode"]] = None,
+ extra: Optional[Dict[str, Any]] = None,
) -> Slot:
if data_var:
if not data_var.isidentifier():
@@ -1006,30 +1575,30 @@ def _nodelist_to_slot_render_func(
f"Slot data alias in fill '{slot_name}' must be a valid identifier. Got '{data_var}'"
)
- if default_var:
- if not default_var.isidentifier():
+ if fallback_var:
+ if not fallback_var.isidentifier():
raise TemplateSyntaxError(
- f"Slot default alias in fill '{slot_name}' must be a valid identifier. Got '{default_var}'"
+ f"Slot fallback alias in fill '{slot_name}' must be a valid identifier. Got '{fallback_var}'"
)
# We use Template.render() to render the nodelist, so that Django correctly sets up
# and binds the context.
template = Template("")
template.nodelist = nodelist
- # This allows the template to access current RenderContext layer.
- template._djc_is_component_nested = True
- def render_func(ctx: Context, slot_data: Dict[str, Any], slot_ref: SlotRef) -> SlotResult:
+ def render_func(ctx: SlotContext) -> SlotResult:
+ context = ctx.context or Context()
+
# Expose the kwargs that were passed to the `{% slot %}` tag. These kwargs
# are made available through a variable name that was set on the `{% fill %}`
# tag.
if data_var:
- ctx[data_var] = slot_data
+ context[data_var] = ctx.data
- # If slot fill is using `{% fill "myslot" default="abc" %}`, then set the "abc" to
- # the context, so users can refer to the default slot from within the fill content.
- if default_var:
- ctx[default_var] = slot_ref
+ # If slot fill is using `{% fill "myslot" fallback="abc" %}`, then set the "abc" to
+ # the context, so users can refer to the fallback slot from within the fill content.
+ if fallback_var:
+ context[fallback_var] = ctx.fallback
# NOTE: If a `{% fill %}` tag inside a `{% component %}` tag is inside a forloop,
# the `extra_context` contains the forloop variables. We want to make these available
@@ -1049,29 +1618,35 @@ def _nodelist_to_slot_render_func(
#
# And so we want to put the `extra_context` into the same layer that contains `_COMPONENT_CONTEXT_KEY`.
#
- # HOWEVER, the layer with `_COMPONENT_CONTEXT_KEY` also contains user-defined data from `get_context_data()`.
- # Data from `get_context_data()` should take precedence over `extra_context`. So we have to insert
+ # HOWEVER, the layer with `_COMPONENT_CONTEXT_KEY` also contains user-defined data from `get_template_data()`.
+ # Data from `get_template_data()` should take precedence over `extra_context`. So we have to insert
# the forloop variables BEFORE that.
- index_of_last_component_layer = get_last_index(ctx.dicts, lambda d: _COMPONENT_CONTEXT_KEY in d)
+ index_of_last_component_layer = get_last_index(context.dicts, lambda d: _COMPONENT_CONTEXT_KEY in d)
if index_of_last_component_layer is None:
index_of_last_component_layer = 0
- # TODO: Currently there's one more layer before the `_COMPONENT_CONTEXT_KEY` layer, which is
+ # TODO_V1: Currently there's one more layer before the `_COMPONENT_CONTEXT_KEY` layer, which is
# pushed in `_prepare_template()` in `component.py`.
# That layer should be removed when `Component.get_template()` is removed, after which
# the following line can be removed.
index_of_last_component_layer -= 1
- # Insert the `extra_context` layer BEFORE the layer that defines the variables from get_context_data.
- # Thus, get_context_data will overshadow these on conflict.
- ctx.dicts.insert(index_of_last_component_layer, extra_context or {})
+ # Insert the `extra_context` layer BEFORE the layer that defines the variables from get_template_data.
+ # Thus, get_template_data will overshadow these on conflict.
+ context.dicts.insert(index_of_last_component_layer, extra_context or {})
trace_component_msg("RENDER_NODELIST", component_name, component_id=None, slot_name=slot_name)
- rendered = template.render(ctx)
+ # NOTE 1: We wrap the slot nodelist in Template. However, we also override Django's `Template.render()`
+ # to call `render_dependencies()` on the results. So we need to set the strategy to `ignore`
+ # so that the dependencies are processed only once the whole component tree is rendered.
+ # NOTE 2: We also set `_DJC_COMPONENT_IS_NESTED` to `True` so that the template can access
+ # current RenderContext layer.
+ with context.push({"DJC_DEPS_STRATEGY": "ignore", COMPONENT_IS_NESTED_KEY: True}):
+ rendered = template.render(context)
# After the rendering is done, remove the `extra_context` from the context stack
- ctx.dicts.pop(index_of_last_component_layer)
+ context.dicts.pop(index_of_last_component_layer)
return rendered
@@ -1079,8 +1654,14 @@ def _nodelist_to_slot_render_func(
content_func=cast(SlotFunc, render_func),
component_name=component_name,
slot_name=slot_name,
- escaped=False,
nodelist=nodelist,
+ # The `contents` param passed to this function may be `None`, because it's taken from
+ # `BaseNode.contents` which is `None` for self-closing tags like `{% fill "footer" / %}`.
+ # But `Slot(contents=None)` would result in `Slot.contents` being the render function.
+ # So we need to special-case this.
+ contents=default(contents, ""),
+ fill_node=default(fill_node, None),
+ extra=default(extra, {}),
)
diff --git a/src/django_components/tag_formatter.py b/src/django_components/tag_formatter.py
index 449c4e2c..5daacc39 100644
--- a/src/django_components/tag_formatter.py
+++ b/src/django_components/tag_formatter.py
@@ -237,27 +237,11 @@ class ComponentFormatter(TagFormatterABC):
if not args:
raise TemplateSyntaxError(f"{self.__class__.__name__}: Component tag did not receive tag name")
- # If the first arg is a kwarg, not a positional arg, then look for the "name" kwarg
- # for component name.
+ # If the first arg is a kwarg, then clearly the component name is not set.
if "=" in args[0]:
comp_name = None
- final_args = []
- for kwarg in args:
- if not kwarg.startswith("name="):
- final_args.append(kwarg)
- continue
-
- if comp_name:
- raise TemplateSyntaxError(
- f"ComponentFormatter: 'name' kwarg for component '{comp_name}'" " was defined more than once."
- )
-
- # NOTE: We intentionally do NOT add to `final_args` here
- # because we want to remove the the `name=` kwarg from args list
- comp_name = kwarg[5:]
else:
comp_name = args.pop(0)
- final_args = args
if not comp_name:
raise TemplateSyntaxError("Component name must be a non-empty quoted string, e.g. 'my_comp'")
@@ -268,7 +252,7 @@ class ComponentFormatter(TagFormatterABC):
# Remove the quotes
comp_name = comp_name[1:-1]
- return TagResult(comp_name, final_args)
+ return TagResult(comp_name, args)
class ShorthandComponentFormatter(TagFormatterABC):
diff --git a/src/django_components/template.py b/src/django_components/template.py
index 5dad8dac..6b6ebb24 100644
--- a/src/django_components/template.py
+++ b/src/django_components/template.py
@@ -1,14 +1,24 @@
-from typing import Any, Optional, Type, TypeVar
+import sys
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Dict, Generator, List, Optional, Type, Union
+from weakref import ReferenceType, ref
-from django.template import Origin, Template
+from django.core.exceptions import ImproperlyConfigured
+from django.template import Context, Origin, Template
+from django.template.loader import get_template as django_get_template
from django_components.cache import get_template_cache
-from django_components.util.misc import get_import_path
+from django_components.util.django_monkeypatch import is_cls_patched
+from django_components.util.loader import get_component_dirs
+from django_components.util.logger import trace_component_msg
+from django_components.util.misc import get_import_path, get_module_info
-TTemplate = TypeVar("TTemplate", bound=Template)
+if TYPE_CHECKING:
+ from django_components.component import Component
-# Central logic for creating Templates from string, so we can cache the results
+# TODO_V1 - Remove, won't be needed once we remove `get_template_string()`, `get_template_name()`, `get_template()`
+# Legacy logic for creating Templates from string
def cached_template(
template_string: str,
template_cls: Optional[Type[Template]] = None,
@@ -17,17 +27,19 @@ def cached_template(
engine: Optional[Any] = None,
) -> Template:
"""
+ DEPRECATED. Template caching will be removed in v1.
+
Create a Template instance that will be cached as per the
[`COMPONENTS.template_cache_size`](../settings#django_components.app_settings.ComponentsSettings.template_cache_size)
setting.
Args:
template_string (str): Template as a string, same as the first argument to Django's\
- [`Template`](https://docs.djangoproject.com/en/5.1/topics/templates/#template). Required.
+ [`Template`](https://docs.djangoproject.com/en/5.2/topics/templates/#template). Required.
template_cls (Type[Template], optional): Specify the Template class that should be instantiated.\
- Defaults to Django's [`Template`](https://docs.djangoproject.com/en/5.1/topics/templates/#template) class.
+ Defaults to Django's [`Template`](https://docs.djangoproject.com/en/5.2/topics/templates/#template) class.
origin (Type[Origin], optional): Sets \
- [`Template.Origin`](https://docs.djangoproject.com/en/5.1/howto/custom-template-backend/#origin-api-and-3rd-party-integration).
+ [`Template.Origin`](https://docs.djangoproject.com/en/5.2/howto/custom-template-backend/#origin-api-and-3rd-party-integration).
name (Type[str], optional): Sets `Template.name`
engine (Type[Any], optional): Sets `Template.engine`
@@ -64,3 +76,403 @@ def cached_template(
template = maybe_cached_template
return template
+
+
+########################################################
+# PREPARING COMPONENT TEMPLATES FOR RENDERING
+########################################################
+
+
+@contextmanager
+def prepare_component_template(
+ component: "Component",
+ template_data: Any,
+) -> Generator[Optional[Template], Any, None]:
+ context = component.context
+ with context.update(template_data):
+ template = _get_component_template(component)
+
+ if template is None:
+ # If template is None, then the component is "template-less",
+ # and we skip template processing.
+ yield template
+ return
+
+ if not is_cls_patched(template):
+ raise RuntimeError(
+ "Django-components received a Template instance which was not patched."
+ "If you are using Django's Template class, check if you added django-components"
+ "to INSTALLED_APPS. If you are using a custom template class, then you need to"
+ "manually patch the class."
+ )
+
+ with _maybe_bind_template(context, template):
+ yield template
+
+
+# `_maybe_bind_template()` handles two problems:
+#
+# 1. Initially, the binding the template was needed for the context processor data
+# to work when using `RequestContext` (See `RequestContext.bind_template()` in e.g. Django v4.2 or v5.1).
+# But as of djc v0.140 (possibly earlier) we generate and apply the context processor data
+# ourselves in `Component._render_impl()`.
+#
+# Now, we still want to "bind the template" by setting the `Context.template` attribute.
+# This is for compatibility with Django, because we don't know if there isn't some code that relies
+# on the `Context.template` attribute being set.
+#
+# But we don't call `context.bind_template()` explicitly. If we did, then we would
+# be generating and applying the context processor data twice if the context was `RequestContext`.
+# Instead, we only run the same logic as `Context.bind_template()` but inlined.
+#
+# The downstream effect of this is that if the user or some third-party library
+# uses custom subclass of `Context` with custom logic for `Context.bind_template()`,
+# then this custom logic will NOT be applied. In such case they should open an issue.
+#
+# See https://github.com/django-components/django-components/issues/580
+# and https://github.com/django-components/django-components/issues/634
+#
+# 2. Not sure if I (Juro) remember right, but I think that with the binding of templates
+# there was also an issue that in *some* cases the template was already bound to the context
+# by the time we got to rendering the component. This is why we need to check if `context.template`
+# is already set.
+#
+# The cause of this may have been compatibility with Django's `{% extends %}` tag, or
+# maybe when using the "isolated" context behavior. But not sure.
+@contextmanager
+def _maybe_bind_template(context: Context, template: Template) -> Generator[None, Any, None]:
+ if context.template is not None:
+ yield
+ return
+
+ # This code is taken from `Context.bind_template()` from Django v5.1
+ context.template = template
+ try:
+ yield
+ finally:
+ context.template = None
+
+
+########################################################
+# LOADING TEMPLATES FROM FILEPATH
+########################################################
+
+
+# Remember which Component class is currently being loaded
+# This is important, because multiple Components may define the same `template_file`.
+# So we need this global state to help us decide which Component class of the list of components
+# that matched for the given `template_file` should be associated with the template.
+#
+# NOTE: Implemented as a list (stack) to handle the case when calling Django's `get_template()`
+# could lead to more components being loaded at once.
+# (For this to happen, user would have to define a Django template loader that renders other components
+# while resolving the template file.)
+loading_components: List["ComponentRef"] = []
+
+
+def load_component_template(
+ component_cls: Type["Component"],
+ filepath: Optional[str] = None,
+ content: Optional[str] = None,
+) -> Template:
+ if filepath is None and content is None:
+ raise ValueError("Either `filepath` or `content` must be provided.")
+
+ loading_components.append(ref(component_cls))
+
+ if filepath is not None:
+ # Use Django's `get_template()` to load the template file
+ template = _load_django_template(filepath)
+ template = ensure_unique_template(component_cls, template)
+
+ elif content is not None:
+ template = _create_template_from_string(component_cls, content, is_component_template=True)
+ else:
+ raise ValueError("Received both `filepath` and `content`. These are mutually exclusive.")
+
+ loading_components.pop()
+
+ return template
+
+
+# When loading a Template instance, it may be cached by Django / template loaders.
+# In that case we want to make a copy of the template which would
+# be owned by the current Component class.
+# Thus each Component has it's own Template instance with their own Origins
+# pointing to the correct Component class.
+def ensure_unique_template(component_cls: Type["Component"], template: Template) -> Template:
+ # Use `template.origin.component_cls` to check if the template was cached by Django / template loaders.
+ if get_component_from_origin(template.origin) is None:
+ set_component_to_origin(template.origin, component_cls)
+ else:
+ origin_copy = Origin(template.origin.name, template.origin.template_name, template.origin.loader)
+ set_component_to_origin(origin_copy, component_cls)
+ template = Template(template.source, origin=origin_copy, name=template.name, engine=template.engine)
+
+ return template
+
+
+def _get_component_template(component: "Component") -> Optional[Template]:
+ trace_component_msg("COMP_LOAD", component_name=component.name, component_id=component.id, slot_name=None)
+
+ # TODO_V1 - Remove, not needed once we remove `get_template_string()`, `get_template_name()`, `get_template()`
+ template_sources: Dict[str, Optional[Union[str, Template]]] = {}
+
+ # TODO_V1 - Remove `get_template_name()` in v1
+ template_sources["get_template_name"] = component.get_template_name(component.context)
+
+ # TODO_V1 - Remove `get_template_string()` in v1
+ if hasattr(component, "get_template_string"):
+ template_string_getter = getattr(component, "get_template_string")
+ template_body_from_getter = template_string_getter(component.context)
+ else:
+ template_body_from_getter = None
+ template_sources["get_template_string"] = template_body_from_getter
+
+ # TODO_V1 - Remove `get_template()` in v1
+ template_sources["get_template"] = component.get_template(component.context)
+
+ # NOTE: `component.template` should be populated whether user has set `template` or `template_file`
+ # so we discern between the two cases by checking `component.template_file`
+ if component.template_file is not None:
+ template_sources["template_file"] = component.template_file
+ else:
+ template_sources["template"] = component.template
+
+ # TODO_V1 - Remove this check in v1
+ # Raise if there are multiple sources for the component template
+ sources_with_values = [k for k, v in template_sources.items() if v is not None]
+ if len(sources_with_values) > 1:
+ raise ImproperlyConfigured(
+ f"Component template was set multiple times in Component {component.name}."
+ f"Sources: {sources_with_values}"
+ )
+
+ # Load the template based on the source
+ if template_sources["get_template_name"]:
+ template_name = template_sources["get_template_name"]
+ template: Optional[Template] = _load_django_template(template_name)
+ template_string: Optional[str] = None
+ elif template_sources["get_template_string"]:
+ template_string = template_sources["get_template_string"]
+ template = None
+ elif template_sources["get_template"]:
+ # `Component.get_template()` returns either string or Template instance
+ if hasattr(template_sources["get_template"], "render"):
+ template = template_sources["get_template"]
+ template_string = None
+ else:
+ template = None
+ template_string = template_sources["get_template"]
+ elif component.template or component.template_file:
+ # If the template was loaded from `Component.template` or `Component.template_file`,
+ # then the Template instance was already created and cached in `Component._template`.
+ #
+ # NOTE: This is important to keep in mind, because the implication is that we should
+ # treat Templates AND their nodelists as IMMUTABLE.
+ template = component.__class__._component_media._template # type: ignore[attr-defined]
+ template_string = None
+ # No template
+ else:
+ template = None
+ template_string = None
+
+ # We already have a template instance, so we can return it
+ if template is not None:
+ return template
+ # Create the template from the string
+ elif template_string is not None:
+ return _create_template_from_string(component.__class__, template_string)
+
+ # Otherwise, Component has no template - this is valid, as it may be instead rendered
+ # via `Component.on_render()`
+ return None
+
+
+def _create_template_from_string(
+ component: Type["Component"],
+ template_string: str,
+ is_component_template: bool = False,
+) -> Template:
+ # Generate a valid Origin instance.
+ # When an Origin instance is created by Django when using Django's loaders, it looks like this:
+ # ```
+ # {
+ # 'name': '/path/to/project/django-components/sampleproject/calendarapp/templates/calendarapp/calendar.html',
+ # 'template_name': 'calendarapp/calendar.html',
+ # 'loader':
- {output}
-
- """
-
- return output
diff --git a/src/django_components/util/context.py b/src/django_components/util/context.py
index 43a54bad..71e33488 100644
--- a/src/django_components/util/context.py
+++ b/src/django_components/util/context.py
@@ -131,7 +131,7 @@ def _copy_block_context(block_context: BlockContext) -> BlockContext:
# See https://github.com/django/django/blame/2d34ebe49a25d0974392583d5bbd954baf742a32/django/template/context.py#L255
def gen_context_processors_data(context: BaseContext, request: HttpRequest) -> Dict[str, Any]:
if request in context_processors_data:
- return context_processors_data[request]
+ return context_processors_data[request].copy()
# TODO_REMOVE_IN_V2 - In v2, if we still support context processors,
# it should be set on our settings, so we wouldn't have to get the Engine for that.
@@ -153,4 +153,6 @@ def gen_context_processors_data(context: BaseContext, request: HttpRequest) -> D
except TypeError as e:
raise TypeError(f"Context processor {processor.__qualname__} didn't return a " "dictionary.") from e
+ context_processors_data[request] = processors_data
+
return processors_data
diff --git a/src/django_components/util/django_monkeypatch.py b/src/django_components/util/django_monkeypatch.py
index 1e2bdafa..722eba02 100644
--- a/src/django_components/util/django_monkeypatch.py
+++ b/src/django_components/util/django_monkeypatch.py
@@ -1,18 +1,92 @@
-from typing import Any, Type
+from typing import Any, Optional, Type
from django.template import Context, NodeList, Template
-from django.template.base import Parser
+from django.template.base import Node, Origin, Parser
+from django.template.loader_tags import IncludeNode
+from django_components.context import _COMPONENT_CONTEXT_KEY, _STRATEGY_CONTEXT_KEY, COMPONENT_IS_NESTED_KEY
+from django_components.dependencies import COMPONENT_COMMENT_REGEX, render_dependencies
+from django_components.extension import OnTemplateCompiledContext, OnTemplateLoadedContext, extensions
from django_components.util.template_parser import parse_template
# In some cases we can't work around Django's design, and need to patch the template class.
def monkeypatch_template_cls(template_cls: Type[Template]) -> None:
+ if is_cls_patched(template_cls):
+ return
+
+ monkeypatch_template_init(template_cls)
monkeypatch_template_compile_nodelist(template_cls)
monkeypatch_template_render(template_cls)
template_cls._djc_patched = True
+# Patch `Template.__init__` to apply `on_template_loaded()` and `on_template_compiled()`
+# extension hooks if the template belongs to a Component.
+def monkeypatch_template_init(template_cls: Type[Template]) -> None:
+ original_init = template_cls.__init__
+
+ # NOTE: Function signature of Template.__init__ hasn't changed in 11 years, so we can safely patch it.
+ # See https://github.com/django/django/blame/main/django/template/base.py#L139
+ def __init__(
+ self: Template,
+ template_string: Any,
+ origin: Optional[Origin] = None,
+ name: Optional[str] = None,
+ *args: Any,
+ **kwargs: Any,
+ ) -> None:
+ # NOTE: Avoids circular import
+ from django_components.template import (
+ get_component_by_template_file,
+ get_component_from_origin,
+ set_component_to_origin,
+ )
+
+ # If this Template instance was created by us when loading a template file for a component
+ # with `load_component_template()`, then we do 2 things:
+ #
+ # 1. Associate the Component class with the template by setting it on the `Origin` instance
+ # (`template.origin.component_cls`). This way the `{% component%}` and `{% slot %}` tags
+ # will know inside which Component class they were defined.
+ #
+ # 2. Apply `extensions.on_template_preprocess()` to the template, so extensions can modify
+ # the template string before it's compiled into a nodelist.
+ if get_component_from_origin(origin) is not None:
+ component_cls = get_component_from_origin(origin)
+ elif origin is not None and origin.template_name is not None:
+ component_cls = get_component_by_template_file(origin.template_name)
+ if component_cls is not None:
+ set_component_to_origin(origin, component_cls)
+ else:
+ component_cls = None
+
+ if component_cls is not None:
+ template_string = str(template_string)
+ template_string = extensions.on_template_loaded(
+ OnTemplateLoadedContext(
+ component_cls=component_cls,
+ content=template_string,
+ origin=origin,
+ name=name,
+ )
+ )
+
+ # Calling original `Template.__init__` should also compile the template into a Nodelist
+ # via `Template.compile_nodelist()`.
+ original_init(self, template_string, origin, name, *args, **kwargs) # type: ignore[misc]
+
+ if component_cls is not None:
+ extensions.on_template_compiled(
+ OnTemplateCompiledContext(
+ component_cls=component_cls,
+ template=self,
+ )
+ )
+
+ template_cls.__init__ = __init__
+
+
# Patch `Template.compile_nodelist` to use our custom parser. Our parser makes it possible
# to use template tags as inputs to the component tag:
#
@@ -58,7 +132,7 @@ def monkeypatch_template_compile_nodelist(template_cls: Type[Template]) -> None:
def monkeypatch_template_render(template_cls: Type[Template]) -> None:
# Modify `Template.render` to set `isolated_context` kwarg of `push_state`
- # based on our custom `Template._djc_is_component_nested`.
+ # based on our custom `_DJC_COMPONENT_IS_NESTED`.
#
# Part of fix for https://github.com/django-components/django-components/issues/508
#
@@ -73,38 +147,101 @@ def monkeypatch_template_render(template_cls: Type[Template]) -> None:
# doesn't require the source to be parsed multiple times. User can pass extra args/kwargs,
# and can modify the rendering behavior by overriding the `_render` method.
#
- # NOTE 2: Instead of setting `Template._djc_is_component_nested`, alternatively we could
+ # NOTE 2: Instead of setting `_DJC_COMPONENT_IS_NESTED` context key, alternatively we could
# have passed the value to `monkeypatch_template_render` directly. However, we intentionally
# did NOT do that, so the monkey-patched method is more robust, and can be e.g. copied
# to other.
- if is_template_cls_patched(template_cls):
+ if is_cls_patched(template_cls):
# Do not patch if done so already. This helps us avoid RecursionError
return
+ # NOTE: This implementation is based on Django v5.1.3)
def _template_render(self: Template, context: Context, *args: Any, **kwargs: Any) -> str:
"Display stage -- can be called many times"
- # ---------------- ORIGINAL (Django v5.1.3) ----------------
- # with context.render_context.push_state(self):
- # ---------------- OUR CHANGES START ----------------
# We parametrized `isolated_context`, which was `True` in the original method.
- if not hasattr(self, "_djc_is_component_nested"):
+ if COMPONENT_IS_NESTED_KEY not in context:
isolated_context = True
else:
# MUST be `True` for templates that are NOT import with `{% extends %}` tag,
# and `False` otherwise.
- isolated_context = not self._djc_is_component_nested
+ isolated_context = not context[COMPONENT_IS_NESTED_KEY]
+ # This is original implementation, except we override `isolated_context`,
+ # and we post-process the result with `render_dependencies()`.
with context.render_context.push_state(self, isolated_context=isolated_context):
- # ---------------- OUR CHANGES END ----------------
if context.template is None:
with context.bind_template(self):
context.template_name = self.name
- return self._render(context, *args, **kwargs)
+ result: str = self._render(context, *args, **kwargs)
else:
- return self._render(context, *args, **kwargs)
+ result = self._render(context, *args, **kwargs)
+
+ # If the key is present, that means this Template is rendered as part of `Component.render()`
+ # or `{% component %}`. In that case the parent component will take care of rendering the
+ # dependencies, so we don't need to do that here.
+ if _COMPONENT_CONTEXT_KEY in context:
+ return result
+
+ # NOTE: Only process dependencies if the rendered result contains AT LEAST ONE rendered component.
+ # This has two reasons:
+ # 1. To keep the behavior consistent with the previous implementation, when `Template.render()`
+ # didn't call `render_dependencies()`.
+ # 2. To avoid unnecessary processing which otherwise has a considerable perf overhead.
+ # See https://github.com/django-components/django-components/pull/1166#issuecomment-2850899765
+ if not COMPONENT_COMMENT_REGEX.search(result.encode("utf-8")):
+ return result
+
+ # Allow users to configure the `deps_strategy` kwarg of `render_dependencies()`, even if
+ # they render a Template directly with `Template.render()` or Django's `django.shortcuts.render()`.
+ #
+ # Example:
+ # ```
+ # result = render_dependencies(
+ # result,
+ # Context({ "DJC_DEPS_STRATEGY": "fragment" }),
+ # )
+ # ```
+ if _STRATEGY_CONTEXT_KEY in context and context[_STRATEGY_CONTEXT_KEY] is not None:
+ strategy = context[_STRATEGY_CONTEXT_KEY]
+ result = render_dependencies(result, strategy)
+ else:
+ result = render_dependencies(result)
+ return result
template_cls.render = _template_render
-def is_template_cls_patched(template_cls: Type[Template]) -> bool:
- return getattr(template_cls, "_djc_patched", False)
+def monkeypatch_include_node(include_node_cls: Type[Node]) -> None:
+ if is_cls_patched(include_node_cls):
+ return
+
+ monkeypatch_include_render(include_node_cls)
+ include_node_cls._djc_patched = True
+
+
+def monkeypatch_include_render(include_node_cls: Type[Node]) -> None:
+ # Modify `IncludeNode.render()` (what renders `{% include %}` tag) so that the included
+ # template does NOT render the JS/CSS by itself.
+ #
+ # Instead, we want the parent template
+ # (which contains the `{% component %}` tag) to decide whether to render the JS/CSS.
+ #
+ # We achieve this by setting `DJC_DEPS_STRATEGY` to `ignore` in the context.
+ #
+ # Fix for https://github.com/django-components/django-components/issues/1296
+ if is_cls_patched(include_node_cls):
+ # Do not patch if done so already. This helps us avoid RecursionError
+ return
+
+ orig_include_render = include_node_cls.render
+
+ # NOTE: This implementation is based on Django v5.1.3)
+ def _include_render(self: IncludeNode, context: Context, *args: Any, **kwargs: Any) -> str:
+ with context.update({_STRATEGY_CONTEXT_KEY: "ignore"}):
+ return orig_include_render(self, context, *args, **kwargs)
+
+ include_node_cls.render = _include_render
+
+
+def is_cls_patched(cls: Type[Any]) -> bool:
+ return getattr(cls, "_djc_patched", False)
diff --git a/src/django_components/util/exception.py b/src/django_components/util/exception.py
index b7dbb97b..dc57b7c3 100644
--- a/src/django_components/util/exception.py
+++ b/src/django_components/util/exception.py
@@ -25,7 +25,7 @@ def component_error_message(component_path: List[str]) -> Generator[None, None,
if not components:
orig_msg = str(err.args[0])
else:
- orig_msg = err.args[0].split("\n", 1)[-1]
+ orig_msg = str(err.args[0]).split("\n", 1)[-1]
else:
orig_msg = str(err)
diff --git a/src/django_components/util/loader.py b/src/django_components/util/loader.py
index f99bf122..00e646a5 100644
--- a/src/django_components/util/loader.py
+++ b/src/django_components/util/loader.py
@@ -87,7 +87,7 @@ def get_component_dirs(include_apps: bool = True) -> List[Path]:
# Validate and add other values from the config
for component_dir in component_dirs:
# Consider tuples for STATICFILES_DIRS (See #489)
- # See https://docs.djangoproject.com/en/5.0/ref/settings/#prefixes-optional
+ # See https://docs.djangoproject.com/en/5.2/ref/settings/#prefixes-optional
if isinstance(component_dir, (tuple, list)):
component_dir = component_dir[1]
try:
diff --git a/src/django_components/util/misc.py b/src/django_components/util/misc.py
index 1ac8698f..def9d6ee 100644
--- a/src/django_components/util/misc.py
+++ b/src/django_components/util/misc.py
@@ -1,17 +1,21 @@
import re
import sys
+from dataclasses import asdict, is_dataclass
from hashlib import md5
from importlib import import_module
from itertools import chain
from types import ModuleType
-from typing import TYPE_CHECKING, Any, Callable, Iterable, List, Optional, Tuple, Type, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional, Tuple, Type, TypeVar, Union, cast
+from urllib import parse
+from django_components.constants import UID_LENGTH
from django_components.util.nanoid import generate
if TYPE_CHECKING:
from django_components.component import Component
T = TypeVar("T")
+U = TypeVar("U")
# Based on nanoid implementation from
@@ -24,7 +28,7 @@ def gen_id() -> str:
# See https://zelark.github.io/nano-id-cc/
return generate(
"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
- size=6,
+ size=UID_LENGTH,
)
@@ -88,8 +92,13 @@ def get_module_info(
return module, module_name, module_file_path
-def default(val: Optional[T], default: T) -> T:
- return val if val is not None else default
+def default(val: Optional[T], default: Union[U, Callable[[], U], Type[T]], factory: bool = False) -> Union[T, U]:
+ if val is not None:
+ return val
+ if factory:
+ default_func = cast(Callable[[], U], default)
+ return default_func()
+ return cast(U, default)
def get_index(lst: List, key: Callable[[Any], bool]) -> Optional[int]:
@@ -112,10 +121,11 @@ def is_nonempty_str(txt: Optional[str]) -> bool:
return txt is not None and bool(txt.strip())
+# Convert Component class to something like `TableComp_a91d03`
def hash_comp_cls(comp_cls: Type["Component"]) -> str:
full_name = get_import_path(comp_cls)
- comp_cls_hash = md5(full_name.encode()).hexdigest()[0:6]
- return comp_cls.__name__ + "_" + comp_cls_hash
+ name_hash = md5(full_name.encode()).hexdigest()[0:6]
+ return comp_cls.__name__ + "_" + name_hash
# String is a glob if it contains at least one of `?`, `*`, or `[`
@@ -128,3 +138,91 @@ def is_glob(filepath: str) -> bool:
def flatten(lst: Iterable[Iterable[T]]) -> List[T]:
return list(chain.from_iterable(lst))
+
+
+def to_dict(data: Any) -> dict:
+ """
+ Convert object to a dict.
+
+ Handles `dict`, `NamedTuple`, and `dataclass`.
+ """
+ if isinstance(data, dict):
+ return data
+ elif hasattr(data, "_asdict"): # Case: NamedTuple
+ return data._asdict()
+ elif is_dataclass(data): # Case: dataclass
+ return asdict(data) # type: ignore[arg-type]
+
+ return dict(data)
+
+
+def format_url(url: str, query: Optional[Dict] = None, fragment: Optional[str] = None) -> str:
+ """
+ Given a URL, add to it query parameters and a fragment, returning an updated URL.
+
+ ```py
+ url = format_url(url="https://example.com", query={"foo": "bar"}, fragment="baz")
+ # https://example.com?foo=bar#baz
+ ```
+
+ `query` and `fragment` are optional, and not applied if `None`.
+ """
+ parts = parse.urlsplit(url)
+ fragment_enc = parse.quote(fragment or parts.fragment, safe="")
+ base_qs = dict(parse.parse_qsl(parts.query))
+ merged = {**base_qs, **(query or {})}
+ encoded_qs = parse.urlencode(merged, safe="")
+
+ return parse.urlunsplit(parts._replace(query=encoded_qs, fragment=fragment_enc))
+
+
+def format_as_ascii_table(data: List[Dict[str, Any]], headers: List[str], include_headers: bool = True) -> str:
+ """
+ Format a list of dictionaries as an ASCII table.
+
+ Example:
+
+ ```python
+ data = [
+ {"name": "ProjectPage", "full_name": "project.pages.project.ProjectPage", "path": "./project/pages/project"},
+ {"name": "ProjectDashboard", "full_name": "project.components.dashboard.ProjectDashboard", "path": "./project/components/dashboard"},
+ {"name": "ProjectDashboardAction", "full_name": "project.components.dashboard_action.ProjectDashboardAction", "path": "./project/components/dashboard_action"},
+ ]
+ headers = ["name", "full_name", "path"]
+ print(format_as_ascii_table(data, headers))
+ ```
+
+ Which prints:
+
+ ```txt
+ name full_name path
+ ==================================================================================================
+ ProjectPage project.pages.project.ProjectPage ./project/pages/project
+ ProjectDashboard project.components.dashboard.ProjectDashboard ./project/components/dashboard
+ ProjectDashboardAction project.components.dashboard_action.ProjectDashboardAction ./project/components/dashboard_action
+ ```
+ """ # noqa: E501
+ # Calculate the width of each column
+ column_widths = {header: len(header) for header in headers}
+ for row in data:
+ for header in headers:
+ row_value = str(row.get(header, ""))
+ column_widths[header] = max(column_widths[header], len(row_value))
+
+ # Create the header row
+ header_row = " ".join(f"{header:<{column_widths[header]}}" for header in headers)
+ separator = "=" * len(header_row)
+
+ # Create the data rows
+ data_rows = []
+ for row in data:
+ row_values = [str(row.get(header, "")) for header in headers]
+ data_row = " ".join(f"{value:<{column_widths[header]}}" for value, header in zip(row_values, headers))
+ data_rows.append(data_row)
+
+ # Combine all parts into the final table
+ if include_headers:
+ table = "\n".join([header_row, separator] + data_rows)
+ else:
+ table = "\n".join(data_rows)
+ return table
diff --git a/src/django_components/util/routing.py b/src/django_components/util/routing.py
index 470018d3..c8da0d4b 100644
--- a/src/django_components/util/routing.py
+++ b/src/django_components/util/routing.py
@@ -1,20 +1,31 @@
from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Protocol
+from typing import Any, Dict, Iterable, Optional, Protocol, Type, TypeVar
+
+TClass = TypeVar("TClass", bound=Type[Any])
+# Mark object as related to extension URLs so we can place these in
+# a separate documentation section
+def mark_extension_url_api(obj: TClass) -> TClass:
+ obj._extension_url_api = True
+ return obj
+
+
+@mark_extension_url_api
class URLRouteHandler(Protocol):
"""Framework-agnostic 'view' function for routes"""
def __call__(self, request: Any, *args: Any, **kwargs: Any) -> Any: ... # noqa: E704
+@mark_extension_url_api
@dataclass
class URLRoute:
"""
Framework-agnostic route definition.
This is similar to Django's `URLPattern` object created with
- [`django.urls.path()`](https://docs.djangoproject.com/en/5.1/ref/urls/#path).
+ [`django.urls.path()`](https://docs.djangoproject.com/en/5.2/ref/urls/#path).
The `URLRoute` must either define a `handler` function or have a list of child routes `children`.
If both are defined, an error will be raised.
@@ -53,10 +64,14 @@ class URLRoute:
path: str
handler: Optional[URLRouteHandler] = None
- children: List["URLRoute"] = field(default_factory=list)
+ children: Iterable["URLRoute"] = field(default_factory=list)
name: Optional[str] = None
extra: Dict[str, Any] = field(default_factory=dict)
def __post_init__(self) -> None:
if self.handler is not None and self.children:
raise ValueError("Cannot have both handler and children")
+
+ # Allow to use `URLRoute` objects in sets and dictionaries
+ def __hash__(self) -> int:
+ return hash(self.path)
diff --git a/src/django_components/util/tag_parser.py b/src/django_components/util/tag_parser.py
index c25a47df..83153b9d 100644
--- a/src/django_components/util/tag_parser.py
+++ b/src/django_components/util/tag_parser.py
@@ -811,7 +811,7 @@ def parse_tag(text: str, parser: Optional[Parser]) -> Tuple[str, List[TagAttr]]:
# or here: ^
if is_next_token(["'", '"', "_("]):
# NOTE: Strings may be wrapped in `_()` to allow for translation.
- # See https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#string-literals-passed-to-tags-and-filters # noqa: E501
+ # See https://docs.djangoproject.com/en/5.2/topics/i18n/translation/#string-literals-passed-to-tags-and-filters # noqa: E501
# NOTE 2: We could potentially raise if this token is supposed to be a filter
# name (after `|`) and we got a translation or a quoted string instead. But we
# leave that up for Django.
diff --git a/src/django_components/util/template_tag.py b/src/django_components/util/template_tag.py
index 3e9184ba..6f382384 100644
--- a/src/django_components/util/template_tag.py
+++ b/src/django_components/util/template_tag.py
@@ -104,7 +104,7 @@ def resolve_params(
class ParsedTag(NamedTuple):
flags: Dict[str, bool]
params: List[TagAttr]
- parse_body: Callable[[], NodeList]
+ parse_body: Callable[[], Tuple[NodeList, Optional[str]]]
def parse_template_tag(
@@ -140,13 +140,15 @@ def parse_template_tag(
raw_params, flags = _extract_flags(tag_name, attrs, allowed_flags or [])
- def _parse_tag_body(parser: Parser, end_tag: str, inline: bool) -> NodeList:
+ def _parse_tag_body(parser: Parser, end_tag: str, inline: bool) -> Tuple[NodeList, Optional[str]]:
if inline:
body = NodeList()
+ contents: Optional[str] = None
else:
+ contents = _extract_contents_until(parser, [end_tag])
body = parser.parse(parse_until=[end_tag])
parser.delete_first_token()
- return body
+ return body, contents
return ParsedTag(
params=raw_params,
@@ -155,10 +157,53 @@ def parse_template_tag(
# loggers before the parsing. This is because, if the body contains any other
# tags, it will trigger their tag handlers. So the code called AFTER
# `parse_body()` is already after all the nested tags were processed.
- parse_body=lambda: _parse_tag_body(parser, end_tag, is_inline) if end_tag else NodeList(),
+ parse_body=lambda: _parse_tag_body(parser, end_tag, is_inline) if end_tag else (NodeList(), None),
)
+# Similar to `parser.parse(parse_until=[end_tag])`, except:
+# 1. Does not remove the token it goes over (unlike `parser.parse()`, which mutates the parser state)
+# 2. Returns a string, instead of a NodeList
+#
+# This is used so we can access the contents of the tag body as strings, for example
+# to be used for caching slots.
+#
+# See https://github.com/django/django/blob/1fb3f57e81239a75eb8f873b392e11534c041fdc/django/template/base.py#L471
+def _extract_contents_until(parser: Parser, until_blocks: List[str]) -> str:
+ contents: List[str] = []
+ for token in reversed(parser.tokens):
+ # Use the raw values here for TokenType.* for a tiny performance boost.
+ token_type = token.token_type.value
+ if token_type == 0: # TokenType.TEXT
+ contents.append(token.contents)
+ elif token_type == 1: # TokenType.VAR
+ contents.append("{{ " + token.contents + " }}")
+ elif token_type == 2: # TokenType.BLOCK
+ try:
+ command = token.contents.split()[0]
+ except IndexError:
+ # NOTE: Django's `Parser.parse()` raises a `TemplateSyntaxError` when there
+ # was a an empty block tag, e.g. `{% %}`.
+ # We skip raising an error here and let `Parser.parse()` raise it.
+ contents.append("{% " + token.contents + " %}")
+ if command in until_blocks:
+ return "".join(contents)
+ else:
+ contents.append("{% " + token.contents + " %}")
+ elif token_type == 3: # TokenType.COMMENT
+ contents.append("{# " + token.contents + " #}")
+ else:
+ raise ValueError(f"Unknown token type {token_type}")
+
+ # NOTE: If we got here, then we've reached the end of the tag body without
+ # encountering any of the `until_blocks`.
+ # Django's `Parser.parse()` raises a `TemplateSyntaxError` in such case.
+ #
+ # Currently `_extract_contents_until()` runs right before `parser.parse()`,
+ # so we skip raising an error here.
+ return "".join(contents)
+
+
def _extract_flags(
tag_name: str, attrs: List[TagAttr], allowed_flags: List[str]
) -> Tuple[List[TagAttr], Dict[str, bool]]:
diff --git a/src/django_components/util/testing.py b/src/django_components/util/testing.py
index 2af46f52..9117692d 100644
--- a/src/django_components/util/testing.py
+++ b/src/django_components/util/testing.py
@@ -6,14 +6,19 @@ from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Set,
from unittest.mock import patch
from weakref import ReferenceType
+import django
from django.conf import settings as _django_settings
+from django.core.cache import BaseCache, caches
from django.template import engines
+from django.template.loaders.base import Loader
from django.test import override_settings
from django_components.component import ALL_COMPONENTS, Component, component_node_subclasses_by_name
from django_components.component_media import ComponentMedia
from django_components.component_registry import ALL_REGISTRIES, ComponentRegistry
from django_components.extension import extensions
+from django_components.perfutil.provide import provide_cache
+from django_components.template import _reset_component_template_file_cache, loading_components
# NOTE: `ReferenceType` is NOT a generic pre-3.9
if sys.version_info >= (3, 9):
@@ -173,7 +178,7 @@ def djc_test(
**Arguments:**
- `django_settings`: Django settings, a dictionary passed to Django's
- [`@override_settings`](https://docs.djangoproject.com/en/5.1/topics/testing/tools/#django.test.override_settings).
+ [`@override_settings`](https://docs.djangoproject.com/en/5.2/topics/testing/tools/#django.test.override_settings).
The test runs within the context of these overridden settings.
If `django_settings` contains django-components settings (`COMPONENTS` field), these are merged.
@@ -236,7 +241,7 @@ def djc_test(
)
)
def test_context_behavior(components_settings):
- rendered = MyComponent().render()
+ rendered = MyComponent.render()
...
```
@@ -296,6 +301,11 @@ def djc_test(
# Contents of this function will run as the test
def _wrapper_impl(*args: Any, **kwargs: Any) -> Any:
+ # If Django is not yet configured, do so now, because we'll need to access
+ # Django's settings when merging the given settings.
+ if not _django_settings.configured:
+ django.setup()
+
# Merge the settings
current_django_settings = django_settings if not callable(django_settings) else None
current_django_settings = current_django_settings.copy() if current_django_settings else {}
@@ -450,7 +460,9 @@ def _clear_djc_global_state(
# beause the IDs count will reset to 0, but we won't generate IDs for the Nodes of the cached
# templates. Thus, the IDs will be out of sync between the tests.
for engine in engines.all():
- engine.engine.template_loaders[0].reset()
+ for loader in engine.engine.template_loaders:
+ if isinstance(loader, Loader):
+ loader.reset()
# NOTE: There are 1-2 tests which check Templates, so we need to clear the cache
from django_components.cache import component_media_cache, template_cache
@@ -461,6 +473,9 @@ def _clear_djc_global_state(
if component_media_cache:
component_media_cache.clear()
+ if provide_cache:
+ provide_cache.clear()
+
# Remove cached Node subclasses
component_node_subclasses_by_name.clear()
@@ -523,6 +538,18 @@ def _clear_djc_global_state(
sys.modules.pop(mod, None)
LOADED_MODULES.clear()
+ # Clear extensions caches
+ extensions._route_to_url.clear()
+
+ # Clear other djc state
+ _reset_component_template_file_cache()
+ loading_components.clear()
+
+ # Clear Django caches
+ all_caches: List[BaseCache] = list(caches.all())
+ for cache in all_caches:
+ cache.clear()
+
# Force garbage collection, so that any finalizers are run.
# If garbage collection is skipped, then in some cases the finalizers
# are run too late, in the context of the next test, causing flaky tests.
diff --git a/src/django_components/util/types.py b/src/django_components/util/types.py
index ab463534..4d490d9c 100644
--- a/src/django_components/util/types.py
+++ b/src/django_components/util/types.py
@@ -1,143 +1,30 @@
-import sys
-import typing
-from typing import Any, Tuple
-
-# See https://peps.python.org/pep-0655/#usage-in-python-3-11
-if sys.version_info >= (3, 11):
- from typing import TypedDict
-else:
- from typing_extensions import TypedDict as TypedDict # for Python <3.11 with (Not)Required
-
-try:
- from typing import Annotated # type: ignore
-except ImportError:
-
- @typing.no_type_check
- class Annotated: # type: ignore
- def __init__(self, type_: str, *args: Any, **kwargs: Any):
- self.type_ = type_
- self.metadata = args, kwargs
-
- def __repr__(self) -> str:
- return f"Annotated[{self.type_}, {self.metadata[0]!r}, {self.metadata[1]!r}]"
-
- def __getitem__(self, params: Any) -> "Annotated[Any, Any, Any]": # type: ignore
- if not isinstance(params, tuple):
- params = (params,)
- return Annotated(self.type_, *params, **self.metadata[1]) # type: ignore
-
- def __class_getitem__(self, *params: Any) -> "Annotated[Any, Any, Any]": # type: ignore
- return Annotated(*params) # type: ignore
+from typing import NamedTuple
-EmptyTuple = Tuple[()]
-"""
-Tuple with no members.
-
-You can use this to define a [Component](../api#django_components.Component)
-that accepts NO positional arguments:
-
-```python
-from django_components import Component, EmptyTuple
-
-class Table(Component(EmptyTuple, Any, Any, Any, Any, Any))
- ...
-```
-
-After that, when you call [`Component.render()`](../api#django_components.Component.render)
-or [`Component.render_to_response()`](../api#django_components.Component.render_to_response),
-the `args` parameter will raise type error if `args` is anything else than an empty
-tuple.
-
-```python
-Table.render(
- args: (),
-)
-```
-
-Omitting `args` is also fine:
-
-```python
-Table.render()
-```
-
-Other values are not allowed. This will raise an error with MyPy:
-
-```python
-Table.render(
- args: ("one", 2, "three"),
-)
-```
-"""
-
-
-class EmptyDict(TypedDict):
+class Empty(NamedTuple):
"""
- TypedDict with no members.
+ Type for an object with no members.
- You can use this to define a [Component](../api#django_components.Component)
- that accepts NO kwargs, or NO slots, or returns NO data from
- [`Component.get_context_data()`](../api#django_components.Component.get_context_data)
- /
- [`Component.get_js_data()`](../api#django_components.Component.get_js_data)
- /
- [`Component.get_css_data()`](../api#django_components.Component.get_css_data):
-
- Accepts NO kwargs:
+ You can use this to define [Component](../api#django_components.Component)
+ types that accept NO args, kwargs, slots, etc:
```python
- from django_components import Component, EmptyDict
+ from django_components import Component, Empty
- class Table(Component(Any, EmptyDict, Any, Any, Any, Any))
+ class Table(Component):
+ Args = Empty
+ Kwargs = Empty
...
```
- Accepts NO slots:
+ This class is a shorthand for:
- ```python
- from django_components import Component, EmptyDict
-
- class Table(Component(Any, Any, EmptyDict, Any, Any, Any))
- ...
+ ```py
+ class Empty(NamedTuple):
+ pass
```
- Returns NO data from `get_context_data()`:
-
- ```python
- from django_components import Component, EmptyDict
-
- class Table(Component(Any, Any, Any, EmptyDict, Any, Any))
- ...
- ```
-
- Going back to the example with NO kwargs, when you then call
- [`Component.render()`](../api#django_components.Component.render)
- or [`Component.render_to_response()`](../api#django_components.Component.render_to_response),
- the `kwargs` parameter will raise type error if `kwargs` is anything else than an empty
- dict.
-
- ```python
- Table.render(
- kwargs: {},
- )
- ```
-
- Omitting `kwargs` is also fine:
-
- ```python
- Table.render()
- ```
-
- Other values are not allowed. This will raise an error with MyPy:
-
- ```python
- Table.render(
- kwargs: {
- "one": 2,
- "three": 4,
- },
- )
- ```
+ Read more about [Typing and validation](../../concepts/fundamentals/typing_and_validation).
"""
pass
diff --git a/src/django_components/util/validation.py b/src/django_components/util/validation.py
deleted file mode 100644
index 2ffc8a53..00000000
--- a/src/django_components/util/validation.py
+++ /dev/null
@@ -1,130 +0,0 @@
-import sys
-import typing
-from typing import Any, Mapping, Tuple, get_type_hints
-
-# Get all types that users may use from the `typing` module.
-#
-# These are the types that we do NOT try to resolve when it's a typed generic,
-# e.g. `Union[int, str]`.
-# If we get a typed generic that's NOT part of this set, we assume it's a user-made
-# generic, e.g. `Component[Args, Kwargs]`. In such case we assert that a given value
-# is an instance of the base class, e.g. `Component`.
-_typing_exports = frozenset(
- [
- value
- for value in typing.__dict__.values()
- if isinstance(
- value,
- (
- typing._SpecialForm,
- # Used in 3.8 and 3.9
- getattr(typing, "_GenericAlias", ()),
- # Used in 3.11+ (possibly 3.10?)
- getattr(typing, "_SpecialGenericAlias", ()),
- ),
- )
- ]
-)
-
-
-def _prepare_type_for_validation(the_type: Any) -> Any:
- # If we got a typed generic (AKA "subscripted" generic), e.g.
- # `Component[CompArgs, CompKwargs, ...]`
- # then we cannot use that generic in `isintance()`, because we get this error:
- # `TypeError("Subscripted generics cannot be used with class and instance checks")`
- #
- # Instead, we resolve the generic to its original class, e.g. `Component`,
- # which can then be used in instance assertion.
- if hasattr(the_type, "__origin__"):
- is_custom_typing = the_type.__origin__ not in _typing_exports
- if is_custom_typing:
- return the_type.__origin__
- else:
- return the_type
- else:
- return the_type
-
-
-# NOTE: tuple_type is a _GenericAlias - See https://stackoverflow.com/questions/74412803
-def validate_typed_tuple(
- value: Tuple[Any, ...],
- tuple_type: Any,
- prefix: str,
- kind: str,
-) -> None:
- # `Any` type is the signal that we should skip validation
- if tuple_type == Any:
- return
-
- # We do two kinds of validation with the given Tuple type:
- # 1. We check whether there are any extra / missing positional args
- # 2. We look at the members of the Tuple (which are types themselves),
- # and check if our concrete list / tuple has correct types under correct indices.
- expected_pos_args = len(tuple_type.__args__)
- actual_pos_args = len(value)
- if expected_pos_args > actual_pos_args:
- # Generate errors like below (listed for searchability)
- # `Component 'name' expected 3 positional arguments, got 2`
- raise TypeError(f"{prefix} expected {expected_pos_args} {kind}s, got {actual_pos_args}")
-
- for index, arg_type in enumerate(tuple_type.__args__):
- arg = value[index]
- arg_type = _prepare_type_for_validation(arg_type)
- if sys.version_info >= (3, 11) and not isinstance(arg, arg_type):
- # Generate errors like below (listed for searchability)
- # `Component 'name' expected positional argument at index 0 to be
+ data-djc-id-ca1bc83="">
+
-
DEMO
@@ -53,9 +53,9 @@
-
+