+ None
+
+ 
+# 
-[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://github.com/EmilStenstrom/django-components/blob/master/LICENSE/) [](https://pypistats.org/packages/django-components) [](https://github.com/EmilStenstrom/django-components/actions/workflows/tests.yml)
+[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://github.com/django-components/django-components/blob/master/LICENSE/) [](https://pypistats.org/packages/django-components) [](https://github.com/django-components/django-components/actions/workflows/tests.yml) [](https://django-components.github.io/django-components/latest/benchmarks/)
-[**Docs (Work in progress)**](https://EmilStenstrom.github.io/django-components/latest/)
+### | [Read the full documentation](https://django-components.github.io/django-components/latest/) |
+ Today's date is {{ date }}
+
```
-With this `template.html` file:
+```py
+# components/calendar/calendar.py
+from django_components import Component, register
-```htmldjango
-Today's date is {{ date }}
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+```
+
+Or a combination of Django template, Python, CSS, and Javascript:
+
+```django
+{# components/calendar/calendar.html #}
+
+ Today's date is {{ date }}
+
+```
+
+```css
+/* components/calendar/calendar.css */
+.calendar {
+ width: 200px;
+ background: pink;
+}
+```
+
+```js
+/* components/calendar/calendar.js */
+document.querySelector(".calendar").onclick = () => {
+ alert("Clicked calendar!");
+};
+```
+
+```py
+# components/calendar/calendar.py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+ js_file = "calendar.js"
+ css_file = "calendar.css"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"date": kwargs["date"]}
```
Use the component like this:
-```htmldjango
+```django
{% component "calendar" date="2024-11-06" %}{% endcomponent %}
```
And this is what gets rendered:
```html
-Today's date is 2024-11-06
+
+ Today's date is 2024-11-06
+
```
Read on to learn about all the exciting details and configuration possibilities!
-(If you instead prefer to jump right into the code, [check out the example project](https://github.com/EmilStenstrom/django-components/tree/master/sampleproject))
+(If you instead prefer to jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject))
+
+## Features
+
+### Modern and modular UI
+
+- Create self-contained, reusable UI elements.
+- Each component can include its own HTML, CSS, and JS, or additional third-party JS and CSS.
+- HTML, CSS, and JS can be defined on the component class, or loaded from files.
+
+```python
+from django_components import Component
+
+@register("calendar")
+class Calendar(Component):
+ template = """
+
+ Today's date is
+ {{ date }}
+
+ """
+
+ css = """
+ .calendar {
+ width: 200px;
+ background: pink;
+ }
+ """
+
+ js = """
+ document.querySelector(".calendar")
+ .addEventListener("click", () => {
+ alert("Clicked calendar!");
+ });
+ """
+
+ # Additional JS and CSS
+ class Media:
+ js = ["https://cdn.jsdelivr.net/npm/htmx.org@2/dist/htmx.min.js"]
+ css = ["bootstrap/dist/css/bootstrap.min.css"]
+
+ # Variables available in the template
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"]
+ }
+```
+
+### Composition with slots
+
+- Render components inside templates with
+ [`{% component %}`](https://django-components.github.io/django-components/latest/reference/template_tags#component) tag.
+- Compose them with [`{% slot %}`](https://django-components.github.io/django-components/latest/reference/template_tags#slot)
+ and [`{% fill %}`](https://django-components.github.io/django-components/latest/reference/template_tags#fill) tags.
+- Vue-like slot system, including [scoped slots](https://django-components.github.io/django-components/latest/concepts/fundamentals/slots/#slot-data).
+
+```django
+{% component "Layout"
+ bookmarks=bookmarks
+ breadcrumbs=breadcrumbs
+%}
+ {% fill "header" %}
+
+
+ {% endfill %}
+
+ {# Access data passed to `{% slot %}` with `data` #}
+ {% fill "tabs" data="tabs_data" %}
+ {% component "TabItem" header="Project Info" %}
+ {% component "ProjectInfo"
+ project=project
+ project_tags=project_tags
+ attrs:class="py-5"
+ attrs:width=tabs_data.width
+ / %}
+ {% endcomponent %}
+ {% endfill %}
+{% endcomponent %}
+```
+
+### Extended template tags
+
+`django-components` is designed for flexibility, making working with templates a breeze.
+
+It extends Django's template tags syntax with:
+
+
+- Literal lists and dictionaries in the template
+- [Self-closing tags](https://django-components.github.io/django-components/latest/concepts/fundamentals/template_tag_syntax#self-closing-tags) `{% mytag / %}`
+- [Multi-line template tags](https://django-components.github.io/django-components/latest/concepts/fundamentals/template_tag_syntax#multiline-tags)
+- [Spread operator](https://django-components.github.io/django-components/latest/concepts/fundamentals/template_tag_syntax#spread-operator) `...` to dynamically pass args or kwargs into the template tag
+- [Template tags inside literal strings](https://django-components.github.io/django-components/latest/concepts/fundamentals/template_tag_syntax#template-tags-inside-literal-strings) like `"{{ first_name }} {{ last_name }}"`
+- [Pass dictonaries by their key-value pairs](https://django-components.github.io/django-components/latest/concepts/fundamentals/template_tag_syntax#pass-dictonary-by-its-key-value-pairs) `attr:key=val`
+
+```django
+{% component "table"
+ ...default_attrs
+ title="Friend list for {{ user.name }}"
+ headers=["Name", "Age", "Email"]
+ data=[
+ {
+ "name": "John"|upper,
+ "age": 30|add:1,
+ "email": "john@example.com",
+ "hobbies": ["reading"],
+ },
+ {
+ "name": "Jane"|upper,
+ "age": 25|add:1,
+ "email": "jane@example.com",
+ "hobbies": ["reading", "coding"],
+ },
+ ],
+ attrs:class="py-4 ma-2 border-2 border-gray-300 rounded-md"
+/ %}
+```
+
+You too can define template tags with these features by using
+[`@template_tag()`](https://django-components.github.io/django-components/latest/reference/api/#django_components.template_tag)
+or [`BaseNode`](https://django-components.github.io/django-components/latest/reference/api/#django_components.BaseNode).
+
+Read more on [Custom template tags](https://django-components.github.io/django-components/latest/concepts/advanced/template_tags/).
+
+### Full programmatic access
+
+When you render a component, you can access everything about the component:
+
+- Component input: [args, kwargs, slots and context](https://django-components.github.io/django-components/latest/concepts/fundamentals/render_api/#component-inputs)
+- Component's template, CSS and JS
+- Django's [context processors](https://django-components.github.io/django-components/latest/concepts/fundamentals/render_api/#request-and-context-processors)
+- Unique [render ID](https://django-components.github.io/django-components/latest/concepts/fundamentals/render_api/#component-id)
+
+```python
+class Table(Component):
+ js_file = "table.js"
+ css_file = "table.css"
+
+ template = """
+
+
+ {{ project.name }}
+
+ {{ project.start_date }} - {{ project.end_date }}
+
+
+ {{ variable }}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ # Access component's ID
+ assert self.id == "djc1A2b3c"
+
+ # Access component's inputs and slots
+ assert self.args == [123, "str"]
+ assert self.kwargs == {"variable": "test", "another": 1}
+ footer_slot = self.slots["footer"]
+ some_var = self.context["some_var"]
+
+ # 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"
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+# Access component's HTML / JS / CSS
+Table.template
+Table.js
+Table.css
+
+# Render the component
+rendered = Table.render(
+ kwargs={"variable": "test", "another": 1},
+ args=(123, "str"),
+ slots={"footer": "MY_FOOTER"},
+)
+```
+
+### Granular HTML attributes
+
+Use the [`{% html_attrs %}`](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/) template tag to render HTML attributes.
+
+It supports:
+
+- Defining attributes as whole dictionaries or keyword arguments
+- Merging attributes from multiple sources
+- Boolean attributes
+- Appending attributes
+- Removing attributes
+- Defining default attributes
+
+```django
+
+```
+
+[`{% html_attrs %}`](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/) offers a Vue-like granular control for
+[`class`](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/#merging-class-attributes)
+and [`style`](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/#merging-style-attributes)
+HTML attributes,
+where you can use a dictionary to manage each class name or style property separately.
+
+```django
+{% html_attrs
+ class="foo bar"
+ class={
+ "baz": True,
+ "foo": False,
+ }
+ class="extra"
+%}
+```
+
+```django
+{% html_attrs
+ style="text-align: center; background-color: blue;"
+ style={
+ "background-color": "green",
+ "color": None,
+ "width": False,
+ }
+ style="position: absolute; height: 12px;"
+%}
+```
+
+Read more about [HTML attributes](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/).
+
+### HTML fragment support
+
+`django-components` makes integration with HTMX, AlpineJS or jQuery easy by allowing components to be rendered as [HTML fragments](https://django-components.github.io/django-components/latest/concepts/advanced/html_fragments/):
+
+- Components's JS and CSS files are loaded automatically when the fragment is inserted into the DOM.
+
+- Components can be [exposed as Django Views](https://django-components.github.io/django-components/latest/concepts/fundamentals/component_views_urls/) with `get()`, `post()`, `put()`, `patch()`, `delete()` methods
+
+- Automatically create an endpoint for a component with [`Component.View.public`](https://django-components.github.io/django-components/latest/concepts/fundamentals/component_views_urls/#register-urls-automatically)
+
+```py
+# components/calendar/calendar.py
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+
+ class View:
+ # Register Component with `urlpatterns`
+ public = True
+
+ # Define handlers
+ def get(self, request, *args, **kwargs):
+ page = request.GET.get("page", 1)
+ return self.component.render_to_response(
+ request=request,
+ kwargs={
+ "page": page,
+ },
+ )
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "page": kwargs["page"],
+ }
+
+# Get auto-generated URL for the component
+url = get_component_url(Calendar)
+
+# Or define explicit URL in urls.py
+path("calendar/", Calendar.as_view())
+```
+
+### Provide / Inject
+
+`django-components` supports the provide / inject pattern, similarly to React's [Context Providers](https://react.dev/learn/passing-data-deeply-with-context) or Vue's [provide / inject](https://vuejs.org/guide/components/provide-inject):
+
+- Use the [`{% provide %}`](https://django-components.github.io/django-components/latest/reference/template_tags/#provide) tag to provide data to the component tree
+- Use the [`Component.inject()`](https://django-components.github.io/django-components/latest/reference/api/#django_components.Component.inject) method to inject data into the component
+
+Read more about [Provide / Inject](https://django-components.github.io/django-components/latest/concepts/advanced/provide_inject).
+
+```django
+
+ {% provide "theme" variant="light" %}
+ {% component "header" / %}
+ {% endprovide %}
+
+```
+
+```djc_py
+@register("header")
+class Header(Component):
+ template = "..."
+
+ def get_template_data(self, args, kwargs, slots, context):
+ theme = self.inject("theme").variant
+ return {
+ "theme": theme,
+ }
+```
+
+### Input validation and static type hints
+
+Avoid needless errors with [type hints and runtime input validation](https://django-components.github.io/django-components/latest/concepts/fundamentals/typing_and_validation/).
+
+To opt-in to input validation, define types for component's args, kwargs, slots, and more:
+
+```py
+from typing import NamedTuple, Optional
+from django.template import Context
+from django_components import Component, Slot, SlotInput
+
+class Button(Component):
+ class Args(NamedTuple):
+ size: int
+ text: str
+
+ class Kwargs(NamedTuple):
+ variable: str
+ another: int
+ maybe_var: Optional[int] = None # May be omitted
+
+ class Slots(NamedTuple):
+ my_slot: Optional[SlotInput] = None
+ another_slot: SlotInput
+
+ def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
+ args.size # int
+ kwargs.variable # str
+ slots.my_slot # Slot[MySlotData]
+```
+
+To have type hints when calling
+[`Button.render()`](https://django-components.github.io/django-components/latest/reference/api/#django_components.Component.render) or
+[`Button.render_to_response()`](https://django-components.github.io/django-components/latest/reference/api/#django_components.Component.render_to_response),
+wrap the inputs in their respective `Args`, `Kwargs`, and `Slots` classes:
+
+```py
+Button.render(
+ # Error: First arg must be `int`, got `float`
+ args=Button.Args(
+ size=1.25,
+ text="abc",
+ ),
+ # Error: Key "another" is missing
+ kwargs=Button.Kwargs(
+ variable="text",
+ ),
+)
+```
+
+### Extensions
+
+Django-components functionality can be extended with [Extensions](https://django-components.github.io/django-components/latest/concepts/advanced/extensions/).
+Extensions allow for powerful customization and integrations. They can:
+
+- Tap into lifecycle events, such as when a component is created, deleted, or registered
+- Add new attributes and methods to the components
+- Add custom CLI commands
+- Add custom URLs
+
+Some of the extensions include:
+
+- [Component caching](https://github.com/django-components/django-components/blob/master/src/django_components/extensions/cache.py)
+- [Django View integration](https://github.com/django-components/django-components/blob/master/src/django_components/extensions/view.py)
+- [Component defaults](https://github.com/django-components/django-components/blob/master/src/django_components/extensions/defaults.py)
+- [Pydantic integration (input validation)](https://github.com/django-components/djc-ext-pydantic)
+
+Some of the planned extensions include:
+
+- AlpineJS integration
+- Storybook integration
+- Component-level benchmarking with asv
+
+### Caching
+
+- [Components can be cached](https://django-components.github.io/django-components/latest/concepts/advanced/component_caching/) using Django's cache framework.
+- Caching rules can be configured on a per-component basis.
+- Components are cached based on their input. Or you can write custom caching logic.
+
+```py
+from django_components import Component
+
+class MyComponent(Component):
+ class Cache:
+ enabled = True
+ ttl = 60 * 60 * 24 # 1 day
+
+ def hash(self, *args, **kwargs):
+ return hash(f"{json.dumps(args)}:{json.dumps(kwargs)}")
+```
+
+### Simple testing
+
+- Write tests for components with [`@djc_test`](https://django-components.github.io/django-components/latest/concepts/advanced/testing/) decorator.
+- The decorator manages global state, ensuring that tests don't leak.
+- If using `pytest`, the decorator allows you to parametrize Django or Components settings.
+- The decorator also serves as a stand-in for Django's [`@override_settings`](https://docs.djangoproject.com/en/5.2/topics/testing/tools/#django.test.override_settings).
+
+```python
+from django_components.testing import djc_test
+
+from components.my_table import MyTable
+
+@djc_test
+def test_my_table():
+ rendered = MyTable.render(
+ kwargs={
+ "title": "My table",
+ },
+ )
+ assert rendered == "My table
"
+```
+
+### Debugging features
+
+- **Visual component inspection**: Highlight components and slots directly in your browser.
+- **Detailed tracing logs to supply AI-agents with context**: The logs include component and slot names and IDs, and their position in the tree.
+
+
- {% slot "header" %}Default header{% endslot %}
- {% slot "main" %}Default main{% endslot %}
-
-
- """
-
-
-class SimpleComponent(Component):
- template: types.django_html = """
- Variable: {{ variable }}
- """
-
- def get_context_data(self, variable, variable2="default"):
- return {
- "variable": variable,
- "variable2": variable2,
- }
-
- class Media:
- css = {"all": ["style.css"]}
- js = ["script.js"]
-
-
-class BreadcrumbComponent(Component):
- template: types.django_html = """
-
- """
-
- LINKS = [
- (
- "https://developer.mozilla.org/en-US/docs/Learn",
- "Learn web development",
- ),
- (
- "https://developer.mozilla.org/en-US/docs/Learn/HTML",
- "Structuring the web with HTML",
- ),
- (
- "https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML",
- "Introduction to HTML",
- ),
- (
- "https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Document_and_website_structure",
- "Document and website structure",
- ),
- ]
-
- def get_context_data(self, items):
- if items > 4:
- items = 4
- elif items < 0:
- items = 0
- return {"links": self.LINKS[: items - 1]}
-
- class Media:
- css = {"all": ["test.css"]}
- js = ["test.js"]
-
-
-EXPECTED_CSS = """"""
-EXPECTED_JS = """"""
-
-
-class RenderBenchmarks(BaseTestCase):
- def setUp(self):
- registry.clear()
- registry.register("test_component", SlottedComponent)
- registry.register("inner_component", SimpleComponent)
- registry.register("breadcrumb_component", BreadcrumbComponent)
-
- @staticmethod
- def timed_loop(func, iterations=1000):
- """Run func iterations times, and return the time in ms per iteration."""
- start_time = perf_counter()
- for _ in range(iterations):
- func()
- end_time = perf_counter()
- total_elapsed = end_time - start_time # NOQA
- return total_elapsed * 1000 / iterations
-
- def test_render_time_for_small_component(self):
- template_str: types.django_html = """
- {% load component_tags %}
- {% component 'test_component' %}
- {% slot "header" %}
- {% component 'inner_component' variable='foo' %}{% endcomponent %}
- {% endslot %}
- {% endcomponent %}
- """
- template = Template(template_str)
-
- print(f"{self.timed_loop(lambda: template.render(Context({})))} ms per iteration")
-
- def test_middleware_time_with_dependency_for_small_page(self):
- template_str: types.django_html = """
- {% load component_tags %}
- {% component_js_dependencies %}
- {% component_css_dependencies %}
- {% component 'test_component' %}
- {% slot "header" %}
- {% component 'inner_component' variable='foo' %}{% endcomponent %}
- {% endslot %}
- {% endcomponent %}
- """
- template = Template(template_str)
- # Sanity tests
- response_content = create_and_process_template_response(template)
- self.assertNotIn(CSS_DEPENDENCY_PLACEHOLDER, response_content)
- self.assertNotIn(JS_DEPENDENCY_PLACEHOLDER, response_content)
- self.assertIn("style.css", response_content)
- self.assertIn("script.js", response_content)
-
- without_middleware = self.timed_loop(
- lambda: create_and_process_template_response(template, use_middleware=False)
- )
- with_middleware = self.timed_loop(lambda: create_and_process_template_response(template, use_middleware=True))
-
- print("Small page middleware test")
- self.report_results(with_middleware, without_middleware)
-
- def test_render_time_with_dependency_for_large_page(self):
- from django.template.loader import get_template
-
- template = get_template("mdn_complete_page.html")
- response_content = create_and_process_template_response(template, {})
- self.assertNotIn(CSS_DEPENDENCY_PLACEHOLDER, response_content)
- self.assertNotIn(JS_DEPENDENCY_PLACEHOLDER, response_content)
- self.assertIn("test.css", response_content)
- self.assertIn("test.js", response_content)
-
- without_middleware = self.timed_loop(
- lambda: create_and_process_template_response(template, {}, use_middleware=False)
- )
- with_middleware = self.timed_loop(
- lambda: create_and_process_template_response(template, {}, use_middleware=True)
- )
-
- print("Large page middleware test")
- self.report_results(with_middleware, without_middleware)
-
- @staticmethod
- def report_results(with_middleware, without_middleware):
- print(f"Middleware active\t\t{with_middleware:.3f} ms per iteration")
- print(f"Middleware inactive\t{without_middleware:.3f} ms per iteration")
- time_difference = with_middleware - without_middleware
- if without_middleware > with_middleware:
- print(f"Decrease of {-100 * time_difference / with_middleware:.2f}%")
- else:
- print(f"Increase of {100 * time_difference / without_middleware:.2f}%")
diff --git a/benchmarks/monkeypatch_asv.py b/benchmarks/monkeypatch_asv.py
new file mode 100644
index 00000000..23003311
--- /dev/null
+++ b/benchmarks/monkeypatch_asv.py
@@ -0,0 +1,29 @@
+from asv_runner.benchmarks.timeraw import TimerawBenchmark, _SeparateProcessTimer
+
+
+# Fix for https://github.com/airspeed-velocity/asv_runner/pull/44
+def _get_timer(self, *param):
+ """
+ Returns a timer that runs the benchmark function in a separate process.
+
+ #### Parameters
+ **param** (`tuple`)
+ : The parameters to pass to the benchmark function.
+
+ #### Returns
+ **timer** (`_SeparateProcessTimer`)
+ : A timer that runs the function in a separate process.
+ """
+ if param:
+
+ def func():
+ # ---------- OUR CHANGES: ADDED RETURN STATEMENT ----------
+ return self.func(*param)
+ # ---------- OUR CHANGES END ----------
+
+ else:
+ func = self.func
+ return _SeparateProcessTimer(func)
+
+
+TimerawBenchmark._get_timer = _get_timer
diff --git a/benchmarks/monkeypatch_asv_ci.txt b/benchmarks/monkeypatch_asv_ci.txt
new file mode 100644
index 00000000..30158b6d
--- /dev/null
+++ b/benchmarks/monkeypatch_asv_ci.txt
@@ -0,0 +1,66 @@
+# ------------ FIX FOR #45 ------------
+# See https://github.com/airspeed-velocity/asv_runner/issues/45
+# This fix is applied in CI in the `benchmark.yml` file.
+# This file is intentionally named `monkeypatch_asv_ci.txt` to avoid being
+# loaded as a python file by `asv`.
+# -------------------------------------
+
+def timeit(self, number):
+ """
+ Run the function's code `number` times in a separate Python process, and
+ return the execution time.
+
+ #### Parameters
+ **number** (`int`)
+ : The number of times to execute the function's code.
+
+ #### Returns
+ **time** (`float`)
+ : The time it took to execute the function's code `number` times.
+
+ #### Notes
+ The function's code is executed in a separate Python process to avoid
+ interference from the parent process. The function can return either a
+ single string of code to be executed, or a tuple of two strings: the
+ code to be executed and the setup code to be run before timing.
+ """
+ stmt = self.func()
+ if isinstance(stmt, tuple):
+ stmt, setup = stmt
+ else:
+ setup = ""
+ stmt = textwrap.dedent(stmt)
+ setup = textwrap.dedent(setup)
+ stmt = stmt.replace(r'"""', r"\"\"\"")
+ setup = setup.replace(r'"""', r"\"\"\"")
+
+ # TODO
+ # -----------ORIGINAL CODE-----------
+ # code = self.subprocess_tmpl.format(stmt=stmt, setup=setup, number=number)
+
+ # res = subprocess.check_output([sys.executable, "-c", code])
+ # return float(res.strip())
+
+ # -----------NEW CODE-----------
+ code = self.subprocess_tmpl.format(stmt=stmt, setup=setup, number=number)
+
+ evaler = textwrap.dedent(
+ """
+ import sys
+ code = sys.stdin.read()
+ exec(code)
+ """
+ )
+
+ proc = subprocess.Popen([sys.executable, "-c", evaler],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE)
+ stdout, stderr = proc.communicate(input=code.encode("utf-8"))
+ if proc.returncode != 0:
+ raise RuntimeError(f"Subprocess failed: {stderr.decode()}")
+ return float(stdout.decode("utf-8").strip())
+
+_SeparateProcessTimer.timeit = timeit
+
+# ------------ END FIX #45 ------------
diff --git a/benchmarks/utils.py b/benchmarks/utils.py
new file mode 100644
index 00000000..eb160cb0
--- /dev/null
+++ b/benchmarks/utils.py
@@ -0,0 +1,99 @@
+import os
+import sys
+from importlib.abc import Loader
+from importlib.util import spec_from_loader, module_from_spec
+from types import ModuleType
+from typing import Any, Dict, List, Optional
+
+
+# NOTE: benchmark_name constraints:
+# - MUST BE UNIQUE
+# - MUST NOT CONTAIN `-`
+# - MUST START WITH `time_`, `mem_`, `peakmem_`
+# See https://github.com/airspeed-velocity/asv/pull/1470
+def benchmark(
+ *,
+ pretty_name: Optional[str] = None,
+ timeout: Optional[int] = None,
+ group_name: Optional[str] = None,
+ params: Optional[Dict[str, List[Any]]] = None,
+ number: Optional[int] = None,
+ min_run_count: Optional[int] = None,
+ include_in_quick_benchmark: bool = False,
+ **kwargs,
+):
+ def decorator(func):
+ # For pull requests, we want to run benchmarks only for a subset of tests,
+ # because the full set of tests takes about 10 minutes to run (5 min per commit).
+ # This is done by setting DJC_BENCHMARK_QUICK=1 in the environment.
+ if os.getenv("DJC_BENCHMARK_QUICK") and not include_in_quick_benchmark:
+ # By setting the benchmark name to something that does NOT start with
+ # valid prefixes like `time_`, `mem_`, or `peakmem_`, this function will be ignored by asv.
+ func.benchmark_name = "noop"
+ return func
+
+ # "group_name" is our custom field, which we actually convert to asv's "benchmark_name"
+ if group_name is not None:
+ benchmark_name = f"{group_name}.{func.__name__}"
+ func.benchmark_name = benchmark_name
+
+ # Also "params" is custom, so we normalize it to "params" and "param_names"
+ if params is not None:
+ func.params, func.param_names = list(params.values()), list(params.keys())
+
+ if pretty_name is not None:
+ func.pretty_name = pretty_name
+ if timeout is not None:
+ func.timeout = timeout
+ if number is not None:
+ func.number = number
+ if min_run_count is not None:
+ func.min_run_count = min_run_count
+
+ # Additional, untyped kwargs
+ for k, v in kwargs.items():
+ setattr(func, k, v)
+
+ return func
+
+ return decorator
+
+
+class VirtualModuleLoader(Loader):
+ def __init__(self, code_string):
+ self.code_string = code_string
+
+ def exec_module(self, module):
+ exec(self.code_string, module.__dict__)
+
+
+def create_virtual_module(name: str, code_string: str, file_path: str) -> ModuleType:
+ """
+ To avoid the headaches of importing the tested code from another diretory,
+ we create a "virtual" module that we can import from anywhere.
+
+ E.g.
+ ```py
+ from benchmarks.utils import create_virtual_module
+
+ create_virtual_module("my_module", "print('Hello, world!')", __file__)
+
+ # Now you can import my_module from anywhere
+ import my_module
+ ```
+ """
+ # Create the module specification
+ spec = spec_from_loader(name, VirtualModuleLoader(code_string))
+
+ # Create the module
+ module = module_from_spec(spec) # type: ignore[arg-type]
+ module.__file__ = file_path
+ module.__name__ = name
+
+ # Add it to sys.modules
+ sys.modules[name] = module
+
+ # Execute the module
+ spec.loader.exec_module(module) # type: ignore[union-attr]
+
+ return module
diff --git a/docs/.nav.yml b/docs/.nav.yml
new file mode 100644
index 00000000..3816ed34
--- /dev/null
+++ b/docs/.nav.yml
@@ -0,0 +1,10 @@
+# For navigation content inspo see Pydantic https://docs.pydantic.dev/latest
+#
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+ - overview
+ - Getting Started: getting_started
+ - concepts
+ - guides
+ - API Documentation: reference
+ - Release Notes: release_notes.md
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
deleted file mode 100644
index 6d871c4a..00000000
--- a/docs/SUMMARY.md
+++ /dev/null
@@ -1,11 +0,0 @@
-
-- [Get Started](overview/)
-- Concepts
- - [Getting started](concepts/getting_started/)
- - [Fundamentals](concepts/fundamentals/)
- - [Advanced](concepts/advanced/)
-- Guides
- - [Setup](guides/setup/)
- - [Dev guides](guides/devguides/)
-- [API Documentation](reference/)
-- [Release notes](release_notes.md)
diff --git a/docs/benchmarks/asv.css b/docs/benchmarks/asv.css
new file mode 100644
index 00000000..d7867516
--- /dev/null
+++ b/docs/benchmarks/asv.css
@@ -0,0 +1,161 @@
+/* Basic navigation */
+
+.asv-navigation {
+ padding: 2px;
+}
+
+nav ul li.active a {
+ height: 52px;
+}
+
+nav li.active span.navbar-brand {
+ background-color: #e7e7e7;
+ height: 52px;
+}
+
+nav li.active span.navbar-brand:hover {
+ background-color: #e7e7e7;
+}
+
+.navbar-default .navbar-link {
+ color: #2458D9;
+}
+
+.panel-body {
+ padding: 0;
+}
+
+.panel {
+ margin-bottom: 4px;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+ border-radius: 0;
+ border-top-left-radius: 3px;
+ border-top-right-radius: 3px;
+}
+
+.panel-default>.panel-heading,
+.panel-heading {
+ font-size: 12px;
+ font-weight:bold;
+ padding: 2px;
+ text-align: center;
+ border-top-left-radius: 3px;
+ border-top-right-radius: 3px;
+ background-color: #eee;
+}
+
+.btn,
+.btn-group,
+.btn-group-vertical>.btn:first-child,
+.btn-group-vertical>.btn:last-child:not(:first-child),
+.btn-group-vertical>.btn:last-child {
+ border: none;
+ border-radius: 0px;
+ overflow: hidden;
+}
+
+.btn-default:focus, .btn-default:active, .btn-default.active {
+ border: none;
+ color: #fff;
+ background-color: #99bfcd;
+}
+
+#range {
+ font-family: monospace;
+ text-align: center;
+ background: #ffffff;
+}
+
+.form-control {
+ border: none;
+ border-radius: 0px;
+ font-size: 12px;
+ padding: 0px;
+}
+
+.tooltip-inner {
+ min-width: 100px;
+ max-width: 800px;
+ text-align: left;
+ white-space: pre-wrap;
+ font-family: monospace;
+}
+
+/* Benchmark tree */
+
+.nav-list {
+ font-size: 12px;
+ padding: 0;
+ padding-left: 15px;
+}
+
+.nav-list>li {
+ overflow-x: hidden;
+}
+
+.nav-list>li>a {
+ padding: 0;
+ padding-left: 5px;
+ color: #000;
+}
+
+.nav-list>li>a:focus {
+ color: #fff;
+ background-color: #99bfcd;
+ box-shadow: inset 0 3px 5px rgba(0,0,0,.125);
+}
+
+.nav-list>li>.nav-header {
+ white-space: nowrap;
+ font-weight: 500;
+ margin-bottom: 2px;
+}
+
+.caret-right {
+ display: inline-block;
+ width: 0;
+ height: 0;
+ margin-left: 2px;
+ vertical-align: middle;
+ border-left: 4px solid;
+ border-bottom: 4px solid transparent;
+ border-top: 4px solid transparent;
+}
+
+/* Summary page */
+
+.benchmark-group > h1 {
+ text-align: center;
+}
+
+.benchmark-container {
+ width: 300px;
+ height: 116px;
+ padding: 4px;
+ border-radius: 3px;
+}
+
+.benchmark-container:hover {
+ background-color: #eee;
+}
+
+.benchmark-plot {
+ width: 292px;
+ height: 88px;
+}
+
+.benchmark-text {
+ font-size: 12px;
+ color: #000;
+ width: 292px;
+ overflow: hidden;
+}
+
+#extra-buttons {
+ margin: 1em;
+}
+
+#extra-buttons a {
+ border: solid 1px #ccc;
+}
diff --git a/docs/benchmarks/asv.js b/docs/benchmarks/asv.js
new file mode 100644
index 00000000..ac235639
--- /dev/null
+++ b/docs/benchmarks/asv.js
@@ -0,0 +1,525 @@
+'use strict';
+
+$(document).ready(function() {
+ /* GLOBAL STATE */
+ /* The index.json content as returned from the server */
+ var main_timestamp = '';
+ var main_json = {};
+ /* Extra pages: {name: show_function} */
+ var loaded_pages = {};
+ /* Previous window scroll positions */
+ var window_scroll_positions = {};
+ /* Previous window hash location */
+ var window_last_location = null;
+ /* Graph data cache */
+ var graph_cache = {};
+ var graph_cache_max_size = 5;
+
+ var colors = [
+ '#247AAD',
+ '#E24A33',
+ '#988ED5',
+ '#777777',
+ '#FBC15E',
+ '#8EBA42',
+ '#FFB5B8'
+ ];
+
+ var time_units = [
+ ['ps', 'picoseconds', 0.000000000001],
+ ['ns', 'nanoseconds', 0.000000001],
+ ['μs', 'microseconds', 0.000001],
+ ['ms', 'milliseconds', 0.001],
+ ['s', 'seconds', 1],
+ ['m', 'minutes', 60],
+ ['h', 'hours', 60 * 60],
+ ['d', 'days', 60 * 60 * 24],
+ ['w', 'weeks', 60 * 60 * 24 * 7],
+ ['y', 'years', 60 * 60 * 24 * 7 * 52],
+ ['C', 'centuries', 60 * 60 * 24 * 7 * 52 * 100]
+ ];
+
+ var mem_units = [
+ ['', 'bytes', 1],
+ ['k', 'kilobytes', 1000],
+ ['M', 'megabytes', 1000000],
+ ['G', 'gigabytes', 1000000000],
+ ['T', 'terabytes', 1000000000000]
+ ];
+
+ function pretty_second(x) {
+ for (var i = 0; i < time_units.length - 1; ++i) {
+ if (Math.abs(x) < time_units[i+1][2]) {
+ return (x / time_units[i][2]).toFixed(3) + time_units[i][0];
+ }
+ }
+
+ return 'inf';
+ }
+
+ function pretty_byte(x) {
+ for (var i = 0; i < mem_units.length - 1; ++i) {
+ if (Math.abs(x) < mem_units[i+1][2]) {
+ break;
+ }
+ }
+ if (i == 0) {
+ return x + '';
+ }
+ return (x / mem_units[i][2]).toFixed(3) + mem_units[i][0];
+ }
+
+ function pretty_unit(x, unit) {
+ if (unit == "seconds") {
+ return pretty_second(x);
+ }
+ else if (unit == "bytes") {
+ return pretty_byte(x);
+ }
+ else if (unit && unit != "unit") {
+ return '' + x.toPrecision(3) + ' ' + unit;
+ }
+ else {
+ return '' + x.toPrecision(3);
+ }
+ }
+
+ function pad_left(s, c, num) {
+ s = '' + s;
+ while (s.length < num) {
+ s = c + s;
+ }
+ return s;
+ }
+
+ function format_date_yyyymmdd(date) {
+ return (pad_left(date.getFullYear(), '0', 4)
+ + '-' + pad_left(date.getMonth() + 1, '0', 2)
+ + '-' + pad_left(date.getDate(), '0', 2));
+ }
+
+ function format_date_yyyymmdd_hhmm(date) {
+ return (format_date_yyyymmdd(date) + ' '
+ + pad_left(date.getHours(), '0', 2)
+ + ':' + pad_left(date.getMinutes(), '0', 2));
+ }
+
+ /* Convert a flat index to permutation to the corresponding value */
+ function param_selection_from_flat_idx(params, idx) {
+ var selection = [];
+ if (idx < 0) {
+ idx = 0;
+ }
+ for (var k = params.length-1; k >= 0; --k) {
+ var j = idx % params[k].length;
+ selection.unshift([j]);
+ idx = (idx - j) / params[k].length;
+ }
+ selection.unshift([null]);
+ return selection;
+ }
+
+ /* Convert a benchmark parameter value from their native Python
+ repr format to a number or a string, ready for presentation */
+ function convert_benchmark_param_value(value_repr) {
+ var match = Number(value_repr);
+ if (!isNaN(match)) {
+ return match;
+ }
+
+ /* Python str */
+ match = value_repr.match(/^'(.+)'$/);
+ if (match) {
+ return match[1];
+ }
+
+ /* Python unicode */
+ match = value_repr.match(/^u'(.+)'$/);
+ if (match) {
+ return match[1];
+ }
+
+ /* Python class */
+ match = value_repr.match(/^$/);
+ if (match) {
+ return match[1];
+ }
+
+ return value_repr;
+ }
+
+ /* Convert loaded graph data to a format flot understands, by
+ treating either time or one of the parameters as x-axis,
+ and selecting only one value of the remaining axes */
+ function filter_graph_data(raw_series, x_axis, other_indices, params) {
+ if (params.length == 0) {
+ /* Simple time series */
+ return raw_series;
+ }
+
+ /* Compute position of data entry in the results list,
+ and stride corresponding to plot x-axis parameter */
+ var stride = 1;
+ var param_stride = 0;
+ var param_idx = 0;
+ for (var k = params.length - 1; k >= 0; --k) {
+ if (k == x_axis - 1) {
+ param_stride = stride;
+ }
+ else {
+ param_idx += other_indices[k + 1] * stride;
+ }
+ stride *= params[k].length;
+ }
+
+ if (x_axis == 0) {
+ /* x-axis is time axis */
+ var series = new Array(raw_series.length);
+ for (var k = 0; k < raw_series.length; ++k) {
+ if (raw_series[k][1] === null) {
+ series[k] = [raw_series[k][0], null];
+ } else {
+ series[k] = [raw_series[k][0],
+ raw_series[k][1][param_idx]];
+ }
+ }
+ return series;
+ }
+ else {
+ /* x-axis is some parameter axis */
+ var time_idx = null;
+ if (other_indices[0] === null) {
+ time_idx = raw_series.length - 1;
+ }
+ else {
+ /* Need to search for the correct time value */
+ for (var k = 0; k < raw_series.length; ++k) {
+ if (raw_series[k][0] == other_indices[0]) {
+ time_idx = k;
+ break;
+ }
+ }
+ if (time_idx === null) {
+ /* No data points */
+ return [];
+ }
+ }
+
+ var x_values = params[x_axis - 1];
+ var series = new Array(x_values.length);
+ for (var k = 0; k < x_values.length; ++k) {
+ if (raw_series[time_idx][1] === null) {
+ series[k] = [convert_benchmark_param_value(x_values[k]),
+ null];
+ }
+ else {
+ series[k] = [convert_benchmark_param_value(x_values[k]),
+ raw_series[time_idx][1][param_idx]];
+ }
+ param_idx += param_stride;
+ }
+ return series;
+ }
+ }
+
+ function filter_graph_data_idx(raw_series, x_axis, flat_idx, params) {
+ var selection = param_selection_from_flat_idx(params, flat_idx);
+ var flat_selection = [];
+ $.each(selection, function(i, v) {
+ flat_selection.push(v[0]);
+ });
+ return filter_graph_data(raw_series, x_axis, flat_selection, params);
+ }
+
+ /* Escape special characters in graph item file names.
+ The implementation must match asv.util.sanitize_filename */
+ function sanitize_filename(name) {
+ var bad_re = /[<>:"\/\\^|?*\x00-\x1f]/g;
+ var bad_names = ["CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3",
+ "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1",
+ "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8",
+ "LPT9"];
+ name = name.replace(bad_re, "_");
+ if (bad_names.indexOf(name.toUpperCase()) != -1) {
+ name = name + "_";
+ }
+ return name;
+ }
+
+ /* Given a specific group of parameters, generate the URL to
+ use to load that graph.
+ The implementation must match asv.graph.Graph.get_file_path
+ */
+ function graph_to_path(benchmark_name, state) {
+ var parts = [];
+ $.each(state, function(key, value) {
+ var part;
+ if (value === null) {
+ part = key + "-null";
+ } else if (value) {
+ part = key + "-" + value;
+ } else {
+ part = key;
+ }
+ parts.push(sanitize_filename('' + part));
+ });
+ parts.sort();
+ parts.splice(0, 0, "graphs");
+ parts.push(sanitize_filename(benchmark_name));
+
+ /* Escape URI components */
+ parts = $.map(parts, function (val) { return encodeURIComponent(val); });
+ return parts.join('/') + ".json";
+ }
+
+ /*
+ Load and cache graph data (on javascript side)
+ */
+ function load_graph_data(url, success, failure) {
+ var dfd = $.Deferred();
+ if (graph_cache[url]) {
+ setTimeout(function() {
+ dfd.resolve(graph_cache[url]);
+ }, 1);
+ }
+ else {
+ $.ajax({
+ url: url + '?timestamp=' + $.asv.main_timestamp,
+ dataType: "json",
+ cache: true
+ }).done(function(data) {
+ if (Object.keys(graph_cache).length > graph_cache_max_size) {
+ $.each(Object.keys(graph_cache), function (i, key) {
+ delete graph_cache[key];
+ });
+ }
+ graph_cache[url] = data;
+ dfd.resolve(data);
+ }).fail(function() {
+ dfd.reject();
+ });
+ }
+ return dfd.promise();
+ }
+
+ /*
+ Parse hash string, assuming format similar to standard URL
+ query strings
+ */
+ function parse_hash_string(str) {
+ var info = {location: [''], params: {}};
+
+ if (str && str[0] == '#') {
+ str = str.slice(1);
+ }
+ if (str && str[0] == '/') {
+ str = str.slice(1);
+ }
+
+ var match = str.match(/^([^?]*?)\?/);
+ if (match) {
+ info['location'] = decodeURIComponent(match[1]).replace(/\/+/, '/').split('/');
+ var rest = str.slice(match[1].length+1);
+ var parts = rest.split('&');
+ for (var i = 0; i < parts.length; ++i) {
+ var part = parts[i].split('=');
+ if (part.length != 2) {
+ continue;
+ }
+ var key = decodeURIComponent(part[0].replace(/\+/g, " "));
+ var value = decodeURIComponent(part[1].replace(/\+/g, " "));
+ if (value == '[none]') {
+ value = null;
+ }
+ if (info['params'][key] === undefined) {
+ info['params'][key] = [value];
+ }
+ else {
+ info['params'][key].push(value);
+ }
+ }
+ }
+ else {
+ info['location'] = decodeURIComponent(str).replace(/\/+/, '/').split('/');
+ }
+ return info;
+ }
+
+ /*
+ Generate a hash string, inverse of parse_hash_string
+ */
+ function format_hash_string(info) {
+ var parts = info['params'];
+ var str = '#' + info['location'];
+
+ if (parts) {
+ str = str + '?';
+ var first = true;
+ $.each(parts, function (key, values) {
+ $.each(values, function (idx, value) {
+ if (!first) {
+ str = str + '&';
+ }
+ if (value === null) {
+ value = '[none]';
+ }
+ str = str + encodeURIComponent(key) + '=' + encodeURIComponent(value);
+ first = false;
+ });
+ });
+ }
+ return str;
+ }
+
+ /*
+ Dealing with sub-pages
+ */
+
+ function show_page(name, params) {
+ if (loaded_pages[name] !== undefined) {
+ $("#nav ul li.active").removeClass('active');
+ $("#nav-li-" + name).addClass('active');
+ $("#graph-display").hide();
+ $("#summarygrid-display").hide();
+ $("#summarylist-display").hide();
+ $('#regressions-display').hide();
+ $('.tooltip').remove();
+ loaded_pages[name](params);
+ return true;
+ }
+ else {
+ return false;
+ }
+ }
+
+ function hashchange() {
+ var info = parse_hash_string(window.location.hash);
+
+ /* Keep track of window scroll position; makes the back-button work */
+ var old_scroll_pos = window_scroll_positions[info.location.join('/')];
+ window_scroll_positions[window_last_location] = $(window).scrollTop();
+ window_last_location = info.location.join('/');
+
+ /* Redirect to correct handler */
+ if (show_page(info.location, info.params)) {
+ /* show_page does the work */
+ }
+ else {
+ /* Display benchmark page */
+ info.params['benchmark'] = info.location[0];
+ show_page('graphdisplay', info.params);
+ }
+
+ /* Scroll back to previous position, if any */
+ if (old_scroll_pos !== undefined) {
+ $(window).scrollTop(old_scroll_pos);
+ }
+ }
+
+ function get_commit_hash(revision) {
+ var commit_hash = main_json.revision_to_hash[revision];
+ if (commit_hash) {
+ // Return printable commit hash
+ commit_hash = commit_hash.slice(0, main_json.hash_length);
+ }
+ return commit_hash;
+ }
+
+ function get_revision(commit_hash) {
+ var rev = null;
+ $.each(main_json.revision_to_hash, function(revision, full_commit_hash) {
+ if (full_commit_hash.startsWith(commit_hash)) {
+ rev = revision;
+ // break the $.each loop
+ return false;
+ }
+ });
+ return rev;
+ }
+
+ function init_index() {
+ /* Fetch the main index.json and then set up the page elements
+ based on it. */
+ $.ajax({
+ url: "index.json" + '?timestamp=' + $.asv.main_timestamp,
+ dataType: "json",
+ cache: true
+ }).done(function (index) {
+ main_json = index;
+ $.asv.main_json = index;
+
+ /* Page title */
+ var project_name = $("#project-name")[0];
+ project_name.textContent = index.project;
+ project_name.setAttribute("href", index.project_url);
+ $("#project-name").textContent = index.project;
+ document.title = "airspeed velocity of an unladen " + index.project;
+
+ $(window).on('hashchange', hashchange);
+
+ $('#graph-display').hide();
+ $('#regressions-display').hide();
+ $('#summarygrid-display').hide();
+ $('#summarylist-display').hide();
+
+ hashchange();
+ }).fail(function () {
+ $.asv.ui.network_error();
+ });
+ }
+
+ function init() {
+ /* Fetch the info.json */
+ $.ajax({
+ url: "info.json",
+ dataType: "json",
+ cache: false
+ }).done(function (info) {
+ main_timestamp = info['timestamp'];
+ $.asv.main_timestamp = main_timestamp;
+ init_index();
+ }).fail(function () {
+ $.asv.ui.network_error();
+ });
+ }
+
+
+ /*
+ Set up $.asv
+ */
+
+ this.register_page = function(name, show_function) {
+ loaded_pages[name] = show_function;
+ }
+ this.parse_hash_string = parse_hash_string;
+ this.format_hash_string = format_hash_string;
+
+ this.filter_graph_data = filter_graph_data;
+ this.filter_graph_data_idx = filter_graph_data_idx;
+ this.convert_benchmark_param_value = convert_benchmark_param_value;
+ this.param_selection_from_flat_idx = param_selection_from_flat_idx;
+ this.graph_to_path = graph_to_path;
+ this.load_graph_data = load_graph_data;
+ this.get_commit_hash = get_commit_hash;
+ this.get_revision = get_revision;
+
+ this.main_timestamp = main_timestamp; /* Updated after info.json loads */
+ this.main_json = main_json; /* Updated after index.json loads */
+
+ this.format_date_yyyymmdd = format_date_yyyymmdd;
+ this.format_date_yyyymmdd_hhmm = format_date_yyyymmdd_hhmm;
+ this.pretty_unit = pretty_unit;
+ this.time_units = time_units;
+ this.mem_units = mem_units;
+
+ this.colors = colors;
+
+ $.asv = this;
+
+
+ /*
+ Launch it
+ */
+
+ init();
+});
diff --git a/docs/benchmarks/asv_ui.js b/docs/benchmarks/asv_ui.js
new file mode 100644
index 00000000..af757c70
--- /dev/null
+++ b/docs/benchmarks/asv_ui.js
@@ -0,0 +1,231 @@
+'use strict';
+
+$(document).ready(function() {
+ function make_panel(nav, heading) {
+ var panel = $('');
+ nav.append(panel);
+ var panel_header = $(
+ 'airspeed velocity error
+
+
+
+
+
+
+
+ ' +
+ ' ');
+ stack[stack.length - 1].append(top);
+ stack.push($(top.children()[1]));
+ cursor.push(parts[j]);
+
+ $(top.children()[0]).on('click', function () {
+ $(this).parent().children('ul.tree').toggle(150);
+ var caret = $(this).children('b');
+ if (caret.attr('class') == 'caret') {
+ caret.removeClass().addClass("caret-right");
+ } else {
+ caret.removeClass().addClass("caret");
+ }
+ });
+ }
+
+ var name = bm.pretty_name || parts[parts.length - 1];
+ var top = $('' + name + ' ');
+ stack[stack.length - 1].append(top);
+
+ top.tooltip({
+ title: bm.code,
+ html: true,
+ placement: 'right',
+ container: 'body',
+ animation: 'false'
+ });
+ });
+
+ panel_body.append(tree);
+
+ $('#log-scale').on('click', function(evt) {
+ log_scale = !evt.target.classList.contains("active");
+ reference_scale = false;
+ zoom_y_axis = false;
+ $('#reference').removeClass('active');
+ $('#zoom-y-axis').removeClass('active');
+ reference = 1.0;
+ update_state_url({'y-axis-scale': log_scale ? ['log']: []});
+ });
+
+ $('#zoom-y-axis').on('click', function(evt) {
+ zoom_y_axis = !evt.target.classList.contains("active");
+ reference_scale = false;
+ log_scale = false;
+ $('#reference').removeClass('active');
+ $('#log-scale').removeClass('active');
+ reference = 1.0;
+ update_state_url({'y-axis-scale': zoom_y_axis ? ['zoom'] : []});
+ });
+
+ $('#reference').on('click', function(evt) {
+ reference_scale = !evt.target.classList.contains("active");
+ log_scale = false;
+ zoom_y_axis = false;
+ $('#log-scale').removeClass('active');
+ $('#zoom-y-axis').removeClass('active');
+ if (!reference_scale) {
+ reference = 1.0;
+ update_graphs();
+ } else {
+ $('#reference').popover({
+ content: 'Select a reference point',
+ placement: 'top',
+ container: 'body'});
+ $('#reference').popover('show');
+ reference = 1.0;
+ select_reference = true;
+ }
+ });
+
+ $('#even-spacing').on('click', function(evt) {
+ even_spacing = !evt.target.classList.contains("active");
+ date_scale = false;
+ $('#date-scale').removeClass('active');
+ update_state_url({'x-axis-scale': even_spacing ? ['even'] : []});
+ });
+
+ $('#date-scale').on('click', function(evt) {
+ date_scale = !evt.target.classList.contains("active");
+ even_spacing = false;
+ $('#even-spacing').removeClass('active');
+ update_state_url({'x-axis-scale': date_scale ? ['date'] : []});
+ });
+
+ $('#show-legend').on('click', function(evt) {
+ show_legend = !show_legend;
+ update_state_url({'show-legend': show_legend ? [] : [false]});
+ });
+
+ tooltip = $("");
+ tooltip.appendTo("body");
+
+ /* The tooltip on a point shows the exact timing and the
+ commit hash */
+ function showTooltip(x, y, contents) {
+ tooltip
+ .css({
+ position: "absolute",
+ display: "none",
+ top: y - 4,
+ left: x - 2,
+ width: 4,
+ height: 4
+ })
+ .fadeIn(0)
+ .tooltip({
+ title: contents,
+ html: true,
+ placement: 'top',
+ container: 'body',
+ animation: false
+ })
+ .tooltip('show');
+ }
+
+ var previous_hover = null;
+ $("#main-graph").on("plothover", function (event, pos, item) {
+ if (item) {
+ if (previous_hover != item.datapoint) {
+ previous_hover = item.datapoint;
+ var y = item.datapoint[1];
+ var commit_hash = get_commit_hash(item.datapoint[0]);
+ if (commit_hash) {
+ var unit = $.asv.main_json.benchmarks[current_benchmark].unit;
+ showTooltip(
+ item.pageX, item.pageY,
+ $.asv.pretty_unit(y, unit) + " @ " + commit_hash);
+ }
+ }
+ } else {
+ tooltip.tooltip("destroy");
+ }
+ });
+
+ /* Clicking on a point should display the particular commit
+ hash in another tab. */
+ var previous_click;
+ var previous_hash;
+ $("#main-graph").on("plotclick", function (event, pos, item) {
+ if (item) {
+ if (previous_click != item.datapoint) {
+ previous_click = item.datapoint;
+ if (select_reference) {
+ $('#reference').popover('destroy');
+ select_reference = false;
+ reference = item.datapoint[1];
+ update_graphs();
+ } else {
+ var commit_hash = get_commit_hash(item.datapoint[0]);
+ if (previous_hash !== commit_hash) {
+ previous_hash = commit_hash;
+ window.open(
+ $.asv.main_json.show_commit_url + previous_hash,
+ '_blank');
+ }
+ }
+ }
+ }
+ });
+ }
+
+ function setup_benchmark_params(state_selection) {
+ if (!current_benchmark) {
+ x_coordinate_axis = 0;
+ x_coordinate_is_category = false;
+ benchmark_param_selection = [[null]];
+ return
+ }
+
+ /*
+ Generic parameter selections
+ */
+ var index = $.asv.main_json;
+ if (!state || state_selection !== null) {
+ /*
+ Setup the default configuration on first load,
+ or when state selector is present
+ */
+ state = {};
+ state.machine = index.params.machine;
+
+ $.each(index.params, function(param, values) {
+ state[param] = values;
+ if (values.length > 1 && param !== 'machine') {
+ if (param == 'branch') {
+ state[param] = [values[0]];
+ }
+ }
+ });
+ }
+
+ if (state_selection !== null) {
+ /* Select a specific generic parameter state */
+ $.each(index.params, function(param, values) {
+ if (state_selection[param]) {
+ state[param] = state_selection[param];
+ }
+ });
+ }
+
+ /*
+ Benchmark-specific parameter selections
+ */
+
+ var params = index.benchmarks[current_benchmark].params;
+ var param_names = index.benchmarks[current_benchmark].param_names;
+
+ /* Default plot: time series */
+ x_coordinate_axis = 0;
+ if (state_selection['x-axis'] !== undefined &&
+ state_selection['x-axis'] != "commit") {
+ for (var k = 0; k < params.length; ++k) {
+ if (state_selection['x-axis'] == param_names[k]) {
+ x_coordinate_axis = k + 1;
+ break;
+ }
+ }
+ }
+
+ /* Default plot: up to 8 lines */
+ benchmark_param_selection = [[null]];
+ if (params.length >= 1) {
+ var count = 1;
+ var max_curves = 8;
+
+ for (var k = 0; k < params.length; ++k) {
+ var param_name = param_names[k]
+ var param_values = params[k]
+ var item = [];
+ if (state_selection['p-'+param_name] !== undefined) {
+ for (var j = 0; j < param_values.length; ++j) {
+ if (state_selection['p-'+param_name].includes(param_values[j])) {
+ item.push(j);
+ }
+ }
+ } else {
+ for (var j = 0; j < param_values.length && (j+1)*count <= max_curves; ++j) {
+ item.push(j);
+ }
+ }
+ count = count * item.length;
+ benchmark_param_selection.push(item);
+ }
+ }
+
+ check_x_coordinate_axis();
+ replace_params_ui();
+ replace_benchmark_params_ui();
+ }
+
+ function update_state_url(params) {
+ var info = $.asv.parse_hash_string(window.location.hash);
+ $.each($.asv.main_json.params, function(param, values) {
+ if (values.length > 1) {
+ if (state[param].length != values.length || param == 'branch') {
+ info.params[param] = state[param];
+ }
+ else if (info.params[param]) {
+ delete info.params[param];
+ }
+ }
+ });
+ $.each(params || {}, function(key, value) {
+ info.params[key] = value;
+ });
+ window.location.hash = $.asv.format_hash_string(info);
+ }
+
+ function replace_params_ui() {
+ var index = $.asv.main_json;
+
+ var nav = $('#graphdisplay-state-params');
+ nav.empty();
+
+ /* Machine selection */
+ $.asv.ui.make_value_selector_panel(nav, 'machine', index.params.machine, function(i, machine, button) {
+ button.text(machine);
+
+ if (index.params.machine.length > 1) {
+ button.on('click', function(evt) {
+ if (!evt.target.classList.contains("active")) {
+ state.machine.push(machine);
+ } else {
+ state.machine = arr_remove_from(
+ state.machine, machine);
+ }
+ update_state_url();
+ });
+ }
+
+ if ($.inArray(machine, state.machine) == -1) {
+ button.removeClass('active');
+ }
+
+ /* Create tooltips for each machine */
+ var details = [];
+ $.each(index.machines[machine], function(key, val) {
+ details.push(key + ': ' + val);
+ });
+ details = details.join('
'); + + button.tooltip({ + title: details, + html: true, + placement: 'right', + container: 'body', + animation: false + }); + }); + + /* Generic parameter selectors */ + $.each(index.params, function(param, values) { + if (values.length > 1 && param != 'machine') { + $.asv.ui.make_value_selector_panel(nav, param, values, function(i, value, button) { + var value_display; + if (value === null) + value_display = '[none]'; + else if (!value) + value_display = '[default]'; + else + value_display = value; + + button.text(value_display); + + if ($.inArray(value, state[param]) == -1) { + button.removeClass('active'); + } + + if (values.length > 1) { + button.on('click', function(evt) { + if (!evt.target.classList.contains("active")) { + state[param].push(value); + } else { + state[param] = arr_remove_from( + state[param], value); + } + update_state_url(); + }); + } + }); + } + }); + } + + function replace_benchmark_params_ui() { + var params = $.asv.main_json.benchmarks[current_benchmark].params; + var param_names = $.asv.main_json.benchmarks[current_benchmark].param_names; + + /* Parameter selection UI */ + var nav = $('#graphdisplay-navigation-params'); + nav.empty(); + + if (params.length == 0) { + /* Simple time series: no need for parameter selection UI */ + $.asv.ui.reflow_value_selector_panels(); + return; + } + + /* x-axis selector */ + { + var axes = []; + for (var axis = 0; axis < params.length + 1; ++axis) { + axes.push(axis); + } + + $.asv.ui.make_value_selector_panel(nav, "x-axis", axes, function (idx, axis, button) { + var text; + if (axis == 0) { + text = "commit"; + } else { + text = param_names[axis - 1]; + } + if (x_coordinate_axis != axis) { + button.removeClass('active'); + } + button.text(text); + + button.on('click', function (evt) { + $(evt.target).siblings().removeClass('active'); + x_coordinate_axis = axis; + update_state_url({'x-axis': [text]}); + }); + }); + } + + /* Revision/commit value selector */ + if (x_coordinate_axis != 0) { + /* Generate list of all revisions */ + var revisions = current_revisions.slice(); + revisions.sort(); + revisions.push(null); + revisions.reverse(); + + /* Add buttons */ + $.asv.ui.make_value_selector_panel(nav, "commit", revisions, function(idx, rev, button) { + if (rev === null) { + button.text("last"); + } else { + var date_fmt = new Date($.asv.main_json.revision_to_date[rev]); + button.text($.asv.get_commit_hash(rev) + + " " + + date_fmt.toUTCString()); + } + + if ($.inArray(rev, benchmark_param_selection[0]) == -1) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + var idx = $.inArray(rev, benchmark_param_selection[0]); + if (!evt.target.classList.contains("active")) { + if (idx == -1) { + benchmark_param_selection[0].push(rev); + benchmark_param_selection[0].sort(); + } + } else { + if (idx != -1) { + benchmark_param_selection[0].splice(idx, 1); + } + } + replace_graphs(); + update_graphs(); + }); + }); + } + + /* Parameters axes value selector */ + $.each(params, function(param_idx, values) { + var axis = param_idx + 1; + + if (axis == x_coordinate_axis) { + return; + } + + name = param_names[param_idx]; + + /* Add benchmark parameter selector */ + $.asv.ui.make_value_selector_panel(nav, name, values, function(value_idx, value, button) { + var value_display; + value_display = '' + $.asv.convert_benchmark_param_value(value); + + button.text(value_display); + + if ($.inArray(value_idx, benchmark_param_selection[axis]) == -1) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + var new_selection = []; + var old_selection = benchmark_param_selection[param_idx+1]; + + if (!evt.target.classList.contains("active")) { + for (var k = 0; k < params[param_idx].length; ++k) { + if ($.inArray(k, old_selection) != -1 || k == value_idx) { + new_selection.push(k); + } + } + } else { + for (var k = 0; k < params[param_idx].length; ++k) { + if ($.inArray(k, old_selection) != -1 && k != value_idx) { + new_selection.push(k); + } + } + } + benchmark_param_selection[param_idx+1] = new_selection; + var new_selection_params = {}; + new_selection_params['p-'+param_names[param_idx]] = new_selection.map(function(k) { + return params[param_idx][k]; + }); + update_state_url(new_selection_params); + }); + }); + }); + + $.asv.ui.reflow_value_selector_panels(); + } + + /* Check if x-axis is a category axis */ + function check_x_coordinate_axis() { + if (!current_benchmark) { + return; + } + + var params = $.asv.main_json.benchmarks[current_benchmark].params; + x_coordinate_is_category = false; + if (x_coordinate_axis != 0) { + for (var j = 0; j < params[x_coordinate_axis-1].length; ++j) { + var value = $.asv.convert_benchmark_param_value(params[x_coordinate_axis-1][j]); + if (typeof value != "number") { + x_coordinate_is_category = true; + break; + } + } + } + } + + function replace_graphs() { + /* Given the settings in the sidebar, generate a list of the + graphs we need to load. */ + function collect_graphs(current_benchmark, state, param_selection) { + /* Given a specific group of parameters, generate the legend + label to display for that line. Differences is an object of + parameters that have different values across all graphs. */ + function graph_label(state, differences) { + var ignore = { + 'os': null, + 'cpu': null, + 'arch': null, + 'ram': null + }; + + var parts = []; + $.each(state, function(key, value) { + if (!ignore.hasOwnProperty(key) && + differences.hasOwnProperty(key)) { + if (value === null) { + // missing key, skip + } else if (value) { + parts.push(key + "-" + value); + } else { + parts.push(key); + } + } + }); + parts.sort(); + return parts.join('; '); + } + + /* For a given parameter matrix, generate all permutations. */ + function permutations(matrix) { + if (obj_length(matrix) === 0) { + return [{}]; + } + + matrix = obj_copy(matrix); + var key = obj_get_first_key(matrix); + var entry = matrix[key]; + delete matrix[key]; + + var results = []; + $.each(permutations(matrix), function(i, result) { + result = obj_copy(result); + if (entry.length) { + $.each(entry, function(i, value) { + result[key] = value; + results.push(obj_copy(result)); + }); + } else { + result[key] = null; + results.push(obj_copy(result)); + } + }); + + results.sort(); + return results; + } + + /* For all of the selected graphs, find out which parameters + have different values across them. We don't want to show + parameters that are the same across all graphs in the + legend labels, as that information is not really + necessary. */ + function find_different_properties(graphs) { + var different = {}; + var last_values = obj_copy(graphs[0]); + $.each(graphs, function(i, graph) { + $.each(graph, function(key, val) { + if (last_values[key] != val) { + different[key] = true; + } + }); + }); + return different; + } + + if (current_benchmark) { + /* For the current set of enabled parameters, generate a + list of all the permutations we need to load. */ + var state_permutations = $.grep($.asv.main_json.graph_param_list, function (params) { + var ok = true; + $.each(state, function (key, values) { + if ($.inArray(params[key], values) == -1) { + ok = false; + } + }); + return ok; + }); + + /* Find where the parameters are different. */ + var different = find_different_properties(state_permutations); + /* For parameterized tests: names of benchmark parameters */ + var params = $.asv.main_json.benchmarks[current_benchmark].params; + var param_names = $.asv.main_json.benchmarks[current_benchmark].param_names; + /* Selected permutations of benchmark parameters, omitting x-axis */ + var selection = obj_copy(param_selection); + selection[x_coordinate_axis] = [null]; /* value not referenced, set to null */ + var param_permutations = permutations(selection); + + /* Generate a main list of URLs and legend labels for + the graphs. */ + var all = []; + $.each(state_permutations, function (i, perm) { + var graph_contents = []; + $.each(param_permutations, function(k, param_perm) { + /* For each state value, there can be several + benchmark parameter sets to plot */ + var labels = obj_copy(perm); + for (var axis = 0; axis < params.length + 1; ++axis) { + if (axis != x_coordinate_axis) { + if (axis == 0) { + /* Add time/commit value to the labels */ + var timestamp = param_perm[axis]; + different["commit"] = true; + if (timestamp === null) { + labels["commit"] = "last"; + } + else { + labels["commit"] = ""+$.asv.get_commit_hash(timestamp); + } + } + else if (params[axis-1].length > 1) { + /* Add parameter value to the labels */ + if (param_perm[axis] === null) { + /* Empty permutation */ + return; + } + different[param_names[axis-1]] = true; + labels[param_names[axis-1]] = "" + $.asv.convert_benchmark_param_value(params[axis-1][param_perm[axis]]); + } + } + } + graph_contents.push([param_perm, + graph_label(labels, different)]); + }); + all.push([$.asv.graph_to_path(current_benchmark, perm), + graph_contents]); + }); + return all; + } else { + return []; + } + } + + /* Before loading graphs, remove any that are currently + active. */ + graphs = []; + orig_graphs = []; + + var to_load = collect_graphs(current_benchmark, state, benchmark_param_selection); + var failures = 0; + var count = 1; + + if (to_load.length === 0) { + $('#main-graph').html("airspeed velocity
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
```
-
-## Rendering HTML attributes outside of templates
-
-If you need to use serialize HTML attributes outside of Django template and the `html_attrs` tag, you can use `attributes_to_string`:
-
-```py
-from django_components.attributes import attributes_to_string
-
-attrs = {
- "class": "my-class text-red pa-4",
- "data-id": 123,
- "required": True,
- "disabled": False,
- "ignored-attr": None,
-}
-
-attributes_to_string(attrs)
-# 'class="my-class text-red pa-4" data-id="123" required'
-```
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 = """
+
+
+
+
+### Sharing components
+
+- Install and use third-party components from PyPI
+- Or publish your own "component registry"
+- Highly customizable - Choose how the components are called in the template (and more):
+
+ ```django
+ {% component "calendar" date="2024-11-06" %}
+ {% endcomponent %}
+
+ {% calendar date="2024-11-06" %}
+ {% endcalendar %}
+ ```
+
+## Documentation
+
+[Read the full documentation here](https://django-components.github.io/django-components/latest/).
+
+... or jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject).
+
+## Performance
+
+Our aim is to be at least as fast as Django templates.
+
+As of `0.130`, `django-components` is ~4x slower than Django templates.
+
+| | Render time|
+|----------|----------------------|
+| django | 68.9±0.6ms |
+| django-components | 259±4ms |
+
+See the [full performance breakdown](https://django-components.github.io/django-components/latest/benchmarks/) for more information.
## Release notes
-Read the [Release Notes](https://github.com/EmilStenstrom/django-components/tree/master/CHANGELOG.md)
+Read the [Release Notes](https://github.com/django-components/django-components/tree/master/CHANGELOG.md)
to see the latest features and fixes.
## Community examples
One of our goals with `django-components` is to make it easy to share components between projects. If you have a set of components that you think would be useful to others, please open a pull request to add them to the list below.
-- [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/). Try out the [live demo](https://dhc.iwanalabs.com/).
+- [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/).
+
+- [djc-heroicons](https://pypi.org/project/djc-heroicons/): A component that renders icons from [Heroicons.com](https://heroicons.com/).
## Contributing and development
-Get involved or sponsor this project - [See here](https://emilstenstrom.github.io/django-components/dev/overview/contributing/)
+Get involved or sponsor this project - [See here](https://django-components.github.io/django-components/dev/overview/contributing/)
-Running django-components locally for development - [See here](https://emilstenstrom.github.io/django-components/dev/overview/development/)
+Running django-components locally for development - [See here](https://django-components.github.io/django-components/dev/overview/development/)
diff --git a/asv.conf.json b/asv.conf.json
new file mode 100644
index 00000000..0ae16e29
--- /dev/null
+++ b/asv.conf.json
@@ -0,0 +1,210 @@
+{
+ // The version of the config file format. Do not change, unless
+ // you know what you are doing
+ "version": 1,
+
+ // The name of the project being benchmarked
+ "project": "django-components",
+
+ // The project's homepage
+ // "project_url": "https://django-components.github.io/django-components/",
+ "project_url": "/django-components/", // Relative path, since benchmarks are nested under the docs site
+
+ // The URL or local path of the source code repository for the
+ // project being benchmarked
+ "repo": ".",
+
+ // The Python project's subdirectory in your repo. If missing or
+ // the empty string, the project is assumed to be located at the root
+ // of the repository.
+ // "repo_subdir": "",
+
+ // Customizable commands for building the project.
+ // See asv.conf.json documentation.
+ // To build the package using pyproject.toml (PEP518), uncomment the following lines
+ // "build_command": [
+ // "python -m pip install build",
+ // "python -m build",
+ // "python -mpip wheel -w {build_cache_dir} {build_dir}"
+ // ],
+ // To build the package using setuptools and a setup.py file, uncomment the following lines
+ // "build_command": [
+ // "python setup.py build",
+ // "python -mpip wheel -w {build_cache_dir} {build_dir}"
+ // ],
+
+ // Customizable commands for installing and uninstalling the project.
+ // See asv.conf.json documentation.
+ // "install_command": ["in-dir={env_dir} python -mpip install {wheel_file}"],
+ // "uninstall_command": ["return-code=any python -mpip uninstall -y {project}"],
+ "install_command": ["in-dir={env_dir} python -mpip install ./project"],
+
+ // List of branches to benchmark. If not provided, defaults to "main"
+ // (for git) or "default" (for mercurial).
+ // "branches": ["main"], // for git
+ // "branches": ["default"], // for mercurial
+ "branches": [
+ "master"
+ ],
+
+ // The DVCS being used. If not set, it will be automatically
+ // determined from "repo" by looking at the protocol in the URL
+ // (if remote), or by looking for special directories, such as
+ // ".git" (if local).
+ // "dvcs": "git",
+
+ // The tool to use to create environments. May be "conda",
+ // "virtualenv", "mamba" (above 3.8)
+ // or other value depending on the plugins in use.
+ // If missing or the empty string, the tool will be automatically
+ // determined by looking for tools on the PATH environment
+ // variable.
+ "environment_type": "virtualenv",
+
+ // timeout in seconds for installing any dependencies in environment
+ // defaults to 10 min
+ //"install_timeout": 600,
+
+ // the base URL to show a commit for the project.
+ // "show_commit_url": "http://github.com/owner/project/commit/",
+
+ // The Pythons you'd like to test against. If not provided, defaults
+ // to the current version of Python used to run `asv`.
+ "pythons": [
+ "3.13"
+ ],
+
+ // The list of conda channel names to be searched for benchmark
+ // dependency packages in the specified order
+ // "conda_channels": ["conda-forge", "defaults"],
+
+ // A conda environment file that is used for environment creation.
+ // "conda_environment_file": "environment.yml",
+
+ // The matrix of dependencies to test. Each key of the "req"
+ // requirements dictionary is the name of a package (in PyPI) and
+ // the values are version numbers. An empty list or empty string
+ // indicates to just test against the default (latest)
+ // version. null indicates that the package is to not be
+ // installed. If the package to be tested is only available from
+ // PyPi, and the 'environment_type' is conda, then you can preface
+ // the package name by 'pip+', and the package will be installed
+ // via pip (with all the conda available packages installed first,
+ // followed by the pip installed packages).
+ //
+ // The ``@env`` and ``@env_nobuild`` keys contain the matrix of
+ // environment variables to pass to build and benchmark commands.
+ // An environment will be created for every combination of the
+ // cartesian product of the "@env" variables in this matrix.
+ // Variables in "@env_nobuild" will be passed to every environment
+ // during the benchmark phase, but will not trigger creation of
+ // new environments. A value of ``null`` means that the variable
+ // will not be set for the current combination.
+ //
+ // "matrix": {
+ // "req": {
+ // "numpy": ["1.6", "1.7"],
+ // "six": ["", null], // test with and without six installed
+ // "pip+emcee": [""] // emcee is only available for install with pip.
+ // },
+ // "env": {"ENV_VAR_1": ["val1", "val2"]},
+ // "env_nobuild": {"ENV_VAR_2": ["val3", null]},
+ // },
+ "matrix": {
+ "req": {
+ "django": [
+ "5.1"
+ ],
+ "djc-core-html-parser": [""] // Empty string means the latest version
+ }
+ },
+
+ // Combinations of libraries/python versions can be excluded/included
+ // from the set to test. Each entry is a dictionary containing additional
+ // key-value pairs to include/exclude.
+ //
+ // An exclude entry excludes entries where all values match. The
+ // values are regexps that should match the whole string.
+ //
+ // An include entry adds an environment. Only the packages listed
+ // are installed. The 'python' key is required. The exclude rules
+ // do not apply to includes.
+ //
+ // In addition to package names, the following keys are available:
+ //
+ // - python
+ // Python version, as in the *pythons* variable above.
+ // - environment_type
+ // Environment type, as above.
+ // - sys_platform
+ // Platform, as in sys.platform. Possible values for the common
+ // cases: 'linux2', 'win32', 'cygwin', 'darwin'.
+ // - req
+ // Required packages
+ // - env
+ // Environment variables
+ // - env_nobuild
+ // Non-build environment variables
+ //
+ // "exclude": [
+ // {"python": "3.2", "sys_platform": "win32"}, // skip py3.2 on windows
+ // {"environment_type": "conda", "req": {"six": null}}, // don't run without six on conda
+ // {"env": {"ENV_VAR_1": "val2"}}, // skip val2 for ENV_VAR_1
+ // ],
+ //
+ // "include": [
+ // // additional env for python3.12
+ // {"python": "3.12", "req": {"numpy": "1.26"}, "env_nobuild": {"FOO": "123"}},
+ // // additional env if run on windows+conda
+ // {"platform": "win32", "environment_type": "conda", "python": "3.12", "req": {"libpython": ""}},
+ // ],
+
+ // The directory (relative to the current directory) that benchmarks are
+ // stored in. If not provided, defaults to "benchmarks"
+ "benchmark_dir": "benchmarks",
+
+ // The directory (relative to the current directory) to cache the Python
+ // environments in. If not provided, defaults to "env"
+ "env_dir": ".asv/env",
+
+ // The directory (relative to the current directory) that raw benchmark
+ // results are stored in. If not provided, defaults to "results".
+ "results_dir": ".asv/results",
+
+ // The directory (relative to the current directory) that the html tree
+ // should be written to. If not provided, defaults to "html".
+ // "html_dir": ".asv/html",
+ "html_dir": "docs/benchmarks", // # TODO
+
+ // The number of characters to retain in the commit hashes.
+ // "hash_length": 8,
+
+ // `asv` will cache results of the recent builds in each
+ // environment, making them faster to install next time. This is
+ // the number of builds to keep, per environment.
+ // "build_cache_size": 2,
+
+ // The commits after which the regression search in `asv publish`
+ // should start looking for regressions. Dictionary whose keys are
+ // regexps matching to benchmark names, and values corresponding to
+ // the commit (exclusive) after which to start looking for
+ // regressions. The default is to start from the first commit
+ // with results. If the commit is `null`, regression detection is
+ // skipped for the matching benchmark.
+ //
+ // "regressions_first_commits": {
+ // "some_benchmark": "352cdf", // Consider regressions only after this commit
+ // "another_benchmark": null, // Skip regression detection altogether
+ // },
+
+ // The thresholds for relative change in results, after which `asv
+ // publish` starts reporting regressions. Dictionary of the same
+ // form as in ``regressions_first_commits``, with values
+ // indicating the thresholds. If multiple entries match, the
+ // maximum is taken. If no entry matches, the default is 5%.
+ //
+ // "regressions_thresholds": {
+ // "some_benchmark": 0.01, // Threshold of 1%
+ // "another_benchmark": 0.5, // Threshold of 50%
+ // },
+}
diff --git a/benchmarks/README.md b/benchmarks/README.md
new file mode 100644
index 00000000..f5f5d524
--- /dev/null
+++ b/benchmarks/README.md
@@ -0,0 +1,195 @@
+# Benchmarks
+
+## Overview
+
+[`asv`](https://github.com/airspeed-velocity/) (Airspeed Velocity) is used for benchmarking performance.
+
+`asv` covers the entire benchmarking workflow. We can:
+
+1. Define benchmark tests similarly to writing pytest tests (supports both timing and memory benchmarks)
+2. Run the benchmarks and generate results for individual git commits, tags, or entire branches
+3. View results as an HTML report (dashboard with charts)
+4. Compare performance between two commits / tags / branches for CI integration
+
+
+
+django-components uses `asv` for these use cases:
+
+- Benchmarking across releases:
+
+ 1. When a git tag is created and pushed, this triggers a Github Action workflow (see `docs.yml`).
+ 2. The workflow runs the benchmarks with the latest release, and commits the results to the repository.
+ Thus, we can see how performance changes across releases.
+
+- Displaying performance results on the website:
+
+ 1. When a git tag is created and pushed, we also update the documentation website (see `docs.yml`).
+ 2. Before we publish the docs website, we generate the HTML report for the benchmark results.
+ 3. The generated report is placed in the `docs/benchmarks/` directory, and is thus
+ published with the rest of the docs website and available under [`/benchmarks/`](https://django-components.github.io/django-components/latest/benchmarks).
+ - NOTE: The location where the report is placed is defined in `asv.conf.json`.
+
+- Compare performance between commits on pull requests:
+ 1. When a pull request is made, this triggers a Github Action workflow (see `benchmark.yml`).
+ 2. The workflow compares performance between commits.
+ 3. The report is added to the PR as a comment made by a bot.
+
+## Interpreting benchmarks
+
+The results CANNOT be taken as ABSOLUTE values e.g.:
+
+"This example took 200ms to render, so my page will also take 200ms to render."
+
+Each UI may consist of different number of Django templates, template tags, and components, and all these may influence the rendering time differently.
+
+Instead, the results MUST be understood as RELATIVE values.
+
+- If a commit is 10% slower than the master branch, that's valid.
+- If Django components are 10% slower than vanilla Django templates, that's valid.
+- If "isolated" mode is 10% slower than "django" mode, that's valid.
+
+## Development
+
+Let's say we want to generate results for the last 5 commits.
+
+1. Install `asv`
+
+ ```bash
+ pip install asv
+ ```
+
+2. Run benchmarks and generate results
+
+ ```bash
+ asv run HEAD --steps 5 -e
+ ```
+
+ - `HEAD` means that we want to run benchmarks against the [current branch](https://stackoverflow.com/a/2304106/9788634).
+ - `--steps 5` means that we want to run benchmarks for the last 5 commits.
+ - `-e` to print out any errors.
+
+ The results will be stored in `.asv/results/`, as configured in `asv.conf.json`.
+
+3. Generate HTML report
+
+ ```bash
+ asv publish
+ asv preview
+ ```
+
+ - `publish` generates the HTML report and stores it in `docs/benchmarks/`, as configured in `asv.conf.json`.
+ - `preview` starts a local server and opens the report in the browser.
+
+ NOTE: Since the results are stored in `docs/benchmarks/`, you can also view the results
+ with `mkdocs serve` and navigating to `http://localhost:9000/django-components/benchmarks/`.
+
+ NOTE 2: Running `publish` will overwrite the existing contents of `docs/benchmarks/`.
+
+## Writing benchmarks
+
+`asv` supports writing different [types of benchmarks](https://asv.readthedocs.io/en/latest/writing_benchmarks.html#benchmark-types). What's relevant for us is:
+
+- [Raw timing benchmarks](https://asv.readthedocs.io/en/latest/writing_benchmarks.html#raw-timing-benchmarks)
+- [Peak memory benchmarks](https://asv.readthedocs.io/en/latest/writing_benchmarks.html#peak-memory)
+
+Notes:
+
+- The difference between "raw timing" and "timing" tests is that "raw timing" is ran in a separate process.
+ And instead of running the logic within the test function itself, we return a script (string)
+ that will be executed in the separate process.
+
+- The difference between "peak memory" and "memory" tests is that "memory" calculates the memory
+ of the object returned from the test function. On the other hand, "peak memory" detects the
+ peak memory usage during the execution of the test function (including the setup function).
+
+You can write the test file anywhere in the `benchmarks/` directory, `asv` will automatically find it.
+
+Inside the file, write a test function. Depending on the type of the benchmark,
+prefix the test function name with `timeraw_` or `peakmem_`. See [`benchmarks/benchmark_templating.py`](benchmark_templating.py) for examples.
+
+### Ensuring that the benchmarked logic is correct
+
+The approach I (Juro) took with benchmarking the overall template rendering is that
+I've defined the actual logic in `tests/test_benchmark_*.py` files. So those files
+are part of the normal pytest testing, and even contain a section with pytest tests.
+
+This ensures that the benchmarked logic remains functional and error-free.
+
+However, there's some caveats:
+
+1. I wasn't able to import files from `tests/`.
+2. When running benchmarks, we don't want to run the pytest tests.
+
+To work around that, the approach I used for loading the files from the `tests/` directory is to:
+
+1. Get the file's source code as a string.
+2. Cut out unwanted sections (like the pytest tests).
+3. Append the benchmark-specific code to the file (e.g. to actually render the templates).
+4. In case of "timeraw" benchmarks, we can simply return the remaining code as a string
+ to be run in a separate process.
+5. In case of "peakmem" benchmarks, we need to access this modified source code as Python objects.
+ So the code is made available as a "virtual" module, which makes it possible to import Python objects like so:
+ ```py
+ from my_virtual_module import run_my_benchmark
+ ```
+
+## Using `asv`
+
+### Compare latest commit against master
+
+Note: Before comparing, you must run the benchmarks first to generate the results. The `continuous` command does not generate the results by itself.
+
+```bash
+asv continuous master^! HEAD^! --factor 1.1
+```
+
+- Factor of `1.1` means that the new commit is allowed to be 10% slower/faster than the master commit.
+
+- `^` means that we mean the COMMIT of the branch, not the BRANCH itself.
+
+ Without it, we would run benchmarks for the whole branch history.
+
+ With it, we run benchmarks FROM the latest commit (incl) TO ...
+
+- `!` means that we want to select range spanning a single commit.
+
+ Without it, we would run benchmarks for all commits FROM the latest commit
+ TO the start of the branch history.
+
+ With it, we run benchmarks ONLY FOR the latest commit.
+
+### More Examples
+
+Notes:
+
+- Use `~1` to select the second-latest commit, `~2` for the third-latest, etc..
+
+Generate benchmarks for the latest commit in `master` branch.
+
+```bash
+asv run master^!
+```
+
+Generate benchmarks for second-latest commit in `master` branch.
+
+```bash
+asv run master~1^!
+```
+
+Generate benchmarks for all commits in `master` branch.
+
+```bash
+asv run master
+```
+
+Generate benchmarks for all commits in `master` branch, but exclude the latest commit.
+
+```bash
+asv run master~1
+```
+
+Generate benchmarks for the LAST 5 commits in `master` branch, but exclude the latest commit.
+
+```bash
+asv run master~1 --steps 5
+```
diff --git a/benchmarks/__init__.py b/benchmarks/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/benchmarks/assets/asv_dashboard.png b/benchmarks/assets/asv_dashboard.png
new file mode 100644
index 00000000..524990b8
Binary files /dev/null and b/benchmarks/assets/asv_dashboard.png differ
diff --git a/benchmarks/benchmark_templating.py b/benchmarks/benchmark_templating.py
new file mode 100644
index 00000000..779c70aa
--- /dev/null
+++ b/benchmarks/benchmark_templating.py
@@ -0,0 +1,446 @@
+# Write the benchmarking functions here
+# See "Writing benchmarks" in the asv docs for more information.
+
+import re
+from pathlib import Path
+from types import ModuleType
+from typing import Literal
+
+# Fix for for https://github.com/airspeed-velocity/asv_runner/pull/44
+import benchmarks.monkeypatch_asv # noqa: F401
+
+from benchmarks.utils import benchmark, create_virtual_module
+
+
+DJC_VS_DJ_GROUP = "Components vs Django"
+DJC_ISOLATED_VS_NON_GROUP = "isolated vs django modes"
+OTHER_GROUP = "Other"
+
+
+DjcContextMode = Literal["isolated", "django"]
+TemplatingRenderer = Literal["django", "django-components", "none"]
+TemplatingTestSize = Literal["lg", "sm"]
+TemplatingTestType = Literal[
+ "first", # Testing performance of the first time the template is rendered
+ "subsequent", # Testing performance of the subsequent times the template is rendered
+ "startup", # Testing performance of the startup time (e.g. defining classes and templates)
+]
+
+
+def _get_templating_filepath(renderer: TemplatingRenderer, size: TemplatingTestSize) -> Path:
+ if renderer == "none":
+ raise ValueError("Cannot get filepath for renderer 'none'")
+ elif renderer not in ["django", "django-components"]:
+ raise ValueError(f"Invalid renderer: {renderer}")
+
+ if size not in ("lg", "sm"):
+ raise ValueError(f"Invalid size: {size}, must be one of ('lg', 'sm')")
+
+ # At this point, we know the renderer is either "django" or "django-components"
+ root = file_path = Path(__file__).parent.parent
+ if renderer == "django":
+ if size == "lg":
+ file_path = root / "tests" / "test_benchmark_django.py"
+ else:
+ file_path = root / "tests" / "test_benchmark_django_small.py"
+ else:
+ if size == "lg":
+ file_path = root / "tests" / "test_benchmark_djc.py"
+ else:
+ file_path = root / "tests" / "test_benchmark_djc_small.py"
+
+ return file_path
+
+
+def _get_templating_script(
+ renderer: TemplatingRenderer,
+ size: TemplatingTestSize,
+ context_mode: DjcContextMode,
+ imports_only: bool,
+) -> str:
+ if renderer == "none":
+ return ""
+ elif renderer not in ["django", "django-components"]:
+ raise ValueError(f"Invalid renderer: {renderer}")
+
+ # At this point, we know the renderer is either "django" or "django-components"
+ file_path = _get_templating_filepath(renderer, size)
+ contents = file_path.read_text()
+
+ # The files with benchmarked code also have a section for testing them with pytest.
+ # We remove that pytest section, so the script is only the benchmark code.
+ contents = contents.split("# ----------- TESTS START ------------ #")[0]
+
+ if imports_only:
+ # There is a benchmark test for measuring the time it takes to import the module.
+ # For that, we exclude from the code everything AFTER this line
+ contents = contents.split("# ----------- IMPORTS END ------------ #")[0]
+ else:
+ # Set the context mode by replacing variable in the script
+ contents = re.sub(r"CONTEXT_MODE.*?\n", f"CONTEXT_MODE = '{context_mode}'\n", contents, count=1)
+
+ return contents
+
+
+def _get_templating_module(
+ renderer: TemplatingRenderer,
+ size: TemplatingTestSize,
+ context_mode: DjcContextMode,
+ imports_only: bool,
+) -> ModuleType:
+ if renderer not in ("django", "django-components"):
+ raise ValueError(f"Invalid renderer: {renderer}")
+
+ file_path = _get_templating_filepath(renderer, size)
+ script = _get_templating_script(renderer, size, context_mode, imports_only)
+
+ # This makes it possible to import the module in the benchmark function
+ # as `import test_templating`
+ module = create_virtual_module("test_templating", script, str(file_path))
+ return module
+
+
+# The `timeraw_` tests run in separate processes. But when running memory benchmarks,
+# the tested logic runs in the same process as the where we run the benchmark functions
+# (e.g. `peakmem_render_lg_first()`). Thus, the `peakmem_` functions have access to this file
+# when the tested logic runs.
+#
+# Secondly, `asv` doesn't offer any way to pass data from `setup` to actual test.
+#
+# And so we define this global, which, when running memory benchmarks, the `setup` function
+# populates. And then we trigger the actual render from within the test body.
+do_render = lambda: None # noqa: E731
+
+
+def setup_templating_memory_benchmark(
+ renderer: TemplatingRenderer,
+ size: TemplatingTestSize,
+ test_type: TemplatingTestType,
+ context_mode: DjcContextMode,
+ imports_only: bool = False,
+):
+ global do_render
+ module = _get_templating_module(renderer, size, context_mode, imports_only)
+ data = module.gen_render_data()
+ render = module.render
+ do_render = lambda: render(data) # noqa: E731
+
+ # Do the first render as part of setup if we're testing the subsequent renders
+ if test_type == "subsequent":
+ do_render()
+
+
+# The timing benchmarks run the actual code in a separate process, by using the `timeraw_` prefix.
+# As such, we don't actually load the code in this file. Instead, we only prepare a script (raw string)
+# that will be run in the new process.
+def prepare_templating_benchmark(
+ renderer: TemplatingRenderer,
+ size: TemplatingTestSize,
+ test_type: TemplatingTestType,
+ context_mode: DjcContextMode,
+ imports_only: bool = False,
+):
+ setup_script = _get_templating_script(renderer, size, context_mode, imports_only)
+
+ # If we're testing the startup time, then the setup is actually the tested code
+ if test_type == "startup":
+ return setup_script
+ else:
+ # Otherwise include also data generation as part of setup
+ setup_script += "\n\n" "render_data = gen_render_data()\n"
+
+ # Do the first render as part of setup if we're testing the subsequent renders
+ if test_type == "subsequent":
+ setup_script += "render(render_data)\n"
+
+ benchmark_script = "render(render_data)\n"
+ return benchmark_script, setup_script
+
+
+# - Group: django-components vs django
+# - time: djc vs django (startup lg)
+# - time: djc vs django (lg - FIRST)
+# - time: djc vs django (sm - FIRST)
+# - time: djc vs django (lg - SUBSEQUENT)
+# - time: djc vs django (sm - SUBSEQUENT)
+# - mem: djc vs django (lg - FIRST)
+# - mem: djc vs django (sm - FIRST)
+# - mem: djc vs django (lg - SUBSEQUENT)
+# - mem: djc vs django (sm - SUBSEQUENT)
+#
+# NOTE: While the name suggests we're comparing Django and Django-components, be aware that
+# in our "Django" tests, we still install and import django-components. We also use
+# django-components's `{% html_attrs %}` tag in the Django scenario. `{% html_attrs %}`
+# was used because the original sample code was from django-components.
+#
+# As such, these tests should seen not as "Using Django vs Using Components". But instead,
+# it should be "What is the relative cost of using Components?".
+#
+# As an example, the benchmarking for the startup time and memory usage is not comparing
+# two independent approaches. Rather, the test is checking if defining Components classes
+# is more expensive than vanilla Django templates.
+class DjangoComponentsVsDjangoTests:
+ # Testing startup time (e.g. defining classes and templates)
+ @benchmark(
+ pretty_name="startup - large",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ )
+ def timeraw_startup_lg(self, renderer: TemplatingRenderer):
+ return prepare_templating_benchmark(renderer, "lg", "startup", "isolated")
+
+ @benchmark(
+ pretty_name="render - small - first render",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ )
+ def timeraw_render_sm_first(self, renderer: TemplatingRenderer):
+ return prepare_templating_benchmark(renderer, "sm", "first", "isolated")
+
+ @benchmark(
+ pretty_name="render - small - second render",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ )
+ def timeraw_render_sm_subsequent(self, renderer: TemplatingRenderer):
+ return prepare_templating_benchmark(renderer, "sm", "subsequent", "isolated")
+
+ @benchmark(
+ pretty_name="render - large - first render",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ include_in_quick_benchmark=True,
+ )
+ def timeraw_render_lg_first(self, renderer: TemplatingRenderer):
+ return prepare_templating_benchmark(renderer, "lg", "first", "isolated")
+
+ @benchmark(
+ pretty_name="render - large - second render",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ )
+ def timeraw_render_lg_subsequent(self, renderer: TemplatingRenderer):
+ return prepare_templating_benchmark(renderer, "lg", "subsequent", "isolated")
+
+ @benchmark(
+ pretty_name="render - small - first render (mem)",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ setup=lambda renderer: setup_templating_memory_benchmark(renderer, "sm", "first", "isolated"),
+ )
+ def peakmem_render_sm_first(self, renderer: TemplatingRenderer):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - small - second render (mem)",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ setup=lambda renderer: setup_templating_memory_benchmark(renderer, "sm", "subsequent", "isolated"),
+ )
+ def peakmem_render_sm_subsequent(self, renderer: TemplatingRenderer):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - large - first render (mem)",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ setup=lambda renderer: setup_templating_memory_benchmark(renderer, "lg", "first", "isolated"),
+ )
+ def peakmem_render_lg_first(self, renderer: TemplatingRenderer):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - large - second render (mem)",
+ group_name=DJC_VS_DJ_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "renderer": ["django", "django-components"],
+ },
+ setup=lambda renderer: setup_templating_memory_benchmark(renderer, "lg", "subsequent", "isolated"),
+ )
+ def peakmem_render_lg_subsequent(self, renderer: TemplatingRenderer):
+ do_render()
+
+
+# - Group: Django-components "isolated" vs "django" modes
+# - time: Isolated vs django djc (startup lg)
+# - time: Isolated vs django djc (lg - FIRST)
+# - time: Isolated vs django djc (sm - FIRST)
+# - time: Isolated vs django djc (lg - SUBSEQUENT)
+# - time: Isolated vs django djc (sm - SUBSEQUENT)
+# - mem: Isolated vs django djc (lg - FIRST)
+# - mem: Isolated vs django djc (sm - FIRST)
+# - mem: Isolated vs django djc (lg - SUBSEQUENT)
+# - mem: Isolated vs django djc (sm - SUBSEQUENT)
+class IsolatedVsDjangoContextModesTests:
+ # Testing startup time (e.g. defining classes and templates)
+ @benchmark(
+ pretty_name="startup - large",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ )
+ def timeraw_startup_lg(self, context_mode: DjcContextMode):
+ return prepare_templating_benchmark("django-components", "lg", "startup", context_mode)
+
+ @benchmark(
+ pretty_name="render - small - first render",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ )
+ def timeraw_render_sm_first(self, context_mode: DjcContextMode):
+ return prepare_templating_benchmark("django-components", "sm", "first", context_mode)
+
+ @benchmark(
+ pretty_name="render - small - second render",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ )
+ def timeraw_render_sm_subsequent(self, context_mode: DjcContextMode):
+ return prepare_templating_benchmark("django-components", "sm", "subsequent", context_mode)
+
+ @benchmark(
+ pretty_name="render - large - first render",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ )
+ def timeraw_render_lg_first(self, context_mode: DjcContextMode):
+ return prepare_templating_benchmark("django-components", "lg", "first", context_mode)
+
+ @benchmark(
+ pretty_name="render - large - second render",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ )
+ def timeraw_render_lg_subsequent(self, context_mode: DjcContextMode):
+ return prepare_templating_benchmark("django-components", "lg", "subsequent", context_mode)
+
+ @benchmark(
+ pretty_name="render - small - first render (mem)",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ setup=lambda context_mode: setup_templating_memory_benchmark("django-components", "sm", "first", context_mode),
+ )
+ def peakmem_render_sm_first(self, context_mode: DjcContextMode):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - small - second render (mem)",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ setup=lambda context_mode: setup_templating_memory_benchmark(
+ "django-components",
+ "sm",
+ "subsequent",
+ context_mode,
+ ),
+ )
+ def peakmem_render_sm_subsequent(self, context_mode: DjcContextMode):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - large - first render (mem)",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ setup=lambda context_mode: setup_templating_memory_benchmark(
+ "django-components",
+ "lg",
+ "first",
+ context_mode,
+ ),
+ )
+ def peakmem_render_lg_first(self, context_mode: DjcContextMode):
+ do_render()
+
+ @benchmark(
+ pretty_name="render - large - second render (mem)",
+ group_name=DJC_ISOLATED_VS_NON_GROUP,
+ number=1,
+ rounds=5,
+ params={
+ "context_mode": ["isolated", "django"],
+ },
+ setup=lambda context_mode: setup_templating_memory_benchmark(
+ "django-components",
+ "lg",
+ "subsequent",
+ context_mode,
+ ),
+ )
+ def peakmem_render_lg_subsequent(self, context_mode: DjcContextMode):
+ do_render()
+
+
+class OtherTests:
+ @benchmark(
+ pretty_name="import time",
+ group_name=OTHER_GROUP,
+ number=1,
+ rounds=5,
+ )
+ def timeraw_import_time(self):
+ return prepare_templating_benchmark("django-components", "lg", "startup", "isolated", imports_only=True)
diff --git a/benchmarks/component_rendering.py b/benchmarks/component_rendering.py
deleted file mode 100644
index a067e0e2..00000000
--- a/benchmarks/component_rendering.py
+++ /dev/null
@@ -1,176 +0,0 @@
-from time import perf_counter
-
-from django.template import Context, Template
-
-from django_components import Component, registry, types
-from django_components.dependencies import CSS_DEPENDENCY_PLACEHOLDER, JS_DEPENDENCY_PLACEHOLDER
-from tests.django_test_setup import * # NOQA
-from tests.testutils import BaseTestCase, create_and_process_template_response
-
-
-class SlottedComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
-
+' + heading + '
');
+ panel.append(panel_header);
+ var panel_body = $('');
+ panel.append(panel_body);
+ return panel_body;
+ }
+
+ function make_value_selector_panel(nav, heading, values, setup_callback) {
+ var panel_body = make_panel(nav, heading);
+ var vertical = false;
+ var buttons = $('');
+
+ panel_body.append(buttons);
+
+ $.each(values, function (idx, value) {
+ var button = $(
+ '');
+ setup_callback(idx, value, button);
+ buttons.append(button);
+ });
+
+ return panel_body;
+ }
+
+ function reflow_value_selector_panels(no_timeout) {
+ $('.panel').each(function (i, panel_obj) {
+ var panel = $(panel_obj);
+ panel.find('.btn-group').each(function (i, buttons_obj) {
+ var buttons = $(buttons_obj);
+ var width = 0;
+
+ if (buttons.hasClass('reflow-done')) {
+ /* already processed */
+ return;
+ }
+
+ $.each(buttons.children(), function(idx, value) {
+ width += value.scrollWidth;
+ });
+
+ var max_width = panel_obj.clientWidth;
+
+ if (width >= max_width) {
+ buttons.addClass("btn-group-vertical");
+ buttons.css("width", "100%");
+ buttons.css("max-height", "20ex");
+ buttons.css("overflow-y", "auto");
+ }
+ else {
+ buttons.addClass("btn-group-justified");
+ }
+
+ /* The widths can be zero if the UI is not fully layouted yet,
+ so mark the adjustment complete only if this is not the case */
+ if (width > 0 && max_width > 0) {
+ buttons.addClass("reflow-done");
+ }
+ });
+ });
+
+ if (!no_timeout) {
+ /* Call again asynchronously, in case the UI was not fully layouted yet */
+ setTimeout(function() { $.asv.ui.reflow_value_selector_panels(true); }, 0);
+ }
+ }
+
+ function network_error(ajax, status, error) {
+ $("#error-message").text(
+ "Error fetching content. " +
+ "Perhaps web server has gone down.");
+ $("#error").modal('show');
+ }
+
+ function hover_graph(element, graph_url, benchmark_basename, parameter_idx, revisions) {
+ /* Show the summary graph as a popup */
+ var plot_div = $('');
+ plot_div.css('width', '11.8em');
+ plot_div.css('height', '7em');
+ plot_div.css('border', '2px solid black');
+ plot_div.css('background-color', 'white');
+
+ function update_plot() {
+ var markings = [];
+
+ if (revisions) {
+ $.each(revisions, function(i, revs) {
+ var rev_a = revs[0];
+ var rev_b = revs[1];
+
+ if (rev_a !== null) {
+ markings.push({ color: '#d00', lineWidth: 2, xaxis: { from: rev_a, to: rev_a }});
+ markings.push({ color: "rgba(255,0,0,0.1)", xaxis: { from: rev_a, to: rev_b }});
+ }
+ markings.push({ color: '#d00', lineWidth: 2, xaxis: { from: rev_b, to: rev_b }});
+ });
+ }
+
+ $.asv.load_graph_data(
+ graph_url
+ ).done(function (data) {
+ var params = $.asv.main_json.benchmarks[benchmark_basename].params;
+ data = $.asv.filter_graph_data_idx(data, 0, parameter_idx, params);
+ var options = {
+ colors: ['#000'],
+ series: {
+ lines: {
+ show: true,
+ lineWidth: 2
+ },
+ shadowSize: 0
+ },
+ grid: {
+ borderWidth: 1,
+ margin: 0,
+ labelMargin: 0,
+ axisMargin: 0,
+ minBorderMargin: 0,
+ markings: markings,
+ },
+ xaxis: {
+ ticks: [],
+ },
+ yaxis: {
+ ticks: [],
+ min: 0
+ },
+ legend: {
+ show: false
+ }
+ };
+ var plot = $.plot(plot_div, [{data: data}], options);
+ }).fail(function () {
+ // TODO: Handle failure
+ });
+
+ return plot_div;
+ }
+
+ element.popover({
+ placement: 'left auto',
+ trigger: 'hover',
+ html: true,
+ delay: 50,
+ content: $('').append(plot_div)
+ });
+
+ element.on('show.bs.popover', update_plot);
+ }
+
+ function hover_summary_graph(element, benchmark_basename) {
+ /* Show the summary graph as a popup */
+ var plot_div = $('');
+ plot_div.css('width', '11.8em');
+ plot_div.css('height', '7em');
+ plot_div.css('border', '2px solid black');
+ plot_div.css('background-color', 'white');
+
+ function update_plot() {
+ var markings = [];
+
+ $.asv.load_graph_data(
+ 'graphs/summary/' + benchmark_basename + '.json'
+ ).done(function (data) {
+ var options = {
+ colors: $.asv.colors,
+ series: {
+ lines: {
+ show: true,
+ lineWidth: 2
+ },
+ shadowSize: 0
+ },
+ grid: {
+ borderWidth: 1,
+ margin: 0,
+ labelMargin: 0,
+ axisMargin: 0,
+ minBorderMargin: 0,
+ markings: markings,
+ },
+ xaxis: {
+ ticks: [],
+ },
+ yaxis: {
+ ticks: [],
+ min: 0
+ },
+ legend: {
+ show: false
+ }
+ };
+ var plot = $.plot(plot_div, [{data: data}], options);
+ }).fail(function () {
+ // TODO: Handle failure
+ });
+
+ return plot_div;
+ }
+
+ element.popover({
+ placement: 'left auto',
+ trigger: 'hover',
+ html: true,
+ delay: 50,
+ content: $('').append(plot_div)
+ });
+
+ element.on('show.bs.popover', update_plot);
+ }
+
+ /*
+ Set up $.asv.ui
+ */
+
+ this.network_error = network_error;
+ this.make_panel = make_panel;
+ this.make_value_selector_panel = make_value_selector_panel;
+ this.reflow_value_selector_panels = reflow_value_selector_panels;
+ this.hover_graph = hover_graph;
+ this.hover_summary_graph = hover_summary_graph;
+
+ $.asv.ui = this;
+});
diff --git a/docs/benchmarks/error.html b/docs/benchmarks/error.html
new file mode 100644
index 00000000..af2a4d54
--- /dev/null
+++ b/docs/benchmarks/error.html
@@ -0,0 +1,23 @@
+
+
+
+
+ 
+ Can not determine continental origin of swallow.
+
+
+ + One or more external (JavaScript) dependencies of airspeed velocity failed to load. +
+ ++ Make sure you have an active internet connection and enable 3rd-party scripts + in your browser the first time you load airspeed velocity. +
+ + diff --git a/docs/benchmarks/graphdisplay.js b/docs/benchmarks/graphdisplay.js new file mode 100644 index 00000000..ba715322 --- /dev/null +++ b/docs/benchmarks/graphdisplay.js @@ -0,0 +1,1427 @@ +'use strict'; + +$(document).ready(function() { + /* The state of the parameters in the sidebar. Dictionary mapping + strings to arrays containing the "enabled" configurations. */ + var state = null; + /* The name of the current benchmark being displayed. */ + var current_benchmark = null; + /* An array of graphs being displayed. */ + var graphs = []; + var orig_graphs = []; + /* An array of commit revisions being displayed */ + var current_revisions = []; + /* True when log scaling is enabled. */ + var log_scale = false; + /* True when zooming in on the y-axis. */ + var zoom_y_axis = false; + /* True when log scaling is enabled. */ + var reference_scale = false; + /* True when selecting a reference point */ + var select_reference = false; + /* The reference value */ + var reference = 1.0; + /* Whether to show the legend */ + var show_legend = true; + /* Is even commit spacing being used? */ + var even_spacing = false; + var even_spacing_revisions = []; + /* Is date scale being used ? */ + var date_scale = false; + var date_to_revision = {}; + /* A little div to handle tooltip placement on the graph */ + var tooltip = null; + /* X-axis coordinate axis in the data set; always 0 for + non-parameterized tests where revision and date are the only potential x-axis */ + var x_coordinate_axis = 0; + var x_coordinate_is_category = false; + /* List of lists of value combinations to plot (apart from x-axis) + in parameterized tests. */ + var benchmark_param_selection = [[null]]; + /* Highlighted revisions */ + var highlighted_revisions = null; + /* Whether benchmark graph display was set up */ + var benchmark_graph_display_ready = false; + + + /* UTILITY FUNCTIONS */ + function arr_remove_from(a, x) { + var out = []; + $.each(a, function(i, val) { + if (x !== val) { + out.push(val); + } + }); + return out; + } + + function obj_copy(obj) { + var newobj = {}; + $.each(obj, function(key, val) { + newobj[key] = val; + }); + return newobj; + } + + function obj_length(obj) { + var i = 0; + for (var x in obj) + ++i; + return i; + } + + function obj_get_first_key(data) { + for (var prop in data) + return prop; + } + + function no_data(ajax, status, error) { + $("#error-message").text( + "No data for this combination of filters. "); + $("#error").modal('show'); + } + + function get_x_from_revision(rev) { + if (date_scale) { + return $.asv.main_json.revision_to_date[rev]; + } else { + return rev; + } + } + + function get_commit_hash(x) { + // Return the commit hash in the current graph located at position x + if (date_scale) { + x = date_to_revision[x]; + } + return $.asv.get_commit_hash(x); + } + + + function display_benchmark(bm_name, state_selection, highlight_revisions) { + setup_benchmark_graph_display(); + + $('#graph-display').show(); + $('#summarygrid-display').hide(); + $('#regressions-display').hide(); + $('.tooltip').remove(); + + if (reference_scale) { + reference_scale = false; + $('#reference').removeClass('active'); + reference = 1.0; + } + current_benchmark = bm_name; + highlighted_revisions = highlight_revisions; + $("#title").text(bm_name); + setup_benchmark_params(state_selection); + replace_graphs(); + } + + function setup_benchmark_graph_display() { + if (benchmark_graph_display_ready) { + return; + } + benchmark_graph_display_ready = true; + + /* When the window resizes, redraw the graphs */ + $(window).on('resize', function() { + update_graphs(); + }); + + var nav = $("#graphdisplay-navigation"); + + /* Make the static tooltips look correct */ + $('[data-toggle="tooltip"]').tooltip({container: 'body'}); + + /* Add insertion point for benchmark parameters */ + var state_params_nav = $(""); + nav.append(state_params_nav); + + /* Add insertion point for benchmark parameters */ + var bench_params_nav = $(""); + nav.append(bench_params_nav); + + /* Benchmark panel */ + var panel_body = $.asv.ui.make_panel(nav, 'benchmark'); + + var tree = $(''); + var cursor = []; + var stack = [tree]; + + /* Sort keys for tree construction */ + var benchmark_keys = Object.keys($.asv.main_json.benchmarks); + benchmark_keys.sort(); + + /* Build tree */ + $.each(benchmark_keys, function(i, bm_name) { + var bm = $.asv.main_json.benchmarks[bm_name]; + var parts = bm_name.split('.'); + var i = 0; + var j; + + for (; i < cursor.length; ++i) { + if (cursor[i] !== parts[i]) { + break; + } + } + + for (j = cursor.length - 1; j >= i; --j) { + stack.pop(); + cursor.pop(); + } + + for (j = i; j < parts.length - 1; ++j) { + var top = $( + ''); + + button.tooltip({ + title: details, + html: true, + placement: 'right', + container: 'body', + animation: false + }); + }); + + /* Generic parameter selectors */ + $.each(index.params, function(param, values) { + if (values.length > 1 && param != 'machine') { + $.asv.ui.make_value_selector_panel(nav, param, values, function(i, value, button) { + var value_display; + if (value === null) + value_display = '[none]'; + else if (!value) + value_display = '[default]'; + else + value_display = value; + + button.text(value_display); + + if ($.inArray(value, state[param]) == -1) { + button.removeClass('active'); + } + + if (values.length > 1) { + button.on('click', function(evt) { + if (!evt.target.classList.contains("active")) { + state[param].push(value); + } else { + state[param] = arr_remove_from( + state[param], value); + } + update_state_url(); + }); + } + }); + } + }); + } + + function replace_benchmark_params_ui() { + var params = $.asv.main_json.benchmarks[current_benchmark].params; + var param_names = $.asv.main_json.benchmarks[current_benchmark].param_names; + + /* Parameter selection UI */ + var nav = $('#graphdisplay-navigation-params'); + nav.empty(); + + if (params.length == 0) { + /* Simple time series: no need for parameter selection UI */ + $.asv.ui.reflow_value_selector_panels(); + return; + } + + /* x-axis selector */ + { + var axes = []; + for (var axis = 0; axis < params.length + 1; ++axis) { + axes.push(axis); + } + + $.asv.ui.make_value_selector_panel(nav, "x-axis", axes, function (idx, axis, button) { + var text; + if (axis == 0) { + text = "commit"; + } else { + text = param_names[axis - 1]; + } + if (x_coordinate_axis != axis) { + button.removeClass('active'); + } + button.text(text); + + button.on('click', function (evt) { + $(evt.target).siblings().removeClass('active'); + x_coordinate_axis = axis; + update_state_url({'x-axis': [text]}); + }); + }); + } + + /* Revision/commit value selector */ + if (x_coordinate_axis != 0) { + /* Generate list of all revisions */ + var revisions = current_revisions.slice(); + revisions.sort(); + revisions.push(null); + revisions.reverse(); + + /* Add buttons */ + $.asv.ui.make_value_selector_panel(nav, "commit", revisions, function(idx, rev, button) { + if (rev === null) { + button.text("last"); + } else { + var date_fmt = new Date($.asv.main_json.revision_to_date[rev]); + button.text($.asv.get_commit_hash(rev) + + " " + + date_fmt.toUTCString()); + } + + if ($.inArray(rev, benchmark_param_selection[0]) == -1) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + var idx = $.inArray(rev, benchmark_param_selection[0]); + if (!evt.target.classList.contains("active")) { + if (idx == -1) { + benchmark_param_selection[0].push(rev); + benchmark_param_selection[0].sort(); + } + } else { + if (idx != -1) { + benchmark_param_selection[0].splice(idx, 1); + } + } + replace_graphs(); + update_graphs(); + }); + }); + } + + /* Parameters axes value selector */ + $.each(params, function(param_idx, values) { + var axis = param_idx + 1; + + if (axis == x_coordinate_axis) { + return; + } + + name = param_names[param_idx]; + + /* Add benchmark parameter selector */ + $.asv.ui.make_value_selector_panel(nav, name, values, function(value_idx, value, button) { + var value_display; + value_display = '' + $.asv.convert_benchmark_param_value(value); + + button.text(value_display); + + if ($.inArray(value_idx, benchmark_param_selection[axis]) == -1) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + var new_selection = []; + var old_selection = benchmark_param_selection[param_idx+1]; + + if (!evt.target.classList.contains("active")) { + for (var k = 0; k < params[param_idx].length; ++k) { + if ($.inArray(k, old_selection) != -1 || k == value_idx) { + new_selection.push(k); + } + } + } else { + for (var k = 0; k < params[param_idx].length; ++k) { + if ($.inArray(k, old_selection) != -1 && k != value_idx) { + new_selection.push(k); + } + } + } + benchmark_param_selection[param_idx+1] = new_selection; + var new_selection_params = {}; + new_selection_params['p-'+param_names[param_idx]] = new_selection.map(function(k) { + return params[param_idx][k]; + }); + update_state_url(new_selection_params); + }); + }); + }); + + $.asv.ui.reflow_value_selector_panels(); + } + + /* Check if x-axis is a category axis */ + function check_x_coordinate_axis() { + if (!current_benchmark) { + return; + } + + var params = $.asv.main_json.benchmarks[current_benchmark].params; + x_coordinate_is_category = false; + if (x_coordinate_axis != 0) { + for (var j = 0; j < params[x_coordinate_axis-1].length; ++j) { + var value = $.asv.convert_benchmark_param_value(params[x_coordinate_axis-1][j]); + if (typeof value != "number") { + x_coordinate_is_category = true; + break; + } + } + } + } + + function replace_graphs() { + /* Given the settings in the sidebar, generate a list of the + graphs we need to load. */ + function collect_graphs(current_benchmark, state, param_selection) { + /* Given a specific group of parameters, generate the legend + label to display for that line. Differences is an object of + parameters that have different values across all graphs. */ + function graph_label(state, differences) { + var ignore = { + 'os': null, + 'cpu': null, + 'arch': null, + 'ram': null + }; + + var parts = []; + $.each(state, function(key, value) { + if (!ignore.hasOwnProperty(key) && + differences.hasOwnProperty(key)) { + if (value === null) { + // missing key, skip + } else if (value) { + parts.push(key + "-" + value); + } else { + parts.push(key); + } + } + }); + parts.sort(); + return parts.join('; '); + } + + /* For a given parameter matrix, generate all permutations. */ + function permutations(matrix) { + if (obj_length(matrix) === 0) { + return [{}]; + } + + matrix = obj_copy(matrix); + var key = obj_get_first_key(matrix); + var entry = matrix[key]; + delete matrix[key]; + + var results = []; + $.each(permutations(matrix), function(i, result) { + result = obj_copy(result); + if (entry.length) { + $.each(entry, function(i, value) { + result[key] = value; + results.push(obj_copy(result)); + }); + } else { + result[key] = null; + results.push(obj_copy(result)); + } + }); + + results.sort(); + return results; + } + + /* For all of the selected graphs, find out which parameters + have different values across them. We don't want to show + parameters that are the same across all graphs in the + legend labels, as that information is not really + necessary. */ + function find_different_properties(graphs) { + var different = {}; + var last_values = obj_copy(graphs[0]); + $.each(graphs, function(i, graph) { + $.each(graph, function(key, val) { + if (last_values[key] != val) { + different[key] = true; + } + }); + }); + return different; + } + + if (current_benchmark) { + /* For the current set of enabled parameters, generate a + list of all the permutations we need to load. */ + var state_permutations = $.grep($.asv.main_json.graph_param_list, function (params) { + var ok = true; + $.each(state, function (key, values) { + if ($.inArray(params[key], values) == -1) { + ok = false; + } + }); + return ok; + }); + + /* Find where the parameters are different. */ + var different = find_different_properties(state_permutations); + /* For parameterized tests: names of benchmark parameters */ + var params = $.asv.main_json.benchmarks[current_benchmark].params; + var param_names = $.asv.main_json.benchmarks[current_benchmark].param_names; + /* Selected permutations of benchmark parameters, omitting x-axis */ + var selection = obj_copy(param_selection); + selection[x_coordinate_axis] = [null]; /* value not referenced, set to null */ + var param_permutations = permutations(selection); + + /* Generate a main list of URLs and legend labels for + the graphs. */ + var all = []; + $.each(state_permutations, function (i, perm) { + var graph_contents = []; + $.each(param_permutations, function(k, param_perm) { + /* For each state value, there can be several + benchmark parameter sets to plot */ + var labels = obj_copy(perm); + for (var axis = 0; axis < params.length + 1; ++axis) { + if (axis != x_coordinate_axis) { + if (axis == 0) { + /* Add time/commit value to the labels */ + var timestamp = param_perm[axis]; + different["commit"] = true; + if (timestamp === null) { + labels["commit"] = "last"; + } + else { + labels["commit"] = ""+$.asv.get_commit_hash(timestamp); + } + } + else if (params[axis-1].length > 1) { + /* Add parameter value to the labels */ + if (param_perm[axis] === null) { + /* Empty permutation */ + return; + } + different[param_names[axis-1]] = true; + labels[param_names[axis-1]] = "" + $.asv.convert_benchmark_param_value(params[axis-1][param_perm[axis]]); + } + } + } + graph_contents.push([param_perm, + graph_label(labels, different)]); + }); + all.push([$.asv.graph_to_path(current_benchmark, perm), + graph_contents]); + }); + return all; + } else { + return []; + } + } + + /* Before loading graphs, remove any that are currently + active. */ + graphs = []; + orig_graphs = []; + + var to_load = collect_graphs(current_benchmark, state, benchmark_param_selection); + var failures = 0; + var count = 1; + + if (to_load.length === 0) { + $('#main-graph').html("
" +
+ "
")
+ return
+ }
+
+ current_revisions = [];
+ $.each(to_load, function(i, item) {
+ $.asv.load_graph_data(
+ item[0]
+ ).done(function (data) {
+ $.each(data, function(i, point) {
+ if (current_revisions.indexOf(point[0]) === -1) {
+ current_revisions.push(point[0]);
+ }
+ });
+ $.each(item[1], function(j, graph_content) {
+ var series;
+ series = $.asv.filter_graph_data(data,
+ x_coordinate_axis,
+ graph_content[0],
+ $.asv.main_json.benchmarks[current_benchmark].params);
+ orig_graphs.push({
+ data: series,
+ label: graph_content[1],
+ bars: { order: count, },
+ });
+ count += 1;
+ });
+ graphs = orig_graphs;
+ update_graphs();
+ }).fail(function () {
+ failures += 1;
+ if (failures == to_load.length) {
+ /* If we don't get any results, we check that the
+ webserver is still live by loading a file we know
+ we have. If that fails, too, then the webserver
+ is probably down. */
+ $.ajax({
+ url: "swallow.ico",
+ dataType: "text",
+ cache: false
+ }).done(function (index) {
+ update_graphs();
+ no_data();
+ }).fail(function () {
+ $.asv.ui.network_error();
+ });
+ }
+ });
+ });
+ }
+
+ /* Handle log scaling the plot */
+ function handle_y_scale(options) {
+ if (!graphs.length)
+ return;
+
+ /* Find the minimum and maximum values */
+ var min = Infinity;
+ var max = -Infinity;
+ var left = options.xaxis.min || 0;
+ var right = options.xaxis.max || Infinity;
+
+ $.each(graphs, function(i, graph) {
+ var data = graph.data;
+ var j = 0;
+ if (!x_coordinate_is_category) {
+ for (; j < data.length; ++j) {
+ var x = data[j][0];
+ if (x >= left) {
+ break;
+ }
+ }
+ }
+ for (; j < data.length; ++j) {
+ if (!x_coordinate_is_category) {
+ var x = data[j][0];
+ if (x >= right) {
+ break;
+ }
+ }
+ var p = data[j][1];
+ if (p !== null && (!log_scale || p > 0)) {
+ if (p < min) {
+ min = p;
+ }
+ if (p > max) {
+ max = p;
+ }
+ }
+ }
+ });
+
+ if (!isFinite(min) || !isFinite(max)) {
+ min = max = 1;
+ }
+
+ min /= reference;
+ max /= reference;
+
+ options.yaxis.min = min;
+ options.yaxis.max = max;
+
+ if (log_scale || reference_scale) {
+ min = Math.floor(Math.log(min) / Math.LN10);
+ max = Math.ceil(Math.log(max) / Math.LN10);
+
+ if (min == max) {
+ --min;
+ }
+ else if (reference_scale) {
+ // Don't allow the reference level to be at graph top/bottom,
+ // as this can look strange.
+ if (min == 0) {
+ --min;
+ }
+ if (max == 0) {
+ ++max;
+ }
+ }
+
+ var ticks = [];
+ for (var x = min; x <= max; ++x) {
+ ticks.push(Math.pow(10, x) * reference);
+ }
+
+ options.yaxis.ticks = ticks;
+ options.yaxis.transform = function(v) {
+ if (v <= 0) {
+ return null;
+ } else {
+ return Math.log(v / reference) / Math.LN10;
+ }
+ };
+ /* inverseTransform is required for plothover to work */
+ options.yaxis.inverseTransform = function (v) {
+ return Math.pow(10.0, v);
+ };
+ options.yaxis.tickDecimals = 3;
+ options.yaxis.tickFormatter = function (v, axis) {
+ return "10" + (
+ Math.round(
+ Math.log(v / reference) / Math.LN10)).toString().sup();
+ };
+ options.yaxis.min = Math.pow(10, min) * reference;
+ options.yaxis.max = Math.pow(10, max) * reference;
+
+ if (!reference_scale) {
+ options.yaxis.axisLabel = $.asv.main_json.benchmarks[current_benchmark].unit;
+ }
+ }
+ else {
+ var unit = $.asv.main_json.benchmarks[current_benchmark].unit;
+ var unit_list = null;
+
+ if (unit == "seconds") {
+ unit_list = $.asv.time_units;
+ }
+ else if (unit == "bytes") {
+ unit_list = $.asv.mem_units;
+ }
+
+ if (unit_list !== null) {
+ if (!zoom_y_axis) {
+ options.yaxis.min = 0.0;
+ options.yaxis.max = max * 1.3;
+ }
+
+ var unit_name = null;
+ var multiplier = null;
+ for (var i = 0; i < unit_list.length - 1; ++i) {
+ if (min < unit_list[i+1][2]) {
+ unit_name = unit_list[i][1];
+ multiplier = unit_list[i][2];
+ break;
+ }
+ }
+ }
+ else {
+ if (unit && unit != "unit") {
+ unit_name = unit;
+ }
+ multiplier = 1.0;
+ }
+
+ if (unit_name) {
+ options.yaxis.axisLabel = unit_name;
+ options.yaxis.tickFormatter = function (v, axis) {
+ return (v / multiplier).toPrecision(3);
+ }
+ }
+ }
+ }
+
+ function even_spacing_transform(value) {
+ /* Map timestamp value to commit index */
+ for (var i = 0; i < even_spacing_revisions.length; i++) {
+ if (value <= even_spacing_revisions[i]) {
+ return i;
+ }
+ }
+ }
+
+ function even_spacing_inverseTransform(value) {
+ /* Map commit index to timestamp value */
+ for (var i = 0; i < even_spacing_revisions.length; i++) {
+ if (value <= i) {
+ return even_spacing_revisions[i];
+ }
+ }
+ }
+
+ function handle_x_scale(options) {
+ if (!graphs.length)
+ return;
+
+ if (x_coordinate_axis == 0) {
+ if (!date_scale) {
+ // restore original graphs
+ graphs = orig_graphs;
+ options.xaxis.mode = null;
+ options.xaxis.axisLabel = 'commits';
+ options.xaxis.tickFormatter = function (v, axis) { return ""; };
+ }
+ if (even_spacing) {
+ even_spacing_revisions = [];
+ $.each(graphs, function(i, graph) {
+ var data = graph.data;
+ for (var j = 0; j < data.length; ++j) {
+ if (even_spacing_revisions.indexOf(data[j][0]) === -1) {
+ even_spacing_revisions.push(data[j][0]);
+ }
+ }
+ });
+ even_spacing_revisions.sort(function(a, b) { return a - b; });
+ options.xaxis.transform = even_spacing_transform;
+ /* inverseTransform is required for plothover to work */
+ options.xaxis.inverseTransform = even_spacing_inverseTransform;
+ } else if (date_scale) {
+ options.xaxis.mode = 'time';
+ options.xaxis.axisLabel = 'commit date';
+ options.xaxis.tickFormatter = null;
+
+ // deep copy graphs and transform into time series data
+ graphs = $.extend(true, [], orig_graphs);
+ date_to_revision = {};
+ $.each(graphs, function(i, graph) {
+ $.each(graph.data, function(j, point) {
+ var date = $.asv.main_json.revision_to_date[point[0]];
+ date_to_revision[date] = point[0];
+ point[0] = date;
+ });
+ graph.data.sort(function(a, b) { return a[0] - b[0]; });
+ });
+ }
+ } else {
+ if (x_coordinate_is_category) {
+ options.xaxis.mode = 'categories';
+ options.xaxis.tickLength = 0;
+ options.series = {
+ bars: {
+ show: true,
+ barWidth: 0.6 / graphs.length,
+ align: "center"
+ }
+ };
+
+ // deep copy graphs and html-escape x-labels
+ graphs = $.extend(true, [], orig_graphs);
+ $.each(graphs, function(i, graph) {
+ $.each(graph.data, function(j, point) {
+ point[0] = $("").text('' + point[0]).html();
+ });
+ });
+ }
+ else {
+ graphs = orig_graphs;
+ }
+ var param_names = $.asv.main_json.benchmarks[current_benchmark].param_names;
+ options.xaxis.axisLabel = param_names[x_coordinate_axis-1];
+ }
+ }
+
+ /* Once we have all of the graphs loaded, send them to flot for
+ drawing. */
+ function update_graphs() {
+ if (current_benchmark === null) {
+ return;
+ }
+
+ var markings = [];
+
+ if (x_coordinate_axis == 0) {
+ $.each($.asv.main_json.tags, function(tag, revision) {
+ var x = get_x_from_revision(revision);
+ markings.push(
+ { color: "#ddd", lineWidth: 1, xaxis: { from: x, to: x } }
+ );
+ });
+
+ if (highlighted_revisions) {
+ $.each(highlighted_revisions, function(i, revs) {
+ var x_values = [];
+ $.each(revs, function(i, rev) {
+ var x = get_x_from_revision(rev);
+ markings.push(
+ { color: '#d00', lineWidth: 2, xaxis: { from: x, to: x } }
+ );
+ x_values.push(x);
+ });
+ if (revs.length > 1) {
+ markings.push(
+ { color: "rgba(200, 0, 0, 0.2)", alpha: 0.5, lineWidth: 2,
+ xaxis: { from: Math.min.apply(null, x_values),
+ to: Math.max.apply(null, x_values) }}
+ );
+ }
+ });
+ }
+ }
+
+ var unit;
+ if (reference_scale) {
+ unit = 'relative';
+ } else {
+ unit = $.asv.main_json.benchmarks[current_benchmark].unit;
+ }
+
+ var options = {
+ colors: $.asv.colors,
+ series: {
+ lines: {
+ show: true,
+ lineWidth: 1
+ },
+ points: {
+ show: true
+ },
+ shadowSize: 0
+ },
+ grid: {
+ hoverable: true,
+ clickable: true,
+ markings: markings
+ },
+ xaxis: {
+ tickLength: 5,
+ axisLabel: "",
+ axisLabelUseCanvas: true,
+ axisLabelFontFamily: "sans-serif",
+ axisLabelFontSizePixels: 12
+ },
+ yaxis: {
+ axisLabel: "",
+ axisLabelUseCanvas: true,
+ axisLabelFontFamily: "sans-serif",
+ axisLabelFontSizePixels: 12
+ },
+ selection: {
+ mode: "x"
+ },
+ legend: {
+ show: show_legend,
+ position: "nw",
+ labelFormatter: function(label, series) {
+ // Ensure HTML escaping
+ return $("").text(label).html();
+ }
+ }
+ };
+
+ handle_x_scale(options);
+ handle_y_scale(options);
+
+ var graph_div = $('#main-graph');
+ var overview_div = $('#overview');
+
+ var plot = $.plot(graph_div, graphs, options);
+
+ /* Set up the "overview" plot */
+ var overview = null;
+
+ if (x_coordinate_axis != 0) {
+ /* Overview is useful mostly for the time axis */
+ overview_div.empty();
+ } else {
+ var overview_options = {
+ colors: $.asv.colors,
+ series: {
+ lines: {
+ show: true,
+ lineWidth: 1
+ },
+ shadowSize: 0
+ },
+ xaxis: {
+ ticks: [],
+ mode: "time"
+ },
+ yaxis: {
+ ticks: [],
+ min: 0,
+ autoscaleMargin: 0.1
+ },
+ selection: {
+ mode: "x"
+ },
+ legend: {
+ show: false
+ }
+ };
+ if (even_spacing) {
+ overview_options.xaxis.transform = even_spacing_transform;
+ overview_options.xaxis.inverseTransform = even_spacing_inverseTransform;
+ }
+ overview = $.plot(overview_div, graphs, overview_options);
+ }
+
+ graph_div.off("plotselected");
+ graph_div.on("plotselected", function (event, ranges) {
+ // do the zooming
+ var new_options = $.extend(true, {}, options, {
+ xaxis: {
+ min: ranges.xaxis.from,
+ max: ranges.xaxis.to
+ }
+ });
+
+ handle_y_scale(new_options);
+
+ plot = $.plot(graph_div, graphs, new_options);
+
+ // Update things that depend on the range
+ update_tags();
+ update_range();
+
+ // don't fire event on the overview to prevent eternal loop
+ if (overview) {
+ overview.setSelection(ranges, true);
+ }
+ });
+
+ overview_div.off("plotselected");
+ overview_div.on("plotselected", function (event, ranges) {
+ plot.setSelection(ranges);
+ // Update things that depend on the range
+ update_tags();
+ update_range();
+ });
+
+ function update_range() {
+ if (x_coordinate_axis != 0) {
+ /* Only applies when x-axis is the time axis */
+ return;
+ }
+
+ /* Find the minimum and maximum values */
+ var min = Infinity;
+ var left = plot.getAxes().xaxis.min;
+ $.each(graphs, function(i, graph) {
+ var data = graph.data;
+ for (var j = 0; j < data.length; ++j) {
+ var p = data[j][0];
+ if (p !== null && p >= left) {
+ if (p < min) {
+ min = p;
+ }
+ break;
+ }
+ }
+ });
+
+ var max = -Infinity;
+ var right = plot.getAxes().xaxis.max;
+ $.each(graphs, function(i, graph) {
+ var data = graph.data;
+ for (var j = data.length - 1; j >= 0; --j) {
+ var p = data[j][0];
+ if (p !== null && p <= right) {
+ if (p > max) {
+ max = p;
+ }
+ break;
+ }
+ }
+ });
+
+ var result;
+ if (min === null || max === null || min > max) {
+ result = '';
+ } else if (min == max) {
+ result = get_commit_hash(min) + '^!';
+ } else {
+ var first_commit = get_commit_hash(min);
+ var last_commit = get_commit_hash(max);
+ result = first_commit + ".." + last_commit;
+ }
+ $("#range")[0].value = result;
+ }
+
+ function update_tags() {
+ if (x_coordinate_axis != 0) {
+ /* Only applies when x-axis is the time axis */
+ return;
+ }
+
+ /* Add the tags as vertical grid lines */
+ var canvas = plot.getCanvas();
+ var xmin = plot.getAxes().xaxis.min;
+ var xmax = plot.getAxes().xaxis.max;
+ $.each($.asv.main_json.tags, function(tag, revision) {
+ var x = get_x_from_revision(revision);
+ if (x >= xmin && x <= xmax) {
+ var p = plot.pointOffset({x: x, y: 0});
+
+ graph_div.append(
+ "No graphs to load.
" + + "" + tag + "
");
+ }
+ });
+ }
+
+ update_tags();
+ update_range();
+ }
+
+
+ $.asv.register_page('graphdisplay', function(params) {
+ var benchmark = params['benchmark'];
+ var highlight_revisions = null;
+ var state_selection = null;
+
+ if (params['commits']) {
+ highlight_revisions = [];
+ $.each(params['commits'], function(i, value) {
+ var match = value.match(/^([a-z0-9]+)-([a-z0-9]+)$/);
+ if (match) {
+ highlight_revisions.push([$.asv.get_revision(match[1]), $.asv.get_revision(match[2])]);
+ }
+ else {
+ highlight_revisions.push([$.asv.get_revision(value)]);
+ }
+ });
+ delete params['commits'];
+ }
+
+ if (params['y-axis-scale']) {
+ if (params['y-axis-scale'][0] === 'log') {
+ $('#log-scale').addClass('active');
+ log_scale = true;
+ } else if (params['y-axis-scale'][0] === 'zoom') {
+ $('#zoom-y-axis').addClass('active');
+ zoom_y_axis = true;
+ }
+ delete params['y-axis-scale'];
+ }
+
+ if (params['x-axis-scale']) {
+ if (params['x-axis-scale'][0] === 'even') {
+ $('#even-spacing').addClass('active');
+ even_spacing = true;
+ } else if (params['x-axis-scale'][0] === 'date') {
+ $('#date-scale').addClass('active');
+ date_scale = true;
+ }
+ delete params['x-axis-scale'];
+ }
+
+ var show_legend_button = $('#show-legend')
+ if (params['show-legend']) {
+ if (params['show-legend'][0] === 'false') {
+ show_legend = false;
+ show_legend_button.removeClass('active');
+ }
+ else {
+ show_legend_button.addClass('active');
+ show_legend = true;
+ }
+ delete params['show-legend'];
+ }
+ else {
+ show_legend_button.addClass('active');
+ }
+
+ if (Object.keys(params).length > 0) {
+ state_selection = params;
+ }
+
+ display_benchmark(benchmark, state_selection, highlight_revisions);
+ });
+});
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_first.json
new file mode 100644
index 00000000..97e6d62b
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, [52920320.0, 54566912.0]], [1672, [52350976.0, 54599680.0]], [1687, [52109312.0, 54779904.0]], [1691, [52899840.0, 54730752.0]], [1709, [52936704.0, 55009280.0]], [1726, [52379648.0, 54992896.0]], [1766, [53084160.0, 55382016.0]], [1770, [53047296.0, 55373824.0]], [1776, [52490240.0, 55361536.0]], [1801, [53153792.0, 55410688.0]], [1937, [52957184.0, 55177216.0]], [1960, [52932608.0, 55693312.0]], [1996, [53096448.0, 55484416.0]], [2029, [52715520.0, 56090624.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_subsequent.json
new file mode 100644
index 00000000..a16e0075
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, [53800960.0, 54734848.0]], [1672, [52289536.0, 55099392.0]], [1687, [52142080.0, 55255040.0]], [1691, [53796864.0, 55238656.0]], [1709, [53768192.0, 55455744.0]], [1726, [51998720.0, 55451648.0]], [1766, [53739520.0, 55812096.0]], [1770, [53948416.0, 55824384.0]], [1776, [52097024.0, 55791616.0]], [1801, [53919744.0, 55799808.0]], [1937, [52822016.0, 56242176.0]], [1960, [53063680.0, 56180736.0]], [1996, [53018624.0, 56389632.0]], [2029, [52736000.0, 56791040.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_first.json
new file mode 100644
index 00000000..6f16f68b
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, [44191744.0, 44191744.0]], [1672, [44056576.0, 44048384.0]], [1687, [44191744.0, 44310528.0]], [1691, [44183552.0, 44175360.0]], [1709, [44191744.0, 44314624.0]], [1726, [44195840.0, 44314624.0]], [1766, [44322816.0, 44314624.0]], [1770, [44326912.0, 44322816.0]], [1776, [44183552.0, 44306432.0]], [1801, [44195840.0, 44453888.0]], [1937, [44756992.0, 44744704.0]], [1960, [44716032.0, 44834816.0]], [1996, [44716032.0, 44969984.0]], [2029, [44871680.0, 44912640.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_subsequent.json
new file mode 100644
index 00000000..76bd2928
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.peakmem_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, [44195840.0, 44187648.0]], [1672, [44060672.0, 43917312.0]], [1687, [44105728.0, 44310528.0]], [1691, [44187648.0, 44183552.0]], [1709, [44191744.0, 44437504.0]], [1726, [44322816.0, 44314624.0]], [1766, [44322816.0, 44310528.0]], [1770, [44101632.0, 44310528.0]], [1776, [44314624.0, 44437504.0]], [1801, [44191744.0, 44453888.0]], [1937, [44527616.0, 44744704.0]], [1960, [44716032.0, 44838912.0]], [1996, [44724224.0, 44969984.0]], [2029, [44617728.0, 44986368.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_first.json
new file mode 100644
index 00000000..e53588c7
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, [0.06960565700001098, 0.25608221199996706]], [1672, [0.07114163800000028, 0.26389872900000455]], [1687, [0.06910802600003763, 0.25746033199999374]], [1691, [0.07048037500001669, 0.2598985070000026]], [1709, [0.07402671400001282, 0.26584690599997884]], [1726, [0.07297276199997782, 0.2569234329999972]], [1766, [0.07308550800001967, 0.26274096600002395]], [1770, [0.0749189080000292, 0.26436952000000247]], [1776, [0.07303507899999317, 0.2628890319999755]], [1801, [0.07360306399999672, 0.2678246009999725]], [1937, [0.07941284200001064, 0.26779402600004687]], [1960, [0.08026317200000221, 0.26819844099998136]], [1996, [0.0814841690000776, 0.28364495499999975]], [2029, [0.08105427499998541, 0.29477426600001877]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_subsequent.json
new file mode 100644
index 00000000..72d384fe
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, [0.03327357099999517, 0.1421111020000012]], [1672, [0.033918617999972867, 0.14395761299999776]], [1687, [0.03317536700001256, 0.14245594600001255]], [1691, [0.034316510999985894, 0.1444248799999741]], [1709, [0.03742426899998463, 0.14901454800002512]], [1726, [0.03658580800001232, 0.1459621130000528]], [1766, [0.03723830100000214, 0.15196534300002895]], [1770, [0.03752758399997447, 0.15356457899997622]], [1776, [0.03678920999999491, 0.14955294699998944]], [1801, [0.037022983000014165, 0.15138703899998518]], [1937, [0.043317416999911984, 0.15457556900003055]], [1960, [0.04349111400000538, 0.15453611999998884]], [1996, [0.04362213900003553, 0.16551773399999092]], [2029, [0.043648402000002307, 0.17461173199995983]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_first.json
new file mode 100644
index 00000000..ffd21cc0
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, [0.0035443229999998493, 0.00467639600003622]], [1672, [0.0036137869999777195, 0.004807943000002979]], [1687, [0.0035223549999727766, 0.004706463999980315]], [1691, [0.00364059099999281, 0.004926952999994683]], [1709, [0.003602947999979733, 0.004853936999950292]], [1726, [0.0035008030000085455, 0.004695608999981005]], [1766, [0.003566315000000486, 0.004791812000007667]], [1770, [0.0036766670000361046, 0.004929383999979109]], [1776, [0.0035613420000117912, 0.004760385999986738]], [1801, [0.003639607999986083, 0.004848561000017071]], [1937, [0.0036632869999948525, 0.00493345400002454]], [1960, [0.0036145729999930154, 0.004811176000004025]], [1996, [0.00375721499995052, 0.0049729269999261305]], [2029, [0.0037106409999978496, 0.004899473999955717]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_subsequent.json
new file mode 100644
index 00000000..7e2dcfd6
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, [0.00010400499999718704, 0.0005328339999977061]], [1672, [0.00010086800000408402, 0.0005549249999887707]], [1687, [9.818199998790078e-05, 0.0005511469999817109]], [1691, [0.0001005780000014056, 0.0005555879999974422]], [1709, [0.00012266099997759738, 0.0005711430000019391]], [1726, [0.00011641800000461444, 0.0005489540000098714]], [1766, [0.00011609900002440554, 0.0005779780000239043]], [1770, [0.0001176700000087294, 0.0005864990000077341]], [1776, [0.00011622699999236374, 0.0005842630000074678]], [1801, [0.00011665800002447213, 0.000582710000003317]], [1937, [0.00012153600005149201, 0.0005999570000199128]], [1960, [0.00012332000000014887, 0.0005915369999911491]], [1996, [0.00012686900004155177, 0.0006182140000419167]], [2029, [0.00012706900002967814, 0.0006100459999629493]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_startup_lg.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_startup_lg.json
new file mode 100644
index 00000000..028b02cc
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Components vs Django.timeraw_startup_lg.json
@@ -0,0 +1 @@
+[[1662, [0.21775109000003567, 0.21398552899995593]], [1672, [0.22476057199997967, 0.22048105400000395]], [1687, [0.21809406599999193, 0.2131839880000257]], [1691, [0.22356123500000535, 0.22167734499998915]], [1709, [0.22133603999998286, 0.21805855799999563]], [1726, [0.2166100470000174, 0.21420494400001644]], [1766, [0.22339861599999722, 0.22020213500002228]], [1770, [0.22985272800002576, 0.22544496099999378]], [1776, [0.22073260000001937, 0.2182690520000392]], [1801, [0.224061646999985, 0.2246476189999953]], [1937, [0.22743783699991127, 0.226070988999993]], [1960, [0.2252378419999843, 0.2247263650000093]], [1996, [0.23076480500003527, 0.23163660399995933]], [2029, [0.22799248500001568, 0.22723498599998493]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Other.timeraw_import_time.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Other.timeraw_import_time.json
new file mode 100644
index 00000000..eb01068a
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/Other.timeraw_import_time.json
@@ -0,0 +1 @@
+[[1662, 0.19832900800003017], [1672, 0.20217585500000723], [1687, 0.19726691500000015], [1691, 0.20350580199999513], [1709, 0.19950735400001918], [1726, 0.19625152499997967], [1766, 0.20073733000003813], [1770, 0.20376683500001036], [1776, 0.19919827600000417], [1801, 0.2053688209999791], [1937, 0.2063091950000171], [1960, 0.20468290799999522], [1996, 0.21042045099989082], [2029, 0.2056691309999792]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_first.json
new file mode 100644
index 00000000..e5e24d49
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, [54439936.0, 53968896.0]], [1672, [54616064.0, 54140928.0]], [1687, [54767616.0, 54296576.0]], [1691, [54743040.0, 54087680.0]], [1709, [55001088.0, 54312960.0]], [1726, [54992896.0, 54345728.0]], [1766, [55373824.0, 54894592.0]], [1770, [55246848.0, 54898688.0]], [1776, [55357440.0, 54874112.0]], [1801, [55382016.0, 54882304.0]], [1937, [55222272.0, 54722560.0]], [1960, [55263232.0, 54693888.0]], [1996, [55476224.0, 54968320.0]], [2029, [56090624.0, 55582720.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_subsequent.json
new file mode 100644
index 00000000..0606c7d9
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, [54968320.0, 54792192.0]], [1672, [54849536.0, 54841344.0]], [1687, [55271424.0, 55304192.0]], [1691, [54984704.0, 54964224.0]], [1709, [55439360.0, 55369728.0]], [1726, [55455744.0, 55177216.0]], [1766, [55545856.0, 55631872.0]], [1770, [55812096.0, 55611392.0]], [1776, [55640064.0, 55631872.0]], [1801, [55812096.0, 55902208.0]], [1937, [56008704.0, 56143872.0]], [1960, [55783424.0, 56160256.0]], [1996, [56352768.0, 56516608.0]], [2029, [56786944.0, 56778752.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_first.json
new file mode 100644
index 00000000..bdcfccea
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, [44187648.0, 44183552.0]], [1672, [44048384.0, 44048384.0]], [1687, [44314624.0, 44310528.0]], [1691, [44179456.0, 44175360.0]], [1709, [44314624.0, 44310528.0]], [1726, [44314624.0, 44314624.0]], [1766, [44318720.0, 44314624.0]], [1770, [44322816.0, 44314624.0]], [1776, [44306432.0, 44240896.0]], [1801, [44453888.0, 44453888.0]], [1937, [44744704.0, 44744704.0]], [1960, [44838912.0, 44838912.0]], [1996, [44969984.0, 44969984.0]], [2029, [44843008.0, 44851200.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_subsequent.json
new file mode 100644
index 00000000..e93df054
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.peakmem_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, [44187648.0, 44187648.0]], [1672, [44052480.0, 44052480.0]], [1687, [44314624.0, 44310528.0]], [1691, [44179456.0, 44179456.0]], [1709, [44310528.0, 44314624.0]], [1726, [44314624.0, 44314624.0]], [1766, [44310528.0, 44314624.0]], [1770, [44314624.0, 44318720.0]], [1776, [44437504.0, 44437504.0]], [1801, [44449792.0, 44449792.0]], [1937, [44744704.0, 44744704.0]], [1960, [44965888.0, 44834816.0]], [1996, [44974080.0, 44974080.0]], [2029, [44982272.0, 44986368.0]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_first.json
new file mode 100644
index 00000000..47b453a9
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, [0.2574955810000006, 0.2591010970000127]], [1672, [0.2600247560000071, 0.26185358800000813]], [1687, [0.2567828300000201, 0.2602957870000182]], [1691, [0.259077934000004, 0.2619792840000059]], [1709, [0.2646600410000133, 0.2676605120000204]], [1726, [0.2570519909999689, 0.2606809000000112]], [1766, [0.262679922000018, 0.2686107789999994]], [1770, [0.265977821000007, 0.26914772099999595]], [1776, [0.2626667089999728, 0.2663110299999971]], [1801, [0.2658582709999848, 0.2712929850000023]], [1937, [0.2675778039999841, 0.2724974679999832]], [1960, [0.26819597400000816, 0.2740507329999957]], [1996, [0.2794132599999557, 0.28440619299999526]], [2029, [0.2920349000000044, 0.2976166970000236]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_subsequent.json
new file mode 100644
index 00000000..2c7b894a
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, [0.14273938200000202, 0.1464969190000147]], [1672, [0.14515931700000806, 0.14909453600000688]], [1687, [0.1423055980000072, 0.14642362500001127]], [1691, [0.1436571560000175, 0.14915657599999577]], [1709, [0.14860135300000366, 0.15305296299999327]], [1726, [0.14520097999997006, 0.14991973799999414]], [1766, [0.15071133700001837, 0.15540660900001058]], [1770, [0.15150350199996865, 0.1558047899999906]], [1776, [0.14876902899999322, 0.15549233400000162]], [1801, [0.15248822700002052, 0.15465820200000735]], [1937, [0.15459265900005903, 0.15926110200007315]], [1960, [0.15396625699997912, 0.16023626799997714]], [1996, [0.16650312799993117, 0.17177308600003016]], [2029, [0.17414895399997476, 0.178393189000019]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_first.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_first.json
new file mode 100644
index 00000000..36aecfd8
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, [0.004720848000005162, 0.004705489000002672]], [1672, [0.004856270999994194, 0.00490694800001279]], [1687, [0.00473016699999107, 0.004734037999980956]], [1691, [0.004871503999993365, 0.0048899079999955575]], [1709, [0.0048215560000244295, 0.004858458999990489]], [1726, [0.004671787999996013, 0.004672599999992144]], [1766, [0.00478528000002143, 0.0047485900000197034]], [1770, [0.004901490999998259, 0.004895917999988342]], [1776, [0.00480728600001612, 0.00472804499997892]], [1801, [0.004847185000016907, 0.004857667999999649]], [1937, [0.004923484000073586, 0.004925836999973399]], [1960, [0.004825538000005736, 0.0047952310000027865]], [1996, [0.005049280000093859, 0.004947880000145233]], [2029, [0.004897051999989799, 0.004863266000029398]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_subsequent.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_subsequent.json
new file mode 100644
index 00000000..a12a8dd8
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, [0.0005377129999999397, 0.0005395769999836375]], [1672, [0.000547750000009728, 0.0005677989999810507]], [1687, [0.0005471899999918151, 0.0005447550000212686]], [1691, [0.0005559489999882317, 0.0005480739999939033]], [1709, [0.0005736080000247057, 0.0005720849999875099]], [1726, [0.000542692999999872, 0.0005430530000012368]], [1766, [0.0005853119999983392, 0.000582014999963576]], [1770, [0.0005929909999622396, 0.000583071999983531]], [1776, [0.0005810670000130358, 0.000576186999978745]], [1801, [0.0005717709999828458, 0.0005785939999896073]], [1937, [0.0005969709999362749, 0.0005864510000037626]], [1960, [0.0005953940000154034, 0.0005933700000468889]], [1996, [0.0006160310000495883, 0.0006166809999967882]], [2029, [0.0006159270000125616, 0.0006080119999865019]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_startup_lg.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_startup_lg.json
new file mode 100644
index 00000000..520c7cbf
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/isolated vs django modes.timeraw_startup_lg.json
@@ -0,0 +1 @@
+[[1662, [0.21402431699999624, 0.21364062999998623]], [1672, [0.2221746719999942, 0.2222580240000127]], [1687, [0.2142312400000037, 0.21397752699999728]], [1691, [0.22129613300000983, 0.21942976399998315]], [1709, [0.2199001029999863, 0.22046102699999892]], [1726, [0.2147675530000015, 0.21506381099999317]], [1766, [0.22056839900000114, 0.21916191200000412]], [1770, [0.22394285699999728, 0.22330144500000415]], [1776, [0.21867883100003382, 0.21859779499999377]], [1801, [0.22378945699995256, 0.22211803700002974]], [1937, [0.22545313400001987, 0.22602228000005198]], [1960, [0.22564571399999522, 0.22598634599995648]], [1996, [0.2295973340000046, 0.23030742100002044]], [2029, [0.22777395400004252, 0.2292747939999913]]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/summary.json b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/summary.json
new file mode 100644
index 00000000..5cfe9e2e
--- /dev/null
+++ b/docs/benchmarks/graphs/branch-master/django-5.1/djc-core-html-parser/machine-ci-linux/python-3.13/summary.json
@@ -0,0 +1 @@
+[{"name": "Components vs Django.peakmem_render_lg_first", "idx": 0, "pretty_name": "render - large - first render (mem)('django')", "last_rev": 2029, "last_value": 52926464.0, "last_err": 238738.2857142857, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_lg_first", "idx": 1, "pretty_name": "render - large - first render (mem)('django-components')", "last_rev": 2029, "last_value": 55269376.0, "last_err": 352841.14285714284, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_lg_subsequent", "idx": 0, "pretty_name": "render - large - second render (mem)('django')", "last_rev": 2029, "last_value": 53041152.0, "last_err": 638098.2857142857, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_lg_subsequent", "idx": 1, "pretty_name": "render - large - second render (mem)('django-components')", "last_rev": 2029, "last_value": 55795712.0, "last_err": 429494.85714285716, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_sm_first", "idx": 0, "pretty_name": "render - small - first render (mem)('django')", "last_rev": 2029, "last_value": 44195840.0, "last_err": 193682.2857142857, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_sm_first", "idx": 1, "pretty_name": "render - small - first render (mem)('django-components')", "last_rev": 2029, "last_value": 44314624.0, "last_err": 206555.42857142858, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_sm_subsequent", "idx": 0, "pretty_name": "render - small - second render (mem)('django')", "last_rev": 2029, "last_value": 44255232.0, "last_err": 179346.2857142857, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.peakmem_render_sm_subsequent", "idx": 1, "pretty_name": "render - small - second render (mem)('django-components')", "last_rev": 2029, "last_value": 44376064.0, "last_err": 238153.14285714287, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_lg_first", "idx": 0, "pretty_name": "render - large - first render('django')", "last_rev": 2029, "last_value": 0.07308550800001967, "last_err": 0.002970056988688463, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_lg_first", "idx": 1, "pretty_name": "render - large - first render('django-components')", "last_rev": 2029, "last_value": 0.26436952000000247, "last_err": 0.005644097774403133, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_lg_subsequent", "idx": 0, "pretty_name": "render - large - second render('django')", "last_rev": 2029, "last_value": 0.04362213900003553, "last_err": 0.00010141391999156615, "prev_value": 0.03723830100000214, "change_rev": [1801, 1937]}, {"name": "Components vs Django.timeraw_render_lg_subsequent", "idx": 1, "pretty_name": "render - large - second render('django-components')", "last_rev": 2029, "last_value": 0.15138703899998518, "last_err": 0.006705386360797588, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_sm_first", "idx": 0, "pretty_name": "render - small - first render('django')", "last_rev": 2029, "last_value": 0.003602947999979733, "last_err": 5.419141048740966e-05, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_sm_first", "idx": 1, "pretty_name": "render - small - first render('django-components')", "last_rev": 2029, "last_value": 0.004811176000004025, "last_err": 7.476107336392598e-05, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_sm_subsequent", "idx": 0, "pretty_name": "render - small - second render('django')", "last_rev": 2029, "last_value": 0.00011641800000461444, "last_err": 6.71568788300834e-06, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_render_sm_subsequent", "idx": 1, "pretty_name": "render - small - second render('django-components')", "last_rev": 2029, "last_value": 0.0005711430000019391, "last_err": 2.3656907602254418e-05, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_startup_lg", "idx": 0, "pretty_name": "startup - large('django')", "last_rev": 2029, "last_value": 0.22356123500000535, "last_err": 0.003663370721264278, "prev_value": null, "change_rev": null}, {"name": "Components vs Django.timeraw_startup_lg", "idx": 1, "pretty_name": "startup - large('django-components')", "last_rev": 2029, "last_value": 0.22048105400000395, "last_err": 0.005292030830577897, "prev_value": null, "change_rev": null}, {"name": "Other.timeraw_import_time", "idx": null, "pretty_name": "import time", "last_rev": 2029, "last_value": 0.19919827600000417, "last_err": 0.0040859881894921846, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_lg_first", "idx": 0, "pretty_name": "render - large - first render (mem)('isolated')", "last_rev": 2029, "last_value": 55234560.0, "last_err": 314806.85714285716, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_lg_first", "idx": 1, "pretty_name": "render - large - first render (mem)('django')", "last_rev": 2029, "last_value": 54708224.0, "last_err": 355474.28571428574, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_lg_subsequent", "idx": 0, "pretty_name": "render - large - second render (mem)('isolated')", "last_rev": 2029, "last_value": 55592960.0, "last_err": 405796.5714285714, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_lg_subsequent", "idx": 1, "pretty_name": "render - large - second render (mem)('django')", "last_rev": 2029, "last_value": 55621632.0, "last_err": 478939.4285714286, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_sm_first", "idx": 0, "pretty_name": "render - small - first render (mem)('isolated')", "last_rev": 2029, "last_value": 44316672.0, "last_err": 201874.2857142857, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_sm_first", "idx": 1, "pretty_name": "render - small - first render (mem)('django')", "last_rev": 2029, "last_value": 44314624.0, "last_err": 207433.14285714287, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_sm_subsequent", "idx": 0, "pretty_name": "render - small - second render (mem)('isolated')", "last_rev": 2029, "last_value": 44314624.0, "last_err": 228498.2857142857, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.peakmem_render_sm_subsequent", "idx": 1, "pretty_name": "render - small - second render (mem)('django')", "last_rev": 2029, "last_value": 44316672.0, "last_err": 219428.57142857142, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_lg_first", "idx": 0, "pretty_name": "render - large - first render('isolated')", "last_rev": 2029, "last_value": 0.2646600410000133, "last_err": 0.007677844017113229, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_lg_first", "idx": 1, "pretty_name": "render - large - first render('django')", "last_rev": 2029, "last_value": 0.2676605120000204, "last_err": 0.00784939843762128, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_lg_subsequent", "idx": 0, "pretty_name": "render - large - second render('isolated')", "last_rev": 2029, "last_value": 0.15071133700001837, "last_err": 0.006184059019873227, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_lg_subsequent", "idx": 1, "pretty_name": "render - large - second render('django')", "last_rev": 2029, "last_value": 0.15540660900001058, "last_err": 0.009898742429098032, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_sm_first", "idx": 0, "pretty_name": "render - small - first render('isolated')", "last_rev": 2029, "last_value": 0.004825538000005736, "last_err": 5.909934210844408e-05, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_sm_first", "idx": 1, "pretty_name": "render - small - first render('django')", "last_rev": 2029, "last_value": 0.0047952310000027865, "last_err": 7.102011245001072e-05, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_sm_subsequent", "idx": 0, "pretty_name": "render - small - second render('isolated')", "last_rev": 2029, "last_value": 0.0005736080000247057, "last_err": 2.103986485491359e-05, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_render_sm_subsequent", "idx": 1, "pretty_name": "render - small - second render('django')", "last_rev": 2029, "last_value": 0.000582014999963576, "last_err": 1.7671096085730627e-05, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_startup_lg", "idx": 0, "pretty_name": "startup - large('isolated')", "last_rev": 2029, "last_value": 0.22129613300000983, "last_err": 0.003939909589791106, "prev_value": null, "change_rev": null}, {"name": "isolated vs django modes.timeraw_startup_lg", "idx": 1, "pretty_name": "startup - large('django')", "last_rev": 2029, "last_value": 0.21916191200000412, "last_err": 0.00459183551388232, "prev_value": null, "change_rev": null}]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_first.json b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_first.json
new file mode 100644
index 00000000..9b9d166a
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, 53737309.613078326], [1672, 53463506.59363525], [1687, 53427924.42970294], [1691, 53807508.99158667], [1709, 53963042.655257314], [1726, 53670369.245800875], [1766, 54220916.6140389], [1770, 54198077.75539557], [1776, 53906774.26269022], [1801, 54270509.344660625], [1937, 54055804.31664803], [1960, 54295416.494559616], [1996, 54277301.04707094], [2029, 54376892.25474807]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_subsequent.json b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_subsequent.json
new file mode 100644
index 00000000..16c667e1
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, 54265895.0709751], [1672, 53676080.7209516], [1687, 53675997.57883592], [1691, 54512993.537089705], [1709, 54605449.27839023], [1726, 53697436.790693834], [1766, 54766004.5031032], [1770, 54878384.55144014], [1776, 53912680.86221259], [1801, 54851721.60114168], [1937, 54505276.07990639], [1960, 54599968.83944605], [1996, 54678155.56971878], [2029, 54725974.50425164]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_first.json b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_first.json
new file mode 100644
index 00000000..b5b77f9d
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, 44191743.99999999], [1672, 44052479.80957694], [1687, 44251096.14326895], [1691, 44179455.81012423], [1709, 44253141.3491094], [1726, 44255192.14695785], [1766, 44318719.81072088], [1770, 44324863.95268679], [1776, 44244949.34121254], [1801, 44324676.21343578], [1937, 44750847.578234404], [1960, 44775384.609963], [1996, 44842828.229087956], [2029, 44892155.328466915]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_subsequent.json b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_subsequent.json
new file mode 100644
index 00000000..764451a5
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.peakmem_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, 44191743.81017703], [1672, 43988933.59873213], [1687, 44208009.40445502], [1691, 44185599.95253766], [1709, 44314453.63272547], [1726, 44318719.81072088], [1766, 44316671.57410231], [1770, 44205956.60747199], [1776, 44376021.4672124], [1801, 44322622.19567646], [1937, 44636028.0238471], [1960, 44777429.84849827], [1996, 44846935.655543014], [2029, 44801668.84315699]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_first.json b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_first.json
new file mode 100644
index 00000000..d7a7b9c6
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, 0.13350944016163727], [1672, 0.1370189324406613], [1687, 0.13338881256624893], [1691, 0.13534306127506], [1709, 0.14028461383291016], [1726, 0.1369248426273554], [1766, 0.13857329097819557], [1770, 0.14073477092350728], [1776, 0.1385645020210802], [1801, 0.14040196312080028], [1937, 0.14582964264952603], [1960, 0.14671897491501892], [1996, 0.15202819951982394], [2029, 0.15457268328939747]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_subsequent.json b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_subsequent.json
new file mode 100644
index 00000000..807386ec
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, 0.0687644082522681], [1672, 0.06987734456556612], [1687, 0.06874611472573841], [1691, 0.07039998567606925], [1709, 0.07467771106069107], [1726, 0.07307627413528986], [1766, 0.0752258677863117], [1770, 0.07591381717343901], [1776, 0.0741750279629251], [1801, 0.07486521068773488], [1937, 0.08182795598310513], [1960, 0.08198138820511656], [1996, 0.08497198126158123], [2029, 0.08730133488241124]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_first.json b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_first.json
new file mode 100644
index 00000000..bd943ad3
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, 0.004071198582731586], [1672, 0.004168318834979474], [1687, 0.004071589002161507], [1691, 0.004235212007582172], [1709, 0.004181923314217816], [1726, 0.004054429932062044], [1766, 0.004133897799028137], [1770, 0.004257194320585938], [1776, 0.004117446125697445], [1801, 0.004200816754404154], [1937, 0.004251194879485355], [1960, 0.0041701734817425696], [1996, 0.004322540447211732], [2029, 0.004263823296369016]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_subsequent.json b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_subsequent.json
new file mode 100644
index 00000000..8d882c01
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, 0.00023540900613243872], [1672, 0.0002365886195511814], [1687, 0.0002326213978668684], [1691, 0.0002363893607261623], [1709, 0.0002646827752432008], [1726, 0.00025280056719810247], [1766, 0.00025904182642747317], [1770, 0.0002627038966898471], [1776, 0.00026058997620285855], [1801, 0.000260725493948419], [1937, 0.0002700303204925571], [1960, 0.00027008950893915996], [1996, 0.0002800574798090668], [2029, 0.000278420428825539]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Components vs Django.timeraw_startup_lg.json b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_startup_lg.json
new file mode 100644
index 00000000..a58dd726
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Components vs Django.timeraw_startup_lg.json
@@ -0,0 +1 @@
+[[1662, 0.21586009863792485], [1672, 0.22261052942796597], [1687, 0.21562505130206716], [1691, 0.2226172972159168], [1709, 0.21969118716012626], [1726, 0.21540413874268913], [1766, 0.2217946171557135], [1770, 0.22763817627917332], [1776, 0.21949736979633283], [1801, 0.22435444169386096], [1937, 0.22675338309844276], [1960, 0.22498195815021013], [1996, 0.23120029358312028], [2029, 0.22761342037999505]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/Other.timeraw_import_time.json b/docs/benchmarks/graphs/summary/Other.timeraw_import_time.json
new file mode 100644
index 00000000..eb01068a
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/Other.timeraw_import_time.json
@@ -0,0 +1 @@
+[[1662, 0.19832900800003017], [1672, 0.20217585500000723], [1687, 0.19726691500000015], [1691, 0.20350580199999513], [1709, 0.19950735400001918], [1726, 0.19625152499997967], [1766, 0.20073733000003813], [1770, 0.20376683500001036], [1776, 0.19919827600000417], [1801, 0.2053688209999791], [1937, 0.2063091950000171], [1960, 0.20468290799999522], [1996, 0.21042045099989082], [2029, 0.2056691309999792]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_first.json b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_first.json
new file mode 100644
index 00000000..4429f303
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, 54203904.32644733], [1672, 54377977.05567385], [1687, 54531587.401090905], [1691, 54414373.37457081], [1709, 54655941.05401974], [1726, 54668354.35558938], [1766, 55133687.30603648], [1770, 55072492.873806104], [1776, 55115246.19008138], [1801, 55131593.83007953], [1937, 54971848.18483294], [1960, 54977822.99733244], [1996, 55221688.06930552], [2029, 55836094.494666085]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_subsequent.json b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_subsequent.json
new file mode 100644
index 00000000..bed4ea23
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, 54880185.34368702], [1672, 54845439.84705003], [1687, 55287805.57238104], [1691, 54974463.04630629], [1709, 55404533.06087942], [1726, 55316304.695168346], [1766, 55588847.36277981], [1770, 55711653.6193069], [1776, 55635967.849223286], [1801, 55857133.82825839], [1937, 56076247.273349956], [1960, 55971522.87008585], [1996, 56434628.542863145], [2029, 56782847.85226863]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_first.json b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_first.json
new file mode 100644
index 00000000..d6903d84
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, 44185599.95253766], [1672, 44048383.99999999], [1687, 44312575.95267366], [1691, 44177407.95252886], [1709, 44312575.95267366], [1726, 44314624.0], [1766, 44316671.95267803], [1770, 44318719.81072088], [1776, 44273651.87380721], [1801, 44453888.0], [1937, 44744704.0], [1960, 44838912.00000001], [1996, 44969983.99999999], [2029, 44847103.812950954]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_subsequent.json b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_subsequent.json
new file mode 100644
index 00000000..1f44ef9f
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.peakmem_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, 44187648.0], [1672, 44052479.99999999], [1687, 44312575.95267366], [1691, 44179455.99999999], [1709, 44312575.95267366], [1726, 44314624.0], [1766, 44312575.95267366], [1770, 44316671.95267803], [1776, 44437504.0], [1801, 44449792.0], [1937, 44744704.0], [1960, 44900304.17220587], [1996, 44974080.0], [2029, 44984319.953380376]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_first.json b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_first.json
new file mode 100644
index 00000000..58c7bd0b
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_first.json
@@ -0,0 +1 @@
+[[1662, 0.2582970915627115], [1672, 0.2609375697890752], [1687, 0.2585333418012986], [1691, 0.2605245701455466], [1709, 0.26615604836262874], [1726, 0.25886008645727265], [1766, 0.2656287982807661], [1770, 0.2675580766089799], [1776, 0.2644825926606367], [1801, 0.26856188100049755], [1937, 0.2700264321932048], [1960, 0.2711075492537049], [1996, 0.28189867248766043], [2029, 0.29481258851469266]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_subsequent.json b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_subsequent.json
new file mode 100644
index 00000000..56f4bd5d
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_lg_subsequent.json
@@ -0,0 +1 @@
+[[1662, 0.144605946222714], [1672, 0.14711376894836906], [1687, 0.14434992731884352], [1691, 0.14638104217028877], [1709, 0.1508107336447194], [1726, 0.14754149544768042], [1766, 0.15304096778650703], [1770, 0.1536390943522132], [1776, 0.15209353551720362], [1801, 0.15356938175949056], [1937, 0.15690951925702573], [1960, 0.15706997937098616], [1996, 0.16911758076913888], [2029, 0.17625829701058932]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_first.json b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_first.json
new file mode 100644
index 00000000..5ba7c936
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_first.json
@@ -0,0 +1 @@
+[[1662, 0.004713162243622524], [1672, 0.004881543738505435], [1687, 0.004732102104161917], [1691, 0.00488069732533968], [1709, 0.004839972328668506], [1726, 0.004672193982353972], [1766, 0.004766899700580667], [1770, 0.004898703707479391], [1776, 0.004767500868992566], [1801, 0.004852423669122516], [1937, 0.004924660359490744], [1960, 0.004810360631940079], [1996, 0.004998322871483767], [2029, 0.004880129761791827]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_subsequent.json b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_subsequent.json
new file mode 100644
index 00000000..dec783d0
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_render_sm_subsequent.json
@@ -0,0 +1 @@
+[[1662, 0.0005386441936864901], [1672, 0.0005576844109755481], [1687, 0.0005459711425132094], [1691, 0.0005519974567116778], [1709, 0.0005728459938648165], [1726, 0.0005428729701593198], [1766, 0.0005836611719634209], [1770, 0.0005880105852110292], [1776, 0.0005786218553806627], [1801, 0.0005751723828193878], [1937, 0.0005916876201898046], [1960, 0.000594381138510516], [1996, 0.0006163559143381376], [2029, 0.0006119567036345985]]
\ No newline at end of file
diff --git a/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_startup_lg.json b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_startup_lg.json
new file mode 100644
index 00000000..2b8c756c
--- /dev/null
+++ b/docs/benchmarks/graphs/summary/isolated vs django modes.timeraw_startup_lg.json
@@ -0,0 +1 @@
+[[1662, 0.21383238744211777], [1672, 0.22221634409189991], [1687, 0.21410434591886193], [1691, 0.2203609725843055], [1709, 0.22018038637622225], [1726, 0.2149156309515977], [1766, 0.2198640308272821], [1770, 0.22362192103085216], [1776, 0.21863830924562072], [1801, 0.22295218072522197], [1937, 0.22573752762853083], [1960, 0.22581596577171012], [1996, 0.22995210340856065], [2029, 0.2285231418957897]]
\ No newline at end of file
diff --git a/docs/benchmarks/index.html b/docs/benchmarks/index.html
new file mode 100644
index 00000000..5e2f6510
--- /dev/null
+++ b/docs/benchmarks/index.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/benchmarks/index.json b/docs/benchmarks/index.json
new file mode 100644
index 00000000..d98e1855
--- /dev/null
+++ b/docs/benchmarks/index.json
@@ -0,0 +1 @@
+{"project": "django-components", "project_url": "/django-components/", "show_commit_url": "#", "hash_length": 8, "revision_to_hash": {"250": "45a18626d74b280aa05498aa380eba687010cc0f", "268": "c9f0068741871b24756045805aaab8fbf368601a", "343": "ed2cd57bdcc12bf390f42058061a6ed077e558b0", "359": "501a055fe21abb4c7ad9af1a3a1b42eea24afacf", "369": "1937d594100d0651b151c8edbe1189b5a88b358f", "380": "1d091f50999cca0fa8c7852da2ea71684eadda6d", "388": "f5c3f64c866d06dfa2435d1d18b936dddb9eb67c", "427": "24d9db39c3c55f5eb91c9ce2112ad22507ccdd60", "457": "9103eda2f4ed80f46ff03d215491009c5476b410", "487": "384ff79e0875ac3a64a2755010ef86ec09a090b5", "500": "c102019811586f40cb11952f283797ddee96de3c", "503": "a350ad1a869bb46c6bac093f54ac40ea85d8cd8f", "508": "16022429da16e459b8a1e6e9cd8ab41d95dcb59d", "536": "ea7beb518c435389d9daff7ea557eec9ddc2464e", "550": "2cfc7285e12677a54247e9998967081c0e031efc", "552": "fcbfae3c5f0611519636290ef99b25bc0a319825", "564": "316310e842f276fd43436b432781430bd255410b", "575": "e0a5c2a4bcf5e8f577e19333e3b719440c37b10b", "577": "c174aa9802cc73b5d8fef4b0c704de3fb68b1cbb", "598": "979781012532f18c147a570ff4441c65c7503b6f", "612": "9d7d0b40b9d3bbd8e5b754e3b1b20df982cdd184", "622": "24032ac2ea80627f0fdde88058a2c3fbcae0d3fe", "646": "4f1a8184465fc472995bc226bebd66c250d501f6", "651": "8ce649498ff63a64761c83cf713983b7e2f24b81", "663": "93facba53e050619a477fa214da89fccf118ec13", "675": "ea33e0db6c54486b67e2fa496ec1c3ec3de06ec7", "681": "6874b1531df0e8836000bbc76fcca5a3de42724a", "691": "9f4243232018708fdf330f0e922a09317c60234c", "704": "188a9dc7eef4c45ee4f87efa8a0d6728e94f210d", "724": "76a0cde3af7b3061127d149c138fbc78462a07fe", "729": "c932f28cb4840dc45d2d26b4d927c1480459272f", "742": "7058f05e0415965ddd162d0ba663c5106e7ffb66", "748": "95d6eacb5c03a611f92cd9a6e254cea7e0ce57eb", "752": "d512cfb0fec8a42ab58d2f106047fc4c0ec65427", "757": "04160f4e0b2ec4d901d6724c34ed8df883363064", "773": "20847b978b3ddb5979489fbb4bd8e971b9b16fbf", "775": "ae5cda9f727454a077ab16c51a237fec076bd442", "779": "cd791caa572c9acd6d56445c04d6c9b55a50c602", "787": "274be104789e31955f88e26f14c89ed648f25448", "806": "c3a80b729049b5ea1b4799e742e4100a7640efab", "845": "0abb5aa63ff0396328ef4dfdc2e78e872671f135", "855": "e4e787b29dc9cd2cf35ad02f22bad6fa15a7211c", "867": "e346c07298b268d9212fcf93d132968e69824730", "884": "2316f79dff66260b7a9fe91effb55c74524deca0", "887": "085c60a8c96442d9fd4f72d66a7eb295e7cfb2d9", "889": "ba86cee578490df944ad167674db32182b8bbf7b", "891": "dd292b03508b7c03b2ad4f9fb9c17dec747845ba", "898": "badffdda3538a8082137453c757509ed4f035a3e", "902": "c07f0e634121ced0119bb665ed544ca4447c416b", "904": "8bbe81d7171ec3512f250927653d8454c7ff005e", "908": "881c36219a45581086da35a17d3715ee0698ca88", "910": "9bfb50b8f27f7ff521226109ab30426633f6b514", "912": "3a7d5355cfa5d37641a4c80ee9fd2423cea10c1b", "930": "09a720009767f45bebcfa48f3587219c03082601", "935": "a4b4905bee778a51f9a99a042ce14ed2424cc9fb", "940": "31257a475dcfdacaaeb408f59ea92b736a668815", "942": "d47927054c820ecf3f9f97a62f03dfbb5496a11b", "956": "fbbbf6c694b8213832fc127ee8a3e31872308aff", "958": "d819f3ff491866abaeb9a7dbba6a6ca3c21da9f8", "960": "c202c5a901106392ccdde49100211182c986eca5", "965": "7bbfcf7565159d92de41bb0d738b7878d78f4533", "978": "b89c09aa5f13903b1d056c70afbfd327f0ed6362", "980": "03af25aad6841b6edb56c925d2599817e08ceb44", "982": "5cb649fae62a42e525c1ea9fb74d7838886cc1a8", "986": "f97717cdb35eaadb78b1f468728b1bd386e742d8", "1056": "b26a2011380c959bfc98043821f6b4aa337a281d", "1058": "8c5b088c31b7166932e18739f882c2eef632f3a4", "1060": "682bfc42397c0bdbeb1a2b6ccabb8aca89686d4f", "1089": "8f13a641ac096e93a0464f048a4fa53e591bb8db", "1098": "30d04fe1b053e6c5de0b6f34a7758a627517be8c", "1125": "f7846b9c0ae7a8fd0b7f6edf664316e485455e76", "1132": "a3d66586b19b7e2aacbf793edfba20bcd9858f4a", "1179": "0064de9c78db5eccc7c498e2a6d4c3c5ffa745ec", "1252": "d093bfb05212555e14c5cd46c94b0ba057cbeceb", "1270": "c0a4fd5f685d694218b583b2d0a3e8417925d53a", "1277": "2a4b0f52894d5d0bb8d325d6096a3950286db541", "1282": "5a23101038d7085959087b2352e71590eafe9529", "1287": "ce3305a5fff095e990707de851f85bc27120596c", "1312": "cdc830fca3bdd98669e0510841536be14d1bd728", "1328": "468a593a472c35379fe7567918e8a534b2d53748", "1337": "2f14e8e0908657459909c6338106e561edc5d0f4", "1352": "a5659691d0f947643ce6542b7f09075e3f931646", "1361": "aaeba99f54b206baed072ffd0572035ddf5118a7", "1366": "6813c9d7aa4acfb04df9665651a2864d04bbe8ba", "1381": "6681fc0085fdb4b76cb74c1bbf20d44fa22f40fe", "1387": "6bb73bd8afd350db84889efc09b74255cea08979", "1392": "c76f8198dd497b34735fc17a0f7a678bdd811a3f", "1447": "3bbd4326e6c1bfb4a02039e16021a3f720910308", "1488": "914576e68133bc6ec356f3918016c45691ed3534", "1505": "3d187d7abad80f8464bd70dfba847d27a8e173db", "1514": "e105500350a320dfccf36fc19cad7421d38c3736", "1546": "61515b34540d27311fc3286b50212c1e314ce39e", "1571": "691443a0a821eb1a02f9b42ad0e32bcd71d94943", "1591": "dcd4203eeadafc5d500b4b72c5cf04f1fe7317e7", "1662": "d0a42a2698f2ba21e7ab2dec750c5dbadeda0db5", "1672": "2037ed20b7252cc52008e69bdd3d8e095ad6ea08", "1687": "2472c2ad338a23fba015d4d9816cb62d1325455f", "1691": "42818ad6ffb47bd650d8a379b84c3d48394f9f77", "1709": "a6455d70f6c28ddbd4be8e58902f6cbc101e5ff3", "1726": "fdd29baa65e9ef78eb24a0ad2ca0b5d7c624dad3", "1766": "1319a95627493fc0745b5af0600af2dc8c5117f9", "1770": "07f747d70500bbe3e135725b0e1b102815ab9416", "1776": "ad402fc619922b6d2edf1e99b7082d2a58632076", "1801": "4c909486069f3c3c8ee7915239174f820f081da4", "1933": "593c66db7fce8f7d0e45768f516d1920e53d0967", "1937": "7b24b86f4a836c697acba926d9d6602afa45418d", "1960": "06c89cf9e89a432197a4cabb5a1d6864dd6089ac", "1996": "c692b7a3105c65414d2c23c357ffed9debdbf6e9", "2029": "5d7e235725449181f6b65b7bf97e43ea0e0f8552"}, "revision_to_date": {"250": 1630912817000, "268": 1631273531000, "343": 1654029104000, "359": 1657786741000, "369": 1657798498000, "380": 1658057264000, "388": 1658128984000, "427": 1670931380000, "457": 1673095465000, "487": 1675977478000, "500": 1678833725000, "503": 1678834812000, "508": 1679329468000, "536": 1680808865000, "550": 1681214445000, "552": 1681388770000, "564": 1682351069000, "575": 1684433482000, "577": 1684760359000, "598": 1693734426000, "612": 1695996512000, "622": 1696883504000, "646": 1702127213000, "651": 1702852887000, "663": 1705268832000, "675": 1705701480000, "681": 1706343740000, "691": 1706393538000, "704": 1707467055000, "724": 1708588716000, "729": 1708984309000, "742": 1709796107000, "748": 1710542375000, "752": 1711216985000, "757": 1711278671000, "773": 1711752109000, "775": 1711786713000, "779": 1712212506000, "787": 1712872453000, "806": 1713128940000, "845": 1713390260000, "855": 1713901297000, "867": 1714590581000, "884": 1714912319000, "887": 1715087715000, "889": 1715111097000, "891": 1715505986000, "898": 1716105516000, "902": 1716441018000, "904": 1716488913000, "908": 1717051130000, "910": 1717227227000, "912": 1717232115000, "930": 1718176374000, "935": 1718991590000, "940": 1720427258000, "942": 1720429478000, "956": 1722279535000, "958": 1722325182000, "960": 1722666822000, "965": 1722890429000, "978": 1723843975000, "980": 1723993321000, "982": 1724243667000, "986": 1724363119000, "1056": 1724732902000, "1058": 1724824521000, "1060": 1724924003000, "1089": 1725480929000, "1098": 1725655525000, "1125": 1726084755000, "1132": 1726347108000, "1179": 1728564427000, "1252": 1732525062000, "1270": 1732629701000, "1277": 1732644681000, "1282": 1732658332000, "1287": 1732726640000, "1312": 1733164405000, "1328": 1733471329000, "1337": 1733644953000, "1352": 1733834654000, "1361": 1734080521000, "1366": 1734245122000, "1381": 1734464187000, "1387": 1734600366000, "1392": 1734955786000, "1447": 1736287315000, "1488": 1737558545000, "1505": 1738157680000, "1514": 1738404847000, "1546": 1738662755000, "1571": 1739736734000, "1591": 1740050674000, "1662": 1742502414000, "1672": 1742645505000, "1687": 1742720064000, "1691": 1742765538000, "1709": 1743430242000, "1726": 1743837055000, "1766": 1744204166000, "1770": 1744216267000, "1776": 1744443333000, "1801": 1745143092000, "1933": 1749073294000, "1937": 1749076521000, "1960": 1749546769000, "1996": 1751538441000, "2029": 1753049108000}, "params": {"machine": ["ci-linux"], "python": ["3.13"], "django": ["5.1"], "djc-core-html-parser": [""], "branch": ["master"]}, "graph_param_list": [{"machine": "ci-linux", "python": "3.13", "django": "5.1", "djc-core-html-parser": "", "branch": "master"}], "benchmarks": {"Components vs Django.peakmem_render_lg_first": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - large - first render (mem)\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n setup=lambda renderer: setup_templating_memory_benchmark(renderer, \"lg\", \"first\", \"isolated\"),\n )\n def peakmem_render_lg_first(self, renderer: TemplatingRenderer):\n do_render()\n\nsetup=lambda renderer: setup_templating_memory_benchmark(renderer, \"lg\", \"first\", \"isolated\"),", "name": "Components vs Django.peakmem_render_lg_first", "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - large - first render (mem)", "type": "peakmemory", "unit": "bytes", "version": "301c396f017f45a5b3f71e85df58d15f54153fcfd951af7ef424641d4b31b528"}, "Components vs Django.peakmem_render_lg_subsequent": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - large - second render (mem)\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n setup=lambda renderer: setup_templating_memory_benchmark(renderer, \"lg\", \"subsequent\", \"isolated\"),\n )\n def peakmem_render_lg_subsequent(self, renderer: TemplatingRenderer):\n do_render()\n\nsetup=lambda renderer: setup_templating_memory_benchmark(renderer, \"lg\", \"subsequent\", \"isolated\"),", "name": "Components vs Django.peakmem_render_lg_subsequent", "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - large - second render (mem)", "type": "peakmemory", "unit": "bytes", "version": "9a44e9999ef3ef42ea7e01323727490244febb43d66a87a4d8f88c6b8a133b8b"}, "Components vs Django.peakmem_render_sm_first": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - small - first render (mem)\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n setup=lambda renderer: setup_templating_memory_benchmark(renderer, \"sm\", \"first\", \"isolated\"),\n )\n def peakmem_render_sm_first(self, renderer: TemplatingRenderer):\n do_render()\n\nsetup=lambda renderer: setup_templating_memory_benchmark(renderer, \"sm\", \"first\", \"isolated\"),", "name": "Components vs Django.peakmem_render_sm_first", "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - small - first render (mem)", "type": "peakmemory", "unit": "bytes", "version": "e93b7a5193681c883edf85bdb30b1bc0821263bf51033fdcee215b155085e036"}, "Components vs Django.peakmem_render_sm_subsequent": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - small - second render (mem)\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n setup=lambda renderer: setup_templating_memory_benchmark(renderer, \"sm\", \"subsequent\", \"isolated\"),\n )\n def peakmem_render_sm_subsequent(self, renderer: TemplatingRenderer):\n do_render()\n\nsetup=lambda renderer: setup_templating_memory_benchmark(renderer, \"sm\", \"subsequent\", \"isolated\"),", "name": "Components vs Django.peakmem_render_sm_subsequent", "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - small - second render (mem)", "type": "peakmemory", "unit": "bytes", "version": "b46e0820b18950aa7cc5e61306ff3425b76b4da9dca42d64fae5b1d25c6c9026"}, "Components vs Django.timeraw_render_lg_first": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - large - first render\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n include_in_quick_benchmark=True,\n )\n def timeraw_render_lg_first(self, renderer: TemplatingRenderer):\n return prepare_templating_benchmark(renderer, \"lg\", \"first\", \"isolated\")", "min_run_count": 2, "name": "Components vs Django.timeraw_render_lg_first", "number": 1, "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - large - first render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "be3bf6236960046a028b6ea007aad28b2337fc2b906b8ce317a09a5d4f1a6193", "warmup_time": -1}, "Components vs Django.timeraw_render_lg_subsequent": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - large - second render\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n )\n def timeraw_render_lg_subsequent(self, renderer: TemplatingRenderer):\n return prepare_templating_benchmark(renderer, \"lg\", \"subsequent\", \"isolated\")", "min_run_count": 2, "name": "Components vs Django.timeraw_render_lg_subsequent", "number": 1, "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - large - second render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "b98221c11a0ee6e9de0778d416d31b9dd514a674d9017a2bb9b2fc1cd0f01920", "warmup_time": -1}, "Components vs Django.timeraw_render_sm_first": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - small - first render\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n )\n def timeraw_render_sm_first(self, renderer: TemplatingRenderer):\n return prepare_templating_benchmark(renderer, \"sm\", \"first\", \"isolated\")", "min_run_count": 2, "name": "Components vs Django.timeraw_render_sm_first", "number": 1, "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - small - first render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "f1fc17e4a31c71f4d9265f1122da52e7cf57addb4dfa02606e303b33d6431b9b", "warmup_time": -1}, "Components vs Django.timeraw_render_sm_subsequent": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"render - small - second render\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n )\n def timeraw_render_sm_subsequent(self, renderer: TemplatingRenderer):\n return prepare_templating_benchmark(renderer, \"sm\", \"subsequent\", \"isolated\")", "min_run_count": 2, "name": "Components vs Django.timeraw_render_sm_subsequent", "number": 1, "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "render - small - second render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "6fce1cd85a9344fee383b40a22f27862120b9488a628420625592dc14e0307d3", "warmup_time": -1}, "Components vs Django.timeraw_startup_lg": {"code": "class DjangoComponentsVsDjangoTests:\n @benchmark(\n pretty_name=\"startup - large\",\n group_name=DJC_VS_DJ_GROUP,\n number=1,\n rounds=5,\n params={\n \"renderer\": [\"django\", \"django-components\"],\n },\n )\n def timeraw_startup_lg(self, renderer: TemplatingRenderer):\n return prepare_templating_benchmark(renderer, \"lg\", \"startup\", \"isolated\")", "min_run_count": 2, "name": "Components vs Django.timeraw_startup_lg", "number": 1, "param_names": ["renderer"], "params": [["'django'", "'django-components'"]], "pretty_name": "startup - large", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "53151821c128ad0ecfb0707fff3146e1abd8d0bcfa301aa056b5d3fae3d793e2", "warmup_time": -1}, "Other.timeraw_import_time": {"code": "class OtherTests:\n @benchmark(\n pretty_name=\"import time\",\n group_name=OTHER_GROUP,\n number=1,\n rounds=5,\n )\n def timeraw_import_time(self):\n return prepare_templating_benchmark(\"django-components\", \"lg\", \"startup\", \"isolated\", imports_only=True)", "min_run_count": 2, "name": "Other.timeraw_import_time", "number": 1, "param_names": [], "params": [], "pretty_name": "import time", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "a0a1c1c0db22509410b946d0d4384b52ea4a09b47b6048d7d1cfb89b0c7fe5c3", "warmup_time": -1}, "isolated vs django modes.peakmem_render_lg_first": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - large - first render (mem)\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n setup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"lg\",\n \"first\",\n context_mode,\n ),\n )\n def peakmem_render_lg_first(self, context_mode: DjcContextMode):\n do_render()\n\nsetup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"lg\",\n \"first\",\n context_mode,\n),", "name": "isolated vs django modes.peakmem_render_lg_first", "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - large - first render (mem)", "type": "peakmemory", "unit": "bytes", "version": "c4bf0016d48d210f08b8db733b57c7dcba1cebbf548c458b93b86ace387067e9"}, "isolated vs django modes.peakmem_render_lg_subsequent": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - large - second render (mem)\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n setup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"lg\",\n \"subsequent\",\n context_mode,\n ),\n )\n def peakmem_render_lg_subsequent(self, context_mode: DjcContextMode):\n do_render()\n\nsetup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"lg\",\n \"subsequent\",\n context_mode,\n),", "name": "isolated vs django modes.peakmem_render_lg_subsequent", "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - large - second render (mem)", "type": "peakmemory", "unit": "bytes", "version": "65bb1b8586487197a79bb6073e4c71642877b845b6eb42d1bd32398299daffbf"}, "isolated vs django modes.peakmem_render_sm_first": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - small - first render (mem)\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n setup=lambda context_mode: setup_templating_memory_benchmark(\"django-components\", \"sm\", \"first\", context_mode),\n )\n def peakmem_render_sm_first(self, context_mode: DjcContextMode):\n do_render()\n\nsetup=lambda context_mode: setup_templating_memory_benchmark(\"django-components\", \"sm\", \"first\", context_mode),", "name": "isolated vs django modes.peakmem_render_sm_first", "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - small - first render (mem)", "type": "peakmemory", "unit": "bytes", "version": "c51b91fc583295776062822225e720b5ed71aef9c9288217c401c54283c62840"}, "isolated vs django modes.peakmem_render_sm_subsequent": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - small - second render (mem)\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n setup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"sm\",\n \"subsequent\",\n context_mode,\n ),\n )\n def peakmem_render_sm_subsequent(self, context_mode: DjcContextMode):\n do_render()\n\nsetup=lambda context_mode: setup_templating_memory_benchmark(\n \"django-components\",\n \"sm\",\n \"subsequent\",\n context_mode,\n),", "name": "isolated vs django modes.peakmem_render_sm_subsequent", "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - small - second render (mem)", "type": "peakmemory", "unit": "bytes", "version": "54d747fb8f40179b7ff3d2fc49eb195909ad1c880b5ef7b82f82742b27b67260"}, "isolated vs django modes.timeraw_render_lg_first": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - large - first render\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n )\n def timeraw_render_lg_first(self, context_mode: DjcContextMode):\n return prepare_templating_benchmark(\"django-components\", \"lg\", \"first\", context_mode)", "min_run_count": 2, "name": "isolated vs django modes.timeraw_render_lg_first", "number": 1, "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - large - first render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "f94af83427c6346f88f8785a3cd2fc42415ac5a9fbbdb7de71d27e22e6a81699", "warmup_time": -1}, "isolated vs django modes.timeraw_render_lg_subsequent": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - large - second render\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n )\n def timeraw_render_lg_subsequent(self, context_mode: DjcContextMode):\n return prepare_templating_benchmark(\"django-components\", \"lg\", \"subsequent\", context_mode)", "min_run_count": 2, "name": "isolated vs django modes.timeraw_render_lg_subsequent", "number": 1, "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - large - second render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "9f7c2fde6b33f0451a1794ed903c48d96cd7822f67da502cec36fe8e977c2414", "warmup_time": -1}, "isolated vs django modes.timeraw_render_sm_first": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - small - first render\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n )\n def timeraw_render_sm_first(self, context_mode: DjcContextMode):\n return prepare_templating_benchmark(\"django-components\", \"sm\", \"first\", context_mode)", "min_run_count": 2, "name": "isolated vs django modes.timeraw_render_sm_first", "number": 1, "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - small - first render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "d15ca68909d7f1f43ff16863befb6f42681f17461417fc0069eefd6db3569296", "warmup_time": -1}, "isolated vs django modes.timeraw_render_sm_subsequent": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"render - small - second render\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n )\n def timeraw_render_sm_subsequent(self, context_mode: DjcContextMode):\n return prepare_templating_benchmark(\"django-components\", \"sm\", \"subsequent\", context_mode)", "min_run_count": 2, "name": "isolated vs django modes.timeraw_render_sm_subsequent", "number": 1, "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "render - small - second render", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "7444bc9516dd087e3f420349345eae991ad6941bbd22fce45265b18034b7cf77", "warmup_time": -1}, "isolated vs django modes.timeraw_startup_lg": {"code": "class IsolatedVsDjangoContextModesTests:\n @benchmark(\n pretty_name=\"startup - large\",\n group_name=DJC_ISOLATED_VS_NON_GROUP,\n number=1,\n rounds=5,\n params={\n \"context_mode\": [\"isolated\", \"django\"],\n },\n )\n def timeraw_startup_lg(self, context_mode: DjcContextMode):\n return prepare_templating_benchmark(\"django-components\", \"lg\", \"startup\", context_mode)", "min_run_count": 2, "name": "isolated vs django modes.timeraw_startup_lg", "number": 1, "param_names": ["context_mode"], "params": [["'isolated'", "'django'"]], "pretty_name": "startup - large", "repeat": 0, "rounds": 5, "sample_time": 0.01, "type": "time", "unit": "seconds", "version": "eabe311ebee4a15c5816617be12f00ec30376f7506bd668219e1c50bc897c134", "warmup_time": -1}}, "machines": {"ci-linux": {"machine": "ci-linux", "version": 1}}, "tags": {"0.100": 1125, "0.101": 1132, "0.102": 1179, "0.110": 1252, "0.111": 1270, "0.112": 1277, "0.113": 1282, "0.114": 1287, "0.115": 1312, "0.116": 1328, "0.117": 1337, "0.118": 1352, "0.119": 1361, "0.120": 1366, "0.121": 1381, "0.122": 1387, "0.123": 1392, "0.124": 1447, "0.125": 1488, "0.126": 1505, "0.127": 1514, "0.128": 1546, "0.129": 1571, "0.130": 1591, "0.131": 1662, "0.132": 1672, "0.133": 1687, "0.134": 1691, "0.135": 1709, "0.136": 1726, "0.137": 1766, "0.138": 1770, "0.139": 1776, "0.139.1": 1801, "0.140.0": 1933, "0.140.1": 1937, "0.141.0": 1960, "0.141.1": 1996, "0.141.2": 2029, "0.16": 250, "0.17": 268, "0.26.2": 508, "0.27": 550, "0.27.1": 552, "0.27.2": 564, "0.28.0": 575, "0.28.1": 577, "0.67": 845, "0.68": 855, "0.70": 867, "0.71": 884, "0.72": 887, "0.73": 889, "0.74": 891, "0.75": 898, "0.76": 902, "0.77": 904, "0.78": 908, "0.79": 910, "0.80": 912, "0.81": 930, "0.82": 935, "0.83": 940, "0.84": 942, "0.85": 956, "0.86": 958, "0.87": 960, "0.88": 965, "0.89": 978, "0.90": 980, "0.91": 982, "0.92": 986, "0.93": 1056, "0.94": 1058, "0.95": 1060, "0.96": 1089, "0.97": 1098, "0.18": 343, "0.22": 388, "0.21": 380, "0.20": 369, "0.19": 359, "0.24": 457, "0.23": 427, "0.25": 487, "0.26": 500, "0.26.1": 503, "0.26.3": 536, "0.28.2": 598, "0.28.3": 612, "0.29": 622, "0.30": 646, "0.31": 651, "0.32": 663, "0.33": 675, "0.34": 681, "0.34.1": 691, "0.35": 704, "0.37": 724, "0.50": 729, "0.51": 742, "0.52": 748, "0.60": 752, "0.61": 757, "0.62": 773, "0.63": 775, "0.64": 779, "0.65": 787, "0.66": 806}, "pages": [["", "Grid view", "Display as a agrid"], ["summarylist", "List view", "Display as a list"], ["regressions", "Show regressions", "Display information about recent regressions"]]}
\ No newline at end of file
diff --git a/docs/benchmarks/info.json b/docs/benchmarks/info.json
new file mode 100644
index 00000000..032015bd
--- /dev/null
+++ b/docs/benchmarks/info.json
@@ -0,0 +1,4 @@
+{
+ "asv-version": "0.6.4",
+ "timestamp": 1753049912703
+}
\ No newline at end of file
diff --git a/docs/benchmarks/jquery.flot.axislabels.js b/docs/benchmarks/jquery.flot.axislabels.js
new file mode 100644
index 00000000..e8017e8e
--- /dev/null
+++ b/docs/benchmarks/jquery.flot.axislabels.js
@@ -0,0 +1,140 @@
+/*
+CAxis Labels Plugin for flot. :P
+Copyright (c) 2010 Xuan Luo
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ */
+(function ($) {
+ var options = { };
+
+ function init(plot) {
+ // This is kind of a hack. There are no hooks in Flot between
+ // the creation and measuring of the ticks (setTicks, measureTickLabels
+ // in setupGrid() ) and the drawing of the ticks and plot box
+ // (insertAxisLabels in setupGrid() ).
+ //
+ // Therefore, we use a trick where we run the draw routine twice:
+ // the first time to get the tick measurements, so that we can change
+ // them, and then have it draw it again.
+ var secondPass = false;
+ plot.hooks.draw.push(function (plot, ctx) {
+ if (!secondPass) {
+ // MEASURE AND SET OPTIONS
+ $.each(plot.getAxes(), function(axisName, axis) {
+ var opts = axis.options // Flot 0.7
+ || plot.getOptions()[axisName]; // Flot 0.6
+ if (!opts || !opts.axisLabel)
+ return;
+
+ var w, h;
+ if (opts.axisLabelUseCanvas != false)
+ opts.axisLabelUseCanvas = true;
+
+ if (opts.axisLabelUseCanvas) {
+ // canvas text
+ if (!opts.axisLabelFontSizePixels)
+ opts.axisLabelFontSizePixels = 14;
+ if (!opts.axisLabelFontFamily)
+ opts.axisLabelFontFamily = 'sans-serif';
+ // since we currently always display x as horiz.
+ // and y as vertical, we only care about the height
+ w = opts.axisLabelFontSizePixels;
+ h = opts.axisLabelFontSizePixels;
+
+ } else {
+ // HTML text
+ var elem = $('
+
+ ' + opts.axisLabel + '
');
+ plot.getPlaceholder().append(elem);
+ w = elem.outerWidth(true);
+ h = elem.outerHeight(true);
+ elem.remove();
+ }
+
+ if (axisName.charAt(0) == 'x')
+ axis.labelHeight += h;
+ else
+ axis.labelWidth += w;
+ opts.labelHeight = axis.labelHeight;
+ opts.labelWidth = axis.labelWidth;
+ });
+ // re-draw with new label widths and heights
+ secondPass = true;
+ plot.setupGrid();
+ plot.draw();
+
+
+ } else {
+ // DRAW
+ $.each(plot.getAxes(), function(axisName, axis) {
+ var opts = axis.options // Flot 0.7
+ || plot.getOptions()[axisName]; // Flot 0.6
+ if (!opts || !opts.axisLabel)
+ return;
+
+ if (opts.axisLabelUseCanvas) {
+ // canvas text
+ var ctx = plot.getCanvas().getContext('2d');
+ ctx.save();
+ ctx.font = opts.axisLabelFontSizePixels + 'px ' +
+ opts.axisLabelFontFamily;
+ var width = ctx.measureText(opts.axisLabel).width;
+ var height = opts.axisLabelFontSizePixels;
+ var x, y;
+ if (axisName.charAt(0) == 'x') {
+ x = plot.getPlotOffset().left + plot.width()/2 - width/2;
+ y = plot.getCanvas().height;
+ } else {
+ x = height * 0.72;
+ y = plot.getPlotOffset().top + plot.height()/2 - width/2;
+ }
+ ctx.translate(x, y);
+ ctx.rotate((axisName.charAt(0) == 'x') ? 0 : -Math.PI/2);
+ ctx.fillText(opts.axisLabel, 0, 0);
+ ctx.restore();
+
+ } else {
+ // HTML text
+ plot.getPlaceholder().find('#' + axisName + 'Label').remove();
+ var elem = $('' + opts.axisLabel + '
');
+ if (axisName.charAt(0) == 'x') {
+ elem.css('left', plot.getPlotOffset().left + plot.width()/2 - elem.outerWidth()/2 + 'px');
+ elem.css('bottom', '0px');
+ } else {
+ elem.css('top', plot.getPlotOffset().top + plot.height()/2 - elem.outerHeight()/2 + 'px');
+ elem.css('left', '0px');
+ }
+ plot.getPlaceholder().append(elem);
+ }
+ });
+ secondPass = false;
+ }
+ });
+ }
+
+
+
+ $.plot.plugins.push({
+ init: init,
+ options: options,
+ name: 'axisLabels',
+ version: '1.0'
+ });
+})(jQuery);
diff --git a/docs/benchmarks/regressions.css b/docs/benchmarks/regressions.css
new file mode 100644
index 00000000..0455b77e
--- /dev/null
+++ b/docs/benchmarks/regressions.css
@@ -0,0 +1,44 @@
+#regressions-body {
+ margin-left: 2em;
+ margin-right: 2em;
+ margin-top: 1em;
+ margin-bottom: 2em;
+}
+
+#regressions-body table thead th {
+ cursor: pointer;
+ white-space: nowrap;
+}
+
+#regressions-body table thead th.desc:after {
+ content: ' \2191';
+}
+
+#regressions-body table thead th.asc:after {
+ content: ' \2193';
+}
+
+#regressions-body table.ignored {
+ padding-top: 1em;
+ color: #ccc;
+ background-color: #eee;
+}
+
+#regressions-body table.ignored a {
+ color: #82abda;
+}
+
+#regressions-body .feed-div {
+ float: right;
+}
+
+#regressions-body table tbody td.date {
+ white-space: nowrap;
+}
+
+#regressions-body table button {
+ margin-top: -2px;
+ padding-top: 2px;
+ padding-bottom: 0px;
+ white-space: nowrap;
+}
diff --git a/docs/benchmarks/regressions.js b/docs/benchmarks/regressions.js
new file mode 100644
index 00000000..7572c4b4
--- /dev/null
+++ b/docs/benchmarks/regressions.js
@@ -0,0 +1,618 @@
+'use strict';
+
+$(document).ready(function() {
+ /* Cached contents of downloaded regressions.json */
+ var regression_data = null;
+ /* Current page title */
+ var current_title = "All regressions";
+ /* Whether HTML5 local storage is available */
+ var local_storage_available = false;
+ /* Key prefix for ignored regressions. For each ignored regression,
+ a key "ignore_key_prefix + md5(benchmark_name + date_a + date_b)"
+ is added to HTML5 local storage.
+ */
+ var ignore_key_prefix = null;
+ /* Set of ignored regressions, same information as in HTML5 local storage.
+ Useful if local storage runs out of space. */
+ var ignored_regressions = {};
+ /* Whether to force reload on next page update */
+ var skip_reload = false;
+
+ function load_data(params) {
+ $("#title").text(current_title);
+
+ if (typeof(Storage) !== "undefined") {
+ /* html5 local storage available */
+ local_storage_available = true;
+ }
+
+ if (regression_data !== null) {
+ // already displayed
+ if (!skip_reload) {
+ var main_div = display_data(regression_data, params);
+ $('#regressions-body').empty();
+ $('#regressions-body').append(main_div);
+ }
+ skip_reload = false;
+ }
+ else {
+ var message = $('Loading...
');
+ skip_reload = false;
+ $('#regressions-body').append(message);
+ $.ajax({
+ url: 'regressions.json' + '?timestamp=' + $.asv.main_timestamp,
+ dataType: "json",
+ cache: true
+ }).done(function (data) {
+ regression_data = data;
+ var main_div = display_data(data, params);
+ $('#regressions-body').empty();
+ $('#regressions-body').append(main_div);
+ });
+ }
+ }
+
+ function update_url(params, reload) {
+ var info = $.asv.parse_hash_string(window.location.hash);
+ $.each(params || {}, function(key, value) {
+ info.params[key] = value;
+ });
+
+ var new_hash = $.asv.format_hash_string(info);
+ if (new_hash != window.location.hash) {
+ if (reload === undefined) {
+ skip_reload = false;
+ }
+ else {
+ skip_reload = !reload;
+ }
+ window.location.hash = new_hash;
+ }
+ else {
+ skip_reload = false;
+ }
+ }
+
+ function display_data(data, params) {
+ var main_div = $('');
+ var branches = $.asv.main_json.params['branch'];
+ var all_ignored_keys = {};
+
+ ignore_key_prefix = 'asv-r-' + $.asv.main_json.project;
+
+ if (branches && branches.length > 1) {
+ /* Add a branch selector */
+ var dropdown_menu = $('');
+ var dropdown_div = $('');
+
+ dropdown_div.append($(''));
+ dropdown_div.append(dropdown_menu);
+
+ main_div.append(dropdown_div);
+ }
+
+ var feed_div = $('');
+ main_div.append(feed_div);
+
+ var group_div = $('/", handler=my_view, name="another_view"),
+ ]
+```
+
+!!! warning
+
+ The [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) objects
+ are different from objects created with Django's
+ [`django.urls.path()`](https://docs.djangoproject.com/en/5.2/ref/urls/#path).
+ Do NOT use `URLRoute` objects in Django's [`urlpatterns`](https://docs.djangoproject.com/en/5.2/topics/http/urls/#example)
+ and vice versa!
+
+ django-components uses a custom [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) class to define framework-agnostic routing rules.
+
+ As of v0.131, `URLRoute` objects are directly converted to Django's `URLPattern` and `URLResolver` objects.
+
+### URL paths
+
+The URLs defined in an extension are available under the path
+
+```
+/components/ext//
+```
+
+For example, if you have defined a URL with the path `my-view//` in an extension named `my_extension`, it can be accessed at:
+
+```
+/components/ext/my_extension/my-view/john/
+```
+
+### Nested URLs
+
+Extensions can also define nested URLs to allow for more complex routing structures.
+
+To define nested URLs, set the [`children`](../../../reference/extension_urls#django_components.URLRoute.children)
+attribute of the [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) object to
+a list of child [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) objects:
+
+```python
+class MyExtension(ComponentExtension):
+ name = "my_extension"
+
+ urls = [
+ URLRoute(
+ path="parent/",
+ name="parent_view",
+ children=[
+ URLRoute(path="child//", handler=my_view, name="child_view"),
+ ],
+ ),
+ ]
+```
+
+In this example, the URL
+
+```
+/components/ext/my_extension/parent/child/john/
+```
+
+would call the `my_view` handler with the parameter `name` set to `"John"`.
+
+### Extra URL data
+
+The [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) class is framework-agnostic,
+so that extensions could be used with non-Django frameworks in the future.
+
+However, that means that there may be some extra fields that Django's
+[`django.urls.path()`](https://docs.djangoproject.com/en/5.2/ref/urls/#path)
+accepts, but which are not defined on the `URLRoute` object.
+
+To address this, the [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) object has
+an [`extra`](../../../reference/extension_urls#django_components.URLRoute.extra) attribute,
+which is a dictionary that can be used to pass any extra kwargs to `django.urls.path()`:
+
+```python
+URLRoute(
+ path="my-view//",
+ handler=my_view,
+ name="my_view",
+ extra={"kwargs": {"foo": "bar"} },
+)
+```
+
+Is the same as:
+
+```python
+django.urls.path(
+ "my-view//",
+ view=my_view,
+ name="my_view",
+ kwargs={"foo": "bar"},
+)
+```
+
+because `URLRoute` is converted to Django's route like so:
+
+```python
+django.urls.path(
+ route.path,
+ view=route.handler,
+ name=route.name,
+ **route.extra,
+)
+```
diff --git a/docs/concepts/advanced/hooks.md b/docs/concepts/advanced/hooks.md
index 13574763..269134cb 100644
--- a/docs/concepts/advanced/hooks.md
+++ b/docs/concepts/advanced/hooks.md
@@ -1,70 +1,340 @@
----
-title: Lifecycle hooks
-weight: 4
----
-
_New in version 0.96_
-Component hooks are functions that allow you to intercept the rendering process at specific positions.
+Intercept the rendering lifecycle with Component hooks.
+
+Unlike the [extension hooks](../../../reference/extension_hooks/), these are defined directly
+on the [`Component`](../../../reference/api#django_components.Component) class.
## Available hooks
-- `on_render_before`
+### `on_render_before`
- ```py
- def on_render_before(
- self: Component,
- context: Context,
- template: Template
- ) -> None:
- ```
+```py
+def on_render_before(
+ self: Component,
+ context: Context,
+ template: Optional[Template],
+) -> None:
+```
- Hook that runs just before the component's template is rendered.
+[`Component.on_render_before`](../../../reference/api#django_components.Component.on_render_before) runs just before the component's template is rendered.
- You can use this hook to access or modify the context or the template:
+It is called for every component, including nested ones, as part of
+the component render lifecycle.
- ```py
- def on_render_before(self, context, template) -> None:
- # Insert value into the Context
- context["from_on_before"] = ":)"
+It receives the [Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context)
+and the [Template](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template)
+as arguments.
- # Append text into the Template
- template.nodelist.append(TextNode("FROM_ON_BEFORE"))
- ```
+The `template` argument is `None` if the component has no template.
-- `on_render_after`
+**Example:**
- ```py
- def on_render_after(
- self: Component,
- context: Context,
- template: Template,
- content: str
- ) -> None | str | SafeString:
- ```
+You can use this hook to access the context or the template:
- Hook that runs just after the component's template was rendered.
- It receives the rendered output as the last argument.
+```py
+from django.template import Context, Template
+from django_components import Component
- You can use this hook to access the context or the template, but modifying
- them won't have any effect.
+class MyTable(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ # Insert value into the Context
+ context["from_on_before"] = ":)"
- To override the content that gets rendered, you can return a string or SafeString from this hook:
+ assert isinstance(template, Template)
+```
- ```py
- def on_render_after(self, context, template, content):
- # Prepend text to the rendered content
- return "Chocolate cookie recipe: " + content
- ```
+!!! warning
-## Component hooks example
+ If you want to pass data to the template, prefer using
+ [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+ instead of this hook.
+
+!!! warning
+
+ Do NOT modify the template in this hook. The template is reused across renders.
+
+ Since this hook is called for every component, this means that the template would be modified
+ every time a component is rendered.
+
+### `on_render`
+
+_New in version 0.140_
+
+```py
+def on_render(
+ self: Component,
+ context: Context,
+ template: Optional[Template],
+) -> Union[str, SafeString, OnRenderGenerator, None]:
+```
+
+[`Component.on_render`](../../../reference/api#django_components.Component.on_render) does the actual rendering.
+
+You can override this method to:
+
+- Change what template gets rendered
+- Modify the context
+- Modify the rendered output after it has been rendered
+- Handle errors
+
+The default implementation renders the component's
+[Template](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template)
+with the given
+[Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context).
+
+```py
+class MyTable(Component):
+ def on_render(self, context, template):
+ if template is None:
+ return None
+ else:
+ return template.render(context)
+```
+
+The `template` argument is `None` if the component has no template.
+
+#### Modifying rendered template
+
+To change what gets rendered, you can:
+
+- Render a different template
+- Render a component
+- Return a different string or SafeString
+
+```py
+class MyTable(Component):
+ def on_render(self, context, template):
+ return "Hello"
+```
+
+You can also use [`on_render()`](../../../reference/api#django_components.Component.on_render) as a router,
+rendering other components based on the parent component's arguments:
+
+```py
+class MyTable(Component):
+ def on_render(self, context, template):
+ # Select different component based on `feature_new_table` kwarg
+ if self.kwargs.get("feature_new_table"):
+ comp_cls = NewTable
+ else:
+ comp_cls = OldTable
+
+ # Render the selected component
+ return comp_cls.render(
+ args=self.args,
+ kwargs=self.kwargs,
+ slots=self.slots,
+ context=context,
+ )
+```
+
+#### Post-processing rendered template
+
+When you render the original template in [`on_render()`](../../../reference/api#django_components.Component.on_render) as:
+
+```py
+template.render(context)
+```
+
+The result is NOT the final output, but an intermediate result. Nested components
+are not rendered yet.
+
+Instead, django-components needs to take this result and process it
+to actually render the child components.
+
+To access the final output, you can `yield` the result instead of returning it.
+
+This will return a tuple of (rendered HTML, error). The error is `None` if the rendering succeeded.
+
+```py
+class MyTable(Component):
+ def on_render(self, context, template):
+ html, error = yield template.render(context)
+
+ if error is None:
+ # The rendering succeeded
+ return html
+ else:
+ # The rendering failed
+ print(f"Error: {error}")
+```
+
+At this point you can do 3 things:
+
+1. Return a new HTML
+
+ The new HTML will be used as the final output.
+
+ If the original template raised an error, it will be ignored.
+
+ ```py
+ class MyTable(Component):
+ def on_render(self, context, template):
+ html, error = yield template.render(context)
+
+ return "NEW HTML"
+ ```
+
+2. Raise a new exception
+
+ The new exception is what will bubble up from the component.
+
+ The original HTML and original error will be ignored.
+
+ ```py
+ class MyTable(Component):
+ def on_render(self, context, template):
+ html, error = yield template.render(context)
+
+ raise Exception("Error message")
+ ```
+
+3. Return nothing (or `None`) to handle the result as usual
+
+ If you don't raise an exception, and neither return a new HTML,
+ then original HTML / error will be used:
+
+ - If rendering succeeded, the original HTML will be used as the final output.
+ - If rendering failed, the original error will be propagated.
+
+ ```py
+ class MyTable(Component):
+ def on_render(self, context, template):
+ html, error = yield template.render(context)
+
+ if error is not None:
+ # The rendering failed
+ print(f"Error: {error}")
+ ```
+
+#### Example: ErrorBoundary
+
+[`on_render()`](../../../reference/api#django_components.Component.on_render) can be used to
+implement React's [ErrorBoundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary).
+
+That is, a component that catches errors in nested components and displays a fallback UI instead:
+
+```django
+{% component "error_boundary" %}
+ {% fill "content" %}
+ {% component "nested_component" %}
+ {% endfill %}
+ {% fill "fallback" %}
+ Sorry, something went wrong.
+ {% endfill %}
+{% endcomponent %}
+```
+
+To implement this, we render the fallback slot in [`on_render()`](../../../reference/api#django_components.Component.on_render)
+and return it if an error occured:
+
+```djc_py
+class ErrorFallback(Component):
+ template = """
+ {% slot "content" default / %}
+ """
+
+ def on_render(self, context, template):
+ fallback = self.slots.fallback
+
+ if fallback is None:
+ raise ValueError("fallback slot is required")
+
+ html, error = yield template.render(context)
+
+ if error is not None:
+ return fallback()
+ else:
+ return html
+```
+
+### `on_render_after`
+
+```py
+def on_render_after(
+ self: Component,
+ context: Context,
+ template: Optional[Template],
+ result: Optional[str | SafeString],
+ error: Optional[Exception],
+) -> Union[str, SafeString, None]:
+```
+
+[`on_render_after()`](../../../reference/api#django_components.Component.on_render_after) runs when the component was fully rendered,
+including all its children.
+
+It receives the same arguments as [`on_render_before()`](#on_render_before),
+plus the outcome of the rendering:
+
+- `result`: The rendered output of the component. `None` if the rendering failed.
+- `error`: The error that occurred during the rendering, or `None` if the rendering succeeded.
+
+[`on_render_after()`](../../../reference/api#django_components.Component.on_render_after) behaves the same way
+as the second part of [`on_render()`](#on_render) (after the `yield`).
+
+```py
+class MyTable(Component):
+ def on_render_after(self, context, template, result, error):
+ if error is None:
+ # The rendering succeeded
+ return result
+ else:
+ # The rendering failed
+ print(f"Error: {error}")
+```
+
+Same as [`on_render()`](#on_render),
+you can return a new HTML, raise a new exception, or return nothing:
+
+1. Return a new HTML
+
+ The new HTML will be used as the final output.
+
+ If the original template raised an error, it will be ignored.
+
+ ```py
+ class MyTable(Component):
+ def on_render_after(self, context, template, result, error):
+ return "NEW HTML"
+ ```
+
+2. Raise a new exception
+
+ The new exception is what will bubble up from the component.
+
+ The original HTML and original error will be ignored.
+
+ ```py
+ class MyTable(Component):
+ def on_render_after(self, context, template, result, error):
+ raise Exception("Error message")
+ ```
+
+3. Return nothing (or `None`) to handle the result as usual
+
+ If you don't raise an exception, and neither return a new HTML,
+ then original HTML / error will be used:
+
+ - If rendering succeeded, the original HTML will be used as the final output.
+ - If rendering failed, the original error will be propagated.
+
+ ```py
+ class MyTable(Component):
+ def on_render_after(self, context, template, result, error):
+ if error is not None:
+ # The rendering failed
+ print(f"Error: {error}")
+ ```
+
+## Example
You can use hooks together with [provide / inject](#how-to-use-provide--inject) to create components
that accept a list of items via a slot.
In the example below, each `tab_item` component will be rendered on a separate tab page, but they are all defined in the default slot of the `tabs` component.
-[See here for how it was done](https://github.com/EmilStenstrom/django-components/discussions/540)
+[See here for how it was done](https://github.com/django-components/django-components/discussions/540)
```django
{% component "tabs" %}
diff --git a/docs/concepts/advanced/html_tragments.md b/docs/concepts/advanced/html_fragments.md
similarity index 72%
rename from docs/concepts/advanced/html_tragments.md
rename to docs/concepts/advanced/html_fragments.md
index 1b93c167..3ac8ea4b 100644
--- a/docs/concepts/advanced/html_tragments.md
+++ b/docs/concepts/advanced/html_fragments.md
@@ -1,13 +1,7 @@
----
-title: HTML fragments
-weight: 2
----
+Django-components provides a seamless integration with HTML fragments with AJAX ([HTML over the wire](https://hotwired.dev/)),
+whether you're using jQuery, HTMX, AlpineJS, vanilla JavaScript, or other.
-Django-components provides a seamless integration with HTML fragments ([HTML over the wire](https://hotwired.dev/)),
-whether you're using HTMX, AlpineJS, or vanilla JavaScript.
-
-When you define a component that has extra JS or CSS, and you use django-components
-to render the fragment, django-components will:
+If the fragment component has any JS or CSS, django-components will:
- Automatically load the associated JS and CSS
- Ensure that JS is loaded and executed only once even if the fragment is inserted multiple times
@@ -27,19 +21,23 @@ to render the fragment, django-components will:
4. A library like HTMX, AlpineJS, or custom function inserts the new HTML into
the correct place.
-## Document and fragment types
+## Document and fragment strategies
-Components support two modes of rendering - As a "document" or as a "fragment".
+Components support different ["strategies"](../../advanced/rendering_js_css#dependencies-strategies)
+for rendering JS and CSS.
+
+Two of them are used to enable HTML fragments - ["document"](../../advanced/rendering_js_css#document)
+and ["fragment"](../../advanced/rendering_js_css#fragment).
What's the difference?
-### Document mode
+### Document strategy
-Document mode assumes that the rendered components will be embedded into the HTML
+Document strategy assumes that the rendered components will be embedded into the HTML
of the initial page load. This means that:
- The JS and CSS is embedded into the HTML as `
+
+ ```
+
+- Components' secondary JS and CSS scripts
+ ([`Component.Media`](../../../reference/api/#django_components.Component.Media)) - inserted as links:
+
+ ```html
+
+
+ ```
+
+- A JS script is injected to manage component dependencies, enabling lazy loading of JS and CSS
+ for HTML fragments.
+
+!!! info
+
+ This strategy is required for fragments to work properly, as it sets up the dependency manager that fragments rely on.
+
+!!! note "How the dependency manager works"
+
+ The dependency manager is a JS script that keeps track of all the JS and CSS dependencies that have already been loaded.
+
+ When a fragment is inserted into the page, it will also insert a JSON `
+
+ ```
+
+- Components' secondary JS and CSS scripts
+ ([`Component.Media`](../../../reference/api/#django_components.Component.Media)) - inserted as links:
+
+ ```html
+
+
+ ```
+
+- No extra scripts are inserted.
+
+### `prepend`
+
+This is the same as [`"simple"`](#simple), but placeholders like [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies) and HTML tags `` and `` are all ignored. The JS and CSS are **always** inserted **before** the rendered content.
+
+```python
+html = MyComponent.render(deps_strategy="prepend")
+```
+
+**Location:**
+
+JS and CSS is **always** inserted before the rendered content.
+
+**Included scripts:**
+
+Same as for the [`"simple"`](#simple) strategy.
+
+### `append`
+
+This is the same as [`"simple"`](#simple), but placeholders like [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies) and HTML tags `` and `` are all ignored. The JS and CSS are **always** inserted **after** the rendered content.
+
+```python
+html = MyComponent.render(deps_strategy="append")
+```
+
+**Location:**
+
+JS and CSS is **always** inserted after the rendered content.
+
+**Included scripts:**
+
+Same as for the [`"simple"`](#simple) strategy.
+
+### `ignore`
+
+`deps_strategy="ignore"` is used when you do NOT want to process JS and CSS of the rendered HTML.
+
+```python
+html = MyComponent.render(deps_strategy="ignore")
+```
+
+The rendered HTML is left as-is. You can still process it with a different strategy later with `render_dependencies()`.
+
+This is useful when you want to insert rendered HTML into another component.
+
+```python
+html = MyComponent.render(deps_strategy="ignore")
+html = AnotherComponent.render(slots={"content": html})
+```
+
+## Manually rendering JS / CSS
+
+When rendering templates or components, django-components covers all the traditional ways how components
+or templates can be rendered:
+
+- [`Component.render()`](../../../reference/api/#django_components.Component.render)
+- [`Component.render_to_response()`](../../../reference/api/#django_components.Component.render_to_response)
+- [`Template.render()`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template.render)
+- [`django.shortcuts.render()`](https://docs.djangoproject.com/en/5.2/topics/http/shortcuts/#render)
+
+This way you don't need to manually handle rendering of JS / CSS.
+
+However, for advanced or low-level use cases, you may need to control when to render JS / CSS.
+
+In such case you can directly pass rendered HTML to [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies).
+
+This function will extract all used components in the HTML string, and insert the components' JS and CSS
+based on given strategy.
+
+!!! info
+
+ The truth is that all the methods listed above call [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies)
+ internally.
+
+**Example:**
+
+To see how [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies) works,
+let's render a template with a component.
+
+We will render it twice:
+
+- First time, we let `template.render()` handle the rendering.
+- Second time, we prevent `template.render()` from inserting the component's JS and CSS with `deps_strategy="ignore"`.
+
+ Instead, we pass the "unprocessed" HTML to `render_dependencies()` ourselves to insert the component's JS and CSS.
```python
from django.template.base import Template
from django.template.context import Context
-from django_component import render_dependencies
+from django_components import render_dependencies
template = Template("""
{% load component_tags %}
@@ -143,85 +402,30 @@ template = Template("""
""")
-rendered = template.render(Context())
-rendered = render_dependencies(rendered)
+rendered = template.render(Context({}))
+
+rendered2_raw = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+rendered2 = render_dependencies(rendered2_raw)
+
+assert rendered == rendered2
```
-Same applies if you render a template using Django's [`django.shortcuts.render`](https://docs.djangoproject.com/en/5.1/topics/http/shortcuts/#render):
+Same applies to other strategies and other methods of rendering:
```python
-from django.shortcuts import render
+raw_html = MyComponent.render(deps_strategy="ignore")
+html = render_dependencies(raw_html, deps_strategy="document")
-def my_view(request):
- rendered = render(request, "pages/home.html")
- rendered = render_dependencies(rendered)
- return rendered
+html2 = MyComponent.render(deps_strategy="document")
+
+assert html == html2
```
-Alternatively, when you render HTML with [`Component.render()`](#TODO)
-or [`Component.render_to_response()`](#TODO),
-these, by default, call [`render_dependencies()`](#TODO) for you, so you don't have to:
+## HTML fragments
-```python
-from django_components import Component
+Django-components provides a seamless integration with HTML fragments with AJAX ([HTML over the wire](https://hotwired.dev/)),
+whether you're using jQuery, HTMX, AlpineJS, vanilla JavaScript, or other.
-class MyButton(Component):
- ...
+This is achieved by the combination of the [`"document"`](#document) and [`"fragment"`](#fragment) strategies.
-# No need to call `render_dependencies()`
-rendered = MyButton.render()
-```
-
-#### Inserting pre-rendered HTML into another component
-
-In previous section we've shown that [`render_dependencies()`](#TODO) does NOT need to be called
-when you render a component via [`Component.render()`](#TODO).
-
-API of django_components makes it possible to compose components in a "React-like" way,
-where we pre-render a piece of HTML and then insert it into a larger structure.
-
-To do this, you must add [`render_dependencies=False`](#TODO) to the nested components:
-
-```python
-card_actions = CardActions.render(
- kwargs={"editable": editable},
- render_dependencies=False,
-)
-
-card = Card.render(
- slots={"actions": card_actions},
- render_dependencies=False,
-)
-
-page = MyPage.render(
- slots={"card": card},
-)
-```
-
-Why is `render_dependencies=False` required?
-
-This is a technical limitation of the current implementation.
-
-As mentioned earlier, each time we call [`Component.render()`](#TODO),
-we also call [`render_dependencies()`](#TODO).
-
-However, there is a problem here - When we call [`render_dependencies()`](#TODO)
-inside [`CardActions.render()`](#TODO),
-we extract and REMOVE the info on components' JS and CSS from the HTML. But the template
-of `CardActions` contains no `{% component_depedencies %}` tags, and nor `` nor `` HTML tags.
-So the component's JS and CSS will NOT be inserted, and will be lost.
-
-To work around this, you must set [`render_dependencies=False`](#TODO) when rendering pieces of HTML
-with [`Component.render()`](#TODO) and inserting them into larger structures.
-
-#### Summary
-
-1. Every time you render HTML that contained components, you have to call [`render_dependencies()`](#TODO)
- on the rendered output.
-2. There are several ways to call [`render_dependencies()`](#TODO):
- - Using the [`ComponentDependencyMiddleware`](#TODO) middleware
- - Rendering the HTML by calling [`Component.render()`](#TODO) with `render_dependencies=True` (default)
- - Rendering the HTML by calling [`Component.render_to_response()`](#TODO) (always renders dependencies)
- - Directly passing rendered HTML to [`render_dependencies()`](#TODO)
-3. If you pre-render one component to pass it into another, the pre-rendered component must be rendered with
- [`render_dependencies=False`](#TODO).
+Read more about [HTML fragments](../../advanced/html_fragments).
diff --git a/docs/concepts/advanced/tag_formatter.md b/docs/concepts/advanced/tag_formatters.md
similarity index 99%
rename from docs/concepts/advanced/tag_formatter.md
rename to docs/concepts/advanced/tag_formatters.md
index a5af24d6..c0d363f5 100644
--- a/docs/concepts/advanced/tag_formatter.md
+++ b/docs/concepts/advanced/tag_formatters.md
@@ -1,8 +1,3 @@
----
-title: Tag formatters
-weight: 7
----
-
## Customizing component tags with TagFormatter
_New in version 0.89_
diff --git a/docs/concepts/advanced/template_tags.md b/docs/concepts/advanced/template_tags.md
new file mode 100644
index 00000000..ff40181c
--- /dev/null
+++ b/docs/concepts/advanced/template_tags.md
@@ -0,0 +1,196 @@
+Template tags introduced by django-components, such as `{% component %}` and `{% slot %}`,
+offer additional features over the default Django template tags:
+
+
+- [Self-closing tags `{% mytag / %}`](../../fundamentals/template_tag_syntax#self-closing-tags)
+- [Allowing the use of `:`, `-` (and more) in keys](../../fundamentals/template_tag_syntax#special-characters)
+- [Spread operator `...`](../../fundamentals/template_tag_syntax#spread-operator)
+- [Using template tags as inputs to other template tags](../../fundamentals/template_tag_syntax#use-template-tags-inside-component-inputs)
+- [Flat definition of dictionaries `attr:key=val`](../../fundamentals/template_tag_syntax#pass-dictonary-by-its-key-value-pairs)
+- Function-like input validation
+
+You too can easily create custom template tags that use the above features.
+
+## Defining template tags with `@template_tag`
+
+The simplest way to create a custom template tag is using
+the [`template_tag`](../../../reference/api#django_components.template_tag) decorator.
+This decorator allows you to define a template tag by just writing a function that returns the rendered content.
+
+```python
+from django.template import Context, Library
+from django_components import BaseNode, template_tag
+
+library = Library()
+
+@template_tag(
+ library,
+ tag="mytag",
+ end_tag="endmytag",
+ allowed_flags=["required"]
+)
+def mytag(node: BaseNode, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+```
+
+This will allow you to use the tag in your templates like this:
+
+```django
+{% mytag name="John" %}
+{% endmytag %}
+
+{# or with self-closing syntax #}
+{% mytag name="John" / %}
+
+{# or with flags #}
+{% mytag name="John" required %}
+{% endmytag %}
+```
+
+### Parameters
+
+The [`@template_tag`](../../../reference/api#django_components.template_tag) decorator accepts the following parameters:
+
+- `library`: The Django template library to register the tag with
+- `tag`: The name of the template tag (e.g. `"mytag"` for `{% mytag %}`)
+- `end_tag`: Optional. The name of the end tag (e.g. `"endmytag"` for `{% endmytag %}`)
+- `allowed_flags`: Optional. List of flags that can be used with the tag (e.g. `["required"]` for `{% mytag required %}`)
+
+### Function signature
+
+The function decorated with [`@template_tag`](../../../reference/api#django_components.template_tag)
+must accept at least two arguments:
+
+1. `node`: The node instance (we'll explain this in detail in the next section)
+2. `context`: The Django template context
+
+Any additional parameters in your function's signature define what inputs your template tag accepts. For example:
+
+```python
+@template_tag(library, tag="greet")
+def greet(
+ node: BaseNode,
+ context: Context,
+ name: str, # required positional argument
+ count: int = 1, # optional positional argument
+ *, # keyword-only arguments marker
+ msg: str, # required keyword argument
+ mode: str = "default", # optional keyword argument
+) -> str:
+ return f"{msg}, {name}!" * count
+```
+
+This allows the tag to be used like:
+
+```django
+{# All parameters #}
+{% greet "John" count=2 msg="Hello" mode="custom" %}
+
+{# Only required parameters #}
+{% greet "John" msg="Hello" %}
+
+{# Missing required parameter - will raise error #}
+{% greet "John" %} {# Error: missing 'msg' #}
+```
+
+When you pass input to a template tag, it behaves the same way as if you passed the input to a function:
+
+- If required parameters are missing, an error is raised
+- If unexpected parameters are passed, an error is raised
+
+To accept keys that are not valid Python identifiers (e.g. `data-id`), or would conflict with Python keywords (e.g. `is`), you can use the `**kwargs` syntax:
+
+```python
+@template_tag(library, tag="greet")
+def greet(
+ node: BaseNode,
+ context: Context,
+ **kwargs,
+) -> str:
+ attrs = kwargs.copy()
+ is_var = attrs.pop("is", None)
+ attrs_str = " ".join(f'{k}="{v}"' for k, v in attrs.items())
+
+ return mark_safe(f"""
+ , got 1.25 of type
-```
-
-In case you need to skip these errors, you can either set the faulty member to `Any`, e.g.:
-
-```py
-# Changed `int` to `Any`
-Args = Tuple[Any, str]
-```
-
-Or you can replace `Args` with `Any` altogether, to skip the validation of args:
-
-```py
-# Replaced `Args` with `Any`
-class Button(Component[Any, Kwargs, Slots, Data, JsData, CssData]):
- ...
-```
-
-Same applies to kwargs, data, and slots.
diff --git a/docs/concepts/fundamentals/.nav.yml b/docs/concepts/fundamentals/.nav.yml
new file mode 100644
index 00000000..d88500a4
--- /dev/null
+++ b/docs/concepts/fundamentals/.nav.yml
@@ -0,0 +1,17 @@
+# `.nav.yml` is provided by https://lukasgeiter.github.io/mkdocs-awesome-nav
+nav:
+ - Single-file components: single_file_components.md
+ - HTML / JS / CSS files: html_js_css_files.md
+ - HTML / JS / CSS variables: html_js_css_variables.md
+ - Secondary JS / CSS files: secondary_js_css_files.md
+ - Component defaults: component_defaults.md
+ - Render API: render_api.md
+ - Rendering components: rendering_components.md
+ - Slots: slots.md
+ - Template tag syntax: template_tag_syntax.md
+ - HTML attributes: html_attributes.md
+ - Component views and URLs: component_views_urls.md
+ - HTTP Request: http_request.md
+ - Typing and validation: typing_and_validation.md
+ - Subclassing components: subclassing_components.md
+ - Autodiscovery: autodiscovery.md
diff --git a/docs/concepts/fundamentals/access_component_input.md b/docs/concepts/fundamentals/access_component_input.md
deleted file mode 100644
index 6bba6117..00000000
--- a/docs/concepts/fundamentals/access_component_input.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Accessing component inputs
-weight: 3
----
-
-When you call `Component.render` or `Component.render_to_response`, the inputs to these methods can be accessed from within the instance under `self.input`.
-
-This means that you can use `self.input` inside:
-
-- `get_context_data`
-- `get_template_name`
-- `get_template`
-- `on_render_before`
-- `on_render_after`
-
-`self.input` is only defined during the execution of `Component.render`, and raises a `RuntimeError` when called outside of this context.
-
-`self.input` has the same fields as the input to `Component.render`:
-
-```python
-class TestComponent(Component):
- def get_context_data(self, var1, var2, variable, another, **attrs):
- assert self.input.args == (123, "str")
- assert self.input.kwargs == {"variable": "test", "another": 1}
- assert self.input.slots == {"my_slot": "MY_SLOT"}
- assert isinstance(self.input.context, Context)
-
- return {
- "variable": variable,
- }
-
-rendered = TestComponent.render(
- kwargs={"variable": "test", "another": 1},
- args=(123, "str"),
- slots={"my_slot": "MY_SLOT"},
-)
-```
-
-NOTE: The slots in `self.input.slots` are normalized to slot functions.
diff --git a/docs/concepts/fundamentals/autodiscovery.md b/docs/concepts/fundamentals/autodiscovery.md
index 8ab8a188..452db11a 100644
--- a/docs/concepts/fundamentals/autodiscovery.md
+++ b/docs/concepts/fundamentals/autodiscovery.md
@@ -1,11 +1,15 @@
----
-title: Autodiscovery
-weight: 9
----
+django-components automatically searches for files containing components in the
+[`COMPONENTS.dirs`](../../../reference/settings#django_components.app_settings.ComponentsSettings.dirs) and
+[`COMPONENTS.app_dirs`](../../../reference/settings#django_components.app_settings.ComponentsSettings.app_dirs)
+directories.
-Every component that you want to use in the template with the [`{% component %}`](django_components.templateags.component_tags)
-tag needs to be registered with the [`ComponentRegistry`](django_components.component_registry.ComponentRegistry).
-Normally, we use the [`@register`](django_components.component_registry.register) decorator for that:
+### Manually register components
+
+Every component that you want to use in the template with the
+[`{% component %}`](../../../reference/template_tags#component)
+tag needs to be registered with the [`ComponentRegistry`](../../../reference/api#django_components.ComponentRegistry).
+
+We use the [`@register`](../../../reference/api#django_components.register) decorator for that:
```python
from django_components import Component, register
@@ -15,7 +19,9 @@ class Calendar(Component):
...
```
-But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
+But for the component to be registered, the code needs to be executed - and for that, the file needs to be imported as a module.
+
+This is the "discovery" part of the process.
One way to do that is by importing all your components in `apps.py`:
@@ -35,22 +41,28 @@ class MyAppConfig(AppConfig):
However, there's a simpler way!
-By default, the Python files in the [`COMPONENTS.dirs`](django_components.app_settings.ComponentsSettings.dirs) directories (and app-level [`[app]/components/`](django_components.app_settings.ComponentsSettings.app_dirs)) are auto-imported in order to auto-register the components.
+### Autodiscovery
-Autodiscovery occurs when Django is loaded, during the [`AppConfig.ready`](https://docs.djangoproject.com/en/5.1/ref/applications/#django.apps.AppConfig.ready)
+By default, the Python files found in the
+[`COMPONENTS.dirs`](../../../reference/settings#django_components.app_settings.ComponentsSettings.dirs) and
+[`COMPONENTS.app_dirs`](../../../reference/settings#django_components.app_settings.ComponentsSettings.app_dirs)
+are auto-imported in order to execute the code that registers the components.
+
+Autodiscovery occurs when Django is loaded, during the [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.ready)
hook of the `apps.py` file.
If you are using autodiscovery, keep a few points in mind:
-- Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
-- Components inside the auto-imported files still need to be registered with [`@register`](django_components.component_registry.register)p
+- Avoid defining any logic on the module-level inside the components directories, that you would not want to run anyway.
+- Components inside the auto-imported files still need to be registered with [`@register`](../../../reference/api#django_components.register)
- Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
+- Subdirectories and files starting with an underscore `_` (except `__init__.py`) are ignored.
-Autodiscovery can be disabled in the [settings](django_components.app_settings.ComponentsSettings.autodiscovery).
+Autodiscovery can be disabled in the settings with [`autodiscover=False`](../../../reference/settings#django_components.app_settings.ComponentsSettings.autodiscover).
### Manually trigger autodiscovery
-Autodiscovery can be also triggered manually, using the [`autodiscover`](django_components.autodiscovery.autodiscover) function. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
+Autodiscovery can be also triggered manually, using the [`autodiscover()`](../../../reference/api#django_components.autodiscover) function. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
```python
from django_components import autodiscover
diff --git a/docs/concepts/fundamentals/component_defaults.md b/docs/concepts/fundamentals/component_defaults.md
new file mode 100644
index 00000000..a57daf45
--- /dev/null
+++ b/docs/concepts/fundamentals/component_defaults.md
@@ -0,0 +1,153 @@
+When a component is being rendered, the component inputs are passed to various methods like
+[`get_template_data()`](../../../reference/api#django_components.Component.get_template_data),
+[`get_js_data()`](../../../reference/api#django_components.Component.get_js_data),
+or [`get_css_data()`](../../../reference/api#django_components.Component.get_css_data).
+
+It can be cumbersome to specify default values for each input in each method.
+
+To make things easier, Components can specify their defaults. Defaults are used when
+no value is provided, or when the value is set to `None` for a particular input.
+
+### Defining defaults
+
+To define defaults for a component, you create a nested [`Defaults`](../../../reference/api#django_components.Component.Defaults)
+class within your [`Component`](../../../reference/api#django_components.Component) class.
+Each attribute in the `Defaults` class represents a default value for a corresponding input.
+
+```py
+from django_components import Component, Default, register
+
+@register("my_table")
+class MyTable(Component):
+
+ class Defaults:
+ position = "left"
+ selected_items = Default(lambda: [1, 2, 3])
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "position": kwargs["position"],
+ "selected_items": kwargs["selected_items"],
+ }
+
+ ...
+```
+
+In this example, `position` is a simple default value, while `selected_items` uses a factory function wrapped in [`Default`](../../../reference/api#django_components.Default) to ensure a new list is created each time the default is used.
+
+Now, when we render the component, the defaults will be applied:
+
+```django
+{% component "my_table" position="right" / %}
+```
+
+In this case:
+
+- `position` input is set to `right`, so no defaults applied
+- `selected_items` is not set, so it will be set to `[1, 2, 3]`.
+
+Same applies to rendering the Component in Python with the
+[`render()`](../../../reference/api#django_components.Component.render) method:
+
+```py
+MyTable.render(
+ kwargs={
+ "position": "right",
+ "selected_items": None,
+ },
+)
+```
+
+Notice that we've set `selected_items` to `None`. `None` values are treated as missing values,
+and so `selected_items` will be set to `[1, 2, 3]`.
+
+!!! warning
+
+ The defaults are aplied only to keyword arguments. They are NOT applied to positional arguments!
+
+!!! warning
+
+ When [typing](../fundamentals/typing_and_validation.md) 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.
+
+### Default factories
+
+For objects such as lists, dictionaries or other instances, you have to be careful - if you simply set a default value, this instance will be shared across all instances of the component!
+
+```py
+from django_components import Component
+
+class MyTable(Component):
+ class Defaults:
+ # All instances will share the same list!
+ selected_items = [1, 2, 3]
+```
+
+To avoid this, you can use a factory function wrapped in [`Default`](../../../reference/api#django_components.Default).
+
+```py
+from django_components import Component, Default
+
+class MyTable(Component):
+ class Defaults:
+ # A new list is created for each instance
+ selected_items = Default(lambda: [1, 2, 3])
+```
+
+This is similar to how the dataclass fields work.
+
+In fact, you can also use the dataclass's [`field`](https://docs.python.org/3/library/dataclasses.html#dataclasses.field) function to define the factories:
+
+```py
+from dataclasses import field
+from django_components import Component
+
+class MyTable(Component):
+ class Defaults:
+ selected_items = field(default_factory=lambda: [1, 2, 3])
+```
+
+### Accessing defaults
+
+Since the defaults are defined on the component class, you can access the defaults for a component with the [`Component.Defaults`](../../../reference/api#django_components.Component.Defaults) property.
+
+So if we have a component like this:
+
+```py
+from django_components import Component, Default, register
+
+@register("my_table")
+class MyTable(Component):
+
+ class Defaults:
+ position = "left"
+ selected_items = Default(lambda: [1, 2, 3])
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "position": kwargs["position"],
+ "selected_items": kwargs["selected_items"],
+ }
+```
+
+We can access individual defaults like this:
+
+```py
+print(MyTable.Defaults.position)
+print(MyTable.Defaults.selected_items)
+```
diff --git a/docs/concepts/fundamentals/component_views_urls.md b/docs/concepts/fundamentals/component_views_urls.md
new file mode 100644
index 00000000..f8398749
--- /dev/null
+++ b/docs/concepts/fundamentals/component_views_urls.md
@@ -0,0 +1,151 @@
+_New in version 0.34_
+
+_Note: Since 0.92, `Component` is no longer a subclass of Django's `View`. Instead, the nested
+[`Component.View`](../../../reference/api#django_components.Component.View) class is a subclass of Django's `View`._
+
+---
+
+For web applications, it's common to define endpoints that serve HTML content (AKA views).
+
+django-components has a suite of features that help you write and manage views and their URLs:
+
+- For each component, you can define methods for handling HTTP requests (GET, POST, etc.) - `get()`, `post()`, etc.
+
+- Use [`Component.as_view()`](../../../reference/api#django_components.Component.as_view) to be able to use your Components with Django's [`urlpatterns`](https://docs.djangoproject.com/en/5.2/topics/http/urls/). This works the same way as [`View.as_view()`](https://docs.djangoproject.com/en/5.2/ref/class-based-views/base/#django.views.generic.base.View.as_view).
+
+- To avoid having to manually define the endpoints for each component, you can set the component to be "public" with [`Component.View.public = True`](../../../reference/api#django_components.ComponentView.public). This will automatically create a URL for the component. To retrieve the component URL, use [`get_component_url()`](../../../reference/api#django_components.get_component_url).
+
+- In addition, [`Component`](../../../reference/api#django_components.Component) has a [`render_to_response()`](../../../reference/api#django_components.Component.render_to_response) method that renders the component template based on the provided input and returns an `HttpResponse` object.
+
+## Define handlers
+
+Here's an example of a calendar component defined as a view. Simply define a `View` class with your custom `get()` method to handle GET requests:
+
+```djc_py title="[project root]/components/calendar.py"
+from django_components import Component, ComponentView, register
+
+@register("calendar")
+class Calendar(Component):
+ template = """
+
```
-You can simplify it with `html_attrs` tag:
+You can rewrite it with the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag:
+
+```django
+
```
-where `attrs` is:
+Then this renders:
-```py
-attrs = {
- "class": classes,
- "data-id": my_id,
-}
+```html
+
```
-This feature is inspired by [`merge_attrs` tag of django-web-components](https://github.com/Xzya/django-web-components/tree/master?tab=readme-ov-file#default--merged-attributes) and
-["fallthrough attributes" feature of Vue](https://vuejs.org/guide/components/attrs).
+### Removing attributes
-## Removing atttributes
-
-Attributes that are set to `None` or `False` are NOT rendered.
+Given how the boolean attributes work, you can "remove" or prevent an attribute from being rendered by setting it to `False` or `None`.
So given this input:
@@ -61,41 +202,9 @@ Then this renders:
```
-## Boolean attributes
+### Default attributes
-In HTML, boolean attributes are usually rendered with no value. Consider the example below where the first button is disabled and the second is not:
-
-```html
-
-```
-
-HTML rendering with `html_attrs` tag or `attributes_to_string` works the same way, where `key=True` is rendered simply as `key`, and `key=False` is not render at all.
-
-So given this input:
-
-```py
-attrs = {
- "disabled": True,
- "autofocus": False,
-}
-```
-
-And template:
-
-```django
-
- `{% html_attr %}` +- **Empty tag** + + ```django + + ``` - renders (empty string):
- ` ` + renders nothing: -- Only kwargs
- `{% html_attr class="some-class" class=class_from_var data-id="123" %}` + ```html + + ``` - renders:
- `class="some-class from-var" data-id="123"` +- **Only kwargs** + + ```django + + ``` -- Only attrs
- `{% html_attr attrs %}` + renders: - renders:
- `class="from-attrs" type="submit"` + ```html + + ``` -- Attrs as kwarg
- `{% html_attr attrs=attrs %}` +- **Only attrs** - renders:
- `class="from-attrs" type="submit"` + ```django + + ``` -- Only defaults (as kwarg)
- `{% html_attr defaults=defaults %}` + renders: - renders:
- `class="from-defaults" role="button"` + ```html + + ``` -- Attrs using the `prefix:key=value` construct
- `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}` +- **Attrs as kwarg** - renders:
- `class="from-attrs" type="submit"` + ```django + + ``` -- Defaults using the `prefix:key=value` construct
- `{% html_attr defaults:class="from-defaults" %}` + renders: - renders:
- `class="from-defaults" role="button"` + ```html + + ``` -- All together (1) - attrs and defaults as positional args:
- `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}` +- **Only defaults (as kwarg)** - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` + ```django + + ``` -- All together (2) - attrs and defaults as kwargs args:
- `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}` + renders: - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` + ```html + + ``` -- All together (3) - mixed:
- `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}` +- **Attrs using the `prefix:key=value` construct** - renders:
- `class="from-attrs added_class from-var" type="submit" data-id=123` + ```django + + ``` -## Full example for `html_attrs` + renders: -```py + ```html + + ``` + +- **Defaults using the `prefix:key=value` construct** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (1) - attrs and defaults as positional args:** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (2) - attrs and defaults as kwargs args:** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (3) - mixed:** + + ```django + + ``` + + renders: + + ```html + + ``` + +## Full example + +```djc_py @register("my_comp") class MyComp(Component): template: t.django_html = """ @@ -272,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"
}
@@ -290,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})
@@ -301,7 +637,9 @@ Note: For readability, we've split the tags across multiple lines.
Inside `MyComp`, we defined a default attribute
-`defaults:class="pa-4 text-red"`
+```
+defaults:class="pa-4 text-red"
+```
So if `attrs` includes key `class`, the default above will be ignored.
@@ -332,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 = {
@@ -357,22 +695,3 @@ So in the end `MyComp` will render:
...
');
+ var group_button = $('');
+ if (params.grouped) {
+ group_button.text('Ungroup regressions');
+ group_button.on('click', function(evt) {
+ update_url({'grouped': []});
+ });
+ }
+ else {
+ group_button.text('Group regressions');
+ group_button.on('click', function(evt) {
+ update_url({'grouped': ["true"]});
+ });
+ }
+ group_div.append(group_button);
+ main_div.append(group_div);
+
+ $.each(branches, function(i, branch) {
+ var branch_div = $('')
+
+ var display_table = $('
');
+ var ignored_table = $('
');
+ var ignored_button = $('');
+ var ignored_conf_sample_div = $('');
+
+ if (branches && branches.length > 1) {
+ var branch_link = $('')
+ branch_link.text(branch);
+
+ dropdown_menu.append($('').append(branch_link));
+ branch_link.on('click', function(evt) {
+ current_title = "Regressions in " + branch + " branch";
+ update_url({'branch': [branch]}, false);
+ $("#title").text(current_title);
+ $(".regression-div").hide();
+ $(".ignored").hide();
+ ignored_button.show();
+ $("#regression-div-" + i).show();
+ $("#regression-div-" + i + '-ignored').show();
+ });
+ }
+ else {
+ branch = null;
+ }
+
+ branch_div.attr('id', 'regression-div-' + i);
+ branch_div.hide();
+ main_div.append(branch_div);
+
+ if (params.grouped) {
+ create_grouped_data_table(display_table, ignored_table, ignored_conf_sample_div,
+ data, params, branch, all_ignored_keys);
+ }
+ else {
+ create_data_table(display_table, ignored_table, ignored_conf_sample_div,
+ data, params, branch, all_ignored_keys);
+ }
+ branch_div.append(display_table);
+ ignored_table.hide();
+ ignored_conf_sample_div.hide();
+
+ branch_div.append(ignored_table);
+ branch_div.append(ignored_conf_sample_div);
+
+ update_ignore_conf_sample(data, ignored_conf_sample_div, branch);
+
+ branch_div.append(ignored_button);
+ ignored_button.on('click', function(evt) {
+ ignored_button.hide();
+ $(".ignored").show();
+ });
+ });
+
+ var branch_index = 0;
+ if (branches && branches.length > 1) {
+ if (params.branch) {
+ branch_index = branches.indexOf(params.branch[0]);
+ if (branch_index < 0) {
+ branch_index = 0;
+ }
+ }
+ current_title = "Regressions in " + branches[branch_index] + " branch";
+ }
+ $("#title").text(current_title);
+ main_div.find("#regression-div-" + branch_index).show();
+ main_div.show();
+
+ if (local_storage_available) {
+ /* Clear out local storage space */
+ var keys = Object.keys(localStorage);
+ $.each(keys, function(i, key) {
+ if (key.slice(0, ignore_key_prefix.length) == ignore_key_prefix &&
+ !all_ignored_keys[key]) {
+ delete localStorage[key];
+ }
+ });
+ }
+
+ return main_div;
+ }
+
+ function create_data_table(display_table, ignored_table, ignored_conf_sample_div,
+ data, params, branch, all_ignored_keys) {
+ var table_head = $('' +
+ 'Benchmark ' +
+ 'Date ' +
+ 'Commit ' +
+ 'Factor ' +
+ 'Before ' +
+ 'Best after ' +
+ ' ');
+
+ display_table.append(table_head);
+ ignored_table.append(table_head.clone());
+
+ var table_body = $('');
+ var ignored_table_body = $('');
+
+ var regressions = data['regressions'];
+
+ $.each(regressions, function (i, item) {
+ var benchmark_name = item[0];
+ var graph_url = item[1];
+ var param_dict = item[2];
+ var parameter_idx = item[3];
+ var last_value = item[4];
+ var best_value = item[5];
+ var jumps = item[6]; // [[rev1, rev2, before, after], ...]
+
+ if (jumps === null) {
+ return;
+ }
+
+ if (branch !== null && param_dict['branch'] != branch) {
+ return;
+ }
+
+ var benchmark_basename = benchmark_name.replace(/\([\s\S]*/, '');
+ var benchmark = $.asv.main_json.benchmarks[benchmark_basename];
+ var url_params = {};
+
+ $.each(param_dict, function (key, value) {
+ url_params[key] = [value];
+ });
+
+ if (parameter_idx !== null) {
+ $.each($.asv.param_selection_from_flat_idx(benchmark.params, parameter_idx).slice(1), function(i, param_values) {
+ url_params['p-'+benchmark.param_names[i]] = [benchmark.params[i][param_values[0]]];
+ });
+ }
+
+ $.each(jumps, function(i, revs) {
+ var row = $('' +
+ 'Benchmark ' +
+ 'Last date ' +
+ 'Commits ' +
+ 'Factor ' +
+ 'Best ' +
+ 'Current ' +
+ ' ');
+
+ display_table.append(table_head);
+ ignored_table.append(table_head.clone());
+
+ var table_body = $('');
+ var regressions = data['regressions'];
+
+ $.each(regressions, function (i, item) {
+ var benchmark_name = item[0];
+ var graph_url = item[1];
+ var param_dict = item[2];
+ var parameter_idx = item[3];
+ var last_value = item[4];
+ var best_value = item[5];
+ var jumps = item[6]; // [[rev1, rev2, before, after], ...]
+
+ if (jumps === null) {
+ return;
+ }
+
+ if (branch !== null && param_dict['branch'] != branch) {
+ return;
+ }
+
+ var benchmark_basename = benchmark_name.replace(/\(.*/, '');
+ var benchmark = $.asv.main_json.benchmarks[benchmark_basename];
+ var url_params = {};
+
+ $.each(param_dict, function (key, value) {
+ url_params[key] = [value];
+ });
+
+ if (parameter_idx !== null) {
+ $.each($.asv.param_selection_from_flat_idx(benchmark.params, parameter_idx).slice(1), function(i, param_values) {
+ url_params['p-'+benchmark.param_names[i]] = [benchmark.params[i][param_values[0]]];
+ });
+ }
+
+ url_params.commits = [];
+
+ var commit_td = $('tag:django-components.asv,1970-01-01:/cddbdcca8b398afd301fbfc73cc4d51103d4e3059c0e6b938d4c467ad3d1aa25 Airspeed Velocity django-components performance regressions 2025-06-04T22:41:21Z tag:django-components.asv,2025-06-04:/38b868a38890eb5bccfd51983abf3a15cedf2846ef6cf2452e941122dbde2bde 17.14% Components vs Django.timeraw_render_lg_subsequent('django') 2025-06-04T22:41:21Z <a href="index.html#Components vs Django.timeraw_render_lg_subsequent?p-renderer=%27django%27&commits=4c909486069f3c3c8ee7915239174f820f081da4-7b24b86f4a836c697acba926d9d6602afa45418d">17.14% regression</a> on 2025-06-04 22:35:21 in commits <a href="#4c909486069f3c3c8ee7915239174f820f081da4">4c909486...7b24b86f</a>.<br>
+ New value: 43.6ms, old value: 37.2ms.<br>
+ Latest value: 43.6ms (31.10% worse
+ than best value 33.3ms). tag:django-components.asv,2025-03-31:/7a13128cbc4d175ca09ebda40e8a303789275bd84b00a5d496cfa08a26ad2f8b 11.92% Components vs Django.timeraw_render_lg_subsequent('django') 2025-03-31T14:16:53Z <a href="index.html#Components vs Django.timeraw_render_lg_subsequent?p-renderer=%27django%27&commits=42818ad6ffb47bd650d8a379b84c3d48394f9f77-a6455d70f6c28ddbd4be8e58902f6cbc101e5ff3">11.92% regression</a> on 2025-03-31 14:10:42 in commits <a href="#42818ad6ffb47bd650d8a379b84c3d48394f9f77">42818ad6...a6455d70</a>.<br>
+ New value: 37.2ms, old value: 33.3ms.<br>
+ Latest value: 43.6ms (31.10% worse
+ than best value 33.3ms).
'); + + button.tooltip({ + title: details, + html: true, + placement: 'right', + container: 'body', + animation: false + }); + }); + + /* Generic parameter selectors */ + $.each(index.params, function(param, values) { + if (values.length > 1 && param != 'machine') { + $.asv.ui.make_value_selector_panel(nav, param, values, function(i, value, button) { + var value_display; + if (value === null) + value_display = '[none]'; + else if (!value) + value_display = '[default]'; + else + value_display = value; + + button.text(value_display); + + if (state[param] != value) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + update_state_url(param, value); + }); + }); + } + }); + + $(nav).find(".btn-group").removeAttr("data-toggle"); + + $.asv.ui.reflow_value_selector_panels(); + } + + function construct_benchmark_table(data) { + var index = $.asv.main_json; + + /* Form a new table */ + + var table = $('
');
+
+ var table_head = $('' +
+ 'Benchmark ' +
+ 'Value ' +
+ 'Recent change ' +
+ 'Changed at ' +
+ ' ');
+ table.append(table_head);
+
+ var table_body = $('');
+
+ $.each(data, function(row_idx, row) {
+ var tr = $('
```
-Assuming that the rendering context has variables such as `date`, you can use `self.outer_context` to access them from within `get_context_data`. Here's how you might implement it:
+Assuming that the rendering context has variables such as `date`, you can use `self.outer_context` to access them from within `get_template_data`. Here's how you might implement it:
```python
class Calender(Component):
...
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
outer_field = self.outer_context["date"]
return {
"date": outer_fields,
@@ -58,10 +53,10 @@ This has two modes:
you can access are a union of:
- All the variables that were OUTSIDE the fill tag, including any\
- [`{% with %}`](https://docs.djangoproject.com/en/5.1/ref/templates/builtins/#with) tags.
- - Any loops ([`{% for ... %}`](https://docs.djangoproject.com/en/5.1/ref/templates/builtins/#cycle))
+ [`{% with %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#with) tags.
+ - Any loops ([`{% for ... %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#cycle))
that the `{% fill %}` tag is part of.
- - Data returned from [`Component.get_context_data()`](../../../reference/api#django_components.Component.get_context_data)
+ - Data returned from [`Component.get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
of the component that owns the fill tag.
- `"isolated"`
@@ -72,22 +67,22 @@ This has two modes:
Inside the [`{% fill %}`](../../../reference/template_tags#fill) tag, you can ONLY access variables from 2 places:
- - Any loops ([`{% for ... %}`](https://docs.djangoproject.com/en/5.1/ref/templates/builtins/#cycle))
+ - Any loops ([`{% for ... %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#cycle))
that the `{% fill %}` tag is part of.
- - [`Component.get_context_data()`](../../../reference/api#django_components.Component.get_context_data)
+ - [`Component.get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
of the component which defined the template (AKA the "root" component).
!!! warning
- Notice that the component whose `get_context_data()` we use inside
+ Notice that the component whose `get_template_data()` we use inside
[`{% fill %}`](../../../reference/template_tags#fill)
is NOT the same across the two modes!
Consider this example:
- ```python
+ ```djc_py
class Outer(Component):
- template = \"\"\"
+ template = """
' + display_name + '
');
+ name.tooltip({
+ title: bm.name,
+ html: true,
+ placement: 'top',
+ container: 'body',
+ animation: false
+ });
+
+ plot_div.tooltip({
+ title: bm.code,
+ html: true,
+ placement: 'bottom',
+ container: 'body',
+ animation: false
+ });
+
+ container.append(name);
+ container.append(plot_div);
+
+ callback_in_view(plot_div, function() {
+ $.asv.load_graph_data(
+ 'graphs/summary/' + bm.name + '.json'
+ ).done(function(data) {
+ var options = {
+ colors: $.asv.colors,
+ series: {
+ lines: {
+ show: true,
+ lineWidth: 2
+ },
+ shadowSize: 0
+ },
+ grid: {
+ borderWidth: 1,
+ margin: 0,
+ labelMargin: 0,
+ axisMargin: 0,
+ minBorderMargin: 0
+ },
+ xaxis: {
+ ticks: [],
+ },
+ yaxis: {
+ ticks: [],
+ min: 0
+ },
+ legend: {
+ show: false
+ }
+ };
+
+ var plot = $.plot(
+ plot_div, [{data: data}], options);
+ }).fail(function() {
+ // TODO: Handle failure
+ });
+ });
+ return container;
+ }
+
+ function make_summary() {
+ var summary_display = $('#summarygrid-display');
+ var main_json = $.asv.main_json;
+ var summary_container = $('');
+
+ if (summary_loaded) {
+ return;
+ }
+
+ $.each(get_benchmarks_by_groups(), function(group, benchmarks) {
+ var group_container = $('')
+ group_container.attr('id', 'group-' + group)
+ group_container.append($('' + group + '
')); + summary_display.append(group_container); + $.each(benchmarks, function(i, bm_name) { + var bm = $.asv.main_json.benchmarks[bm_name]; + group_container.append(benchmark_container(bm)); + }); + }); + + summary_display.append(summary_container); + $(window).trigger('scroll'); + + summary_loaded = true; + } + + $.asv.register_page('', function(params) { + $('#summarygrid-display').show(); + $("#title").text("All benchmarks"); + $('.tooltip').remove(); + make_summary(); + }); +}); diff --git a/docs/benchmarks/summarylist.css b/docs/benchmarks/summarylist.css new file mode 100644 index 00000000..93854336 --- /dev/null +++ b/docs/benchmarks/summarylist.css @@ -0,0 +1,50 @@ +#summarylist-body { + padding-left: 2em; + padding-right: 2em; + padding-top: 1em; + padding-bottom: 2em; +} + +#summarylist-body table thead th { + cursor: pointer; + white-space: nowrap; +} + +#summarylist-body table thead th.desc:after { + content: ' \2191'; +} + +#summarylist-body table thead th.asc:after { + content: ' \2193'; +} + +#summarylist-body table.ignored { + padding-top: 1em; + color: #ccc; + background-color: #eee; +} + +#summarylist-body table.ignored a { + color: #82abda; +} + +#summarylist-body table tbody td.positive-change { + background-color: #fdd; +} + +#summarylist-body table tbody td.negative-change { + background-color: #dfd; +} + +#summarylist-body table tbody td.value { + white-space: nowrap; +} + +#summarylist-body table tbody td.change a { + color: black; + white-space: nowrap; +} + +#summarylist-body table tbody td.change-date { + white-space: nowrap; +} diff --git a/docs/benchmarks/summarylist.js b/docs/benchmarks/summarylist.js new file mode 100644 index 00000000..e5f9e13c --- /dev/null +++ b/docs/benchmarks/summarylist.js @@ -0,0 +1,451 @@ +'use strict'; + +$(document).ready(function() { + /* The state of the parameters in the sidebar. Dictionary mapping + strings to values determining the "enabled" configurations. */ + var state = null; + /* Cache of constructed tables, {data_path: table_dom_id} */ + var table_cache = {}; + var table_cache_counter = 0; + + function setup_display(state_selection) { + var new_state = setup_state(state_selection); + var same_state = (state !== null); + + /* Avoid needless UI updates, e.g., on table sort */ + + if (same_state) { + $.each(state, function (key, value) { + if (value != new_state[key]) { + same_state = false; + } + }); + } + + if (!same_state) { + state = new_state; + replace_params_ui(); + + var filename = $.asv.graph_to_path('summary', state); + + $("#summarylist-body table").hide(); + $("#summarylist-body .message").remove(); + + if (table_cache[filename] !== undefined) { + $(table_cache[filename]).show(); + } + else { + $("#summarylist-body").append($("")); + $.asv.load_graph_data( + filename + ).done(function (data) { + var table = construct_benchmark_table(data); + var table_name = 'summarylist-table-' + table_cache_counter; + ++table_cache_counter; + + table.attr('id', table_name); + table_cache[filename] = '#' + table_name; + $("#summarylist-body .message").remove(); + $("#summarylist-body").append(table); + table.show() + }); + } + } + } + + function update_state_url(key, value) { + var info = $.asv.parse_hash_string(window.location.hash); + var new_state = get_valid_state(state, key, value); + + $.each($.asv.main_json.params, function(param, values) { + if (values.length > 1) { + info.params[param] = [new_state[param]]; + } + else if (info.params[param]) { + delete info.params[param]; + } + }); + + window.location.hash = $.asv.format_hash_string(info); + } + + function obj_copy(obj) { + var newobj = {}; + $.each(obj, function(key, val) { + newobj[key] = val; + }); + return newobj; + } + + function obj_diff(obj1, obj2) { + var count = 0; + $.each(obj1, function(key, val) { + if (obj2[key] != val) { + ++count + } + }); + return count; + } + + function get_valid_state(tmp_state, wanted_key, wanted_value) { + /* + Get an available state with wanted_key having wanted_value, + preferably as a minor modification of tmp_state. + */ + var best_params = null; + var best_diff = 1e99; + var best_hit = false; + + tmp_state = obj_copy(tmp_state); + if (wanted_key !== undefined) { + tmp_state[wanted_key] = wanted_value; + } + + $.each($.asv.main_json.graph_param_list, function(idx, params) { + var diff = obj_diff(tmp_state, params); + var hit = (wanted_key === undefined || params[wanted_key] == wanted_value); + + if ((!best_hit && hit) || (hit == best_hit && diff < best_diff)) { + best_params = params; + best_diff = diff; + best_hit = hit; + } + }); + + if (best_params === null) { + best_params = $.asv.main_json.graph_param_list[0]; + } + + return obj_copy(best_params); + } + + function setup_state(state_selection) { + var index = $.asv.main_json; + var state = {}; + + state.machine = index.params.machine; + + $.each(index.params, function(param, values) { + state[param] = values[0]; + }); + + if (state_selection !== null) { + /* Select a specific generic parameter state */ + $.each(index.params, function(param, values) { + if (state_selection[param]) { + state[param] = state_selection[param][0]; + } + }); + } + + return get_valid_state(state); + } + + function replace_params_ui() { + var index = $.asv.main_json; + + var nav = $('#summarylist-navigation'); + nav.empty(); + + /* Machine selection */ + $.asv.ui.make_value_selector_panel(nav, 'machine', index.params.machine, function(i, machine, button) { + button.text(machine); + + button.on('click', function(evt) { + update_state_url('machine', machine); + }); + + if (state.machine != machine) { + button.removeClass('active'); + } + button.removeAttr('data-toggle'); + + /* Create tooltips for each machine */ + var details = []; + $.each(index.machines[machine], function(key, val) { + details.push(key + ': ' + val); + }); + details = details.join(''); + + button.tooltip({ + title: details, + html: true, + placement: 'right', + container: 'body', + animation: false + }); + }); + + /* Generic parameter selectors */ + $.each(index.params, function(param, values) { + if (values.length > 1 && param != 'machine') { + $.asv.ui.make_value_selector_panel(nav, param, values, function(i, value, button) { + var value_display; + if (value === null) + value_display = '[none]'; + else if (!value) + value_display = '[default]'; + else + value_display = value; + + button.text(value_display); + + if (state[param] != value) { + button.removeClass('active'); + } + + button.on('click', function(evt) { + update_state_url(param, value); + }); + }); + } + }); + + $(nav).find(".btn-group").removeAttr("data-toggle"); + + $.asv.ui.reflow_value_selector_panels(); + } + + function construct_benchmark_table(data) { + var index = $.asv.main_json; + + /* Form a new table */ + + var table = $('
{% component "inner" %}
{% fill "content" %}
@@ -95,20 +90,20 @@ This has two modes:
{% endfill %}
{% endcomponent %}
- \"\"\"
+ """
```
- - `"django"` - `my_var` has access to data from `get_context_data()` of both `Inner` and `Outer`.
+ - `"django"` - `my_var` has access to data from `get_template_data()` of both `Inner` and `Outer`.
If there are variables defined in both, then `Inner` overshadows `Outer`.
- - `"isolated"` - `my_var` has access to data from `get_context_data()` of ONLY `Outer`.
+ - `"isolated"` - `my_var` has access to data from `get_template_data()` of ONLY `Outer`.
### Example "django"
Given this template:
-```python
+```djc_py
@register("root_comp")
class RootComp(Component):
template = """
@@ -120,11 +115,11 @@ class RootComp(Component):
{% endwith %}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return { "my_var": 123 }
```
-Then if [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data)
+Then if [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
of the component `"my_comp"` returns following data:
```py
@@ -148,7 +143,7 @@ all the data defined in the outer layers, like the `{% with %}` tag.
Given this template:
-```python
+```djc_py
class RootComp(Component):
template = """
{% with cheese="feta" %}
@@ -159,11 +154,11 @@ class RootComp(Component):
{% endwith %}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return { "my_var": 123 }
```
-Then if [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data)
+Then if [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
of the component `"my_comp"` returns following data:
```py
@@ -177,10 +172,10 @@ Then the template will be rendered as:
# cheese
```
-Because variables `"my_var"` and `"cheese"` are searched only inside `RootComponent.get_context_data()`.
+Because variables `"my_var"` and `"cheese"` are searched only inside `RootComponent.get_template_data()`.
But since `"cheese"` is not defined there, it's empty.
!!! info
- Notice that the variables defined with the [`{% with %}`](https://docs.djangoproject.com/en/5.1/ref/templates/builtins/#with)
+ Notice that the variables defined with the [`{% with %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#with)
tag are ignored inside the [`{% fill %}`](../../../reference/template_tags#fill) tag with the `"isolated"` mode.
diff --git a/docs/concepts/advanced/authoring_component_libraries.md b/docs/concepts/advanced/component_libraries.md
similarity index 85%
rename from docs/concepts/advanced/authoring_component_libraries.md
rename to docs/concepts/advanced/component_libraries.md
index f10693d7..44aa4577 100644
--- a/docs/concepts/advanced/authoring_component_libraries.md
+++ b/docs/concepts/advanced/component_libraries.md
@@ -1,9 +1,6 @@
----
-title: Authoring component libraries
-weight: 8
----
+You can publish and share your components for others to use. Below you will find the steps to do so.
-You can publish and share your components for others to use. Here are the steps to do so:
+For live examples, see the [Community examples](../../overview/community.md#community-examples).
## Writing component libraries
@@ -26,13 +23,13 @@ You can publish and share your components for others to use. Here are the steps
|-- mytags.py
```
-2. Create custom [`Library`](https://docs.djangoproject.com/en/5.1/howto/custom-template-tags/#how-to-create-custom-template-tags-and-filters)
+2. Create custom [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#how-to-create-custom-template-tags-and-filters)
and [`ComponentRegistry`](django_components.component_registry.ComponentRegistry) instances in `mytags.py`
This will be the entrypoint for using the components inside Django templates.
- Remember that Django requires the [`Library`](https://docs.djangoproject.com/en/5.1/howto/custom-template-tags/#how-to-create-custom-template-tags-and-filters)
- instance to be accessible under the `register` variable ([See Django docs](https://docs.djangoproject.com/en/dev/howto/custom-template-tags)):
+ Remember that Django requires the [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#how-to-create-custom-template-tags-and-filters)
+ instance to be accessible under the `register` variable ([See Django docs](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags)):
```py
from django.template import Library
@@ -103,36 +100,31 @@ You can publish and share your components for others to use. Here are the steps
It's also a good idea to have a common prefix for your components, so they can be easily distinguished from users' components. In the example below, we use the prefix `my_` / `My`.
- ```py
- from typing import Dict, NotRequired, Optional, Tuple, TypedDict
-
- from django_components import Component, SlotFunc, register, types
+ ```djc_py
+ from typing import NamedTuple, Optional
+ from django_components import Component, SlotInput, register, types
from myapp.templatetags.mytags import comp_registry
- # Define the types
- class EmptyDict(TypedDict):
- pass
-
- type MyMenuArgs = Tuple[int, str]
-
- class MyMenuSlots(TypedDict):
- default: NotRequired[Optional[SlotFunc[EmptyDict]]]
-
- class MyMenuProps(TypedDict):
- vertical: NotRequired[bool]
- klass: NotRequired[str]
- style: NotRequired[str]
-
# Define the component
# NOTE: Don't forget to set the `registry`!
@register("my_menu", registry=comp_registry)
- class MyMenu(Component[MyMenuArgs, MyMenuProps, MyMenuSlots, Any, Any, Any]):
- def get_context_data(
- self,
- *args,
- attrs: Optional[Dict] = None,
- ):
+ class MyMenu(Component):
+ # Define the types
+ class Args(NamedTuple):
+ size: int
+ text: str
+
+ class Kwargs(NamedTuple):
+ vertical: Optional[bool] = None
+ klass: Optional[str] = None
+ style: Optional[str] = None
+
+ class Slots(NamedTuple):
+ default: Optional[SlotInput] = None
+
+ def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
+ attrs = ...
return {
"attrs": attrs,
}
@@ -156,7 +148,7 @@ You can publish and share your components for others to use. Here are the steps
Since you, as the library author, are not in control of the file system, it is recommended to load the components manually.
- We recommend doing this in the [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.1/ref/applications/#django.apps.AppConfig.ready)
+ We recommend doing this in the [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.ready)
hook of your `apps.py`:
```py
@@ -178,7 +170,7 @@ You can publish and share your components for others to use. Here are the steps
```
Note that you can also include any other startup logic within
- [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.1/ref/applications/#django.apps.AppConfig.ready).
+ [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.ready).
And that's it! The next step is to publish it.
@@ -193,7 +185,7 @@ django_components uses the [`build`](https://build.pypa.io/en/stable/) utility t
python -m build --sdist --wheel --outdir dist/ .
```
-And to publish to PyPI, you can use [`twine`](https://docs.djangoproject.com/en/5.1/ref/applications/#django.apps.AppConfig.ready)
+And to publish to PyPI, you can use [`twine`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.ready)
([See Python user guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives))
```bash
@@ -227,7 +219,7 @@ After the package has been published, all that remains is to install it in other
]
```
-3. Optionally add the template tags to the [`builtins`](https://docs.djangoproject.com/en/5.1/topics/templates/#django.template.backends.django.DjangoTemplates),
+3. Optionally add the template tags to the [`builtins`](https://docs.djangoproject.com/en/5.2/topics/templates/#django.template.backends.django.DjangoTemplates),
so you don't have to call `{% load mytags %}` in every template:
```python
diff --git a/docs/concepts/advanced/component_registry.md b/docs/concepts/advanced/component_registry.md
index be481912..f5865420 100644
--- a/docs/concepts/advanced/component_registry.md
+++ b/docs/concepts/advanced/component_registry.md
@@ -1,8 +1,3 @@
----
-title: Registering components
-weight: 5
----
-
In previous examples you could repeatedly see us using `@register()` to "register"
the components. In this section we dive deeper into what it actually means and how you can
manage (add or remove) components.
@@ -14,12 +9,12 @@ from django_components import Component, register
@register("calendar")
class Calendar(Component):
- template_name = "template.html"
+ template_file = "template.html"
# This component takes one parameter, a date string to show in the template
- def get_context_data(self, date):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "date": date,
+ "date": kwargs["date"],
}
```
@@ -85,6 +80,9 @@ registry.register("card", CardComponent)
registry.all() # {"button": ButtonComponent, "card": CardComponent}
registry.get("card") # CardComponent
+# Check if component is registered
+registry.has("button") # True
+
# Unregister single component
registry.unregister("card")
@@ -127,6 +125,7 @@ NOTE: The Library instance can be accessed under `library` attribute of `Compone
When you are creating an instance of `ComponentRegistry`, you can define the components' behavior within the template.
The registry accepts these settings:
+
- `context_behavior`
- `tag_formatter`
diff --git a/docs/concepts/advanced/extensions.md b/docs/concepts/advanced/extensions.md
new file mode 100644
index 00000000..50d76cd4
--- /dev/null
+++ b/docs/concepts/advanced/extensions.md
@@ -0,0 +1,902 @@
+_New in version 0.131_
+
+Django-components functionality can be extended with "extensions". Extensions allow for powerful customization and integrations. They can:
+
+- Tap into lifecycle events, such as when a component is created, deleted, registered, or unregistered.
+- Add new attributes and methods to the components under an extension-specific nested class.
+- Define custom commands that can be executed via the Django management command interface.
+
+## Live examples
+
+- [djc-ext-pydantic](https://github.com/django-components/djc-ext-pydantic)
+
+## Install extensions
+
+Extensions are configured in the Django settings under [`COMPONENTS.extensions`](../../../reference/settings#django_components.app_settings.ComponentsSettings.extensions).
+
+Extensions can be set by either as an import string or by passing in a class:
+
+```python
+# settings.py
+
+class MyExtension(ComponentExtension):
+ name = "my_extension"
+
+ class ComponentConfig(ExtensionComponentConfig):
+ ...
+
+COMPONENTS = ComponentsSettings(
+ extensions=[
+ MyExtension,
+ "another_app.extensions.AnotherExtension",
+ "my_app.extensions.ThirdExtension",
+ ],
+)
+```
+
+## Lifecycle hooks
+
+Extensions can define methods to hook into lifecycle events, such as:
+
+- Component creation or deletion
+- Un/registering a component
+- Creating or deleting a registry
+- Pre-processing data passed to a component on render
+- Post-processing data returned from [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+ and others.
+
+See the full list in [Extension Hooks Reference](../../../reference/extension_hooks).
+
+## Per-component configuration
+
+Each extension has a corresponding nested class within the [`Component`](../../../reference/api#django_components.Component) class. These allow
+to configure the extensions on a per-component basis.
+
+E.g.:
+
+- `"view"` extension -> [`Component.View`](../../../reference/api#django_components.Component.View)
+- `"cache"` extension -> [`Component.Cache`](../../../reference/api#django_components.Component.Cache)
+- `"defaults"` extension -> [`Component.Defaults`](../../../reference/api#django_components.Component.Defaults)
+
+!!! note
+
+ **Accessing the component instance from inside the nested classes:**
+
+ Each method of the nested classes has access to the `component` attribute,
+ which points to the component instance.
+
+ ```python
+ class MyTable(Component):
+ class MyExtension:
+ def get(self, request):
+ # `self.component` points to the instance of `MyTable` Component.
+ return self.component.render_to_response(request=request)
+ ```
+
+### Example: Component as View
+
+The [Components as Views](../../fundamentals/component_views_urls) feature is actually implemented as an extension
+that is configured by a `View` nested class.
+
+You can override the `get()`, `post()`, etc methods to customize the behavior of the component as a view:
+
+```python
+class MyTable(Component):
+ class View:
+ def get(self, request):
+ return self.component_class.render_to_response(request=request)
+
+ def post(self, request):
+ return self.component_class.render_to_response(request=request)
+
+ ...
+```
+
+
+### Example: Storybook integration
+
+The Storybook integration (work in progress) is an extension that is configured by a `Storybook` nested class.
+
+You can override methods such as `title`, `parameters`, etc, to customize how to generate a Storybook
+JSON file from the component.
+
+```python
+class MyTable(Component):
+ class Storybook:
+ def title(self):
+ return self.component_cls.__name__
+
+ def parameters(self) -> Parameters:
+ return {
+ "server": {
+ "id": self.component_cls.__name__,
+ }
+ }
+
+ def stories(self) -> List[StoryAnnotations]:
+ return []
+
+ ...
+```
+
+### Extension defaults
+
+Extensions are incredibly flexible, but configuring the same extension for every component can be a pain.
+
+For this reason, django-components allows for extension defaults. This is like setting the extension config for every component.
+
+To set extension defaults, use the [`COMPONENTS.extensions_defaults`](../../../reference/settings#django_components.app_settings.ComponentsSettings.extensions_defaults) setting.
+
+The `extensions_defaults` setting is a dictionary where the key is the extension name and the value is a dictionary of config attributes:
+
+```python
+COMPONENTS = ComponentsSettings(
+ extensions=[
+ "my_extension.MyExtension",
+ "storybook.StorybookExtension",
+ ],
+ extensions_defaults={
+ "my_extension": {
+ "key": "value",
+ },
+ "view": {
+ "public": True,
+ },
+ "cache": {
+ "ttl": 60,
+ },
+ "storybook": {
+ "title": lambda self: self.component_cls.__name__,
+ },
+ },
+)
+```
+
+Which is equivalent to setting the following for every component:
+
+```python
+class MyTable(Component):
+ class MyExtension:
+ key = "value"
+
+ class View:
+ public = True
+
+ class Cache:
+ ttl = 60
+
+ class Storybook:
+ def title(self):
+ return self.component_cls.__name__
+```
+
+!!! info
+
+ If you define an attribute as a function, it is like defining a method on the extension class.
+
+ E.g. in the example above, `title` is a method on the `Storybook` extension class.
+
+As the name suggests, these are defaults, and so you can still selectively override them on a per-component basis:
+
+```python
+class MyTable(Component):
+ class View:
+ public = False
+```
+
+### Extensions in component instances
+
+Above, we've configured extensions `View` and `Storybook` for the `MyTable` component.
+
+You can access the instances of these extension classes in the component instance.
+
+Extensions are available under their names (e.g. `self.view`, `self.storybook`).
+
+For example, the View extension is available as `self.view`:
+
+```python
+class MyTable(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # `self.view` points to the instance of `View` extension.
+ return {
+ "view": self.view,
+ }
+```
+
+And the Storybook extension is available as `self.storybook`:
+
+```python
+class MyTable(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ # `self.storybook` points to the instance of `Storybook` extension.
+ return {
+ "title": self.storybook.title(),
+ }
+```
+
+## Writing extensions
+
+Creating extensions in django-components involves defining a class that inherits from
+[`ComponentExtension`](../../../reference/api/#django_components.ComponentExtension).
+This class can implement various lifecycle hooks and define new attributes or methods to be added to components.
+
+### Extension class
+
+To create an extension, define a class that inherits from [`ComponentExtension`](../../../reference/api/#django_components.ComponentExtension)
+and implement the desired hooks.
+
+- Each extension MUST have a `name` attribute. The name MUST be a valid Python identifier.
+- The extension may implement any of the [hook methods](../../../reference/extension_hooks).
+
+ Each hook method receives a context object with relevant data.
+
+- Extension may own [URLs](#extension-urls) or [CLI commands](#extension-commands).
+
+```python
+from django_components.extension import ComponentExtension, OnComponentClassCreatedContext
+
+class MyExtension(ComponentExtension):
+ name = "my_extension"
+
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ # Custom logic for when a component class is created
+ ctx.component_cls.my_attr = "my_value"
+```
+
+!!! warning
+
+ The `name` attribute MUST be unique across all extensions.
+
+ Moreover, the `name` attribute MUST NOT conflict with existing Component class API.
+
+ So if you name an extension `render`, it will conflict with the [`render()`](../../../reference/api/#django_components.Component.render) method of the `Component` class.
+
+### Component config
+
+In previous sections we've seen the `View` and `Storybook` extensions classes that were nested
+within the [`Component`](../../../reference/api/#django_components.Component) class:
+
+```python
+class MyComponent(Component):
+ class View:
+ ...
+
+ class Storybook:
+ ...
+```
+
+These can be understood as component-specific overrides or configuration.
+
+Whether it's `Component.View` or `Component.Storybook`, their respective extensions
+defined how these nested classes will behave.
+
+For example, the View extension defines the API that users may override in `ViewExtension.ComponentConfig`:
+
+```python
+from django_components.extension import ComponentExtension, ExtensionComponentConfig
+
+class ViewExtension(ComponentExtension):
+ name = "view"
+
+ # The default behavior of the `View` extension class.
+ class ComponentConfig(ExtensionComponentConfig):
+ def get(self, request):
+ raise NotImplementedError("You must implement the `get` method.")
+
+ def post(self, request):
+ raise NotImplementedError("You must implement the `post` method.")
+
+ ...
+```
+
+In any component that then defines a nested `Component.View` extension class, the resulting `View` class
+will actually subclass from the `ViewExtension.ComponentConfig` class.
+
+In other words, when you define a component like this:
+
+```python
+class MyTable(Component):
+ class View:
+ def get(self, request):
+ # Do something
+ ...
+```
+
+Behind the scenes it is as if you defined the following:
+
+```python
+class MyTable(Component):
+ class View(ViewExtension.ComponentConfig):
+ def get(self, request):
+ # Do something
+ ...
+```
+
+!!! warning
+
+ When writing an extension, the `ComponentConfig` MUST subclass the base class [`ExtensionComponentConfig`](../../../reference/api/#django_components.ExtensionComponentConfig).
+
+ This base class ensures that the extension class will have access to the component instance.
+
+### Install your extension
+
+Once the extension is defined, it needs to be installed in the Django settings to be used by the application.
+
+Extensions can be given either as an extension class, or its import string:
+
+```python
+# settings.py
+COMPONENTS = {
+ "extensions": [
+ "my_app.extensions.MyExtension",
+ ],
+}
+```
+
+Or by reference:
+
+```python
+# settings.py
+from my_app.extensions import MyExtension
+
+COMPONENTS = {
+ "extensions": [
+ MyExtension,
+ ],
+}
+```
+
+### Full example: Custom logging extension
+
+To tie it all together, here's an example of a custom logging extension that logs when components are created, deleted, or rendered:
+
+- Each component can specify which color to use for the logging by setting `Component.ColorLogger.color`.
+- The extension will log the component name and color when the component is created, deleted, or rendered.
+
+```python
+from django_components.extension import (
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentClassCreatedContext,
+ OnComponentClassDeletedContext,
+ OnComponentInputContext,
+)
+
+
+class ColorLoggerExtension(ComponentExtension):
+ name = "color_logger"
+
+ # All `Component.ColorLogger` classes will inherit from this class.
+ class ComponentConfig(ExtensionComponentConfig):
+ color: str
+
+ # These hooks don't have access to the Component instance,
+ # only to the Component class, so we access the color
+ # as `Component.ColorLogger.color`.
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext):
+ log.info(
+ f"Component {ctx.component_cls} created.",
+ color=ctx.component_cls.ColorLogger.color,
+ )
+
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext):
+ log.info(
+ f"Component {ctx.component_cls} deleted.",
+ color=ctx.component_cls.ColorLogger.color,
+ )
+
+ # This hook has access to the Component instance, so we access the color
+ # as `self.component.color_logger.color`.
+ def on_component_input(self, ctx: OnComponentInputContext):
+ log.info(
+ f"Rendering component {ctx.component_cls}.",
+ color=ctx.component.color_logger.color,
+ )
+```
+
+To use the `ColorLoggerExtension`, add it to your settings:
+
+```python
+# settings.py
+COMPONENTS = {
+ "extensions": [
+ ColorLoggerExtension,
+ ],
+}
+```
+
+Once installed, in any component, you can define a `ColorLogger` attribute:
+
+```python
+class MyComponent(Component):
+ class ColorLogger:
+ color = "red"
+```
+
+This will log the component name and color when the component is created, deleted, or rendered.
+
+### Utility functions
+
+django-components provides a few utility functions to help with writing extensions:
+
+- [`all_components()`](../../../reference/api#django_components.all_components) - returns a list of all created component classes.
+- [`all_registries()`](../../../reference/api#django_components.all_registries) - returns a list of all created registry instances.
+
+### Access component class
+
+You can access the owner [`Component`](../../../reference/api/#django_components.Component) class (`MyTable`) from within methods
+of the extension class (`MyExtension`) by using
+the [`component_cls`](../../../reference/api/#django_components.ExtensionComponentConfig.component_cls) attribute:
+
+```py
+class MyTable(Component):
+ class MyExtension:
+ def some_method(self):
+ print(self.component_cls)
+```
+
+Here is how the `component_cls` attribute may be used with our `ColorLogger`
+extension shown above:
+
+```python
+class ColorLoggerComponentConfig(ExtensionComponentConfig):
+ color: str
+
+ def log(self, msg: str) -> None:
+ print(f"{self.component_cls.__name__}: {msg}")
+
+
+class ColorLoggerExtension(ComponentExtension):
+ name = "color_logger"
+
+ # All `Component.ColorLogger` classes will inherit from this class.
+ ComponentConfig = ColorLoggerComponentConfig
+```
+
+### Pass slot metadata
+
+When a slot is passed to a component, it is copied, so that the original slot is not modified
+with rendering metadata.
+
+Therefore, don't use slot's identity to associate metadata with the slot:
+
+```py
+# ❌ Don't do this:
+slots_cache = {}
+
+class LoggerExtension(ComponentExtension):
+ name = "logger"
+
+ def on_component_input(self, ctx: OnComponentInputContext):
+ for slot in ctx.component.slots.values():
+ slots_cache[id(slot)] = {"some": "metadata"}
+```
+
+Instead, use the [`Slot.extra`](../../../reference/api#django_components.Slot.extra) attribute,
+which is copied from the original slot:
+
+```python
+# ✅ Do this:
+class LoggerExtension(ComponentExtension):
+ name = "logger"
+
+ # Save component-level logger settings for each slot when a component is rendered.
+ def on_component_input(self, ctx: OnComponentInputContext):
+ for slot in ctx.component.slots.values():
+ slot.extra["logger"] = ctx.component.logger
+
+ # Then, when a fill is rendered with `{% slot %}`, we can access the logger settings
+ # from the slot's metadata.
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext):
+ logger = ctx.slot.extra["logger"]
+ logger.log(...)
+```
+
+## Extension commands
+
+Extensions in django-components can define custom commands that can be executed via the Django management command interface. This allows for powerful automation and customization capabilities.
+
+For example, if you have an extension that defines a command that prints "Hello world", you can run the command with:
+
+```bash
+python manage.py components ext run my_ext hello
+```
+
+Where:
+
+- `python manage.py components` - is the Django entrypoint
+- `ext run` - is the subcommand to run extension commands
+- `my_ext` - is the extension name
+- `hello` - is the command name
+
+### Define commands
+
+To define a command, subclass from [`ComponentCommand`](../../../reference/extension_commands#django_components.ComponentCommand).
+This subclass should define:
+
+- `name` - the command's name
+- `help` - the command's help text
+- `handle` - the logic to execute when the command is run
+
+```python
+from django_components import ComponentCommand, ComponentExtension
+
+class HelloCommand(ComponentCommand):
+ name = "hello"
+ help = "Say hello"
+
+ def handle(self, *args, **kwargs):
+ print("Hello, world!")
+
+class MyExt(ComponentExtension):
+ name = "my_ext"
+ commands = [HelloCommand]
+```
+
+### Define arguments and options
+
+Commands can accept positional arguments and options (e.g. `--foo`), which are defined using the
+[`arguments`](../../../reference/extension_commands#django_components.ComponentCommand.arguments)
+attribute of the [`ComponentCommand`](../../../reference/extension_commands#django_components.ComponentCommand) class.
+
+The arguments are parsed with [`argparse`](https://docs.python.org/3/library/argparse.html)
+into a dictionary of arguments and options. These are then available
+as keyword arguments to the [`handle`](../../../reference/extension_commands#django_components.ComponentCommand.handle)
+method of the command.
+
+```python
+from django_components import CommandArg, ComponentCommand, ComponentExtension
+
+class HelloCommand(ComponentCommand):
+ name = "hello"
+ help = "Say hello"
+
+ arguments = [
+ # Positional argument
+ CommandArg(
+ name_or_flags="name",
+ help="The name to say hello to",
+ ),
+ # Optional argument
+ CommandArg(
+ name_or_flags=["--shout", "-s"],
+ action="store_true",
+ help="Shout the hello",
+ ),
+ ]
+
+ def handle(self, name: str, *args, **kwargs):
+ shout = kwargs.get("shout", False)
+ msg = f"Hello, {name}!"
+ if shout:
+ msg = msg.upper()
+ print(msg)
+```
+
+You can run the command with arguments and options:
+
+```bash
+python manage.py components ext run my_ext hello John --shout
+>>> HELLO, JOHN!
+```
+
+!!! note
+
+ Command definitions are parsed with `argparse`, so you can use all the features of `argparse` to define your arguments and options.
+
+ See the [argparse documentation](https://docs.python.org/3/library/argparse.html) for more information.
+
+ django-components defines types as
+ [`CommandArg`](../../../reference/extension_commands#django_components.CommandArg),
+ [`CommandArgGroup`](../../../reference/extension_commands#django_components.CommandArgGroup),
+ [`CommandSubcommand`](../../../reference/extension_commands#django_components.CommandSubcommand),
+ and [`CommandParserInput`](../../../reference/extension_commands#django_components.CommandParserInput)
+ to help with type checking.
+
+!!! note
+
+ If a command doesn't have the [`handle`](../../../reference/extension_commands#django_components.ComponentCommand.handle)
+ method defined, the command will print a help message and exit.
+
+### Argument groups
+
+Arguments can be grouped using [`CommandArgGroup`](../../../reference/extension_commands#django_components.CommandArgGroup)
+to provide better organization and help messages.
+
+Read more on [argparse argument groups](https://docs.python.org/3/library/argparse.html#argument-groups).
+
+```python
+from django_components import CommandArg, CommandArgGroup, ComponentCommand, ComponentExtension
+
+class HelloCommand(ComponentCommand):
+ name = "hello"
+ help = "Say hello"
+
+ # Argument parsing is managed by `argparse`.
+ arguments = [
+ # Positional argument
+ CommandArg(
+ name_or_flags="name",
+ help="The name to say hello to",
+ ),
+ # Optional argument
+ CommandArg(
+ name_or_flags=["--shout", "-s"],
+ action="store_true",
+ help="Shout the hello",
+ ),
+ # When printing the command help message, `--bar` and `--baz`
+ # will be grouped under "group bar".
+ CommandArgGroup(
+ title="group bar",
+ description="Group description.",
+ arguments=[
+ CommandArg(
+ name_or_flags="--bar",
+ help="Bar description.",
+ ),
+ CommandArg(
+ name_or_flags="--baz",
+ help="Baz description.",
+ ),
+ ],
+ ),
+ ]
+
+ def handle(self, name: str, *args, **kwargs):
+ shout = kwargs.get("shout", False)
+ msg = f"Hello, {name}!"
+ if shout:
+ msg = msg.upper()
+ print(msg)
+```
+
+### Subcommands
+
+Extensions can define subcommands, allowing for more complex command structures.
+
+Subcommands are defined similarly to root commands, as subclasses of
+[`ComponentCommand`](../../../reference/extension_commands#django_components.ComponentCommand) class.
+
+However, instead of defining the subcommands in the
+[`commands`](../../../reference/extension_commands#django_components.ComponentExtension.commands)
+attribute of the extension, you define them in the
+[`subcommands`](../../../reference/extension_commands#django_components.ComponentCommand.subcommands)
+attribute of the parent command:
+
+```python
+from django_components import CommandArg, CommandArgGroup, ComponentCommand, ComponentExtension
+
+class ChildCommand(ComponentCommand):
+ name = "child"
+ help = "Child command"
+
+ def handle(self, *args, **kwargs):
+ print("Child command")
+
+class ParentCommand(ComponentCommand):
+ name = "parent"
+ help = "Parent command"
+ subcommands = [
+ ChildCommand,
+ ]
+
+ def handle(self, *args, **kwargs):
+ print("Parent command")
+```
+
+In this example, we can run two commands.
+
+Either the parent command:
+
+```bash
+python manage.py components ext run parent
+>>> Parent command
+```
+
+Or the child command:
+
+```bash
+python manage.py components ext run parent child
+>>> Child command
+```
+
+!!! warning
+
+ Subcommands are independent of the parent command. When a subcommand runs, the parent command is NOT executed.
+
+ As such, if you want to pass arguments to both the parent and child commands, e.g.:
+
+ ```bash
+ python manage.py components ext run parent --foo child --bar
+ ```
+
+ You should instead pass all the arguments to the subcommand:
+
+ ```bash
+ python manage.py components ext run parent child --foo --bar
+ ```
+
+### Help message
+
+By default, all commands will print their help message when run with the `--help` / `-h` flag.
+
+```bash
+python manage.py components ext run my_ext --help
+```
+
+The help message prints out all the arguments and options available for the command, as well as any subcommands.
+
+### Testing commands
+
+Commands can be tested using Django's [`call_command()`](https://docs.djangoproject.com/en/5.2/ref/django-admin/#running-management-commands-from-your-code)
+function, which allows you to simulate running the command in tests.
+
+```python
+from django.core.management import call_command
+
+call_command('components', 'ext', 'run', 'my_ext', 'hello', '--name', 'John')
+```
+
+To capture the output of the command, you can use the [`StringIO`](https://docs.python.org/3/library/io.html#io.StringIO)
+module to redirect the output to a string:
+
+```python
+from io import StringIO
+
+out = StringIO()
+with patch("sys.stdout", new=out):
+ call_command('components', 'ext', 'run', 'my_ext', 'hello', '--name', 'John')
+output = out.getvalue()
+```
+
+And to temporarily set the extensions, you can use the [`@djc_test`](../../../reference/testing_api#djc_test) decorator.
+
+Thus, a full test example can then look like this:
+
+```python
+from io import StringIO
+from unittest.mock import patch
+
+from django.core.management import call_command
+from django_components.testing import djc_test
+
+@djc_test(
+ components_settings={
+ "extensions": [
+ "my_app.extensions.MyExtension",
+ ],
+ },
+)
+def test_hello_command(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command('components', 'ext', 'run', 'my_ext', 'hello', '--name', 'John')
+ output = out.getvalue()
+ assert output == "Hello, John!\n"
+```
+
+## Extension URLs
+
+Extensions can define custom views and endpoints that can be accessed through the Django application.
+
+To define URLs for an extension, set them in the [`urls`](../../../reference/api#django_components.ComponentExtension.urls) attribute of your [`ComponentExtension`](../../../reference/api#django_components.ComponentExtension) class. Each URL is defined using the [`URLRoute`](../../../reference/extension_urls#django_components.URLRoute) class, which specifies the path, handler, and optional name for the route.
+
+Here's an example of how to define URLs within an extension:
+
+```python
+from django_components.extension import ComponentExtension, URLRoute
+from django.http import HttpResponse
+
+def my_view(request):
+ return HttpResponse("Hello from my extension!")
+
+class MyExtension(ComponentExtension):
+ name = "my_extension"
+
+ urls = [
+ URLRoute(path="my-view/", handler=my_view, name="my_view"),
+ URLRoute(path="another-view/
+ Hello, {is_var}!
+
+ """)
+```
+
+This allows you to use the tag like this:
+
+```django
+{% greet is="John" data-id="123" %}
+```
+
+## Defining template tags with `BaseNode`
+
+For more control over your template tag, you can subclass [`BaseNode`](../../../reference/api#django_components.BaseNode) directly instead of using the decorator. This gives you access to additional features like the node's internal state and parsing details.
+
+```python
+from django_components import BaseNode
+
+class GreetNode(BaseNode):
+ tag = "greet"
+ end_tag = "endgreet"
+ allowed_flags = ["required"]
+
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ # Access node properties
+ if self.flags["required"]:
+ return f"Required greeting: Hello, {name}!"
+ return f"Hello, {name}!"
+
+# Register the node
+GreetNode.register(library)
+```
+
+### Node properties
+
+When using [`BaseNode`](../../../reference/api#django_components.BaseNode), you have access to several useful properties:
+
+- [`node_id`](../../../reference/api#django_components.BaseNode.node_id): A unique identifier for this node instance
+- [`flags`](../../../reference/api#django_components.BaseNode.flags): Dictionary of flag values (e.g. `{"required": True}`)
+- [`params`](../../../reference/api#django_components.BaseNode.params): List of raw parameters passed to the tag
+- [`nodelist`](../../../reference/api#django_components.BaseNode.nodelist): The template nodes between the start and end tags
+- [`contents`](../../../reference/api#django_components.BaseNode.contents): The raw contents between the start and end tags
+- [`active_flags`](../../../reference/api#django_components.BaseNode.active_flags): List of flags that are currently set to True
+- [`template_name`](../../../reference/api#django_components.BaseNode.template_name): The name of the `Template` instance inside which the node was defined
+- [`template_component`](../../../reference/api#django_components.BaseNode.template_component): The component class that the `Template` belongs to
+
+This is what the `node` parameter in the [`@template_tag`](../../../reference/api#django_components.template_tag) decorator gives you access to - it's the instance of the node class that was automatically created for your template tag.
+
+### Rendering content between tags
+
+When your tag has an end tag, you can access and render the content between the tags using `nodelist`:
+
+```python
+class WrapNode(BaseNode):
+ tag = "wrap"
+ end_tag = "endwrap"
+
+ def render(self, context: Context, tag: str = "div", **attrs) -> str:
+ # Render the content between tags
+ inner = self.nodelist.render(context)
+ attrs_str = " ".join(f'{k}="{v}"' for k, v in attrs.items())
+ return f"<{tag} {attrs_str}>{inner}"
+
+# Usage:
+{% wrap tag="section" class="content" %}
+ Hello, world!
+{% endwrap %}
+```
+
+### Unregistering nodes
+
+You can unregister a node from a library using the `unregister` method:
+
+```python
+GreetNode.unregister(library)
+```
+
+This is particularly useful in testing when you want to clean up after registering temporary tags.
diff --git a/docs/concepts/advanced/testing.md b/docs/concepts/advanced/testing.md
new file mode 100644
index 00000000..5fc15665
--- /dev/null
+++ b/docs/concepts/advanced/testing.md
@@ -0,0 +1,115 @@
+_New in version 0.131_
+
+The [`@djc_test`](../../../reference/testing_api#djc_test) decorator is a powerful tool for testing components created with `django-components`. It ensures that each test is properly isolated, preventing components registered in one test from affecting others.
+
+## Usage
+
+The [`@djc_test`](../../../reference/testing_api#djc_test) decorator can be applied to functions, methods, or classes.
+
+When applied to a class, it decorates all methods starting with `test_`, and all nested classes starting with `Test`,
+recursively.
+
+### Applying to a Function
+
+To apply [`djc_test`](../../../reference/testing_api#djc_test) to a function,
+simply decorate the function as shown below:
+
+```python
+import django
+from django_components.testing import djc_test
+
+@djc_test
+def test_my_component():
+ @register("my_component")
+ class MyComponent(Component):
+ template = "..."
+ ...
+```
+
+### Applying to a Class
+
+When applied to a class, `djc_test` decorates each `test_` method, as well as all nested classes starting with `Test`.
+
+```python
+import django
+from django_components.testing import djc_test
+
+@djc_test
+class TestMyComponent:
+ def test_something(self):
+ ...
+
+ class TestNested:
+ def test_something_else(self):
+ ...
+```
+
+This is equivalent to applying the decorator to both of the methods individually:
+
+```python
+import django
+from django_components.testing import djc_test
+
+class TestMyComponent:
+ @djc_test
+ def test_something(self):
+ ...
+
+ class TestNested:
+ @djc_test
+ def test_something_else(self):
+ ...
+```
+
+### Arguments
+
+See the API reference for [`@djc_test`](../../../reference/testing_api#djc_test) for more details.
+
+### Setting Up Django
+
+If you want to define a common Django settings that would be the baseline for all tests,
+you can call [`django.setup()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.setup)
+before the `@djc_test` decorator:
+
+```python
+import django
+from django_components.testing import djc_test
+
+django.setup(...)
+
+@djc_test
+def test_my_component():
+ ...
+```
+
+!!! info
+
+ If you omit [`django.setup()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.setup)
+ in the example above, `@djc_test` will call it for you, so you don't need to do it manually.
+
+## Example: Parametrizing Context Behavior
+
+You can parametrize the [context behavior](../../../reference/settings#django_components.app_settings.ComponentsSettings.context_behavior) using [`djc_test`](../../../reference/testing_api#djc_test):
+
+```python
+from django_components.testing import djc_test
+
+@djc_test(
+ # Settings applied to all cases
+ components_settings={
+ "app_dirs": ["custom_dir"],
+ },
+ # Parametrized settings
+ parametrize=(
+ ["components_settings"],
+ [
+ [{"context_behavior": "django"}],
+ [{"context_behavior": "isolated"}],
+ ],
+ ["django", "isolated"],
+ )
+)
+def test_context_behavior(components_settings):
+ rendered = MyComponent.render()
+ ...
+```
diff --git a/docs/concepts/advanced/typing_and_validation.md b/docs/concepts/advanced/typing_and_validation.md
deleted file mode 100644
index e6c0842b..00000000
--- a/docs/concepts/advanced/typing_and_validation.md
+++ /dev/null
@@ -1,178 +0,0 @@
----
-title: Typing and validation
-weight: 6
----
-
-## Adding type hints with Generics
-
-_New in version 0.92_
-
-The `Component` class optionally accepts type parameters
-that allow you to specify the types of args, kwargs, slots, and
-data:
-
-```py
-class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
- ...
-```
-
-- `Args` - Must be a `Tuple` or `Any`
-- `Kwargs` - Must be a `TypedDict` or `Any`
-- `Data` - Must be a `TypedDict` or `Any`
-- `Slots` - Must be a `TypedDict` or `Any`
-
-Here's a full example:
-
-```py
-from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
-
-# Positional inputs
-Args = Tuple[int, str]
-
-# Kwargs inputs
-class Kwargs(TypedDict):
- variable: str
- another: int
- maybe_var: NotRequired[int] # May be ommited
-
-# Data returned from `get_context_data`
-class Data(TypedDict):
- variable: str
-
-# The data available to the `my_slot` scoped slot
-class MySlotData(TypedDict):
- value: int
-
-# Slots
-class Slots(TypedDict):
- # Use SlotFunc for slot functions.
- # The generic specifies the `data` dictionary
- my_slot: NotRequired[SlotFunc[MySlotData]]
- # SlotContent == Union[str, SafeString]
- another_slot: SlotContent
-
-class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
- def get_context_data(self, variable, another):
- return {
- "variable": variable,
- }
-```
-
-When you then call `Component.render` or `Component.render_to_response`, you will get type hints:
-
-```py
-Button.render(
- # Error: First arg must be `int`, got `float`
- args=(1.25, "abc"),
- # Error: Key "another" is missing
- kwargs={
- "variable": "text",
- },
-)
-```
-
-### Usage for Python <3.11
-
-On Python 3.8-3.10, use `typing_extensions`
-
-```py
-from typing_extensions import TypedDict, NotRequired
-```
-
-Additionally on Python 3.8-3.9, also import `annotations`:
-
-```py
-from __future__ import annotations
-```
-
-Moreover, on 3.10 and less, you may not be able to use `NotRequired`, and instead you will need to mark either all keys are required, or all keys as optional, using TypeDict's `total` kwarg.
-
-[See PEP-655](https://peps.python.org/pep-0655) for more info.
-
-## Passing additional args or kwargs
-
-You may have a function that supports any number of args or kwargs:
-
-```py
-def get_context_data(self, *args, **kwargs):
- ...
-```
-
-This is not supported with the typed components.
-
-As a workaround:
-
-- For `*args`, set a positional argument that accepts a list of values:
-
- ```py
- # Tuple of one member of list of strings
- Args = Tuple[List[str]]
- ```
-
-- For `*kwargs`, set a keyword argument that accepts a dictionary of values:
-
- ```py
- class Kwargs(TypedDict):
- variable: str
- another: int
- # Pass any extra keys under `extra`
- extra: Dict[str, any]
- ```
-
-## Handling no args or no kwargs
-
-To declare that a component accepts no Args, Kwargs, etc, you can use `EmptyTuple` and `EmptyDict` types:
-
-```py
-from django_components import Component, EmptyDict, EmptyTuple
-
-Args = EmptyTuple
-Kwargs = Data = Slots = EmptyDict
-
-class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
- ...
-```
-
-## Runtime input validation with types
-
-_New in version 0.96_
-
-> NOTE: Kwargs, slots, and data validation is supported only for Python >=3.11
-
-In Python 3.11 and later, when you specify the component types, you will get also runtime validation of the inputs you pass to `Component.render` or `Component.render_to_response`.
-
-So, using the example from before, if you ignored the type errors and still ran the following code:
-
-```py
-Button.render(
- # Error: First arg must be `int`, got `float`
- args=(1.25, "abc"),
- # Error: Key "another" is missing
- kwargs={
- "variable": "text",
- },
-)
-```
-
-This would raise a `TypeError`:
-
-```txt
-Component 'Button' expected positional argument at index 0 to be
+
+ """
+
+ 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 c950b1db..00000000
--- a/docs/concepts/fundamentals/components_as_views.md
+++ /dev/null
@@ -1,153 +0,0 @@
----
-title: Components as views
-weight: 10
----
-
-_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:
-
-```python
-# 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 5afd54d5..00000000
--- a/docs/concepts/fundamentals/components_in_python.md
+++ /dev/null
@@ -1,139 +0,0 @@
----
-title: Components in Python
-weight: 2
----
-
-_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:
-
-```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/defining_js_css_html_files.md b/docs/concepts/fundamentals/defining_js_css_html_files.md
deleted file mode 100644
index 70cc8720..00000000
--- a/docs/concepts/fundamentals/defining_js_css_html_files.md
+++ /dev/null
@@ -1,203 +0,0 @@
----
-title: Defining HTML / JS / CSS files
-weight: 8
----
-
-django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/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/)
-
-## Defining file paths relative to component or static dirs
-
-As seen in the [getting started example](#create-your-first-component), to associate HTML/JS/CSS
-files with a component, you set them as `template_name`, `Media.js` and `Media.css` respectively:
-
-```py
-# In a file [project root]/components/calendar/calendar.py
-from django_components import Component, register
-
-@register("calendar")
-class Calendar(Component):
- template_name = "template.html"
-
- class Media:
- css = "style.css"
- js = "script.js"
-```
-
-In the example above, the files are defined relative to the directory where `component.py` is.
-
-Alternatively, you can specify the file paths relative to the directories set in `COMPONENTS.dirs` or `COMPONENTS.app_dirs`.
-
-Assuming that `COMPONENTS.dirs` contains path `[project root]/components`, we can rewrite the example as:
-
-```py
-# In a file [project root]/components/calendar/calendar.py
-from django_components import Component, register
-
-@register("calendar")
-class Calendar(Component):
- template_name = "calendar/template.html"
-
- class Media:
- css = "calendar/style.css"
- js = "calendar/script.js"
-```
-
-NOTE: In case of conflict, the preference goes to resolving the files relative to the component's directory.
-
-## Defining multiple paths
-
-Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
-
-```py
-class MyComponent(Component):
- class Media:
- js = ["path/to/script1.js", "path/to/script2.js"]
- css = ["path/to/style1.css", "path/to/style2.css"]
-```
-
-## Configuring CSS Media Types
-
-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.
-
-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",
- }
-```
-
-```py
-class MyComponent(Component):
- class Media:
- css = {
- "all": ["path/to/style1.css", "path/to/style2.css"],
- "print": ["path/to/style3.css", "path/to/style4.css"],
- }
-```
-
-NOTE: When you define CSS as a string or a list, the `all` media type is implied.
-
-## Supported types for file paths
-
-File paths can be any of:
-
-- `str`
-- `bytes`
-- `PathLike` (`__fspath__` method)
-- `SafeData` (`__html__` method)
-- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
-
-```py
-from pathlib import Path
-
-from django.utils.safestring import mark_safe
-
-class SimpleComponent(Component):
- class Media:
- css = [
- mark_safe(''),
- Path("calendar/style1.css"),
- "calendar/style2.css",
- b"calendar/style3.css",
- lambda: "calendar/style4.css",
- ]
- js = [
- mark_safe(''),
- Path("calendar/script1.js"),
- "calendar/script2.js",
- b"calendar/script3.js",
- lambda: "calendar/script4.js",
- ]
-```
-
-## Path as objects
-
-In the example [above](#supported-types-for-file-paths), you could see that when we used `mark_safe` to mark a string as a `SafeString`, we had to define the full `'
- )
-
-@register("calendar")
-class Calendar(Component):
- template_name = "calendar/template.html"
-
- def get_context_data(self, date):
- return {
- "date": date,
- }
-
- class Media:
- css = "calendar/style.css"
- js = [
- # ',
- self.absolute_path(path)
- )
- return tags
-
-@register("calendar")
-class Calendar(Component):
- template_name = "calendar/template.html"
-
- class Media:
- css = "calendar/style.css"
- js = "calendar/script.js"
-
- # Override the behavior of Media class
- media_class = MyMedia
-```
-
-NOTE: The instance of the `Media` class (or it's subclass) is available under `Component.media` after the class creation (`__new__`).
diff --git a/docs/concepts/fundamentals/html_attributes.md b/docs/concepts/fundamentals/html_attributes.md
index 64e04b23..22b111d3 100644
--- a/docs/concepts/fundamentals/html_attributes.md
+++ b/docs/concepts/fundamentals/html_attributes.md
@@ -1,42 +1,183 @@
----
-title: HTML attributes
-weight: 7
----
-
_New in version 0.74_:
-You can use the `html_attrs` tag to render HTML attributes, given a dictionary
-of values.
+You can use the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag to render various data
+as `key="value"` HTML attributes.
-So if you have a template:
+[`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag is versatile, allowing you to define HTML attributes however you need:
+
+- Define attributes within the HTML template
+- Define attributes in Python code
+- Merge attributes from multiple sources
+- Boolean attributes
+- Append attributes
+- Remove attributes
+- Define default attributes
+
+From v0.135 onwards, [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag also supports merging [`style`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) and [`class`](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/class) attributes
+the same way [how Vue does](https://vuejs.org/guide/essentials/class-and-style).
+
+To get started, let's consider a simple example. If you have a template:
```django
- {% slot "header" / %}
-
-
- Today's date is {{ date }}
-
-
+
+```
+
+The [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag accepts any number of keyword arguments, which will be merged and rendered as HTML attributes:
+
+```django
+
+
+```
+
+Moreover, the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag accepts two positional arguments:
+
+- `attrs` - a dictionary of attributes to be rendered
+- `defaults` - a dictionary of default attributes
+
+You can use this for example to allow users of your component to add extra attributes. We achieve this by capturing the extra attributes and passing them to the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag as a dictionary:
+
+```djc_py
+@register("my_comp")
+class MyComp(Component):
+ # Pass all kwargs as `attrs`
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "attrs": kwargs,
+ "classes": "text-red",
+ "my_id": 123,
+ }
+
+ template: t.django_html = """
+ {# Pass the extra attributes to `html_attrs` #}
+
+
+ """
+```
+
+This way you can render `MyComp` with extra attributes:
+
+Either via Django template:
+
+```django
+{% component "my_comp"
+ id="example"
+ class="pa-4"
+ style="color: red;"
+%}
+```
+
+Or via Python:
+
+```py
+MyComp.render(
+ kwargs={
+ "id": "example",
+ "class": "pa-4",
+ "style": "color: red;",
+ }
+)
+```
+
+In both cases, the attributes will be merged and rendered as:
+
+```html
+
+```
+
+### Summary
+
+1. The two arguments, `attrs` and `defaults`, can be passed as positional args:
+
+ ```django
+ {% html_attrs attrs defaults key=val %}
+ ```
+
+ or as kwargs:
+
+ ```django
+ {% html_attrs key=val defaults=defaults attrs=attrs %}
+ ```
+
+2. Both `attrs` and `defaults` are optional and can be omitted.
+
+3. Both `attrs` and `defaults` are dictionaries. As such, there's multiple ways to define them:
+
+ - By referencing a variable:
+
+ ```django
+ {% html_attrs attrs=attrs %}
+ ```
+
+ - By defining a literal dictionary:
+
+ ```django
+ {% html_attrs attrs={"key": value} %}
+ ```
+
+ - Or by defining the [dictionary keys](../template_tag_syntax/#pass-dictonary-by-its-key-value-pairs):
+
+ ```django
+ {% html_attrs attrs:key=value %}
+ ```
+
+4. All other kwargs are merged and can be repeated.
+
+ ```django
+ {% html_attrs class="text-red" class="pa-4" %}
+ ```
+
+ Will render:
+
+ ```html
+
+ ```
+
+## Usage
+
+### Boolean attributes
+
+In HTML, boolean attributes are usually rendered with no value. Consider the example below where the first button is disabled and the second is not:
+
+```html
+
+
+```
+
+HTML rendering with [`html_attrs`](../../../reference/template_tags#html_attrs) tag or [`format_attributes`](../../../reference/api#django_components.format_attributes) works the same way - an attribute set to `True` is rendered without the value, and an attribute set to `False` is not rendered at all.
+
+So given this input:
+
+```py
+attrs = {
+ "disabled": True,
+ "autofocus": False,
+}
+```
+
+And template:
```django
-
-```
-
-Then this renders:
-
-```html
-
-```
-
-## Default attributes
-
-Sometimes you may want to specify default values for attributes. You can pass a second argument (or kwarg `defaults`) to set the defaults.
+Sometimes you may want to specify default values for attributes. You can pass a second positional argument to set the defaults.
```django
@@ -103,20 +212,30 @@ Sometimes you may want to specify default values for attributes. You can pass a
```
-In the example above, if `attrs` contains e.g. the `class` key, `html_attrs` will render:
+In the example above, if `attrs` contains a certain key, e.g. the `class` key, [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) will render:
-`class="{{ attrs.class }}"`
+```html
+
+ ...
+
+```
-Otherwise, `html_attrs` will render:
+Otherwise, [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) will render:
-`class="{{ defaults.class }}"`
+```html
+
+ ...
+
+```
-## Appending attributes
+### Appending attributes
For the `class` HTML attribute, it's common that we want to _join_ multiple values,
-instead of overriding them. For example, if you're authoring a component, you may
+instead of overriding them.
+
+For example, if you're authoring a component, you may
want to ensure that the component will ALWAYS have a specific class. Yet, you may
-want to allow users of your component to supply their own classes.
+want to allow users of your component to supply their own `class` attribute.
We can achieve this by adding extra kwargs. These values
will be appended, instead of overwriting the previous value.
@@ -129,7 +248,7 @@ attrs = {
}
```
-And on `html_attrs` tag, we set the key `class`:
+And on [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag, we set the key `class`:
```django
@@ -158,23 +277,179 @@ Renders:
>
```
-## Rules for `html_attrs`
+### Merging `class` attributes
-1. Both `attrs` and `defaults` can be passed as positional args
+The `class` attribute can be specified as a string of class names as usual.
- `{% html_attrs attrs defaults key=val %}`
+If you want granular control over individual class names, you can use a dictionary.
- or as kwargs
+- **String**: Used as is.
- `{% html_attrs key=val defaults=defaults attrs=attrs %}`
+ ```django
+ {% html_attrs class="my-class other-class" %}
+ ```
-2. Both `attrs` and `defaults` are optional (can be omitted)
+ Renders:
-3. Both `attrs` and `defaults` are dictionaries, and we can define them the same way [we define dictionaries for the `component` tag](#pass-dictonary-by-its-key-value-pairs). So either as `attrs=attrs` or `attrs:key=value`.
+ ```html
+
+ ```
-4. All other kwargs are appended and can be repeated.
+- **Dictionary**: Keys are the class names, and values are booleans. Only keys with truthy values are rendered.
-## Examples for `html_attrs`
+ ```django
+ {% html_attrs class={
+ "extra-class": True,
+ "other-class": False,
+ } %}
+ ```
+
+ Renders:
+
+ ```html
+
+ ```
+
+If a certain class is specified multiple times, it's the last instance that decides whether the class is rendered or not.
+
+**Example:**
+
+In this example, the `other-class` is specified twice. The last instance is `{"other-class": False}`, so the class is not rendered.
+
+```django
+{% html_attrs
+ class="my-class other-class"
+ class={"extra-class": True, "other-class": False}
+%}
+```
+
+Renders:
+
+```html
+
+```
+
+### Merging `style` attributes
+
+The `style` attribute can be specified as a string of style properties as usual.
+
+If you want granular control over individual style properties, you can use a dictionary.
+
+- **String**: Used as is.
+
+ ```django
+ {% html_attrs style="color: red; background-color: blue;" %}
+ ```
+
+ Renders:
+
+ ```html
+
+ ```
+
+- **Dictionary**: Keys are the style properties, and values are their values.
+
+ ```django
+ {% html_attrs style={
+ "color": "red",
+ "background-color": "blue",
+ } %}
+ ```
+
+ Renders:
+
+ ```html
+
+ ```
+
+If a style property is specified multiple times, the last value is used.
+
+- Properties set to `None` are ignored.
+- If the last non-`None` instance of the property is set to `False`, the property is removed.
+
+**Example:**
+
+In this example, the `width` property is specified twice. The last instance is `{"width": False}`, so the property is removed.
+
+Secondly, the `background-color` property is also set twice. But the second time it's set to `None`, so that instance is ignored, leaving us only with `background-color: blue`.
+
+The `color` property is set to a valid value in both cases, so the latter (`green`) is used.
+
+```django
+{% html_attrs
+ style="color: red; background-color: blue; width: 100px;"
+ style={"color": "green", "background-color": None, "width": False}
+%}
+```
+
+Renders:
+
+```html
+
+```
+
+## Usage outside of templates
+
+In some cases, you want to prepare HTML attributes outside of templates.
+
+To achieve the same behavior as [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag, you can use the [`merge_attributes()`](../../../reference/api#django_components.merge_attributes) and [`format_attributes()`](../../../reference/api#django_components.format_attributes) helper functions.
+
+### Merging attributes
+
+[`merge_attributes()`](../../../reference/api#django_components.merge_attributes) accepts any number of dictionaries and merges them together, using the same merge strategy as [`{% html_attrs %}`](../../../reference/template_tags#html_attrs).
+
+```python
+from django_components import merge_attributes
+
+merge_attributes(
+ {"class": "my-class", "data-id": 123},
+ {"class": "extra-class"},
+ {"class": {"cool-class": True, "uncool-class": False} },
+)
+```
+
+Which will output:
+
+```python
+{
+ "class": "my-class extra-class cool-class",
+ "data-id": 123,
+}
+```
+
+!!! warning
+
+ Unlike [`{% html_attrs %}`](../../../reference/template_tags#html_attrs), where you can pass extra kwargs, [`merge_attributes()`](../../../reference/api#django_components.merge_attributes) requires each argument to be a dictionary.
+
+### Formatting attributes
+
+[`format_attributes()`](../../../reference/api#django_components.format_attributes) serializes attributes the same way as [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag does.
+
+```py
+from django_components import format_attributes
+
+format_attributes({
+ "class": "my-class text-red pa-4",
+ "data-id": 123,
+ "required": True,
+ "disabled": False,
+ "ignored-attr": None,
+})
+```
+
+Which will output:
+
+```python
+'class="my-class text-red pa-4" data-id="123" required'
+```
+
+!!! note
+
+ Prior to v0.135, the `format_attributes()` function was named `attributes_to_string()`.
+
+ This function is now deprecated and will be removed in v1.0.
+
+## Cheat sheet
Assuming that:
@@ -194,69 +469,129 @@ defaults = {
Then:
-- Empty tag - `{% html_attr %}` +- **Empty tag** + + ```django + + ``` - renders (empty string):
- ` ` + renders nothing: -- Only kwargs
- `{% html_attr class="some-class" class=class_from_var data-id="123" %}` + ```html + + ``` - renders:
- `class="some-class from-var" data-id="123"` +- **Only kwargs** + + ```django + + ``` -- Only attrs
- `{% html_attr attrs %}` + renders: - renders:
- `class="from-attrs" type="submit"` + ```html + + ``` -- Attrs as kwarg
- `{% html_attr attrs=attrs %}` +- **Only attrs** - renders:
- `class="from-attrs" type="submit"` + ```django + + ``` -- Only defaults (as kwarg)
- `{% html_attr defaults=defaults %}` + renders: - renders:
- `class="from-defaults" role="button"` + ```html + + ``` -- Attrs using the `prefix:key=value` construct
- `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}` +- **Attrs as kwarg** - renders:
- `class="from-attrs" type="submit"` + ```django + + ``` -- Defaults using the `prefix:key=value` construct
- `{% html_attr defaults:class="from-defaults" %}` + renders: - renders:
- `class="from-defaults" role="button"` + ```html + + ``` -- All together (1) - attrs and defaults as positional args:
- `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}` +- **Only defaults (as kwarg)** - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` + ```django + + ``` -- All together (2) - attrs and defaults as kwargs args:
- `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}` + renders: - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` + ```html + + ``` -- All together (3) - mixed:
- `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}` +- **Attrs using the `prefix:key=value` construct** - renders:
- `class="from-attrs added_class from-var" type="submit" data-id=123` + ```django + + ``` -## Full example for `html_attrs` + renders: -```py + ```html + + ``` + +- **Defaults using the `prefix:key=value` construct** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (1) - attrs and defaults as positional args:** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (2) - attrs and defaults as kwargs args:** + + ```django + + ``` + + renders: + + ```html + + ``` + +- **All together (3) - mixed:** + + ```django + + ``` + + renders: + + ```html + + ``` + +## Full example + +```djc_py @register("my_comp") class MyComp(Component): template: t.django_html = """ @@ -272,10 +607,11 @@ class MyComp(Component):
+ 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
new file mode 100644
index 00000000..148fdc7b
--- /dev/null
+++ b/docs/concepts/fundamentals/http_request.md
@@ -0,0 +1,97 @@
+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 the HttpRequest object
+
+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`](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).
+
+So the request object is available to components either when:
+
+- 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
+# ✅ With request
+MyComponent.render(request=request)
+MyComponent.render(context=RequestContext(request, {}))
+
+# ❌ Without request
+MyComponent.render()
+MyComponent.render(context=Context({}))
+```
+
+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("""
+{{ user.username }}
+ + {% if show_details %} +Member for {{ user_joined_days }} days
+Email: {{ user.email }}
+ {% endif %} +
+ {% component "MyComponent" / %}
+
+""")
+
+# ❌ No request
+rendered = template.render(Context({}))
+
+# ✅ 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.
+
+```djc_py
+class MyComponent(Component):
+ template = """
+
+ {{ csrf_token }}
+
+ """
+
+MyComponent.render(request=request)
+```
+
+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_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 = """
+
+ {% 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) (`Today's date is {{ date }}
+
+ Today's date is {{ date }}
+
"""
css: types.css = """
- .calendar-component { width: 200px; background: pink; }
- .calendar-component span { font-weight: bold; }
+ .calendar {
+ width: 200px;
+ background: pink;
+ }
+ .calendar span {
+ font-weight: bold;
+ }
+ """
+
+ js: types.js = """
+ (function(){
+ if (document.querySelector(".calendar")) {
+ document.querySelector(".calendar").onclick = () => {
+ alert("Clicked calendar!");
+ };
+ }
+ })()
+ """
+```
+
+You can mix and match, so you can have a component with inlined HTML,
+while the JS and CSS are in separate files:
+
+```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 = """
@@ -34,4 +144,112 @@ class Calendar(Component):
"""
```
-This makes it easy to create small components without having to create a separate template, CSS, and JS file.
+### 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 f1ba610a..7a65dcc4 100644
--- a/docs/concepts/fundamentals/slots.md
+++ b/docs/concepts/fundamentals/slots.md
@@ -1,51 +1,74 @@
----
-title: Slots
-weight: 6
----
+django-components has the most extensive slot system of all the popular Python templating engines.
-_New in version 0.26_:
+The slot system is based on [Vue](https://vuejs.org/guide/components/slots.html), and works across both Django templates and Python code.
-- 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.
-
----
+## 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 %}
+
+
@@ -58,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
-
@@ -353,7 +424,7 @@ class RenderDependenciesTests(BaseTestCase):
"""
- self.assertHTMLEqual(expected, rendered)
+ assertHTMLEqual(expected, rendered)
# Explanation: The component is used in the template, but the template doesn't use
# {% component_js_dependencies %} or {% component_css_dependencies %} tags,
@@ -390,8 +461,8 @@ class RenderDependenciesTests(BaseTestCase):
"""
- rendered_raw = Template(template_str).render(Context({"formset": [1]}))
- rendered = render_dependencies(rendered_raw, type="fragment")
+ rendered_raw = Template(template_str).render(Context({"formset": [1], "DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw, strategy="fragment")
# Base64 encodings:
# `PGxpbmsgaHJlZj0ic3R5bGUuY3NzIiBtZWRpYT0iYWxsIiByZWw9InN0eWxlc2hlZXQiPg==` -> `` # noqa: E501
@@ -415,7 +486,7 @@ class RenderDependenciesTests(BaseTestCase):
1
- Variable: hi
+ Variable: hi
@@ -430,7 +501,7 @@ class RenderDependenciesTests(BaseTestCase):
""" # noqa: E501
- self.assertHTMLEqual(expected, rendered)
+ assertHTMLEqual(expected, rendered)
def test_raises_if_script_end_tag_inside_component_js(self):
class ComponentWithScript(SimpleComponent):
@@ -440,9 +511,9 @@ class RenderDependenciesTests(BaseTestCase):
registry.register(name="test", component=ComponentWithScript)
- with self.assertRaisesMessage(
+ with pytest.raises(
RuntimeError,
- "Content of `Component.js` for component 'ComponentWithScript' contains '' end tag.",
+ match=re.escape("Content of `Component.js` for component 'ComponentWithScript' contains '' end tag."), # noqa: E501
):
ComponentWithScript.render(kwargs={"variable": "foo"})
@@ -457,51 +528,597 @@ class RenderDependenciesTests(BaseTestCase):
registry.register(name="test", component=ComponentWithScript)
- with self.assertRaisesMessage(
+ with pytest.raises(
RuntimeError,
- "Content of `Component.css` for component 'ComponentWithScript' contains '' end tag.",
+ match=re.escape("Content of `Component.css` for component 'ComponentWithScript' contains '' end tag."), # noqa: E501
):
ComponentWithScript.render(kwargs={"variable": "foo"})
-class MiddlewareTests(BaseTestCase):
- def test_middleware_response_without_content_type(self):
- response = HttpResponseNotModified()
- middleware = ComponentDependencyMiddleware(get_response=lambda _: response)
- request = Mock()
- self.assertEqual(response, middleware(request=request))
+@djc_test
+class TestDependenciesStrategyDocument:
+ def test_inserts_styles_and_script_to_default_places_if_not_overriden(self):
+ registry.register(name="test", component=SimpleComponent)
- def test_middleware_response_with_components_with_slash_dash_and_underscore(
- self,
- ):
- registry.register("dynamic", DynamicComponent)
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+
+ {% component "test" variable="foo" / %}
+
+
+ """
+ rendered_raw = Template(template_str).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw, strategy="document")
- component_names = [
- "test-component",
- "test/component",
- "test_component",
- ]
- for component_name in component_names:
- registry.register(name=component_name, component=SimpleComponent)
- template_str: types.django_html = """
- {% load component_tags %}
- {% component_css_dependencies %}
- {% component_js_dependencies %}
- {% component "dynamic" is=component_name variable='value' / %}
+ assert rendered.count("
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
- # Dependency manager script (empty)
- self.assertInHTML('', rendered, count=1)
+ body_re = re.compile(r"(.*?)", re.DOTALL)
+ rendered_body = body_re.search(rendered).group(1) # type: ignore[union-attr]
- # Inlined JS
- self.assertInHTML('', rendered, count=1)
- # Inlined CSS
- self.assertInHTML("", rendered, count=1)
- # Media.css
- self.assertInHTML('', rendered, count=1)
+ assertInHTML(
+ """',
+ rendered_body,
+ count=1,
+ )
- self.assertEqual(rendered.count("Variable: value"), 1)
+ def test_does_not_insert_styles_and_script_to_default_places_if_overriden(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_js_dependencies %}
+
+
+ {% component "test" variable="foo" / %}
+ {% component_css_dependencies %}
+
+
+ """
+ rendered_raw = Template(template_str).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw, strategy="document")
+
+ assert rendered.count("
+ Variable: foo
+
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ head_re = re.compile(r"(.*?)", re.DOTALL)
+ rendered_head = head_re.search(rendered).group(1) # type: ignore[union-attr]
+
+ assertInHTML(
+ """',
+ rendered_head,
+ count=1,
+ )
+
+
+@djc_test
+class TestDependenciesStrategySimple:
+ def test_single_component(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ # Placeholders
+ assert rendered_raw.count('') == 1
+ assert rendered_raw.count('') == 1
+
+ assert rendered_raw.count("', rendered, count=0)
+
+ # Check that it contains inlined JS and CSS, and Media.css
+ assert rendered.strip() == (
+ '\n'
+ " \n'
+ " \n"
+ ' Variable: foo'
+ )
+
+ def test_multiple_components_dependencies(self):
+ class SimpleComponentNested(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ .my-class { color: red; }
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.css
+ # Order:
+ # - "style.css", "style2.css" (from SimpleComponentNested)
+ # - "style.css" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.css" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.js followed by inlined JS
+ # Order:
+ # - "script2.js" (from SimpleComponentNested)
+ # - "script.js" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.js" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Check that there's no payload like with "document" or "fragment" modes
+ assert "application/json" not in rendered
+
+
+@djc_test
+class TestDependenciesStrategyPrepend:
+ def test_single_component(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ # Placeholders
+ assert rendered_raw.count('') == 1
+ assert rendered_raw.count('') == 1
+
+ assert rendered_raw.count("', rendered, count=0)
+
+ # Check that it contains inlined JS and CSS, and Media.css
+ assert rendered.strip() == (
+ '\n'
+ " \n"
+ " \n"
+ " \n"
+ " \n"
+ ' Variable: foo'
+ )
+
+ def test_multiple_components_dependencies(self):
+ class SimpleComponentNested(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ .my-class { color: red; }
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.css
+ # Order:
+ # - "style.css", "style2.css" (from SimpleComponentNested)
+ # - "style.css" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.css" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.js followed by inlined JS
+ # Order:
+ # - "script2.js" (from SimpleComponentNested)
+ # - "script.js" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.js" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Check that there's no payload like with "document" or "fragment" modes
+ assert "application/json" not in rendered
+
+
+@djc_test
+class TestDependenciesStrategyAppend:
+ def test_single_component(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ # Placeholders
+ assert rendered_raw.count('') == 1
+ assert rendered_raw.count('') == 1
+
+ assert rendered_raw.count("', rendered, count=0)
+
+ # Check that it contains inlined JS and CSS, and Media.css
+ assert rendered.strip() == (
+ 'Variable: foo\n'
+ " \n"
+ ' '
+ )
+
+ def test_multiple_components_dependencies(self):
+ class SimpleComponentNested(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ .my-class { color: red; }
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.css
+ # Order:
+ # - "style.css", "style2.css" (from SimpleComponentNested)
+ # - "style.css" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.css" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Components' Media.js followed by inlined JS
+ # Order:
+ # - "script2.js" (from SimpleComponentNested)
+ # - "script.js" (from SimpleComponent inside SimpleComponentNested)
+ # - "xyz1.js" (from OtherComponent inserted into SimpleComponentNested)
+ assertInHTML(
+ """
+
+
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ # Check that there's no payload like with "document" or "fragment" modes
+ assert "application/json" not in rendered
+
+
+@djc_test
+class TestDependenciesStrategyRaw:
+ def test_single_component(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ # Placeholders
+ assert rendered_raw.count('') == 1
+ assert rendered_raw.count('') == 1
+
+ assert rendered_raw.count("\n'
+ ' \n'
+ ' \n'
+ ' Variable: foo'
+ )
diff --git a/tests/test_dependency_manager.py b/tests/test_dependency_manager.py
index 21980718..7b293f3f 100644
--- a/tests/test_dependency_manager.py
+++ b/tests/test_dependency_manager.py
@@ -1,12 +1,13 @@
+import re
from typing import List
-from django.test import override_settings
-from playwright.async_api import Error, Page
+import pytest
+from playwright.async_api import Browser, Error, Page
from django_components import types
-from tests.django_test_setup import setup_test_config
+from django_components.testing import djc_test
+from tests.testutils import setup_test_config
from tests.e2e.utils import TEST_SERVER_URL, with_playwright
-from tests.testutils import BaseTestCase
setup_test_config(
components={"autodiscover": False},
@@ -18,69 +19,73 @@ setup_test_config(
urlpatterns: List = []
-class _BaseDepManagerTestCase(BaseTestCase):
- async def _create_page_with_dep_manager(self) -> Page:
- page = await self.browser.new_page()
+async def _create_page_with_dep_manager(browser: Browser) -> Page:
+ page = await browser.new_page()
- # Load the JS library by opening a page with the script, and then running the script code
- # E.g. `http://localhost:54017/static/django_components/django_components.min.js`
- script_url = TEST_SERVER_URL + "/static/django_components/django_components.min.js"
- await page.goto(script_url)
+ # Load the JS library by opening a page with the script, and then running the script code
+ # E.g. `http://localhost:54017/static/django_components/django_components.min.js`
+ script_url = TEST_SERVER_URL + "/static/django_components/django_components.min.js"
+ await page.goto(script_url)
- # The page's body is the script code. We load it by executing the code
- await page.evaluate(
- """
- () => {
- eval(document.body.textContent);
- }
- """
- )
+ # The page's body is the script code. We load it by executing the code
+ await page.evaluate(
+ """
+ () => {
+ eval(document.body.textContent);
+ }
+ """
+ )
- # Ensure the body is clear
- await page.evaluate(
- """
- () => {
- document.body.innerHTML = '';
- document.head.innerHTML = '';
- }
- """
- )
+ # Ensure the body is clear
+ await page.evaluate(
+ """
+ () => {
+ document.body.innerHTML = '';
+ document.head.innerHTML = '';
+ }
+ """
+ )
- return page
+ return page
-@override_settings(STATIC_URL="static/")
-class DependencyManagerTests(_BaseDepManagerTestCase):
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestDependencyManager:
@with_playwright
async def test_script_loads(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
# Check the exposed API
keys = sorted(await page.evaluate("Object.keys(Components)"))
- self.assertEqual(keys, ["createComponentsManager", "manager", "unescapeJs"])
+ assert keys == ["createComponentsManager", "manager", "unescapeJs"]
keys = await page.evaluate("Object.keys(Components.manager)")
- self.assertEqual(
- keys,
- [
- "callComponent",
- "registerComponent",
- "registerComponentData",
- "loadJs",
- "loadCss",
- "markScriptLoaded",
- ],
- )
+ assert keys == [
+ "callComponent",
+ "registerComponent",
+ "registerComponentData",
+ "loadJs",
+ "loadCss",
+ "markScriptLoaded",
+ ]
await page.close()
# Tests for `manager.loadJs()` / `manager.loadCss()` / `manager.markAsLoaded()`
-@override_settings(STATIC_URL="static/")
-class LoadScriptTests(_BaseDepManagerTestCase):
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestLoadScript:
@with_playwright
async def test_load_js_scripts(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
# JS code that loads a few dependencies, capturing the HTML after each action
test_js: types.js = """() => {
@@ -113,20 +118,18 @@ class LoadScriptTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["bodyAfterFirstLoad"], '')
- self.assertEqual(data["bodyAfterSecondLoad"], '')
- self.assertEqual(
- data["bodyAfterThirdLoad"], ''
- )
+ assert data["bodyAfterFirstLoad"] == ''
+ assert data["bodyAfterSecondLoad"] == ''
+ assert data["bodyAfterThirdLoad"] == ''
- self.assertEqual(data["headBeforeFirstLoad"], data["headAfterThirdLoad"])
- self.assertEqual(data["headBeforeFirstLoad"], "")
+ assert data["headBeforeFirstLoad"] == data["headAfterThirdLoad"]
+ assert data["headBeforeFirstLoad"] == ""
await page.close()
@with_playwright
async def test_load_css_scripts(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
# JS code that loads a few dependencies, capturing the HTML after each action
test_js: types.js = """() => {
@@ -159,18 +162,18 @@ class LoadScriptTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["headAfterFirstLoad"], '')
- self.assertEqual(data["headAfterSecondLoad"], '')
- self.assertEqual(data["headAfterThirdLoad"], '')
+ assert data["headAfterFirstLoad"] == ''
+ assert data["headAfterSecondLoad"] == ''
+ assert data["headAfterThirdLoad"] == ''
- self.assertEqual(data["bodyBeforeFirstLoad"], data["bodyAfterThirdLoad"])
- self.assertEqual(data["bodyBeforeFirstLoad"], "")
+ assert data["bodyBeforeFirstLoad"] == data["bodyAfterThirdLoad"]
+ assert data["bodyBeforeFirstLoad"] == ""
await page.close()
@with_playwright
async def test_does_not_load_script_if_marked_as_loaded(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
# JS code that loads a few dependencies, capturing the HTML after each action
test_js: types.js = """() => {
@@ -194,28 +197,32 @@ class LoadScriptTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["headAfterFirstLoad"], "")
- self.assertEqual(data["bodyAfterSecondLoad"], "")
+ assert data["headAfterFirstLoad"] == ""
+ assert data["bodyAfterSecondLoad"] == ""
await page.close()
# Tests for `manager.registerComponent()` / `registerComponentData()` / `callComponent()`
-@override_settings(STATIC_URL="static/")
-class CallComponentTests(_BaseDepManagerTestCase):
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestCallComponent:
@with_playwright
async def test_calls_component_successfully(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
const compName = 'my_comp';
- const compId = '12345';
+ const compId = 'c12345';
const inputHash = 'input-abc';
// Pretend that this HTML belongs to our component
- document.body.insertAdjacentHTML('beforeend', '\n'
+ ' '
+ )
def test_no_js_dependencies_when_no_components_used(self):
registry.register(name="test", component=SimpleComponent)
@@ -139,19 +137,21 @@ class DependencyRenderingTests(BaseTestCase):
{% load component_tags %}{% component_js_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=0)
- self.assertEqual(rendered.count("'
def test_no_css_dependencies_when_no_components_used(self):
registry.register(name="test", component=SimpleComponent)
@@ -160,11 +160,13 @@ class DependencyRenderingTests(BaseTestCase):
{% load component_tags %}{% component_css_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered: str = template.render(Context({}))
- self.assertEqual(rendered.count("'
def test_single_component_dependencies(self):
registry.register(name="test", component=SimpleComponent)
@@ -176,19 +178,19 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' variable='foo' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=1)
- self.assertEqual(rendered.count(''), 1) # Media.css
- self.assertEqual(rendered.count("') == 1 # Media.css
+ assert rendered.count("
{"loadedCssUrls": ["c3R5bGUuY3Nz"],
@@ -211,19 +213,19 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'te-s/t' variable='foo' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=1)
- self.assertEqual(rendered.count(''), 1) # Media.css
- self.assertEqual(rendered.count("') == 1 # Media.css
+ assert rendered.count("
{"loadedCssUrls": ["c3R5bGUuY3Nz"],
@@ -246,9 +248,9 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' variable='foo' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
- self.assertNotIn("_RENDERED", rendered)
+ assert "_RENDERED" not in rendered
def test_single_component_css_dependencies(self):
registry.register(name="test", component=SimpleComponent)
@@ -258,16 +260,16 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' variable='foo' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script - NOT present
- self.assertInHTML('', rendered, count=0)
+ assertInHTML('', rendered, count=0)
- self.assertEqual(rendered.count("'), 1) # Media.css
+ assert rendered.count('') == 1 # Media.css
def test_single_component_js_dependencies(self):
registry.register(name="test", component=SimpleComponent)
@@ -277,19 +279,19 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' variable='foo' %}{% endcomponent %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=1)
# CSS NOT included
- self.assertEqual(rendered.count("
{"loadedCssUrls": ["c3R5bGUuY3Nz"],
@@ -313,17 +315,17 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=1)
- self.assertEqual(rendered.count("
@@ -333,7 +335,7 @@ class DependencyRenderingTests(BaseTestCase):
)
# Media.js
- self.assertInHTML(
+ assertInHTML(
"""
@@ -347,7 +349,7 @@ class DependencyRenderingTests(BaseTestCase):
# `c3R5bGUyLmNzcw==` -> `style2.css`
# `c2NyaXB0Lmpz` -> `script.js`
# `c2NyaXB0Mi5qcw==` -> `script2.js`
- self.assertInHTML(
+ assertInHTML(
"""
', rendered, count=1)
+ assertInHTML('', rendered, count=0)
- self.assertEqual(rendered.count("\n'
+ ' '
+ )
def test_multiple_components_dependencies(self):
registry.register(name="inner", component=SimpleComponent)
@@ -398,19 +405,19 @@ class DependencyRenderingTests(BaseTestCase):
{% endcomponent %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered: str = template.render(Context({}))
# Dependency manager script
# NOTE: Should be present only ONCE!
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=1)
- self.assertEqual(rendered.count(".my-class { color: red; }
@@ -424,7 +431,7 @@ class DependencyRenderingTests(BaseTestCase):
# - "style.css", "style2.css" (from SimpleComponentNested)
# - "style.css" (from SimpleComponent inside SimpleComponentNested)
# - "xyz1.css" (from OtherComponent inserted into SimpleComponentNested)
- self.assertInHTML(
+ assertInHTML(
"""
@@ -439,7 +446,7 @@ class DependencyRenderingTests(BaseTestCase):
# - "script2.js" (from SimpleComponentNested)
# - "script.js" (from SimpleComponent inside SimpleComponentNested)
# - "xyz1.js" (from OtherComponent inserted into SimpleComponentNested)
- self.assertInHTML(
+ assertInHTML(
"""
@@ -456,17 +463,25 @@ class DependencyRenderingTests(BaseTestCase):
# `c3R5bGUyLmNzcw==` -> `style2.css`
# `eHl6MS5jc3M=` -> `xyz1.css`
# `L2NvbXBvbmVudHMvY2FjaGUvT3RoZXJDb21wb25lbnRfNjMyOWFlLmNzcw==` -> `/components/cache/OtherComponent_6329ae.css`
- # `L2NvbXBvbmVudHMvY2FjaGUvU2ltcGxlQ29tcG9uZW50TmVzdGVkX2YwMmQzMi5jc3M=` -> `/components/cache/SimpleComponentNested_f02d32.css`
# `L2NvbXBvbmVudHMvY2FjaGUvT3RoZXJDb21wb25lbnRfNjMyOWFlLmpz` -> `/components/cache/OtherComponent_6329ae.js`
+ # `L2NvbXBvbmVudHMvY2FjaGUvU2ltcGxlQ29tcG9uZW50TmVzdGVkX2YwMmQzMi5jc3M=` -> `/components/cache/SimpleComponentNested_f02d32.css`
# `L2NvbXBvbmVudHMvY2FjaGUvU2ltcGxlQ29tcG9uZW50TmVzdGVkX2YwMmQzMi5qcw==` -> `/components/cache/SimpleComponentNested_f02d32.js`
# `c2NyaXB0Lmpz` -> `script.js`
# `c2NyaXB0Mi5qcw==` -> `script2.js`
# `eHl6MS5qcw==` -> `xyz1.js`
- self.assertInHTML(
+ assertInHTML(
"""
@@ -489,5 +504,130 @@ class DependencyRenderingTests(BaseTestCase):
{% component 'test' variable='variable' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertNotIn("_RENDERED", rendered)
+ rendered = template.render(Context({}))
+ assert "_RENDERED" not in rendered
+
+ def test_adds_component_id_html_attr_single(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(rendered, "Variable: foo")
+
+ def test_adds_component_id_html_attr_single_multiroot(self):
+ class SimpleMultiroot(SimpleComponent):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ Variable2:
-
-```
-
-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:
-
-```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`):
-
-```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
+ {% component "inner" variable=variable / %}
+ {% slot "default" default / %}
+
+ """
+
+ css: types.css = """
+ .my-class {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("Hello");
+ """
+
+ class Media:
+ css = ["style.css", "style2.css"]
+ js = "script2.js"
+
+ class OtherComponent(Component):
+ template: types.django_html = """
+ XYZ: {{ variable }}
+ """
+
+ css: types.css = """
+ .xyz {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("xyz");
+ """
+
+ class Media:
+ css = "xyz1.css"
+ js = "xyz1.js"
+
+ registry.register(name="inner", component=SimpleComponent)
+ registry.register(name="outer", component=SimpleComponentNested)
+ registry.register(name="other", component=OtherComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ rendered = render_dependencies(rendered_raw, strategy="simple")
+
+ # Dependency manager script NOT present
+ assertInHTML('', rendered, count=0)
+
+ assert rendered.count("
+ {% component "inner" variable=variable / %}
+ {% slot "default" default / %}
+
+ """
+
+ css: types.css = """
+ .my-class {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("Hello");
+ """
+
+ class Media:
+ css = ["style.css", "style2.css"]
+ js = "script2.js"
+
+ class OtherComponent(Component):
+ template: types.django_html = """
+ XYZ: {{ variable }}
+ """
+
+ css: types.css = """
+ .xyz {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("xyz");
+ """
+
+ class Media:
+ css = "xyz1.css"
+ js = "xyz1.js"
+
+ registry.register(name="inner", component=SimpleComponent)
+ registry.register(name="outer", component=SimpleComponentNested)
+ registry.register(name="other", component=OtherComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ rendered = render_dependencies(rendered_raw, strategy="prepend")
+
+ # Dependency manager script NOT present
+ assertInHTML('', rendered, count=0)
+
+ assert rendered.count("
+ {% component "inner" variable=variable / %}
+ {% slot "default" default / %}
+
+ """
+
+ css: types.css = """
+ .my-class {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("Hello");
+ """
+
+ class Media:
+ css = ["style.css", "style2.css"]
+ js = "script2.js"
+
+ class OtherComponent(Component):
+ template: types.django_html = """
+ XYZ: {{ variable }}
+ """
+
+ css: types.css = """
+ .xyz {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("xyz");
+ """
+
+ class Media:
+ css = "xyz1.css"
+ js = "xyz1.js"
+
+ registry.register(name="inner", component=SimpleComponent)
+ registry.register(name="outer", component=SimpleComponentNested)
+ registry.register(name="other", component=OtherComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered_raw: str = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ rendered = render_dependencies(rendered_raw, strategy="append")
+
+ # Dependency manager script NOT present
+ assertInHTML('', rendered, count=0)
+
+ assert rendered.count(" abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
let captured = null;
manager.registerComponent(compName, (data, ctx) => {
@@ -240,36 +247,33 @@ class CallComponentTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["result"], 123)
- self.assertEqual(
- data["captured"],
- {
- "data": {
- "hello": "world",
- },
- "ctx": {
- "els": [' abc
'],
- "id": "12345",
- "name": "my_comp",
- },
+ assert data["result"] == 123
+ assert data["captured"] == {
+ "data": {
+ "hello": "world",
},
- )
+ "ctx": {
+ "els": [' abc
'],
+ "id": "c12345",
+ "name": "my_comp",
+ },
+ }
await page.close()
@with_playwright
async def test_calls_component_successfully_async(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
const compName = 'my_comp';
- const compId = '12345';
+ const compId = 'c12345';
const inputHash = 'input-abc';
// Pretend that this HTML belongs to our component
- document.body.insertAdjacentHTML('beforeend', ' abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
manager.registerComponent(compName, (data, ctx) => {
return Promise.resolve(123);
@@ -292,24 +296,24 @@ class CallComponentTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["result"], 123)
- self.assertEqual(data["isPromise"], True)
+ assert data["result"] == 123
+ assert data["isPromise"] is True
await page.close()
@with_playwright
async def test_error_in_component_call_do_not_propagate_sync(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
const compName = 'my_comp';
- const compId = '12345';
+ const compId = 'c12345';
const inputHash = 'input-abc';
// Pretend that this HTML belongs to our component
- document.body.insertAdjacentHTML('beforeend', ' abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
manager.registerComponent(compName, (data, ctx) => {
throw Error('Oops!');
@@ -327,23 +331,23 @@ class CallComponentTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data, None)
+ assert data is None
await page.close()
@with_playwright
async def test_error_in_component_call_do_not_propagate_async(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
const compName = 'my_comp';
- const compId = '12345';
+ const compId = 'c12345';
const inputHash = 'input-abc';
// Pretend that this HTML belongs to our component
- document.body.insertAdjacentHTML('beforeend', ' abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
manager.registerComponent(compName, async (data, ctx) => {
throw Error('Oops!');
@@ -360,16 +364,16 @@ class CallComponentTests(_BaseDepManagerTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(len(data), 1)
- self.assertEqual(data[0]["status"], "rejected")
- self.assertIsInstance(data[0]["reason"], Error)
- self.assertEqual(data[0]["reason"].message, "Oops!")
+ assert len(data) == 1
+ assert data[0]["status"] == "rejected"
+ assert isinstance(data[0]["reason"], Error)
+ assert data[0]["reason"].message == "Oops!"
await page.close()
@with_playwright
async def test_raises_if_component_element_not_in_dom(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
@@ -390,8 +394,9 @@ class CallComponentTests(_BaseDepManagerTestCase):
manager.callComponent(compName, compId, inputHash);
}"""
- with self.assertRaisesMessage(
- Error, "Error: [Components] 'my_comp': No elements with component ID '12345' found"
+ with pytest.raises(
+ Error,
+ match=re.escape("Error: [Components] 'my_comp': No elements with component ID '12345' found"),
):
await page.evaluate(test_js)
@@ -399,16 +404,16 @@ class CallComponentTests(_BaseDepManagerTestCase):
@with_playwright
async def test_raises_if_input_hash_not_registered(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
const compName = 'my_comp';
- const compId = '12345';
+ const compId = 'c12345';
const inputHash = 'input-abc';
- document.body.insertAdjacentHTML('beforeend', ' abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
manager.registerComponent(compName, (data, ctx) => {
return Promise.resolve(123);
@@ -418,14 +423,17 @@ class CallComponentTests(_BaseDepManagerTestCase):
manager.callComponent(compName, compId, inputHash);
}"""
- with self.assertRaisesMessage(Error, "Error: [Components] 'my_comp': Cannot find input for hash 'input-abc'"):
+ with pytest.raises(
+ Error,
+ match=re.escape("Error: [Components] 'my_comp': Cannot find input for hash 'input-abc'"),
+ ):
await page.evaluate(test_js)
await page.close()
@with_playwright
async def test_raises_if_component_not_registered(self):
- page = await self._create_page_with_dep_manager()
+ page = await _create_page_with_dep_manager(self.browser) # type: ignore[attr-defined]
test_js: types.js = """() => {
const manager = Components.createComponentsManager();
@@ -434,7 +442,7 @@ class CallComponentTests(_BaseDepManagerTestCase):
const compId = '12345';
const inputHash = 'input-abc';
- document.body.insertAdjacentHTML('beforeend', ' abc
');
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
manager.registerComponentData(compName, inputHash, () => {
return { hello: 'world' };
@@ -444,7 +452,10 @@ class CallComponentTests(_BaseDepManagerTestCase):
manager.callComponent(compName, compId, inputHash);
}"""
- with self.assertRaisesMessage(Error, "Error: [Components] 'my_comp': No component registered for that name"):
+ with pytest.raises(
+ Error,
+ match=re.escape("Error: [Components] 'my_comp': No component registered for that name"),
+ ):
await page.evaluate(test_js)
await page.close()
diff --git a/tests/test_dependency_rendering.py b/tests/test_dependency_rendering.py
index 9875d8b1..336d6fd9 100644
--- a/tests/test_dependency_rendering.py
+++ b/tests/test_dependency_rendering.py
@@ -5,12 +5,13 @@ During actual rendering, the HTML is then picked up by the JS-side dependency ma
import re
-from django.template import Template
+from django.template import Context, Template
+from pytest_django.asserts import assertHTMLEqual, assertInHTML
from django_components import Component, registry, types
+from django_components.testing import djc_test
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase, create_and_process_template_response
+from .testutils import setup_test_config
setup_test_config({"autodiscover": False})
@@ -24,10 +25,10 @@ class SimpleComponent(Component):
Variable: {{ variable }}
"""
- def get_context_data(self, variable, variable2="default"):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "variable": variable,
- "variable2": variable2,
+ "variable": kwargs["variable"],
+ "variable2": kwargs.get("variable2", "default"),
}
class Media:
@@ -54,9 +55,6 @@ class SimpleComponentNested(Component):
console.log("Hello");
"""
- def get_context_data(self, variable):
- return {}
-
class Media:
css = ["style.css", "style2.css"]
js = "script2.js"
@@ -77,9 +75,6 @@ class OtherComponent(Component):
console.log("xyz");
"""
- def get_context_data(self, variable):
- return {}
-
class Media:
css = "xyz1.css"
js = "xyz1.js"
@@ -90,9 +85,6 @@ class SimpleComponentWithSharedDependency(Component):
Variable: {{ variable }}
"""
- def get_context_data(self, variable, variable2="default"):
- return {}
-
class Media:
css = ["style.css", "style2.css"]
js = ["script.js", "script2.js"]
@@ -108,7 +100,8 @@ class MultistyleComponent(Component):
js = ["script.js", "script2.js"]
-class DependencyRenderingTests(BaseTestCase):
+@djc_test
+class TestDependencyRendering:
def test_no_dependencies_when_no_components_used(self):
registry.register(name="test", component=SimpleComponent)
@@ -118,19 +111,24 @@ class DependencyRenderingTests(BaseTestCase):
{% component_css_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
+ rendered: str = template.render(Context({}))
# Dependency manager script
- self.assertInHTML('', rendered, count=1)
+ assertInHTML('', rendered, count=0)
- self.assertEqual(rendered.count("{{ variable }}
+ Variable3: {{ variable }}
+ """
+
+ registry.register(name="test", component=SimpleMultiroot)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: foo
+ Variable2: foo
+ Variable3: foo
+ """,
+ )
+
+ # Test that, if multiple components share the same root HTML elements,
+ # then those elemens will have the `data-djc-id-` attribute added for each component.
+ def test_adds_component_id_html_attr_nested(self):
+ class SimpleMultiroot(SimpleComponent):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ Variable2: {{ variable }}
+ Variable3: {{ variable }}
+ """
+
+ class SimpleOuter(SimpleComponent):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component 'multiroot' variable='foo' / %}
+ Another
+ """
+
+ registry.register(name="multiroot", component=SimpleMultiroot)
+ registry.register(name="outer", component=SimpleOuter)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'outer' variable='foo' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: foo
+ Variable2: foo
+ Variable3: foo
+ Another
+ """,
+ )
+
+ # `data-djc-id-` attribute should be added on each instance in the RESULTING HTML.
+ # So if in a loop, each iteration creates a new component, and each of those should
+ # have a unique `data-djc-id-` attribute.
+ def test_adds_component_id_html_attr_loops(self):
+ class SimpleMultiroot(SimpleComponent):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ Variable2: {{ variable }}
+ Variable3: {{ variable }}
+ """
+
+ class SimpleOuter(SimpleComponent):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component 'multiroot' variable='foo' / %}
+ Another
+ """
+
+ registry.register(name="multiroot", component=SimpleMultiroot)
+ registry.register(name="outer", component=SimpleOuter)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% for i in lst %}
+ {% component 'outer' variable='foo' / %}
+ {% endfor %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({"lst": range(3)}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: foo
+ Variable2: foo
+ Variable3: foo
+ Another
+
+ Variable: foo
+ Variable2: foo
+ Variable3: foo
+ Another
+
+ Variable: foo
+ Variable2: foo
+ Variable3: foo
+ Another
+ """,
+ )
diff --git a/tests/test_dependency_rendering_e2e.py b/tests/test_dependency_rendering_e2e.py
index d016a7c1..f53ceb72 100644
--- a/tests/test_dependency_rendering_e2e.py
+++ b/tests/test_dependency_rendering_e2e.py
@@ -3,24 +3,28 @@ Here we check that all parts of managing JS and CSS dependencies work together
in an actual browser.
"""
+import re
+
from playwright.async_api import Page
+from pytest_django.asserts import assertHTMLEqual, assertInHTML
from django_components import types
-from tests.django_test_setup import setup_test_config
+from django_components.testing import djc_test
+from tests.testutils import setup_test_config
from tests.e2e.utils import TEST_SERVER_URL, with_playwright
-from tests.testutils import BaseTestCase
setup_test_config({"autodiscover": False})
# NOTE: All views, components, and associated JS and CSS are defined in
# `tests/e2e/testserver/testserver`
-class E2eDependencyRenderingTests(BaseTestCase):
+@djc_test
+class TestE2eDependencyRendering:
@with_playwright
async def test_single_component_dependencies(self):
single_comp_url = TEST_SERVER_URL + "/single"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -44,21 +48,23 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
# Check that the actual HTML content was loaded
- self.assertIn('Variable: foo', data["bodyHTML"])
- self.assertInHTML(' 123
', data["bodyHTML"], count=1)
- self.assertInHTML(' xyz
', data["bodyHTML"], count=1)
+ assert re.compile(
+ r'Variable: foo'
+ ).search(data["bodyHTML"]) is not None
+ assertInHTML(' 123
', data["bodyHTML"], count=1)
+ assertInHTML(' xyz
', data["bodyHTML"], count=1)
# Check components' inlined JS got loaded
- self.assertEqual(data["componentJsMsg"], "kapowww!")
+ assert data["componentJsMsg"] == "kapowww!"
# Check JS from Media.js got loaded
- self.assertEqual(data["scriptJsMsg"], {"hello": "world"})
+ assert data["scriptJsMsg"] == {"hello": "world"}
# Check components' inlined CSS got loaded
- self.assertEqual(data["innerFontSize"], "4px")
+ assert data["innerFontSize"] == "4px"
# Check CSS from Media.css got loaded
- self.assertIn("rgb(0, 0, 255)", data["myStyleBg"]) # AKA 'background: blue'
+ assert "rgb(0, 0, 255)" in data["myStyleBg"] # AKA 'background: blue'
await page.close()
@@ -66,7 +72,7 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_multiple_component_dependencies(self):
single_comp_url = TEST_SERVER_URL + "/multi"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -106,36 +112,50 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
# Check that the actual HTML content was loaded
- self.assertInHTML(
- """
-
- Variable: variable
- XYZ: variable_inner
-
- 123
- xyz
- """,
- data["bodyHTML"],
- count=1,
- )
+ assert re.compile(
+ #
+ # Variable:
+ #
+ # variable
+ #
+ # XYZ:
+ #
+ # variable_inner
+ #
+ #
+ # 123
+ # xyz
+ r'\s*'
+ r"Variable:\s*"
+ r'\s*'
+ r"variable\s*"
+ r"<\/strong>\s*"
+ r"XYZ:\s*"
+ r'\s*'
+ r"variable_inner\s*"
+ r"<\/strong>\s*"
+ r"<\/div>\s*"
+ r'
123<\/div>\s*'
+ r'
xyz<\/div>\s*'
+ ).search(data["bodyHTML"]) is not None
# Check components' inlined JS got loaded
- self.assertEqual(data["component1JsMsg"], "kapowww!")
- self.assertEqual(data["component2JsMsg"], "bongo!")
- self.assertEqual(data["component3JsMsg"], "wowzee!")
+ assert data["component1JsMsg"] == "kapowww!"
+ assert data["component2JsMsg"] == "bongo!"
+ assert data["component3JsMsg"] == "wowzee!"
# Check JS from Media.js got loaded
- self.assertEqual(data["scriptJs1Msg"], {"hello": "world"})
- self.assertEqual(data["scriptJs2Msg"], {"hello2": "world2"})
+ assert data["scriptJs1Msg"] == {"hello": "world"}
+ assert data["scriptJs2Msg"] == {"hello2": "world2"}
# Check components' inlined CSS got loaded
- self.assertEqual(data["innerFontSize"], "4px")
- self.assertEqual(data["outerFontSize"], "40px")
- self.assertEqual(data["otherDisplay"], "flex")
+ assert data["innerFontSize"] == "4px"
+ assert data["outerFontSize"] == "40px"
+ assert data["otherDisplay"] == "flex"
# Check CSS from Media.css got loaded
- self.assertIn("rgb(0, 0, 255)", data["myStyleBg"]) # AKA 'background: blue'
- self.assertEqual("rgb(255, 0, 0)", data["myStyle2Color"]) # AKA 'color: red'
+ assert "rgb(0, 0, 255)" in data["myStyleBg"] # AKA 'background: blue'
+ assert data["myStyle2Color"] == "rgb(255, 0, 0)" # AKA 'color: red'
await page.close()
@@ -143,7 +163,7 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_renders_css_nojs_env(self):
single_comp_url = TEST_SERVER_URL + "/multi"
- page: Page = await self.browser.new_page(java_script_enabled=False)
+ page: Page = await self.browser.new_page(java_script_enabled=False) # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -183,36 +203,51 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
# Check that the actual HTML content was loaded
- self.assertInHTML(
- """
-
- Variable: variable
- XYZ: variable_inner
-
- 123
- xyz
- """,
- data["bodyHTML"],
- count=1,
- )
+ #
+ #
+ # Variable:
+ #
+ # variable
+ #
+ # XYZ:
+ #
+ # variable_inner
+ #
+ #
+ # 123
+ # xyz
+ assert re.compile(
+ r'\s*'
+ r"Variable:\s*"
+ r'\s*'
+ r"variable\s*"
+ r"<\/strong>\s*"
+ r"XYZ:\s*"
+ r'\s*'
+ r"variable_inner\s*"
+ r"<\/strong>\s*"
+ r"<\/div>\s*"
+ r'
123<\/div>\s*'
+ r'
xyz<\/div>\s*'
+ ).search(data["bodyHTML"]) is not None
# Check components' inlined JS did NOT get loaded
- self.assertEqual(data["component1JsMsg"], None)
- self.assertEqual(data["component2JsMsg"], None)
- self.assertEqual(data["component3JsMsg"], None)
+ assert data["component1JsMsg"] is None
+ assert data["component2JsMsg"] is None
+ assert data["component3JsMsg"] is None
# Check JS from Media.js did NOT get loaded
- self.assertEqual(data["scriptJs1Msg"], None)
- self.assertEqual(data["scriptJs2Msg"], None)
+ assert data["scriptJs1Msg"] is None
+ assert data["scriptJs2Msg"] is None
# Check components' inlined CSS got loaded
- self.assertEqual(data["innerFontSize"], "4px")
- self.assertEqual(data["outerFontSize"], "40px")
- self.assertEqual(data["otherDisplay"], "flex")
+ assert data["innerFontSize"] == "4px"
+ assert data["outerFontSize"] == "40px"
+ assert data["otherDisplay"] == "flex"
# Check CSS from Media.css got loaded
- self.assertIn("rgb(0, 0, 255)", data["myStyleBg"]) # AKA 'background: blue'
- self.assertEqual("rgb(255, 0, 0)", data["myStyle2Color"]) # AKA 'color: red'
+ assert "rgb(0, 0, 255)" in data["myStyleBg"] # AKA 'background: blue'
+ assert "rgb(255, 0, 0)" in data["myStyle2Color"] # AKA 'color: red'
await page.close()
@@ -220,7 +255,7 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_js_executed_in_order__js(self):
single_comp_url = TEST_SERVER_URL + "/js-order/js"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -232,13 +267,13 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
# Check components' inlined JS got loaded
- self.assertEqual(data["testSimpleComponent"], "kapowww!")
- self.assertEqual(data["testSimpleComponentNested"], "bongo!")
- self.assertEqual(data["testOtherComponent"], "wowzee!")
+ assert data["testSimpleComponent"] == "kapowww!"
+ assert data["testSimpleComponentNested"] == "bongo!"
+ assert data["testOtherComponent"] == "wowzee!"
# Check JS from Media.js got loaded
- self.assertEqual(data["testMsg"], {"hello": "world"})
- self.assertEqual(data["testMsg2"], {"hello2": "world2"})
+ assert data["testMsg"] == {"hello": "world"}
+ assert data["testMsg2"] == {"hello2": "world2"}
await page.close()
@@ -246,7 +281,7 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_js_executed_in_order__media(self):
single_comp_url = TEST_SERVER_URL + "/js-order/media"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -259,13 +294,13 @@ class E2eDependencyRenderingTests(BaseTestCase):
# Check components' inlined JS got loaded
# NOTE: The Media JS are loaded BEFORE the components' JS, so they should be empty
- self.assertEqual(data["testSimpleComponent"], None)
- self.assertEqual(data["testSimpleComponentNested"], None)
- self.assertEqual(data["testOtherComponent"], None)
+ assert data["testSimpleComponent"] is None
+ assert data["testSimpleComponentNested"] is None
+ assert data["testOtherComponent"] is None
# Check JS from Media.js
- self.assertEqual(data["testMsg"], {"hello": "world"})
- self.assertEqual(data["testMsg2"], {"hello2": "world2"})
+ assert data["testMsg"] == {"hello": "world"}
+ assert data["testMsg2"] == {"hello2": "world2"}
await page.close()
@@ -276,7 +311,7 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_js_executed_in_order__invalid(self):
single_comp_url = TEST_SERVER_URL + "/js-order/invalid"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
test_js: types.js = """() => {
@@ -287,20 +322,20 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
# Check components' inlined JS got loaded
- self.assertEqual(data["testSimpleComponent"], None)
- self.assertEqual(data["testSimpleComponentNested"], None)
- self.assertEqual(data["testOtherComponent"], None)
+ assert data["testSimpleComponent"] is None
+ assert data["testSimpleComponentNested"] is None
+ assert data["testOtherComponent"] is None
# Check JS from Media.js got loaded
- self.assertEqual(data["testMsg"], None)
- self.assertEqual(data["testMsg2"], None)
+ assert data["testMsg"] is None
+ assert data["testMsg2"] is None
await page.close()
# Fragment where JS and CSS is defined on Component class
@with_playwright
async def test_fragment_comp(self):
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(f"{TEST_SERVER_URL}/fragment/base/js?frag=comp")
test_before_js: types.js = """() => {
@@ -314,8 +349,8 @@ class E2eDependencyRenderingTests(BaseTestCase):
data_before = await page.evaluate(test_before_js)
- self.assertEqual(data_before["targetHtml"], ' ", # noqa E501
+ # NOTE: This is whitespace-sensitive test, so we check exact output
+ assert rendered.strip() == (
+ "\n"
+ ' \n'
+ ' '
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_mixed_in_template(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_mixed_in_template(self, components_settings):
registry.library.tag(noop)
captured = {}
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- pos_var2: Any,
- *args: Any,
- bool_var: bool,
- list_var: Dict,
- dict_var: Dict,
- ):
- captured["pos_var1"] = pos_var1
- captured["bool_var"] = bool_var
- captured["list_var"] = list_var
- captured["dict_var"] = dict_var
+ def get_template_data(self, args, kwargs, slots, context):
+ captured["pos_var1"] = args[0]
+ captured["bool_var"] = kwargs["bool_var"]
+ captured["list_var"] = kwargs["list_var"]
+ captured["dict_var"] = kwargs["dict_var"]
return {
- "pos_var1": pos_var1,
- "pos_var2": pos_var2,
- "bool_var": bool_var,
- "list_var": list_var,
- "dict_var": dict_var,
+ "pos_var1": args[0],
+ "pos_var2": args[1],
+ "bool_var": kwargs["bool_var"],
+ "list_var": kwargs["list_var"],
+ "dict_var": kwargs["dict_var"],
}
template: types.django_html = """
@@ -335,20 +289,19 @@ class DynamicExprTests(BaseTestCase):
{% load component_tags %}
{% component 'test'
" {% lorem var_a w %} "
- " {% lorem var_a w %} {{ list|slice:':-1' }} "
+ " {% lorem var_a w %} {{ list|slice:':-1'|safe }} "
bool_var=" {% noop is_active %} "
list_var=" {% noop list %} "
dict_var=" {% noop dict %} "
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
- rendered = template.render(
+ rendered: str = template.render(
Context(
{
+ "DJC_DEPS_STRATEGY": "ignore",
"var_a": 3,
"is_active": True,
"list": [{"a": 1}, {"a": 2}],
@@ -358,32 +311,31 @@ class DynamicExprTests(BaseTestCase):
)
# Check that variables passed to the component are of correct type
- self.assertEqual(captured["bool_var"], " True ")
- self.assertEqual(captured["dict_var"], " {'a': 3} ")
- self.assertEqual(captured["list_var"], " [{'a': 1}, {'a': 2}] ")
+ assert captured["bool_var"] == " True "
+ assert captured["dict_var"] == " {'a': 3} "
+ assert captured["list_var"] == " [{'a': 1}, {'a': 2}] "
- self.assertEqual(
- rendered.strip(),
- "\n
OLD
')
- self.assertEqual(data_before["fragHtml"], None)
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
# Clicking button should load and insert the fragment
await page.locator("button").click()
@@ -341,16 +376,18 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["targetHtml"], None)
- self.assertHTMLEqual(' 123 xxx
', data["fragHtml"])
- self.assertIn("rgb(0, 0, 255)", data["fragBg"]) # AKA 'background: blue'
+ assert data["targetHtml"] is None
+ assert re.compile(
+ r'\s*' r"123\s*" r'xxx\s*' r"
"
+ ).search(data["fragHtml"]) is not None
+ assert "rgb(0, 0, 255)" in data["fragBg"] # AKA 'background: blue'
await page.close()
# Fragment where JS and CSS is defined on Media class
@with_playwright
async def test_fragment_media(self):
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(f"{TEST_SERVER_URL}/fragment/base/js?frag=media")
test_before_js: types.js = """() => {
@@ -364,8 +401,8 @@ class E2eDependencyRenderingTests(BaseTestCase):
data_before = await page.evaluate(test_before_js)
- self.assertEqual(data_before["targetHtml"], 'OLD
')
- self.assertEqual(data_before["fragHtml"], None)
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
# Clicking button should load and insert the fragment
await page.locator("button").click()
@@ -389,16 +426,18 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["targetHtml"], None)
- self.assertHTMLEqual(' 123 xxx
', data["fragHtml"])
- self.assertIn("rgb(0, 0, 255)", data["fragBg"]) # AKA 'background: blue'
+ assert data["targetHtml"] is None
+ assert re.compile(
+ r'\s*' r"123\s*" r'xxx\s*' r"
"
+ ).search(data["fragHtml"]) is not None
+ assert "rgb(0, 0, 255)" in data["fragBg"] # AKA 'background: blue'
await page.close()
# Fragment loaded by AlpineJS
@with_playwright
async def test_fragment_alpine(self):
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(f"{TEST_SERVER_URL}/fragment/base/alpine?frag=comp")
test_before_js: types.js = """() => {
@@ -412,8 +451,8 @@ class E2eDependencyRenderingTests(BaseTestCase):
data_before = await page.evaluate(test_before_js)
- self.assertEqual(data_before["targetHtml"], 'OLD
')
- self.assertEqual(data_before["fragHtml"], None)
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
# Clicking button should load and insert the fragment
await page.locator("button").click()
@@ -441,19 +480,17 @@ class E2eDependencyRenderingTests(BaseTestCase):
# NOTE: Unlike the vanilla JS tests, for the Alpine test we don't remove the targetHtml,
# but only change its contents.
- self.assertInHTML(
- ' 123 xxx
',
- data["targetHtml"],
- )
- self.assertHTMLEqual(data["fragHtml"], ' 123 xxx
')
- self.assertIn("rgb(0, 0, 255)", data["fragBg"]) # AKA 'background: blue'
+ assert re.compile(
+ r'\s*' r"123\s*" r'xxx\s*' r"
"
+ ).search(data["targetHtml"]) is not None
+ assert "rgb(0, 0, 255)" in data["fragBg"] # AKA 'background: blue'
await page.close()
# Fragment loaded by HTMX
@with_playwright
async def test_fragment_htmx(self):
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(f"{TEST_SERVER_URL}/fragment/base/htmx?frag=comp")
test_before_js: types.js = """() => {
@@ -467,8 +504,8 @@ class E2eDependencyRenderingTests(BaseTestCase):
data_before = await page.evaluate(test_before_js)
- self.assertEqual(data_before["targetHtml"], 'OLD
')
- self.assertEqual(data_before["fragHtml"], None)
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
# Clicking button should load and insert the fragment
await page.locator("button").click()
@@ -494,14 +531,11 @@ class E2eDependencyRenderingTests(BaseTestCase):
data = await page.evaluate(test_js)
- self.assertEqual(data["targetHtml"], None)
+ assert data["targetHtml"] is None
# NOTE: We test only the inner HTML, because the element itself may or may not have
# extra CSS classes added by HTMX, which results in flaky tests.
- self.assertHTMLEqual(
- data["fragInnerHtml"],
- '123 xxx',
- )
- self.assertIn("rgb(0, 0, 255)", data["fragBg"]) # AKA 'background: blue'
+ assert re.compile(r'123\s*xxx').search(data["fragInnerHtml"]) is not None
+ assert "rgb(0, 0, 255)" in data["fragBg"] # AKA 'background: blue'
await page.close()
@@ -509,11 +543,11 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_alpine__head(self):
single_comp_url = TEST_SERVER_URL + "/alpine/head"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
component_text = await page.locator('[x-data="alpine_test"]').text_content()
- self.assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
await page.close()
@@ -521,11 +555,11 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_alpine__body(self):
single_comp_url = TEST_SERVER_URL + "/alpine/body"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
component_text = await page.locator('[x-data="alpine_test"]').text_content()
- self.assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
await page.close()
@@ -533,11 +567,11 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_alpine__body2(self):
single_comp_url = TEST_SERVER_URL + "/alpine/body2"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
component_text = await page.locator('[x-data="alpine_test"]').text_content()
- self.assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
await page.close()
@@ -545,10 +579,10 @@ class E2eDependencyRenderingTests(BaseTestCase):
async def test_alpine__invalid(self):
single_comp_url = TEST_SERVER_URL + "/alpine/invalid"
- page: Page = await self.browser.new_page()
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
await page.goto(single_comp_url)
component_text = await page.locator('[x-data="alpine_test"]').text_content()
- self.assertHTMLEqual(component_text.strip(), "ALPINE_TEST:")
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST:")
await page.close()
diff --git a/tests/test_expression.py b/tests/test_expression.py
index 065b895d..8694043e 100644
--- a/tests/test_expression.py
+++ b/tests/test_expression.py
@@ -1,15 +1,18 @@
"""Catch-all for tests that use template tags and don't fit other files"""
-from typing import Any, Dict
+import re
+from typing import Dict
+import pytest
from django.template import Context, Template, TemplateSyntaxError
from django.template.base import FilterExpression, Node, Parser, Token
+from pytest_django.asserts import assertHTMLEqual
from django_components import Component, register, registry, types
-from django_components.expression import DynamicFilterExpression, safe_resolve_dict, safe_resolve_list
+from django_components.expression import DynamicFilterExpression, is_aggregate_key
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase, parametrize_context_behavior
+from django_components.testing import djc_test
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
setup_test_config({"autodiscover": False})
@@ -46,71 +49,34 @@ def make_context(d: Dict):
#######################
-class ResolveTests(BaseTestCase):
- def test_safe_resolve(self):
- expr = default_parser.compile_filter("var_abc")
-
- ctx = make_context({"var_abc": 123})
- self.assertEqual(
- expr.resolve(ctx),
- 123,
- )
-
- ctx2 = make_context({"var_xyz": 123})
- self.assertEqual(expr.resolve(ctx2), "")
-
- def test_safe_resolve_list(self):
- exprs = [default_parser.compile_filter(f"var_{char}") for char in "abc"]
-
- ctx = make_context({"var_a": 123, "var_b": [{}, {}]})
- self.assertEqual(
- safe_resolve_list(ctx, exprs),
- [123, [{}, {}], ""],
- )
-
- def test_safe_resolve_dict(self):
- exprs = {char: default_parser.compile_filter(f"var_{char}") for char in "abc"}
-
- ctx = make_context({"var_a": 123, "var_b": [{}, {}]})
- self.assertEqual(
- safe_resolve_dict(ctx, exprs),
- {"a": 123, "b": [{}, {}], "c": ""},
- )
-
-
# NOTE: Django calls the `{{ }}` syntax "variables" and `{% %}` "blocks"
-class DynamicExprTests(BaseTestCase):
+@djc_test
+class TestDynamicExpr:
def test_variable_resolve_dynamic_expr(self):
expr = DynamicFilterExpression(default_parser, '"{{ var_a|lower }}"')
ctx = make_context({"var_a": "LoREM"})
- self.assertEqual(expr.resolve(ctx), "lorem")
+ assert expr.resolve(ctx) == "lorem"
def test_variable_raises_on_dynamic_expr_with_quotes_mismatch(self):
- with self.assertRaises(TemplateSyntaxError):
+ with pytest.raises(TemplateSyntaxError):
DynamicFilterExpression(default_parser, "'{{ var_a|lower }}\"")
- @parametrize_context_behavior(["django", "isolated"])
- def test_variable_in_template(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_variable_in_template(self, components_settings):
captured = {}
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- *args: Any,
- bool_var: bool,
- list_var: Dict,
- ):
- captured["pos_var1"] = pos_var1
- captured["bool_var"] = bool_var
- captured["list_var"] = list_var
+ def get_template_data(self, args, kwargs, slots, context):
+ captured["pos_var1"] = args[0]
+ captured["bool_var"] = kwargs["bool_var"]
+ captured["list_var"] = kwargs["list_var"]
return {
- "pos_var1": pos_var1,
- "bool_var": bool_var,
- "list_var": list_var,
+ "pos_var1": args[0],
+ "bool_var": kwargs["bool_var"],
+ "list_var": kwargs["list_var"],
}
template: types.django_html = """
@@ -127,9 +93,7 @@ class DynamicExprTests(BaseTestCase):
bool_var="{{ is_active }}"
list_var="{{ list|slice:':-1' }}"
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
@@ -144,40 +108,38 @@ class DynamicExprTests(BaseTestCase):
)
# Check that variables passed to the component are of correct type
- self.assertEqual(captured["pos_var1"], "lorem")
- self.assertEqual(captured["bool_var"], True)
- self.assertEqual(captured["list_var"], [{"a": 1}, {"a": 2}])
+ assert captured["pos_var1"] == "lorem"
+ assert captured["bool_var"] is True
+ assert captured["list_var"] == [{"a": 1}, {"a": 2}]
- self.assertEqual(
- rendered.strip(),
- "\n lorem
\n True
\n [{'a': 1}, {'a': 2}]
", # noqa: E501
+ assertHTMLEqual(
+ rendered,
+ """
+
+ lorem
+ True
+ [{'a': 1}, {'a': 2}]
+ """,
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_block_in_template(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_block_in_template(self, components_settings):
registry.library.tag(noop)
captured = {}
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- *args: Any,
- bool_var: bool,
- list_var: Dict,
- dict_var: Dict,
- ):
- captured["pos_var1"] = pos_var1
- captured["bool_var"] = bool_var
- captured["list_var"] = list_var
- captured["dict_var"] = dict_var
+ def get_template_data(self, args, kwargs, slots, context):
+ captured["pos_var1"] = args[0]
+ captured["bool_var"] = kwargs["bool_var"]
+ captured["list_var"] = kwargs["list_var"]
+ captured["dict_var"] = kwargs["dict_var"]
return {
- "pos_var1": pos_var1,
- "bool_var": bool_var,
- "list_var": list_var,
- "dict_var": dict_var,
+ "pos_var1": args[0],
+ "bool_var": kwargs["bool_var"],
+ "list_var": kwargs["list_var"],
+ "dict_var": kwargs["dict_var"],
}
template: types.django_html = """
@@ -196,9 +158,7 @@ class DynamicExprTests(BaseTestCase):
list_var="{% noop list %}"
dict_var="{% noop dict %}"
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
@@ -214,40 +174,39 @@ class DynamicExprTests(BaseTestCase):
)
# Check that variables passed to the component are of correct type
- self.assertEqual(captured["bool_var"], True)
- self.assertEqual(captured["dict_var"], {"a": 3})
- self.assertEqual(captured["list_var"], [{"a": 1}, {"a": 2}])
+ assert captured["bool_var"] is True
+ assert captured["dict_var"] == {"a": 3}
+ assert captured["list_var"] == [{"a": 1}, {"a": 2}]
- self.assertEqual(
- rendered.strip(),
- "\n lorem ipsum dolor
\n True
\n [{'a': 1}, {'a': 2}]
\n {'a': 3}
", # noqa E501
+ assertHTMLEqual(
+ rendered,
+ """
+
+ lorem ipsum dolor
+ True
+ [{'a': 1}, {'a': 2}]
+ {'a': 3}
+ """,
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_comment_in_template(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_comment_in_template(self, components_settings):
registry.library.tag(noop)
captured = {}
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- pos_var2: Any,
- *args: Any,
- bool_var: bool,
- list_var: Dict,
- ):
- captured["pos_var1"] = pos_var1
- captured["pos_var2"] = pos_var2
- captured["bool_var"] = bool_var
- captured["list_var"] = list_var
+ def get_template_data(self, args, kwargs, slots, context):
+ captured["pos_var1"] = args[0]
+ captured["pos_var2"] = args[1]
+ captured["bool_var"] = kwargs["bool_var"]
+ captured["list_var"] = kwargs["list_var"]
return {
- "pos_var1": pos_var1,
- "pos_var2": pos_var2,
- "bool_var": bool_var,
- "list_var": list_var,
+ "pos_var1": args[0],
+ "pos_var2": args[1],
+ "bool_var": kwargs["bool_var"],
+ "list_var": kwargs["list_var"],
}
template: types.django_html = """
@@ -266,15 +225,14 @@ class DynamicExprTests(BaseTestCase):
bool_var="{# noop is_active #}"
list_var=" {# noop list #} "
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
- rendered = template.render(
+ rendered: str = template.render(
Context(
{
+ "DJC_DEPS_STRATEGY": "ignore",
"var_a": 3,
"is_active": True,
"list": [{"a": 1}, {"a": 2}],
@@ -283,43 +241,39 @@ class DynamicExprTests(BaseTestCase):
)
# Check that variables passed to the component are of correct type
- self.assertEqual(captured["pos_var1"], "")
- self.assertEqual(captured["pos_var2"], " abc")
- self.assertEqual(captured["bool_var"], "")
- self.assertEqual(captured["list_var"], " ")
+ assert captured["pos_var1"] == ""
+ assert captured["pos_var2"] == " abc"
+ assert captured["bool_var"] == ""
+ assert captured["list_var"] == " "
- self.assertEqual(
- rendered.strip(),
- "\n \n abc
\n \n abc
\n'
+ ' \n'
+ ' lorem ipsum dolor
\n lorem ipsum dolor [{'a': 1}]
\n True
\n [{'a': 1}, {'a': 2}]
\n {'a': 3}
", # noqa E501
+ # NOTE: This is whitespace-sensitive test, so we check exact output
+ assert rendered.strip() == (
+ "\n"
+ ' lorem ipsum dolor
\n'
+ ' lorem ipsum dolor [{\'a\': 1}]
\n'
+ ' True
\n'
+ ' [{\'a\': 1}, {\'a\': 2}]
\n'
+ ' {\'a\': 3}
'
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_ignores_invalid_tag(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_ignores_invalid_tag(self, components_settings):
registry.library.tag(noop)
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- pos_var2: Any,
- *args: Any,
- bool_var: bool,
- ):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "pos_var1": pos_var1,
- "pos_var2": pos_var2,
- "bool_var": bool_var,
+ "pos_var1": args[0],
+ "pos_var2": args[1],
+ "bool_var": kwargs["bool_var"],
}
template: types.django_html = """
@@ -396,9 +348,7 @@ class DynamicExprTests(BaseTestCase):
"""
{% load component_tags %}
{% component 'test' '"' "{%}" bool_var="{% noop is_active %}" / %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
@@ -406,26 +356,26 @@ class DynamicExprTests(BaseTestCase):
Context({"is_active": True}),
)
- self.assertEqual(
- rendered.strip(),
- '\n "
\n {%}
\n True
', # noqa: E501
+ assertHTMLEqual(
+ rendered,
+ """
+
+ "
+ {%}
+ True
+ """,
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_nested_in_template(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_in_template(self, components_settings):
registry.library.tag(noop)
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- *args: Any,
- bool_var: bool,
- ):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "pos_var1": pos_var1,
- "bool_var": bool_var,
+ "pos_var1": args[0],
+ "bool_var": kwargs["bool_var"],
}
template: types.django_html = """
@@ -440,9 +390,7 @@ class DynamicExprTests(BaseTestCase):
"{% component 'test' '{{ var_a }}' bool_var=is_active / %}"
bool_var="{% noop is_active %}"
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
@@ -455,30 +403,33 @@ class DynamicExprTests(BaseTestCase):
),
)
- self.assertEqual(
- rendered.strip(),
- "\n \n
\n 3
\n True
\n True
", # noqa E501
+ assertHTMLEqual(
+ rendered,
+ """
+
+
+
+
+ 3
+ True
+ True
+ """,
)
-class SpreadOperatorTests(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_component(self):
+class TestSpreadOperator:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component(self, components_settings):
captured = {}
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- pos_var1: Any,
- *args: Any,
- **kwargs: Any,
- ):
+ def get_template_data(self, args, kwargs, slots, context):
nonlocal captured
captured = kwargs
return {
- "pos_var1": pos_var1,
+ "pos_var1": args[0],
**kwargs,
}
@@ -499,9 +450,7 @@ class SpreadOperatorTests(BaseTestCase):
..."{{ list|first }}"
x=123
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
@@ -520,27 +469,27 @@ class SpreadOperatorTests(BaseTestCase):
)
# Check that variables passed to the component are of correct type
- self.assertEqual(captured["attrs"], {"@click": "() => {}", "style": "height: 20px"})
- self.assertEqual(captured["items"], [1, 2, 3])
- self.assertEqual(captured["a"], 1)
- self.assertEqual(captured["x"], 123)
+ assert captured["attrs"] == {"@click": "() => {}", "style": "height: 20px"}
+ assert captured["items"] == [1, 2, 3]
+ assert captured["a"] == 1
+ assert captured["x"] == 123
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- LoREM
- {'@click': '() => {}', 'style': 'height: 20px'}
- [1, 2, 3]
- 1
- 123
+ LoREM
+ {'@click': '() => {}', 'style': 'height: 20px'}
+ [1, 2, 3]
+ 1
+ 123
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot(self, components_settings):
@register("test")
class SimpleComponent(Component):
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"my_dict": {
"attrs:@click": "() => {}",
@@ -566,18 +515,18 @@ class SpreadOperatorTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
{'items': [1, 2, 3], 'a': 1, 'x': 123, 'attrs': {'@click': '() => {}', 'style': 'height: 20px'}}
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_fill(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_fill(self, components_settings):
@register("test")
class SimpleComponent(Component):
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"my_dict": {
"attrs:@click": "() => {}",
@@ -615,7 +564,7 @@ class SpreadOperatorTests(BaseTestCase):
),
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
{'items': [1, 2, 3], 'a': 1, 'x': 123, 'attrs': {'@click': '() => {}', 'style': 'height: 20px'}}
@@ -623,11 +572,11 @@ class SpreadOperatorTests(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide(self, components_settings):
@register("test")
class SimpleComponent(Component):
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
data = self.inject("test")
return {
"attrs": data.attrs,
@@ -662,17 +611,17 @@ class SpreadOperatorTests(BaseTestCase):
),
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- {'@click': '() => {}', 'style': 'height: 20px'}
- [1, 2, 3]
- 1
+ {'@click': '() => {}', 'style': 'height: 20px'}
+ [1, 2, 3]
+ 1
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_html_attrs(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_html_attrs(self, components_settings):
template_str: types.django_html = """
{% load component_tags %}
@@ -690,22 +639,18 @@ class SpreadOperatorTests(BaseTestCase):
}
),
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-