+ None
+
+
+ {% component "child" %}
+ {% for slot_name in slots %}
+ {% fill name=slot_name data="data" %}
+ {% slot name=slot_name ...data / %}
+ {% endfill %}
+ {% endfor %}
+ {% endcomponent %}
+
+ """
+ ```
+
+#### Fix
+
+- Slots defined with `{% fill %}` tags are now properly accessible via `self.input.slots` in `get_context_data()`
+
+- Do not raise error if multiple slots with same name are flagged as default
+
+- Slots can now be defined within loops (`{% for %}`) or other tags (like `{% with %}`),
+ or even other templates using `{% include %}`.
+
+ Previously, following would cause the kwarg `name` to be an empty string:
+
+ ```django
+ {% for slot_name in slots %}
+ {% slot name=slot_name %}
+ {% endfor %}
+ ```
+
+#### Refactor
+
+- When you define multiple slots with the same name inside a template,
+ you now have to set the `default` and `required` flags individually.
+
+ ```htmldjango
+
+
+ ```
+
+ This means you can also 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 of 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.
+
+ ```htmldjango
+
+ {% slot "image" default required %}Image here{% endslot %}
+
+
+ {% slot "image" default required %}Image here{% endslot %}
+
+
+ {% if image_src %}
+ {% slot "image" default %}
+ 
+ {% endslot %}
+ {% elif name_initials %}
+ {% slot "image" default required %}
+
+ ```
+
+- The slot fills that were passed to a component and which can be accessed as `Component.input.slots`
+ can now be passed through the Django template, e.g. as inputs to other tags.
+
+ Internally, django-components handles slot fills as functions.
+
+ Previously, if you tried to pass a slot fill within a template, Django would try to call it as a function.
+
+ Now, something like this is possible:
+
+ ```py
+ class MyTable(Component):
+ def get_context_data(self, *args, **kwargs):
+ return {
+ "child_slot": self.input.slots["child_slot"],
+ }
+
+ template: """
+
+ {{ name_initials }}
+
+ {% endslot %}
+ {% else %}
+ {% slot "image" default required / %}
+ {% endif %}
+
+ {% component "child" content=child_slot / %}
+
+ """
+ ```
+
+ NOTE: Using `{% slot %}` and `{% fill %}` tags is still the preferred method, but the approach above
+ may be necessary in some complex or edge cases.
+
+- The `is_filled` variable (and the `{{ component_vars.is_filled }}` context variable) now returns
+ `False` when you try to access a slot name which has not been defined:
+
+ Before:
+
+ ```django
+ {{ component_vars.is_filled.header }} -> True
+ {{ component_vars.is_filled.footer }} -> False
+ {{ component_vars.is_filled.nonexist }} -> "" (empty string)
+ ```
+
+ After:
+ ```django
+ {{ component_vars.is_filled.header }} -> True
+ {{ component_vars.is_filled.footer }} -> False
+ {{ component_vars.is_filled.nonexist }} -> False
+ ```
+
+- Components no longer raise an error if there are extra slot fills
+
+- Components will raise error when a slot is doubly-filled.
+
+ E.g. if we have a component with a default slot:
+
+ ```django
+ {% slot name="content" default / %}
+ ```
+
+ Now there is two ways how we can target this slot: Either using `name="default"`
+ or `name="content"`.
+
+ In case you specify BOTH, the component will raise an error:
+
+ ```django
+ {% component "child" %}
+ {% fill slot="default" %}
+ Hello from default slot
+ {% endfill %}
+ {% fill slot="content" data="data" %}
+ Hello from content slot
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+## 🚨📢 v0.100
+
+#### BREAKING CHANGES
+
+- `django_components.safer_staticfiles` app was removed. It is no longer needed.
+
+- Installation changes:
+
+ - Instead of defining component directories in `STATICFILES_DIRS`, set them to [`COMPONENTS.dirs`](https://github.com/django-components/django-components#dirs).
+ - You now must define `STATICFILES_FINDERS`
+
+ - [See here how to migrate your settings.py](https://github.com/django-components/django-components/blob/master/docs/migrating_from_safer_staticfiles.md)
+
+#### Feat
+
+- Beside the top-level `/components` directory, you can now define also app-level components dirs, e.g. `[app]/components`
+ (See [`COMPONENTS.app_dirs`](https://github.com/django-components/django-components#app_dirs)).
+
+#### Refactor
+
+- When you call `as_view()` on a component instance, that instance will be passed to `View.as_view()`
+
+## v0.97
+
+#### Fix
+
+- Fixed template caching. You can now also manually create cached templates with [`cached_template()`](https://github.com/django-components/django-components#template_cache_size---tune-the-template-cache)
+
+#### Refactor
+
+- The previously undocumented `get_template` was made private.
+
+- In it's place, there's a new `get_template`, which supersedes `get_template_string` (will be removed in v1). The new `get_template` is the same as `get_template_string`, except
+ it allows to return either a string or a Template instance.
+
+- You now must use only one of `template`, `get_template`, `template_name`, or `get_template_name`.
+
+## v0.96
+
+#### Feat
+
+- Run-time type validation for Python 3.11+ - If the `Component` class is typed, e.g. `Component[Args, Kwargs, ...]`, the args, kwargs, slots, and data are validated against the given types. (See [Runtime input validation with types](https://github.com/django-components/django-components#runtime-input-validation-with-types))
+
+- Render hooks - Set `on_render_before` and `on_render_after` methods on `Component` to intercept or modify the template or context before rendering, or the rendered result afterwards. (See [Component hooks](https://github.com/django-components/django-components#component-hooks))
+
+- `component_vars.is_filled` context variable can be accessed from within `on_render_before` and `on_render_after` hooks as `self.is_filled.my_slot`
+
+## 0.95
+
+#### Feat
+
+- Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](https://github.com/django-components/django-components#dynamic-components))
+
+#### Refactor
+
+- Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
+
+## v0.94
+
+#### Feat
+
+- django_components now automatically configures Django to support multi-line tags. (See [Multi-line tags](https://github.com/django-components/django-components#multi-line-tags))
+
+- New setting `reload_on_template_change`. Set this to `True` to reload the dev server on changes to component template files. (See [Reload dev server on component file changes](https://github.com/django-components/django-components#reload-dev-server-on-component-file-changes))
+
+## v0.93
+
+#### Feat
+
+- Spread operator `...dict` inside template tags. (See [Spread operator](https://github.com/django-components/django-components#spread-operator))
+
+- Use template tags inside string literals in component inputs. (See [Use template tags inside component inputs](https://github.com/django-components/django-components#use-template-tags-inside-component-inputs))
+
+- Dynamic slots, fills and provides - The `name` argument for these can now be a variable, a template expression, or via spread operator
+
+- Component library authors can now configure `CONTEXT_BEHAVIOR` and `TAG_FORMATTER` settings independently from user settings.
+
+## 🚨📢 v0.92
+
+#### BREAKING CHANGES
+
+- `Component` class is no longer a subclass of `View`. To configure the `View` class, set the `Component.View` nested class. HTTP methods like `get` or `post` can still be defined directly on `Component` class, and `Component.as_view()` internally calls `Component.View.as_view()`. (See [Modifying the View class](https://github.com/django-components/django-components#modifying-the-view-class))
+
+#### Feat
+
+- The inputs (args, kwargs, slots, context, ...) that you pass to `Component.render()` can be accessed from within `get_context_data`, `get_template` and `get_template_name` via `self.input`. (See [Accessing data passed to the component](https://github.com/django-components/django-components#accessing-data-passed-to-the-component))
+
+- Typing: `Component` class supports generics that specify types for `Component.render` (See [Adding type hints with Generics](https://github.com/django-components/django-components#adding-type-hints-with-generics))
+
+## v0.90
+
+#### Feat
+
+- All tags (`component`, `slot`, `fill`, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
+
+ ```django
+ {# Before #}
+ {% component "button" %}{% endcomponent %}
+ {# After #}
+ {% component "button" / %}
+ ```
+
+- All tags now support the "dictionary key" or "aggregate" syntax (`kwarg:key=val`):
+
+ ```django
+ {% component "button" attrs:class="hidden" %}
+ ```
+
+- You can change how the components are written in the template with [TagFormatter](https://github.com/django-components/django-components#customizing-component-tags-with-tagformatter).
+
+ The default is `django_components.component_formatter`:
+
+ ```django
+ {% component "button" href="..." disabled %}
+ Click me!
+ {% endcomponent %}
+ ```
+
+ While `django_components.shorthand_component_formatter` allows you to write components like so:
+
+ ```django
+ {% button href="..." disabled %}
+ Click me!
+ {% endbutton %}
+ ```
+
+## 🚨📢 v0.85
+
+#### BREAKING CHANGES
+
+- Autodiscovery module resolution changed. Following undocumented behavior was removed:
+
+ - Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
+
+ To migrate from:
+
+ - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
+ or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
+
+ - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
+
+ - Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.2/ref/settings/#std-setting-STATICFILES_DIRS)).
+
+## 🚨📢 v0.81
+
+#### BREAKING CHANGES
+
+- The order of arguments to `render_to_response` has changed, to align with the (now public) `render` method of `Component` class.
+
+#### Feat
+
+- `Component.render()` is public and documented
+
+- Slots passed `render_to_response` and `render` can now be rendered also as functions.
+
+## v0.80
+
+#### Feat
+
+- Vue-like provide/inject with the `{% provide %}` tag and `inject()` method.
+
+## 🚨📢 v0.79
+
+#### BREAKING CHANGES
+
+- Default value for the `COMPONENTS.context_behavior` setting was changes from `"isolated"` to `"django"`. If you did not set this value explicitly before, this may be a breaking change. See the rationale for change [here](https://github.com/django-components/django-components/issues/498).
+
+## 🚨📢 v0.77
+
+#### BREAKING
+
+- The syntax for accessing default slot content has changed from
+
+ ```django
+ {% fill "my_slot" as "alias" %}
+ {{ alias.default }}
+ {% endfill %}
+
+ ```
+
+ to
+
+ ```django
+ {% fill "my_slot" default="alias" %}
+ {{ alias }}
+ {% endfill %}
+ ```
+
+## v0.74
+
+#### Feat
+
+- `{% html_attrs %}` tag for formatting data as HTML attributes
+
+- `prefix:key=val` construct for passing dicts to components
+
+## 🚨📢 v0.70
+
+#### BREAKING CHANGES
+
+- `{% if_filled "my_slot" %}` tags were replaced with `{{ component_vars.is_filled.my_slot }}` variables.
+
+- Simplified settings - `slot_context_behavior` and `context_behavior` were merged. See the [documentation](https://github.com/django-components/django-components#context-behavior) for more details.
+
+## v0.67
+
+#### Refactor
+
+- Changed the default way how context variables are resolved in slots. See the [documentation](https://github.com/django-components/django-components/tree/0.67#isolate-components-slots) for more details.
+
+## 🚨📢 v0.50
+
+#### BREAKING CHANGES
+
+- `{% component_block %}` is now `{% component %}`, and `{% component %}` blocks need an ending `{% endcomponent %}` tag.
+
+ The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use `--path` argument to point to each dir) of templates that use components to the new syntax automatically.
+
+ This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
+
+## v0.34
+
+#### Feat
+
+- Components as views, which allows you to handle requests and render responses from within a component. See the [documentation](https://github.com/django-components/django-components#use-components-as-views) for more details.
+
+## v0.28
+
+#### Feat
+
+- 'implicit' slot filling and the `default` option for `slot` tags.
+
+## v0.27
+
+#### Feat
+
+- A second installable app `django_components.safer_staticfiles`. It provides the same behavior as `django.contrib.staticfiles` but with extra security guarantees (more info below in [Security Notes](https://github.com/django-components/django-components#security-notes)).
+
+## 🚨📢 v0.26
+
+#### BREAKING CHANGES
+
+- Changed the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill.
+
+ We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice feature to have access to. Hoping that this will feel worth it!
+
+## v0.22
+
+#### Feat
+
+- All files inside components subdirectores are autoimported to simplify setup.
+
+ An existing project might start to get `AlreadyRegistered` errors because of this. To solve this, either remove your custom loading of components, or set `"autodiscover": False` in `settings.COMPONENTS`.
+
+## v0.17
+
+#### BREAKING CHANGES
+
+- Renamed `Component.context` and `Component.template` to `get_context_data` and `get_template_name`. The old methods still work, but emit a deprecation warning.
+
+ This change was done to sync naming with Django's class based views, and make using django-components more familiar to Django users. `Component.context` and `Component.template` will be removed when version 1.0 is released.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 00000000..8b126249
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,5 @@
+# MANIFEST.in is defined so we can include non-Python (e.g. JS) files
+# in the built distribution.
+# See https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html
+graft src/django_components/static
+prune tests
diff --git a/README.md b/README.md
index 7a2061dc..8df3262e 100644
--- a/README.md
+++ b/README.md
@@ -1,3356 +1,565 @@
-# 
+# 
-[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://EmilStenstrom.github.io/django-components/latest/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 }}
+
```
-And this is what gets rendered (plus the CSS and Javascript you've specified):
+```py
+# components/calendar/calendar.py
+from django_components import Component, register
-```html
-Today's date is 2015-06-19
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
```
-[See the example project](./sampleproject) or read on to learn about the details!
+Or a combination of Django template, Python, CSS, and Javascript:
-## Table of Contents
-
-- [Release notes](#release-notes)
-- [Security notes 🚨](#security-notes-)
-- [Installation](#installation)
-- [Compatibility](#compatibility)
-- [Create your first component](#create-your-first-component)
-- [Using single-file components](#using-single-file-components)
-- [Use components in templates](#use-components-in-templates)
-- [Use components outside of templates](#use-components-outside-of-templates)
-- [Registering components](#registering-components)
-- [Use components as views](#use-components-as-views)
-- [Autodiscovery](#autodiscovery)
-- [Using slots in templates](#using-slots-in-templates)
-- [Accessing data passed to the component](#accessing-data-passed-to-the-component)
-- [Rendering HTML attributes](#rendering-html-attributes)
-- [Template tag syntax](#template-tag-syntax)
-- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
-- [Component context and scope](#component-context-and-scope)
-- [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter)
-- [Defining HTML/JS/CSS files](#defining-htmljscss-files)
-- [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
-- [Available settings](#available-settings)
-- [Logging and debugging](#logging-and-debugging)
-- [Management Command](#management-command)
-- [Writing and sharing component libraries](#writing-and-sharing-component-libraries)
-- [Community examples](#community-examples)
-- [Running django-components project locally](#running-django-components-project-locally)
-- [Development guides](#development-guides)
-
-## Release notes
-
-**Version 0.93**
-- Spread operator `...dict` inside template tags. See [Spread operator](#spread-operator))
-- Use template tags inside string literals in component inputs. See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
-- Dynamic slots, fills and provides - The `name` argument for these can now be a variable, a template expression, or via spread operator
-- Component library authors can now configure `CONTEXT_BEHAVIOR` and `TAG_FORMATTER` settings independently from user settings.
-
-🚨📢 **Version 0.92**
-- BREAKING CHANGE: `Component` class is no longer a subclass of `View`. To configure the `View` class, set the `Component.View` nested class. HTTP methods like `get` or `post` can still be defined directly on `Component` class, and `Component.as_view()` internally calls `Component.View.as_view()`. (See [Modifying the View class](#modifying-the-view-class))
-
-- The inputs (args, kwargs, slots, context, ...) that you pass to `Component.render()` can be accessed from within `get_context_data`, `get_template_string` and `get_template_name` via `self.input`. (See [Accessing data passed to the component](#accessing-data-passed-to-the-component))
-
-- Typing: `Component` class supports generics that specify types for `Component.render` (See [Adding type hints with Generics](#adding-type-hints-with-generics))
-
-**Version 0.90**
-- All tags (`component`, `slot`, `fill`, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
- ```django
- {# Before #}
- {% component "button" %}{% endcomponent %}
- {# After #}
- {% component "button" / %}
- ```
-- All tags now support the "dictionary key" or "aggregate" syntax (`kwarg:key=val`):
- ```django
- {% component "button" attrs:class="hidden" %}
- ```
-- You can change how the components are written in the template with [TagFormatter](#customizing-component-tags-with-tagformatter).
-
- The default is `django_components.component_formatter`:
- ```django
- {% component "button" href="..." disabled %}
- Click me!
- {% endcomponent %}
- ```
-
- While `django_components.shorthand_component_formatter` allows you to write components like so:
-
- ```django
- {% button href="..." disabled %}
- Click me!
- {% endbutton %}
-
-🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
-
-- Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
- - To migrate from:
- - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
- or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
- - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
-- Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#std-setting-STATICFILES_DIRS)).
-
-🚨📢 **Version 0.81** Aligned the `render_to_response` method with the (now public) `render` method of `Component` class. Moreover, slots passed to these can now be rendered also as functions.
-
-- BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
-
-**Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
-
-🚨📢 **Version 0.79**
-
-- BREAKING CHANGE: Default value for the `COMPONENTS.context_behavior` setting was changes from `"isolated"` to `"django"`. If you did not set this value explicitly before, this may be a breaking change. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
-
-🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
-
-- Previously, the syntax was
- `{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
-- Now, the syntax is
- `{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
-
-**Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
-
-🚨📢 **Version 0.70**
-
-- `{% if_filled "my_slot" %}` tags were replaced with `{{ component_vars.is_filled.my_slot }}` variables.
-- Simplified settings - `slot_context_behavior` and `context_behavior` were merged. See the [documentation](#context-behavior) for more details.
-
-**Version 0.67** CHANGED the default way how context variables are resolved in slots. See the [documentation](https://github.com/EmilStenstrom/django-components/tree/0.67#isolate-components-slots) for more details.
-
-🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of templates that use components to the new syntax automatically.
-
-This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
-
-**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#use-components-as-views) for more details.
-
-**Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
-
-**Version 0.27** adds a second installable app: _django_components.safer_staticfiles_. It provides the same behavior as _django.contrib.staticfiles_ but with extra security guarantees (more info below in Security Notes).
-
-**Version 0.26** changes the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill. We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice featuPpre to have access to. Hoping that this will feel worth it!
-
-**Version 0.22** starts autoimporting all files inside components subdirectores, to simplify setup. An existing project might start to get AlreadyRegistered-errors because of this. To solve this, either remove your custom loading of components, or set "autodiscover": False in settings.COMPONENTS.
-
-**Version 0.17** renames `Component.context` and `Component.template` to `get_context_data` and `get_template_name`. The old methods still work, but emit a deprecation warning. This change was done to sync naming with Django's class based views, and make using django-components more familiar to Django users. `Component.context` and `Component.template` will be removed when version 1.0 is released.
-
-## Security notes 🚨
-
-_You are advised to read this section before using django-components in production._
-
-### Static files
-
-Components can be organized however you prefer.
-That said, our prefered way is to keep the files of a component close together by bundling them in the same directory.
-This means that files containing backend logic, such as Python modules and HTML templates, live in the same directory as static files, e.g. JS and CSS.
-
-If your are using _django.contrib.staticfiles_ to collect static files, no distinction is made between the different kinds of files.
-As a result, your Python code and templates may inadvertently become available on your static file server.
-You probably don't want this, as parts of your backend logic will be exposed, posing a **potential security vulnerability**.
-
-As of _v0.27_, django-components ships with an additional installable app _django_components.**safer_staticfiles**_.
-It is a drop-in replacement for _django.contrib.staticfiles_.
-Its behavior is 100% identical except it ignores .py and .html files, meaning these will not end up on your static files server.
-To use it, add it to INSTALLED_APPS and remove _django.contrib.staticfiles_.
-
-```python
-INSTALLED_APPS = [
- # 'django.contrib.staticfiles', # <-- REMOVE
- 'django_components',
- 'django_components.safer_staticfiles' # <-- ADD
-]
+```django
+{# components/calendar/calendar.html #}
+
+ Today's date is {{ date }}
+
```
-If you are on an older version of django-components, your alternatives are a) passing `--ignore Today's date is {{ date }}
-```
-
-Finally, we use django-components to tie this together. Start by creating a file called `calendar.py` in your component calendar directory. It will be auto-detected and loaded by the app.
-
-Inside this file we create a Component by inheriting from the Component class and specifying the context method. We also register the global component registry so that we easily can render it anywhere in our templates.
-
-```python title="[project root]/components/calendar/calendar.py"
-# In a file called [project root]/components/calendar/calendar.py
+```py
+# components/calendar/calendar.py
from django_components import Component, register
@register("calendar")
class Calendar(Component):
- # Templates inside `[your apps]/components` dir and `[project root]/components` dir
- # will be automatically found. To customize which template to use based on context
- # you can override method `get_template_name` instead of specifying `template_name`.
- #
- # `template_name` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
- template_name = "template.html"
+ template_file = "calendar.html"
+ js_file = "calendar.js"
+ css_file = "calendar.css"
- # This component takes one parameter, a date string to show in the template
- def get_context_data(self, date):
- return {
- "date": date,
- }
-
- # Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
- class Media:
- css = "style.css"
- js = "script.js"
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"date": kwargs["date"]}
```
-And voilá!! We've created our first component.
+Use the component like this:
-## Using single-file components
-
-Components can also be defined in a single file, which is useful for small components. To do this, you can use the `template`, `js`, and `css` class attributes instead of the `template_name` and `Media`. For example, here's the calendar component from above, defined in a single file:
-
-```python title="[project root]/components/calendar.py"
-# In a file called [project root]/components/calendar.py
-from django_components import Component, register, types
-
-@register("calendar")
-class Calendar(Component):
- def get_context_data(self, date):
- return {
- "date": date,
- }
-
- template: types.django_html = """
- Today's date is {{ date }}
- """
-
- css: types.css = """
- .calendar-component { width: 200px; background: pink; }
- .calendar-component span { font-weight: bold; }
- """
-
- js: types.js = """
- (function(){
- if (document.querySelector(".calendar-component")) {
- document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
- }
- })()
- """
+```django
+{% component "calendar" date="2024-11-06" %}{% endcomponent %}
```
-This makes it easy to create small components without having to create a separate template, CSS, and JS file.
-
-### Syntax highlight and code assistance
-
-#### VSCode
-
-Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [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.
-
-#### Pycharm (or other Jetbrains IDEs)
-
-If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
-
-```python
-from django_components import Component, register
-
-@register("calendar")
-class Calendar(Component):
- def get_context_data(self, date):
- return {
- "date": date,
- }
-
- # language=HTML
- template= """
- 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!"); };
- }
- })()
- """
-```
-
-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 2015-06-19
-
-
-
-
-
+
+ Today's date is 2024-11-06
+
```
-This makes it possible to organize your front-end around reusable components. Instead of relying on template tags and keeping your CSS and Javascript in the static directory.
+Read on to learn about all the exciting details and configuration possibilities!
-## Use components outside of templates
+(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))
-_New in version 0.81_
+## Features
-Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
+### Modern and modular UI
-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.
-
-#### `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,
- },
-)
-```
-
-### Adding type hints with Generics
-
-The `Component` class optionally accepts type parameters
-that allow you to specify the types of args, kwargs, slots, and
-data.
-
-```py
-from typing import NotRequired, Tuple, TypedDict, SlotFunc
-
-# Positional inputs - Tuple
-Args = Tuple[int, str]
-
-# Kwargs inputs - Mapping
-class Kwargs(TypedDict):
- variable: str
- another: int
- maybe_var: NotRequired[int]
-
-# Data returned from `get_context_data` - Mapping
-class Data(TypedDict):
- variable: str
-
-# The data available to the `my_slot` scoped slot
-class MySlotData(TypedDict):
- value: int
-
-# Slot functions - Mapping
-class Slots(TypedDict):
- # Use SlotFunc for slot functions.
- # The generic specifies the `data` dictionary
- my_slot: NotRequired[SlotFunc[MySlotData]]
-
-class Button(Component[Args, Kwargs, Data, Slots]):
- 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",
- },
-)
-```
-
-### 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)
-```
-
-## Use components as views
-
-_New in version 0.34_
-
-_Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested `Component.View` class_
-
-Components can now be used as views:
-- Components define the `Component.as_view()` class method that can be used the same as [`View.as_view()`](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:
+- 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
-# In a file called [project root]/components/calendar.py
-from django_components import Component, ComponentView, register
+from django_components import Component
@register("calendar")
class Calendar(Component):
-
template = """
-
- %}`/`{% endslot %}`: Declares a new slot in the component template.
-- `{% fill %}`/`{% endfill %}`: (Used inside a `component` tag pair.) Fills a declared slot with the specified content.
-
-Let's update our calendar component to support more customization. We'll add `slot` tag pairs to its template, _template.html_.
-
-```htmldjango
-
- {% endfill %}
-{% endcomponent %}
-```
-
-This renders:
-
-```htmldjango
-
-{% endcomponent %}
-```
-
-### Accessing original content of slots
-
-_Added in version 0.26_
-
-> 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
-
-
-```
-
-When using the component, you can either set the fill explicitly:
-
-```django
-{% component "table" headers=headers items=items %}
- {% fill "header-name" data="data" %}
- {{ data.value }}
- {% endfill %}
-{% endcomponent %}
-```
-
-Or also use a variable:
-
-```django
-{% component "table" headers=headers items=items %}
- {# Make only the active column bold #}
- {% fill "header-{{ active_header_name }}" data="data" %}
- {{ data.value }}
- {% endfill %}
-{% endcomponent %}
-```
-
-> NOTE: It's better to use static slot names whenever possible for clarity. The dynamic slot names should be reserved for advanced use only.
-
-Lastly, in rare cases, you can also pass the slot name via [the spread operator](#spread-operator). This is possible, because the slot name argument is actually a shortcut for a `name` keyword argument.
-
-So this:
-
-```django
-{% slot "content" / %}
-```
-
-is the same as:
-
-```django
-{% slot name="content" / %}
-```
-
-So it's possible to define a `name` key on a dictionary, and then spread that onto the slot tag:
-
-```django
-{# slot_props = {"name": "content"} #}
-{% slot ...slot_props / %}
-```
-
-## Accessing data passed to the component
-
-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_string`
-
-`self.input` is defined only for the duration of `Component.render`, and returns `None` when called outside of this.
-
-`self.input` has the same fields as the input to `Component.render`:
-
-```py
-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"},
-)
-```
-
-## Rendering HTML attributes
-
-_New in version 0.74_:
-
-You can use the `html_attrs` tag to render HTML attributes, given a dictionary
-of values.
-
-So if you have a template:
-
-```django
-
- `{% html_attr %}` - - renders (empty string):
- ` ` - -- Only kwargs
- `{% html_attr class="some-class" class=class_from_var data-id="123" %}` - - renders:
- `class="some-class from-var" data-id="123"` - -- Only attrs
- `{% html_attr attrs %}` - - renders:
- `class="from-attrs" type="submit"` - -- Attrs as kwarg
- `{% html_attr attrs=attrs %}` - - renders:
- `class="from-attrs" type="submit"` - -- Only defaults (as kwarg)
- `{% html_attr defaults=defaults %}` - - renders:
- `class="from-defaults" role="button"` - -- Attrs using the `prefix:key=value` construct
- `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}` - - renders:
- `class="from-attrs" type="submit"` - -- Defaults using the `prefix:key=value` construct
- `{% html_attr defaults:class="from-defaults" %}` - - renders:
- `class="from-defaults" role="button"` - -- All together (1) - attrs and defaults as positional args:
- `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` - -- All together (2) - attrs and defaults as kwargs args:
- `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` - -- All together (3) - mixed:
- `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" data-id=123` - -### Full example for `html_attrs` - -```py -@register("my_comp") -class MyComp(Component): - template: t.django_html = """ -
""" # noqa: E501
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
- {% slot "header" / %}
-
-
- Today's date is {{ date }}
-
+
+ Today's date is
+ {{ date }}
"""
- # Handle GET requests
- def get(self, request, *args, **kwargs):
- context = {
- "date": request.GET.get("date", "2020-06-06"),
+ css = """
+ .calendar {
+ width: 200px;
+ background: pink;
}
- 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:
+ js = """
+ document.querySelector(".calendar")
+ .addEventListener("click", () => {
+ alert("Clicked calendar!");
+ });
+ """
-```python
-# In a file called [project root]/components/urls.py
-from django.urls import path
-from components.calendar.calendar import 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"]
-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)
-```
-
-## Registering components
-
-In previous examples you could repeatedly see us using `@register()` to "register"
-the components. In this section we dive deeper into what it actually means and how you can
-manage (add or remove) components.
-
-As a reminder, we may have a component like this:
-
-```python
-from django_components import Component, register
-
-@register("calendar")
-class Calendar(Component):
- template_name = "template.html"
-
- # This component takes one parameter, a date string to show in the template
- def get_context_data(self, date):
+ # Variables available in the template
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "date": date,
+ "date": kwargs["date"]
}
```
-which we then render in the template as:
+### 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 "calendar" date="1970-01-01" %}
-{% endcomponent %}
-```
-
-As you can see, `@register` links up the component class
-with the `{% component %}` template tag. So when the template tag comes across
-a component called `"calendar"`, it can look up it's class and instantiate it.
-
-### What is ComponentRegistry
-
-The `@register` decorator is a shortcut for working with the `ComponentRegistry`.
-
-`ComponentRegistry` manages which components can be used in the template tags.
-
-Each `ComponentRegistry` instance is associated with an instance
-of Django's `Library`. And Libraries are inserted into Django template
-using the `{% load %}` tags.
-
-The `@register` decorator accepts an optional kwarg `registry`, which specifies, the `ComponentRegistry` to register components into.
-If omitted, the default `ComponentRegistry` instance defined in django_components is used.
-
-```py
-my_registry = ComponentRegistry()
-
-@register(registry=my_registry)
-class MyComponent(Component):
- ...
-```
-
-The default `ComponentRegistry` is associated with the `Library` that
-you load when you call `{% load component_tags %}` inside your template, or when you
-add `django_components.templatetags.component_tags` to the template builtins.
-
-So when you register or unregister a component to/from a component registry,
-then behind the scenes the registry automatically adds/removes the component's
-template tags to/from the Library, so you can call the component from within the templates
-such as `{% component "my_comp" %}`.
-
-### Working with ComponentRegistry
-
-The default `ComponentRegistry` instance can be imported as:
-
-```py
-from django_components import registry
-```
-
-You can use the registry to manually add/remove/get components:
-
-```py
-from django_components import registry
-
-# Register components
-registry.register("button", ButtonComponent)
-registry.register("card", CardComponent)
-
-# Get all or single
-registry.all() # {"button": ButtonComponent, "card": CardComponent}
-registry.get("card") # CardComponent
-
-# Unregister single component
-registry.unregister("card")
-
-# Unregister all components
-registry.clear()
-```
-
-### Registering components to custom ComponentRegistry
-
-If you are writing a component library to be shared with others, you may want to manage your own instance of `ComponentRegistry`
-and register components onto a different `Library` instance than the default one.
-
-The `Library` instance can be set at instantiation of `ComponentRegistry`. If omitted,
-then the default Library instance from django_components is used.
-
-```py
-from django.template import Library
-from django_components import ComponentRegistry
-
-my_library = Library(...)
-my_registry = ComponentRegistry(library=my_library)
-```
-
-When you have defined your own `ComponentRegistry`, you can either register the components
-with `my_registry.register()`, or pass the registry to the `@component.register()` decorator
-via the `registry` kwarg:
-
-```py
-from path.to.my.registry import my_registry
-
-@register("my_component", registry=my_registry)
-class MyComponent(Component):
- ...
-```
-
-NOTE: The Library instance can be accessed under `library` attribute of `ComponentRegistry`.
-
-### ComponentRegistry settings
-
-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`
-
-```py
-from django.template import Library
-from django_components import ComponentRegistry, RegistrySettings
-
-register = library = django.template.Library()
-comp_registry = ComponentRegistry(
- library=library,
- settings=RegistrySettings(
- CONTEXT_BEHAVIOR="isolated",
- TAG_FORMATTER="django_components.component_formatter",
- ),
-)
-```
-
-These settings are [the same as the ones you can set for django_components](#available-settings).
-
-In fact, when you set `COMPONENT.tag_formatter` or `COMPONENT.context_behavior`, these are forwarded to the default `ComponentRegistry`.
-
-This makes it possible to have multiple registries with different settings in one projects, and makes sharing of component libraries possible.
-
-## Autodiscovery
-
-Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@register` decorator for that:
-
-```py
-from django_components import Component, register
-
-@register("calendar")
-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.
-
-One way to do that is by importing all your components in `apps.py`:
-
-```py
-from django.apps import AppConfig
-
-class MyAppConfig(AppConfig):
- name = "my_app"
-
- def ready(self) -> None:
- from components.card.card import Card
- from components.list.list import List
- from components.menu.menu import Menu
- from components.button.button import Button
- ...
-```
-
-However, there's a simpler way!
-
-By default, the Python files in the `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
-
-Autodiscovery occurs when Django is loaded, during the `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()`
-- 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).
-
-Autodiscovery can be disabled in the [settings](#autodiscover---toggle-autodiscovery).
-
-### Manually trigger autodiscovery
-
-Autodiscovery can be also triggered manually as a function call. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
-
-```py
-from django_components import autodiscover
-
-autodiscover()
-```
-
-## Using slots in templates
-
-_New in version 0.26_:
-
-- The `slot` tag now serves only to declare new slots inside the component template.
- - To override the content of a declared slot, use the newly introduced `fill` tag instead.
-- Whereas unfilled slots used to raise a warning, filling a slot is now optional by default.
- - To indicate that a slot must be filled, the new `required` option should be added at the end of the `slot` tag.
-
----
-
-Components support something called 'slots'.
-When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content.
-This mechanism makes components more reusable and composable.
-This behavior is similar to [slots in Vue](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...
-
-- `{% slot
-
-```
-
-When using the component, you specify which slots you want to fill and where you want to use the defaults from the template. It looks like this:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "body" %}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:
-
-```htmldjango
-
- {% slot "header" %}Calendar header{% endslot %}
-
-
- {% slot "body" %}Today's date is {{ date }}{% endslot %}
-
-
-
-```
-
-### Default slot
-
-_Added in version 0.28_
-
-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 end of 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
-
- Calendar header
-
-
- Can you believe it's already 2020-06-06??
-
-
-
-```
-
-Including the component (notice how the `fill` tag is omitted):
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- Can you believe it's already {{ date }}??
-{% endcomponent %}
-```
-
-The rendered result (exactly the same as before):
-
-```html
-
- {% slot "header" %}Calendar header{% endslot %}
-
-
- {% slot "body" default %}Today's date is {{ date }}{% endslot %}
-
-
-
-```
-
-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 compiled.
-
-```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 %}
-```
-
-By contrast, it is permitted to use `fill` tags in nested components, e.g.:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% component "beautiful-box" %}
- {% fill "content" %} Can you believe it's already {{ date }}?? {% endfill %}
- {% endcomponent %}
-{% endcomponent %}
-```
-
-This is fine too:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
+{% component "Layout"
+ bookmarks=bookmarks
+ breadcrumbs=breadcrumbs
+%}
{% fill "header" %}
- {% component "calendar-header" %}
- Super Special Calendar Header
+ Calendar header
- Can you believe it's already 2020-06-06??
-
+
+ {% 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 %}
```
-### Render fill in multiple places
+### Extended template tags
-_Added in version 0.70_
+`django-components` is designed for flexibility, making working with templates a breeze.
-You can render the same content in multiple places by defining multiple slots with
-identical names:
+It extends Django's template tags syntax with:
-```htmldjango
-
+
+ {{ project.name }}
+
+ {{ project.start_date }} - {{ project.end_date }}
+
+
-
-```
-
-So if used like:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
- {% fill "image" %}
-
- {% slot "image" %}Image here{% endslot %}
-
-
- {% slot "image" %}Image here{% endslot %}
-
-
-
-```
-
-#### Default and required slots
-
-If you use a slot multiple times, you can still mark the slot as `default` or `required`.
-For that, you must mark ONLY ONE of the identical slots.
-
-We recommend to mark the first occurence for consistency, e.g.:
-
-```htmldjango
-
-
-
-
-
-
-
-
-```
-
-Which you can then use are regular default slot:
-
-```htmldjango
-{% component "calendar" date="2020-06-06" %}
-
- {% slot "image" default required %}Image here{% endslot %}
-
-
- {% slot "image" %}Image here{% endslot %}
-
-
-
-```
-
-### 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 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___`.
-
-### 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`:
+
+- 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 "my_comp" %}
- {% fill "content" data="data" %}
- {{ data.input }}
- {% endfill %}
-{% endcomponent %}
+{% 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"
+/ %}
```
-To access slot data on a default slot, you have to explictly define the `{% fill %}` tags.
+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).
-So this works:
+Read more on [Custom template tags](https://django-components.github.io/django-components/latest/concepts/advanced/template_tags/).
-```django
-{% component "my_comp" %}
- {% fill "content" data="data" %}
- {{ data.input }}
- {% endfill %}
-{% endcomponent %}
-```
+### Full programmatic access
-While this does not:
+When you render a component, you can access everything about the component:
-```django
-{% component "my_comp" data="data" %}
- {{ data.input }}
-{% endcomponent %}
-```
+- 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)
-Note: You cannot set the `data` attribute and
-[`default` attribute)](#accessing-original-content-of-slots)
-to the same name. This raises an error:
+```python
+class Table(Component):
+ js_file = "table.js"
+ css_file = "table.css"
-```django
-{% component "my_comp" %}
- {% fill "content" data="slot_var" default="slot_var" %}
- {{ slot_var.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:
-
-```django
-| - {% slot "header-{{ header.key }}" value=header.title %} - {{ header.title }} - {% endslot %} - | - {% endfor %} -
|---|
-
-```
-
-You can simplify it with `html_attrs` tag:
-
-```django
-
-
-```
-
-where `attrs` is:
-
-```py
-attrs = {
- "class": classes,
- "data-id": my_id,
-}
-```
-
-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 atttributes
-
-Attributes that are set to `None` or `False` are NOT rendered.
-
-So given this input:
-
-```py
-attrs = {
- "class": "text-green",
- "required": False,
- "data-id": None,
-}
-```
-
-And template:
-
-```django
-
-
-```
-
-Then this renders:
-
-```html
-
-```
-
-### 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` 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
-
-
-```
-
-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.
-
-```django
-
- ...
-
-```
-
-In the example above, if `attrs` contains e.g. the `class` key, `html_attrs` will render:
-
-`class="{{ attrs.class }}"`
-
-Otherwise, `html_attrs` will render:
-
-`class="{{ defaults.class }}"`
-
-### 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
-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.
-
-We can achieve this by adding extra kwargs. These values
-will be appended, instead of overwriting the previous value.
-
-So if we have a variable `attrs`:
-
-```py
-attrs = {
- "class": "my-class pa-4",
-}
-```
-
-And on `html_attrs` tag, we set the key `class`:
-
-```django
-
-
-```
-
-Then these will be merged and rendered as:
-
-```html
-
-```
-
-To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
-
-```django
-{# my_var = "class-from-var text-red" #}
-
-
-```
-
-Renders:
-
-```html
-
-```
-
-### Rules for `html_attrs`
-
-1. Both `attrs` and `defaults` can be passed as positional args
-
- `{% html_attrs attrs defaults key=val %}`
-
- or as kwargs
-
- `{% html_attrs key=val defaults=defaults attrs=attrs %}`
-
-2. Both `attrs` and `defaults` are optional (can be omitted)
-
-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`.
-
-4. All other kwargs are appended and can be repeated.
-
-### Examples for `html_attrs`
-
-Assuming that:
-
-```py
-class_from_var = "from-var"
-
-attrs = {
- "class": "from-attrs",
- "type": "submit",
-}
-
-defaults = {
- "class": "from-defaults",
- "role": "button",
-}
-```
-
-Then:
-
-- Empty tag - `{% html_attr %}` - - renders (empty string):
- ` ` - -- Only kwargs
- `{% html_attr class="some-class" class=class_from_var data-id="123" %}` - - renders:
- `class="some-class from-var" data-id="123"` - -- Only attrs
- `{% html_attr attrs %}` - - renders:
- `class="from-attrs" type="submit"` - -- Attrs as kwarg
- `{% html_attr attrs=attrs %}` - - renders:
- `class="from-attrs" type="submit"` - -- Only defaults (as kwarg)
- `{% html_attr defaults=defaults %}` - - renders:
- `class="from-defaults" role="button"` - -- Attrs using the `prefix:key=value` construct
- `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}` - - renders:
- `class="from-attrs" type="submit"` - -- Defaults using the `prefix:key=value` construct
- `{% html_attr defaults:class="from-defaults" %}` - - renders:
- `class="from-defaults" role="button"` - -- All together (1) - attrs and defaults as positional args:
- `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` - -- All together (2) - attrs and defaults as kwargs args:
- `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123` - -- All together (3) - mixed:
- `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}` - - renders:
- `class="from-attrs added_class from-var" type="submit" data-id=123` - -### Full example for `html_attrs` - -```py -@register("my_comp") -class MyComp(Component): - template: t.django_html = """ -
- Today's date is {{ date }}
+ template = """
+ `
- as an end tag.
-
- Example as block:
- ```django
- {% button href="..." %}
- Click me!
- {% endbutton %}
- ```
-
- Example as inlined tag:
- ```django
- {% button href="..." / %}
- ```
-
-### Writing your own TagFormatter
-
-#### Background
-
-First, let's discuss how TagFormatters work, and how components are rendered in django_components.
-
-When you render a component with `{% component %}` (or your own tag), the following happens:
-1. `component` must be registered as a Django's template tag
-2. Django triggers django_components's tag handler for tag `component`.
-3. The tag handler passes the tag contents for pre-processing to `TagFormatter.parse()`.
-
- So if you render this:
- ```django
- {% component "button" href="..." disabled %}
- {% endcomponent %}
- ```
-
- Then `TagFormatter.parse()` will receive a following input:
- ```py
- ["component", '"button"', 'href="..."', 'disabled']
- ```
-4. `TagFormatter` extracts the component name and the remaining input.
-
- So, given the above, `TagFormatter.parse()` returns the following:
- ```py
- TagResult(
- component_name="button",
- tokens=['href="..."', 'disabled']
+@djc_test
+def test_my_table():
+ rendered = MyTable.render(
+ kwargs={
+ "title": "My table",
+ },
)
- ```
-5. The tag handler resumes, using the tokens returned from `TagFormatter`.
-
- So, continuing the example, at this point the tag handler practically behaves as if you rendered:
- ```django
- {% component href="..." disabled %}
- ```
-6. Tag handler looks up the component `button`, and passes the args, kwargs, and slots to it.
-
-#### TagFormatter
-
-`TagFormatter` handles following parts of the process above:
-- Generates start/end tags, given a component. This is what you then call from within your template as `{% component %}`.
-
-- When you `{% component %}`, tag formatter pre-processes the tag contents, so it can link back the custom template tag to the right component.
-
-To do so, subclass from `TagFormatterABC` and implement following method:
-- `start_tag`
-- `end_tag`
-- `parse`
-
-For example, this is the implementation of [`ShorthandComponentFormatter`](#available-tagformatters)
-
-```py
-class ShorthandComponentFormatter(TagFormatterABC):
- # Given a component name, generate the start template tag
- def start_tag(self, name: str) -> str:
- return name # e.g. 'button'
-
- # Given a component name, generate the start template tag
- def end_tag(self, name: str) -> str:
- return f"end{name}" # e.g. 'endbutton'
-
- # Given a tag, e.g.
- # `{% button href="..." disabled %}`
- #
- # The parser receives:
- # `['button', 'href="..."', 'disabled']`
- def parse(self, tokens: List[str]) -> TagResult:
- tokens = [*tokens]
- name = tokens.pop(0)
- return TagResult(
- name, # e.g. 'button'
- tokens # e.g. ['href="..."', 'disabled']
- )
+ assert rendered == "My table
"
```
-That's it! And once your `TagFormatter` is ready, don't forget to update the settings!
+### Debugging features
-## Defining HTML/JS/CSS files
+- **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.
-django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
+$/);
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ DEMO
+
+
+
+
+
+
+
+
+
+
+ "
+
+ # We should be able to access the global variables set by the previous components:
+ # Scripts:
+ # - script.js - testMsg
+ # - script2.js - testMsg2
+ # Components:
+ # - SimpleComponent - testSimpleComponent
+ # - SimpleComponentNested - testSimpleComponentNested
+ # - OtherComponent - testOtherComponent
+ js: types.js = """
+ globalThis.checkVars = {
+ testSimpleComponent,
+ testSimpleComponentNested,
+ testOtherComponent,
+ testMsg,
+ testMsg2,
+ };
+ """
+
+
+@register("check_script_order_in_media")
+class CheckScriptOrderInMedia(Component):
+ template = ""
+
+ class Media:
+ js = "check_script_order.js"
+
+
+# Fragment where the JS and CSS are defined on the Component
+@register("frag_comp")
+class FragComp(Component):
+ template: types.django_html = """
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
diff --git a/tests/templates/blocked_and_slotted_template_2.html b/tests/templates/blocked_and_slotted_template_2.html
new file mode 100644
index 00000000..94abb18f
--- /dev/null
+++ b/tests/templates/blocked_and_slotted_template_2.html
@@ -0,0 +1,7 @@
+{% load component_tags %}
+{% block before_custom %}{% endblock %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
diff --git a/tests/templates/component_inside_include_base.html b/tests/templates/component_inside_include_base.html
new file mode 100644
index 00000000..2711df5f
--- /dev/null
+++ b/tests/templates/component_inside_include_base.html
@@ -0,0 +1,4 @@
+{% include "component_inside_include_sub.html" %}
+{% block content %}
+ THIS_IS_IN_BASE_TEMPLATE_SO_SHOULD_BE_OVERRIDDEN
+{% endblock %}
\ No newline at end of file
diff --git a/tests/templates/component_inside_include_sub.html b/tests/templates/component_inside_include_sub.html
new file mode 100644
index 00000000..a6f29bd3
--- /dev/null
+++ b/tests/templates/component_inside_include_sub.html
@@ -0,0 +1 @@
+{% component "test_component" / %}
\ No newline at end of file
diff --git a/tests/templates/included.html b/tests/templates/included.html
new file mode 100644
index 00000000..25ef907c
--- /dev/null
+++ b/tests/templates/included.html
@@ -0,0 +1,4 @@
+{% extends "simple_template.html" %}
+{% block before_custom %}
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+ {{ variable }}
"""
- def get_context_data(self, date: Date, attrs: dict):
+ 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 {
- "date": date,
- "attrs": attrs,
- "class_from_var": "extra-class"
+ "variable": kwargs["variable"],
}
-@register("parent")
-class Parent(Component):
- template: t.django_html = """
- {% component "my_comp"
- date=date
- attrs:class="pa-0 border-solid border-red"
- attrs:data-json=json_data
- attrs:@click="(e) => onClick(e, 'from_parent')"
- / %}
- """
+# Access component's HTML / JS / CSS
+Table.template
+Table.js
+Table.css
- def get_context_data(self, date: Date):
- return {
- "date": datetime.now(),
- "json_data": json.dumps({"value": 456})
- }
+# Render the component
+rendered = Table.render(
+ kwargs={"variable": "test", "another": 1},
+ args=(123, "str"),
+ slots={"footer": "MY_FOOTER"},
+)
```
-Note: For readability, we've split the tags across multiple lines.
+### Granular HTML attributes
-Inside `MyComp`, we defined a default attribute
+Use the [`{% html_attrs %}`](https://django-components.github.io/django-components/latest/concepts/fundamentals/html_attributes/) template tag to render HTML attributes.
-`defaults:class="pa-4 text-red"`
+It supports:
-So if `attrs` includes key `class`, the default above will be ignored.
-
-`MyComp` also defines `class` key twice. It means that whether the `class`
-attribute is taken from `attrs` or `defaults`, the two `class` values
-will be appended to it.
-
-So by default, `MyComp` renders:
-
-```html
-...
-```
-
-Next, let's consider what will be rendered when we call `MyComp` from `Parent`
-component.
-
-`MyComp` accepts a `attrs` dictionary, that is passed to `html_attrs`, so the
-contents of that dictionary are rendered as the HTML attributes.
-
-In `Parent`, we make use of passing dictionary key-value pairs as kwargs to define
-individual attributes as if they were regular kwargs.
-
-So all kwargs that start with `attrs:` will be collected into an `attrs` dict.
+- Defining attributes as whole dictionaries or keyword arguments
+- Merging attributes from multiple sources
+- Boolean attributes
+- Appending attributes
+- Removing attributes
+- Defining default attributes
```django
- attrs:class="pa-0 border-solid border-red"
- attrs:data-json=json_data
- attrs:@click="(e) => onClick(e, 'from_parent')"
-```
-
-And `get_context_data` of `MyComp` will receive `attrs` input with following keys:
-
-```py
-attrs = {
- "class": "pa-0 border-solid",
- "data-json": '{"value": 456}',
- "@click": "(e) => onClick(e, 'from_parent')",
-}
-```
-
-`attrs["class"]` overrides the default value for `class`, whereas other keys
-will be merged.
-
-So in the end `MyComp` will render:
-
-```html
- ...
-
```
-### Rendering HTML attributes outside of templates
+[`{% 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.
-If you need to use serialize HTML attributes outside of Django template and the `html_attrs` tag, you can use `attributes_to_string`:
+```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
-from django_components.attributes import attributes_to_string
+# components/calendar/calendar.py
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
-attrs = {
- "class": "my-class text-red pa-4",
- "data-id": 123,
- "required": True,
- "disabled": False,
- "ignored-attr": None,
-}
+ class View:
+ # Register Component with `urlpatterns`
+ public = True
-attributes_to_string(attrs)
-# 'class="my-class text-red pa-4" data-id="123" required'
+ # 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())
```
-## Template tag syntax
+### Provide / Inject
-All template tags in django_component, like `{% component %}` or `{% slot %}`, and so on,
-support extra syntax that makes it possible to write components like in Vue or React (JSX).
+`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):
-### Self-closing tags
+- 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
-When you have a tag like `{% component %}` or `{% slot %}`, but it has no content, you can simply append a forward slash `/` at the end, instead of writing out the closing tags like `{% endcomponent %}` or `{% endslot %}`:
-
-So this:
-
-```django
-{% component "button" %}{% endcomponent %}
-```
-
-becomes
-
-```django
-{% component "button" / %}
-```
-
-### Special characters
-
-_New in version 0.71_:
-
-Keyword arguments can contain special characters `# @ . - _`, so keywords like
-so are still valid:
+Read more about [Provide / Inject](https://django-components.github.io/django-components/latest/concepts/advanced/provide_inject).
```django
- {% component "calendar" my-date="2015-06-19" @click.native=do_something #some_id=True / %}
+ {% provide "theme" variant="light" %}
+ {% component "header" / %}
+ {% endprovide %}
```
-These can then be accessed inside `get_context_data` so:
+```djc_py
+@register("header")
+class Header(Component):
+ template = "..."
-```py
-@register("calendar")
-class Calendar(Component):
- # Since # . @ - are not valid identifiers, we have to
- # use `**kwargs` so the method can accept these args.
- def get_context_data(self, **kwargs):
+ def get_template_data(self, args, kwargs, slots, context):
+ theme = self.inject("theme").variant
return {
- "date": kwargs["my-date"],
- "id": kwargs["#some_id"],
- "on_click": kwargs["@click.native"]
+ "theme": theme,
}
```
-### Spread operator
+### Input validation and static type hints
-_New in version 0.93_:
+Avoid needless errors with [type hints and runtime input validation](https://django-components.github.io/django-components/latest/concepts/fundamentals/typing_and_validation/).
-Instead of passing keyword arguments one-by-one:
-
-```django
-{% component "calendar" title="How to abc" date="2015-06-19" author="John Wick" / %}
-```
-
-You can use a spread operator `...dict` to apply key-value pairs from a dictionary:
+To opt-in to input validation, define types for component's args, kwargs, slots, and more:
```py
-post_data = {
- "title": "How to...",
- "date": "2015-06-19",
- "author": "John Wick",
-}
+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]
```
-```django
-{% component "calendar" ...post_data / %}
-```
-
-This behaves similar to [JSX's spread operator](https://kevinyckim33.medium.com/jsx-spread-operator-component-props-meaning-3c9bcadd2493)
-or [Vue's `v-bind`](https://vuejs.org/api/built-in-directives.html#v-bind).
-
-Spread operators are treated as keyword arguments, which means that:
-1. Spread operators must come after positional arguments.
-2. You cannot use spread operators for [positional-only arguments](https://martinxpn.medium.com/positional-only-and-keyword-only-arguments-in-python-37-100-days-of-python-310c311657b0).
-
-Other than that, you can use spread operators multiple times, and even put keyword arguments in-between or after them:
-
-```django
-{% component "calendar" ...post_data id=post.id ...extra / %}
-```
-
-In a case of conflicts, the values added later (right-most) overwrite previous values.
-
-### Use template tags inside component inputs
-
-_New in version 0.93_
-
-When passing data around, sometimes you may need to do light transformations, like negating booleans or filtering lists.
-
-Normally, what you would have to do is to define ALL the variables
-inside `get_context_data()`. But this can get messy if your components contain a lot of logic.
+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
-@register("calendar")
-class Calendar(Component):
- def get_context_data(self, id: str, editable: bool):
- return {
- "editable": editable,
- "readonly": not editable,
- "input_id": f"input-{id}",
- "icon_id": f"icon-{id}",
- ...
- }
+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",
+ ),
+)
```
-Instead, template tags in django_components (`{% component %}`, `{% slot %}`, `{% provide %}`, etc) allow you to treat literal string values as templates:
+### Extensions
-```django
-{% component 'blog_post'
- "As positional arg {# yay #}"
- title="{{ person.first_name }} {{ person.last_name }}"
- id="{% random_int 10 20 %}"
- readonly="{{ editable|not }}"
- author="John Wick {# TODO: parametrize #}"
-/ %}
-```
+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:
-In the example above:
-- Component `test` receives a positional argument with value `"As positional arg "`. The comment is omitted.
-- Kwarg `title` is passed as a string, e.g. `John Doe`
-- Kwarg `id` is passed as `int`, e.g. `15`
-- Kwarg `readonly` is passed as `bool`, e.g. `False`
-- Kwarg `author` is passed as a string, e.g. `John Wick ` (Comment omitted)
+- 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
-This is inspired by [django-cotton](https://github.com/wrabit/django-cotton#template-expressions-in-attributes).
+Some of the extensions include:
-#### Passing data as string vs original values
+- [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)
-Sometimes you may want to use the template tags to transform
-or generate the data that is then passed to the component.
+Some of the planned extensions include:
-The data doesn't necessarily have to be strings. In the example above, the kwarg `id` was passed as an integer, NOT a string.
+- AlpineJS integration
+- Storybook integration
+- Component-level benchmarking with asv
-Although the string literals for components inputs are treated as regular Django templates, there is one special case:
+### Caching
-When the string literal contains only a single template tag, with no extra text, then the value is passed as the original type instead of a string.
-
-Here, `page` is an integer:
-
-```django
-{% component 'blog_post' page="{% random_int 10 20 %}" / %}
-```
-
-Here, `page` is a string:
-
-```django
-{% component 'blog_post' page=" {% random_int 10 20 %} " / %}
-```
-
-And same applies to the `{{ }}` variable tags:
-
-Here, `items` is a list:
-
-```django
-{% component 'cat_list' items="{{ cats|slice:':2' }}" / %}
-```
-
-Here, `items` is a string:
-
-```django
-{% component 'cat_list' items="{{ cats|slice:':2' }} See more" / %}
-```
-
-#### Evaluating Python expressions in template
-
-You can even go a step further and have a similar experience to Vue or React,
-where you can evaluate arbitrary code expressions:
-
-```jsx
- {{ my_data.key }}
- {{ my_data.another }}
- """
-
- def get_context_data(self):
- my_data = self.inject("my_data", "default")
- return {"my_data": my_data}
-
-template_str = """
- {% load component_tags %}
- {% provide "my_data" key="hi" another=123 %}
- {% component "child" / %}
- {% endprovide %}
-"""
-```
-
-renders:
-
-```html
-hi
-123
-```
-
-## Component context and scope
-
-By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
-
-With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.
-
-And just like with `{% include %}`, if you don't want a specific component template to have access to the parent context, add `only` to the `{% component %}` tag:
-
-```htmldjango
-{% component "calendar" date="2015-06-19" only / %}
-```
-
-NOTE: `{% csrf_token %}` tags need access to the top-level context, and they will not function properly if they are rendered in a component that is called with the `only` modifier.
-
-If you find yourself using the `only` modifier often, you can set the [context_behavior](#context-behavior) option to `"isolated"`, which automatically applies the `only` modifier. This is useful if you want to make sure that components don't accidentally access the outer context.
-
-Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
-
-## Customizing component tags with TagFormatter
-
-_New in version 0.89_
-
-By default, components are rendered using the pair of `{% component %}` / `{% endcomponent %}` template tags:
-
-```django
-{% component "button" href="..." disabled %}
-Click me!
-{% endcomponent %}
-
-{# or #}
-
-{% component "button" href="..." disabled / %}
-```
-
-You can change this behaviour in the settings under the [`COMPONENTS.tag_formatter`](#tag-formatter-setting).
-
-For example, if you set the tag formatter to `django_components.shorthand_component_formatter`, the components will use their name as the template tags:
-
-```django
-{% button href="..." disabled %}
- Click me!
-{% endbutton %}
-
-{# or #}
-
-{% button href="..." disabled / %}
-```
-
-### Available TagFormatters
-
-django_components provides following predefined TagFormatters:
-
-- **`ComponentFormatter` (`django_components.component_formatter`)**
-
- Default
-
- Uses the `component` and `endcomponent` tags, and the component name is gives as the first positional argument.
-
- Example as block:
- ```django
- {% component "button" href="..." %}
- {% fill "content" %}
- ...
- {% endfill %}
- {% endcomponent %}
- ```
-
- Example as inlined tag:
- ```django
- {% component "button" href="..." / %}
- ```
-
-- **`ShorthandComponentFormatter` (`django_components.shorthand_component_formatter`)**
-
- Uses the component name as start tag, and `end
+
+
-To be familiar with how Django handles static files, we recommend reading also:
+### Sharing components
-- [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 `STATICFILES_DIRS`.
-
-Assuming that `STATICFILES_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__`).
-
-## Rendering JS/CSS dependencies
-
-The JS and CSS files included in components are not automatically rendered.
-Instead, use the following tags to specify where to render the dependencies:
-
-- `component_dependencies` - Renders both JS and CSS
-- `component_js_dependencies` - Renders only JS
-- `component_css_dependencies` - Reneders only CSS
-
-JS files are rendered as `"""
-
-
-@override_settings(COMPONENTS={"RENDER_DEPENDENCIES": True})
-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_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/CHANGELOG.md b/docs/CHANGELOG.md
deleted file mode 100644
index 2e473032..00000000
--- a/docs/CHANGELOG.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-hide:
- - toc
----
-
-# Release notes
-
-{!
- include-markdown "../README.md"
- start="## Release notes"
- end='## '
- heading-offset=1
-!}
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 612c7a5e..74b225f9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1 +1,6 @@
---8<-- "README.md"
+---
+title: Welcome to Django Components
+weight: 1
+---
+
+--8<-- "docs/overview/welcome.md:4"
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
deleted file mode 100644
index 18286a21..00000000
--- a/docs/SUMMARY.md
+++ /dev/null
@@ -1,6 +0,0 @@
-* [README](README.md)
- * [Changelog](CHANGELOG.md)
- * [Code of Conduct](CODE_OF_CONDUCT.md)
- * [License](license.md)
-* Reference
- * [API Reference](reference/)
\ No newline at end of file
diff --git a/docs/__init__.py b/docs/__init__.py
new file mode 100644
index 00000000..e69de29b
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(/^
+' + 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 = $('
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <script>
+ document.addEventListener('alpine:init', () => {
+ // NOTE: Defined as standalone function so we can call it variable initialization
+ const computeSidebarState = (prevState) => {
+ const width = (window.innerWidth > 0) ? window.innerWidth : screen.width;
+ // We automatically hide the sidebar when window is smaller than 1024px
+ const sidebarBreakpoint = 1024;
+ if (!prevState && width >= sidebarBreakpoint) {
+ return true;
+ } else if (prevState && width < sidebarBreakpoint) {
+ return false;
+ } else {
+ return prevState;
+ }
+ };
+
+ Alpine.data('layout', () => ({
+ // Variables
+ sidebarOpen: computeSidebarState(false),
+
+ init() {
+ this.onWindowResize();
+ },
+
+ // Handlers
+ toggleSidebar() {
+ this.sidebarOpen = !this.sidebarOpen;
+ },
+
+ onWindowResize() {
+ this.sidebarOpen = computeSidebarState(this.sidebarOpen);
+ },
+ }));
+ });
+ </script>
+
+
+
+
+
+
+
+
+ '''
+# ---
diff --git a/tests/__snapshots__/test_benchmark_django_small.ambr b/tests/__snapshots__/test_benchmark_django_small.ambr
new file mode 100644
index 00000000..48fec390
--- /dev/null
+++ b/tests/__snapshots__/test_benchmark_django_small.ambr
@@ -0,0 +1,21 @@
+# serializer version: 1
+# name: test_render
+ '''
+
+
+
+
+
+
+
+ Click me!
+
+
+
+
+
+ '''
+# ---
diff --git a/tests/__snapshots__/test_benchmark_djc.ambr b/tests/__snapshots__/test_benchmark_djc.ambr
new file mode 100644
index 00000000..4a23fe00
--- /dev/null
+++ b/tests/__snapshots__/test_benchmark_djc.ambr
@@ -0,0 +1,8590 @@
+# serializer version: 1
+# name: test_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 = $('
+```
+
+Notes on publishing:
+
+- If you use components where the HTML / CSS / JS files are separate, you may need to define
+ [`MANIFEST.in`](https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html)
+ to include those files with the distribution
+ ([see user guide](https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html)).
+
+## Installing and using component libraries
+
+After the package has been published, all that remains is to install it in other django projects:
+
+1. Install the package:
+
+ ```bash
+ pip install myapp django_components
+ ```
+
+2. Add the package to `INSTALLED_APPS`
+
+ ```py
+ INSTALLED_APPS = [
+ ...
+ "django_components",
+ "myapp",
+ ]
+ ```
+
+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
+ TEMPLATES = [
+ {
+ ...,
+ 'OPTIONS': {
+ 'builtins': [
+ 'myapp.templatetags.mytags',
+ ]
+ },
+ },
+ ]
+ ```
+
+4. And, at last, you can use the components in your own project!
+
+ ```django
+ {% my_menu title="Abc..." %}
+ Hello World!
+ {% endmy_menu %}
+ ```
diff --git a/docs/concepts/advanced/component_registry.md b/docs/concepts/advanced/component_registry.md
new file mode 100644
index 00000000..f5865420
--- /dev/null
+++ b/docs/concepts/advanced/component_registry.md
@@ -0,0 +1,150 @@
+In previous examples you could repeatedly see us using `@register()` to "register"
+the components. In this section we dive deeper into what it actually means and how you can
+manage (add or remove) components.
+
+As a reminder, we may have a component like this:
+
+```python
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "template.html"
+
+ # This component takes one parameter, a date string to show in the template
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"],
+ }
+```
+
+which we then render in the template as:
+
+```django
+{% component "calendar" date="1970-01-01" %}
+{% endcomponent %}
+```
+
+As you can see, `@register` links up the component class
+with the `{% component %}` template tag. So when the template tag comes across
+a component called `"calendar"`, it can look up it's class and instantiate it.
+
+## What is ComponentRegistry
+
+The `@register` decorator is a shortcut for working with the `ComponentRegistry`.
+
+`ComponentRegistry` manages which components can be used in the template tags.
+
+Each `ComponentRegistry` instance is associated with an instance
+of Django's `Library`. And Libraries are inserted into Django template
+using the `{% load %}` tags.
+
+The `@register` decorator accepts an optional kwarg `registry`, which specifies, the `ComponentRegistry` to register components into.
+If omitted, the default `ComponentRegistry` instance defined in django_components is used.
+
+```py
+my_registry = ComponentRegistry()
+
+@register(registry=my_registry)
+class MyComponent(Component):
+ ...
+```
+
+The default `ComponentRegistry` is associated with the `Library` that
+you load when you call `{% load component_tags %}` inside your template, or when you
+add `django_components.templatetags.component_tags` to the template builtins.
+
+So when you register or unregister a component to/from a component registry,
+then behind the scenes the registry automatically adds/removes the component's
+template tags to/from the Library, so you can call the component from within the templates
+such as `{% component "my_comp" %}`.
+
+## Working with ComponentRegistry
+
+The default `ComponentRegistry` instance can be imported as:
+
+```py
+from django_components import registry
+```
+
+You can use the registry to manually add/remove/get components:
+
+```py
+from django_components import registry
+
+# Register components
+registry.register("button", ButtonComponent)
+registry.register("card", CardComponent)
+
+# Get all or single
+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")
+
+# Unregister all components
+registry.clear()
+```
+
+## Registering components to custom ComponentRegistry
+
+If you are writing a component library to be shared with others, you may want to manage your own instance of `ComponentRegistry`
+and register components onto a different `Library` instance than the default one.
+
+The `Library` instance can be set at instantiation of `ComponentRegistry`. If omitted,
+then the default Library instance from django_components is used.
+
+```py
+from django.template import Library
+from django_components import ComponentRegistry
+
+my_library = Library(...)
+my_registry = ComponentRegistry(library=my_library)
+```
+
+When you have defined your own `ComponentRegistry`, you can either register the components
+with `my_registry.register()`, or pass the registry to the `@component.register()` decorator
+via the `registry` kwarg:
+
+```py
+from path.to.my.registry import my_registry
+
+@register("my_component", registry=my_registry)
+class MyComponent(Component):
+ ...
+```
+
+NOTE: The Library instance can be accessed under `library` attribute of `ComponentRegistry`.
+
+## ComponentRegistry settings
+
+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`
+
+```py
+from django.template import Library
+from django_components import ComponentRegistry, RegistrySettings
+
+register = library = django.template.Library()
+comp_registry = ComponentRegistry(
+ library=library,
+ settings=RegistrySettings(
+ context_behavior="isolated",
+ tag_formatter="django_components.component_formatter",
+ ),
+)
+```
+
+These settings are [the same as the ones you can set for django_components](#available-settings).
+
+In fact, when you set `COMPONENT.tag_formatter` or `COMPONENT.context_behavior`, these are forwarded to the default `ComponentRegistry`.
+
+This makes it possible to have multiple registries with different settings in one projects, and makes sharing of component libraries possible.
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//", 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
new file mode 100644
index 00000000..269134cb
--- /dev/null
+++ b/docs/concepts/advanced/hooks.md
@@ -0,0 +1,354 @@
+_New in version 0.96_
+
+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`
+
+```py
+def on_render_before(
+ self: Component,
+ context: Context,
+ template: Optional[Template],
+) -> None:
+```
+
+[`Component.on_render_before`](../../../reference/api#django_components.Component.on_render_before) runs just before the component's template is rendered.
+
+It is called for every component, including nested ones, as part of
+the component render lifecycle.
+
+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.
+
+The `template` argument is `None` if the component has no template.
+
+**Example:**
+
+You can use this hook to access the context or the template:
+
+```py
+from django.template import Context, Template
+from django_components import Component
+
+class MyTable(Component):
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ # Insert value into the Context
+ context["from_on_before"] = ":)"
+
+ assert isinstance(template, Template)
+```
+
+!!! warning
+
+ 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/django-components/django-components/discussions/540)
+
+```django
+{% component "tabs" %}
+ {% component "tab_item" header="Tab 1" %}
+ MyPage
+ ...
+ {% component_css_dependencies %}
+
+
+
+ ...
+
+ {% component_js_dependencies %}
+
+
+```
+
+!!! warning
+
+ If the rendered HTML does NOT contain neither `{% component_dependencies %}` template tags,
+ nor `` and `` HTML tags, then the JS and CSS will NOT be inserted!
+
+ To force the JS and CSS to be inserted, use the [`"append"`](#append) or [`"prepend"`](#prepend)
+ strategies.
+
+## Dependencies strategies
+
+The rendered HTML may be used in different contexts (browser, email, etc).
+If your components use JS and CSS scripts, you may need to handle them differently.
+
+The different ways for handling JS / CSS are called **"dependencies strategies"**.
+
+[`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.
+
+```python
+main_page = MainPage.render(deps_strategy="document")
+fragment = MyComponent.render_to_response(deps_strategy="fragment")
+```
+
+The `deps_strategy` parameter is set at the root of a component render tree, which is why it is not available for
+the [`{% component %}`](../../../reference/template_tags#component) tag.
+
+When you use Django's [`django.shortcuts.render()`](https://docs.djangoproject.com/en/5.2/topics/http/shortcuts/#render)
+or [`Template.render()`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template.render) to render templates,
+you can't directly set the `deps_strategy` parameter.
+
+In this case, you can set the `deps_strategy` with the `DJC_DEPS_STRATEGY` context variable.
+
+```python
+from django.template.context import Context
+from django.shortcuts import render
+
+ctx = Context({"DJC_DEPS_STRATEGY": "fragment"})
+fragment = render(request, "my_component.html", ctx=ctx)
+```
+
+!!! info
+
+ The `deps_strategy` parameter is ultimately passed to [`render_dependencies()`](../../../reference/api/#django_components.render_dependencies).
+
+!!! note "Why is `deps_strategy` required?"
+
+ This is a technical limitation of the current implementation.
+
+ When a component is rendered, django-components embeds metadata about the component's JS and CSS into the HTML.
+
+ This way we can compose components together, and know which JS / CSS dependencies are needed.
+
+ As the last step of rendering, django-components extracts this metadata and uses a selected strategy
+ to insert the JS / CSS into the HTML.
+
+There are six dependencies strategies:
+
+- [`document`](../../advanced/rendering_js_css#document) (default)
+ - Smartly inserts JS / CSS into placeholders or into `` and `` tags.
+ - Inserts extra script to allow `fragment` strategy 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.
+ - No JS / CSS included.
+- [`simple`](../../advanced/rendering_js_css#simple)
+ - Smartly insert JS / CSS into placeholders or into `` and `` tags.
+ - No extra script loaded.
+- [`prepend`](../../advanced/rendering_js_css#prepend)
+ - Insert JS / CSS before the rendered HTML.
+ - No extra script loaded.
+- [`append`](../../advanced/rendering_js_css#append)
+ - Insert JS / CSS after the rendered HTML.
+ - 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.
+
+### `document`
+
+`deps_strategy="document"` is the default. Use this if you are rendering a whole page, or if no other option suits better.
+
+```python
+html = Button.render(deps_strategy="document")
+```
+
+When you render a component tree with the `"document"` strategy, it is expected that:
+
+- The HTML will be rendered at page load.
+- The HTML will be inserted into a page / browser where JS can be executed.
+
+**Location:**
+
+JS and CSS is inserted:
+
+- Preferentially into JS / CSS placeholders like [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies)
+- Otherwise, JS into `` element, and CSS into `` element
+- If neither found, JS / CSS are NOT inserted
+
+**Included scripts:**
+
+For the `"document"` strategy, the JS and CSS is set up to avoid any delays when the end user loads
+the page in the browser:
+
+- Components' primary JS and CSS scripts ([`Component.js`](../../../reference/api/#django_components.Component.js)
+ and [`Component.css`](../../../reference/api/#django_components.Component.css)) - fully inlined:
+
+ ```html
+
+
+ ```
+
+- 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_components import render_dependencies
+
+template = Template("""
+ {% load component_tags %}
+
+
+
+ MyPage
+
+
+
+ {% component "my_button" %}
+ Click me!
+ {% endcomponent %}
+
+
+
+""")
+
+rendered = template.render(Context({}))
+
+rendered2_raw = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+rendered2 = render_dependencies(rendered2_raw)
+
+assert rendered == rendered2
+```
+
+Same applies to other strategies and other methods of rendering:
+
+```python
+raw_html = MyComponent.render(deps_strategy="ignore")
+html = render_dependencies(raw_html, deps_strategy="document")
+
+html2 = MyComponent.render(deps_strategy="document")
+
+assert html == html2
+```
+
+## HTML fragments
+
+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.
+
+This is achieved by the combination of the [`"document"`](#document) and [`"fragment"`](#fragment) strategies.
+
+Read more about [HTML fragments](../../advanced/html_fragments).
diff --git a/docs/concepts/advanced/tag_formatters.md b/docs/concepts/advanced/tag_formatters.md
new file mode 100644
index 00000000..c0d363f5
--- /dev/null
+++ b/docs/concepts/advanced/tag_formatters.md
@@ -0,0 +1,166 @@
+## Customizing component tags with TagFormatter
+
+_New in version 0.89_
+
+By default, components are rendered using the pair of `{% component %}` / `{% endcomponent %}` template tags:
+
+```django
+{% component "button" href="..." disabled %}
+Click me!
+{% endcomponent %}
+
+{# or #}
+
+{% component "button" href="..." disabled / %}
+```
+
+You can change this behaviour in the settings under the [`COMPONENTS.tag_formatter`](#tag-formatter-setting).
+
+For example, if you set the tag formatter to
+
+`django_components.component_shorthand_formatter`
+
+then the components' names will be used as the template tags:
+
+```django
+{% button href="..." disabled %}
+ Click me!
+{% endbutton %}
+
+{# or #}
+
+{% button href="..." disabled / %}
+```
+
+## Available TagFormatters
+
+django_components provides following predefined TagFormatters:
+
+- **`ComponentFormatter` (`django_components.component_formatter`)**
+
+ Default
+
+ Uses the `component` and `endcomponent` tags, and the component name is gives as the first positional argument.
+
+ Example as block:
+
+ ```django
+ {% component "button" href="..." %}
+ {% fill "content" %}
+ ...
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+ Example as inlined tag:
+
+ ```django
+ {% component "button" href="..." / %}
+ ```
+
+- **`ShorthandComponentFormatter` (`django_components.component_shorthand_formatter`)**
+
+ Uses the component name as start tag, and `end`
+ as an end tag.
+
+ Example as block:
+
+ ```django
+ {% button href="..." %}
+ Click me!
+ {% endbutton %}
+ ```
+
+ Example as inlined tag:
+
+ ```django
+ {% button href="..." / %}
+ ```
+
+## Writing your own TagFormatter
+
+### Background
+
+First, let's discuss how TagFormatters work, and how components are rendered in django_components.
+
+When you render a component with `{% component %}` (or your own tag), the following happens:
+
+1. `component` must be registered as a Django's template tag
+2. Django triggers django_components's tag handler for tag `component`.
+3. The tag handler passes the tag contents for pre-processing to `TagFormatter.parse()`.
+
+ So if you render this:
+
+ ```django
+ {% component "button" href="..." disabled %}
+ {% endcomponent %}
+ ```
+
+ Then `TagFormatter.parse()` will receive a following input:
+
+ ```py
+ ["component", '"button"', 'href="..."', 'disabled']
+ ```
+
+4. `TagFormatter` extracts the component name and the remaining input.
+
+ So, given the above, `TagFormatter.parse()` returns the following:
+
+ ```py
+ TagResult(
+ component_name="button",
+ tokens=['href="..."', 'disabled']
+ )
+ ```
+
+5. The tag handler resumes, using the tokens returned from `TagFormatter`.
+
+ So, continuing the example, at this point the tag handler practically behaves as if you rendered:
+
+ ```django
+ {% component href="..." disabled %}
+ ```
+
+6. Tag handler looks up the component `button`, and passes the args, kwargs, and slots to it.
+
+### TagFormatter
+
+`TagFormatter` handles following parts of the process above:
+
+- Generates start/end tags, given a component. This is what you then call from within your template as `{% component %}`.
+
+- When you `{% component %}`, tag formatter pre-processes the tag contents, so it can link back the custom template tag to the right component.
+
+To do so, subclass from `TagFormatterABC` and implement following method:
+
+- `start_tag`
+- `end_tag`
+- `parse`
+
+For example, this is the implementation of [`ShorthandComponentFormatter`](#available-tagformatters)
+
+```py
+class ShorthandComponentFormatter(TagFormatterABC):
+ # Given a component name, generate the start template tag
+ def start_tag(self, name: str) -> str:
+ return name # e.g. 'button'
+
+ # Given a component name, generate the start template tag
+ def end_tag(self, name: str) -> str:
+ return f"end{name}" # e.g. 'endbutton'
+
+ # Given a tag, e.g.
+ # `{% button href="..." disabled %}`
+ #
+ # The parser receives:
+ # `['button', 'href="..."', 'disabled']`
+ def parse(self, tokens: List[str]) -> TagResult:
+ tokens = [*tokens]
+ name = tokens.pop(0)
+ return TagResult(
+ name, # e.g. 'button'
+ tokens # e.g. ['href="..."', 'disabled']
+ )
+```
+
+That's it! And once your `TagFormatter` is ready, don't forget to update the settings!
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"""
+ `).
+
+```django
+{% component "dynamic" is=table_comp data=table_data headers=table_headers %}
+ {% fill "pagination" %}
+ {% component "pagination" / %}
+ {% endfill %}
+{% endcomponent %}
+```
+
+The args, kwargs, and slot fills are all passed down to the underlying component.
+
+As with other components, the dynamic component can be rendered from Python:
+
+```py
+from django_components import DynamicComponent
+
+DynamicComponent.render(
+ kwargs={
+ "is": table_comp,
+ "data": table_data,
+ "headers": table_headers,
+ },
+ slots={
+ "pagination": PaginationComponent.render(
+ deps_strategy="ignore",
+ ),
+ },
+)
+```
+
+### Dynamic component name
+
+By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict,
+you can set the
+[`COMPONENTS.dynamic_component_name`](../../../reference/settings#django_components.app_settings.ComponentsSettings.dynamic_component_name)
+setting to change the name used for the dynamic components.
+
+```py
+# settings.py
+COMPONENTS = ComponentsSettings(
+ dynamic_component_name="my_dynamic",
+)
+```
+
+After which you will be able to use the dynamic component with the new name:
+
+```django
+{% component "my_dynamic" is=table_comp data=table_data headers=table_headers %}
+ {% fill "pagination" %}
+ {% component "pagination" / %}
+ {% endfill %}
+{% endcomponent %}
+```
+
+## HTML fragments
+
+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.
+
+This is achieved by the combination of the [`"document"`](../../advanced/rendering_js_css#document)
+and [`"fragment"`](../../advanced/rendering_js_css#fragment) dependencies rendering strategies.
+
+Read more about [HTML fragments](../../advanced/html_fragments) and [Rendering JS / CSS](../../advanced/rendering_js_css).
diff --git a/docs/concepts/fundamentals/secondary_js_css_files.md b/docs/concepts/fundamentals/secondary_js_css_files.md
new file mode 100644
index 00000000..ad7e5873
--- /dev/null
+++ b/docs/concepts/fundamentals/secondary_js_css_files.md
@@ -0,0 +1,484 @@
+## Overview
+
+Each component can define extra or "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).
+
+The [main HTML / JS / CSS files](../html_js_css_files) are limited to 1 per component. This is not the case for the secondary files,
+where components can have many of them.
+
+There is also no special behavior or post-processing for these secondary files, they are loaded as is.
+
+You can use these for third-party libraries, or for shared CSS / JS files.
+
+These must be set as paths, URLs, or [custom objects](#paths-as-objects).
+
+```py
+@register("calendar")
+class Calendar(Component):
+ class Media:
+ js = [
+ "https://unpkg.com/alpinejs@3.14.7/dist/cdn.min.js",
+ "calendar/script.js",
+ ]
+ css = [
+ "https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css",
+ "calendar/style.css",
+ ]
+```
+
+!!! note
+
+ django-component's management of files is inspired by [Django's `Media` class](https://docs.djangoproject.com/en/5.2/topics/forms/media/).
+
+ To be familiar with how Django handles static files, we recommend reading also:
+
+ - [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.2/howto/static-files/)
+
+## `Media` class
+
+
+
+Use the `Media` class to define secondary JS / CSS files for a component.
+
+This `Media` class behaves similarly to
+[Django's Media class](https://docs.djangoproject.com/en/5.2/topics/forms/media/#assets-as-a-static-definition):
+
+- **Static paths** - Paths are handled as static file paths, and are resolved to URLs with Django's
+ [`{% static %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#static) template tag.
+- **URLs** - A path that starts with `http`, `https`, or `/` is considered a URL. URLs are NOT resolved with [`{% static %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#static).
+- **HTML tags** - Both static paths and URLs are rendered to `
+#
+```
+
+When working with component media files, it is important to understand the difference:
+
+- `Component.Media`
+
+ - Is the "raw" media definition, or the input, which holds only the component's **own** media definition
+ - This class is NOT instantiated, it merely holds the JS / CSS files.
+
+- `Component.media`
+ - Returns all resolved media files, **including** those inherited from parent components
+ - Is an instance of [`Component.media_class`](../../reference/api.md#django_components.Component.media_class)
+
+```python
+class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+class ChildComponent(ParentComponent):
+ class Media:
+ js = ["child.js"]
+
+# Access only this component's media
+print(ChildComponent.Media.js) # ["child.js"]
+
+# Access all inherited media
+print(ChildComponent.media._js) # ["parent.js", "child.js"]
+```
+
+!!! note
+
+ You should **not** manually modify `Component.media` or `Component.Media` after the component has been resolved, as this may lead to unexpected behavior.
+
+If you want to modify the class that is instantiated for [`Component.media`](../../reference/api.md#django_components.Component.media),
+you can configure [`Component.media_class`](../../reference/api.md#django_components.Component.media_class)
+([See example](#rendering-paths)).
+
+## File paths
+
+Unlike the [main HTML / JS / CSS files](../html_js_css_files), the path definition for the secondary files are quite ergonomic.
+
+### Relative to component
+
+As seen in the [getting started example](../../getting_started/your_first_component.md), to associate HTML / JS / CSS
+files with a component, you can set them as
+[`Component.template_file`](../../reference/api.md#django_components.Component.template_file),
+[`Component.js_file`](../../reference/api.md#django_components.Component.js_file)
+and
+[`Component.css_file`](../../reference/api.md#django_components.Component.css_file) respectively:
+
+```py title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "template.html"
+ css_file = "style.css"
+ js_file = "script.js"
+```
+
+In the example above, we defined the files relative to the directory where the component file is defined.
+
+Alternatively, you can specify the file paths relative to the directories 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).
+
+If you specify the paths relative to component's directory, django-componenents does the conversion automatically
+for you.
+
+Thus, 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:
+
+```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"
+```
+
+!!! important
+
+ **File path resolution in-depth**
+
+ At component class creation, django-components checks all file paths defined on the component (e.g. `Component.template_file`).
+
+ For each file path, it checks if the file path is relative to the component's directory.
+ And such file exists, the component's file path is re-written to be defined relative to a first matching directory
+ in [`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
+ or
+ [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs).
+
+ **Example:**
+
+ ```py title="[root]/components/mytable/mytable.py"
+ class MyTable(Component):
+ template_file = "mytable.html"
+ ```
+
+ 1. Component `MyTable` is defined in file `[root]/components/mytable/mytable.py`.
+ 2. The component's directory is thus `[root]/components/mytable/`.
+ 3. Because `MyTable.template_file` is `mytable.html`, django-components tries to
+ resolve it as `[root]/components/mytable/mytable.html`.
+ 4. django-components checks the filesystem. If there's no such file, nothing happens.
+ 5. If there IS such file, django-components tries to rewrite the path.
+ 6. django-components searches `COMPONENTS.dirs` and `COMPONENTS.app_dirs` for a first
+ directory that contains `[root]/components/mytable/mytable.html`.
+ 7. It comes across `[root]/components/`, which DOES contain the path to `mytable.html`.
+ 8. Thus, it rewrites `template_file` from `mytable.html` to `mytable/mytable.html`.
+
+ NOTE: In case of ambiguity, the preference goes to resolving the files relative to the component's directory.
+
+### Globs
+
+Components can have many secondary files. To simplify their declaration, you can use globs.
+
+Globs MUST be relative to the component's directory.
+
+```py title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ class Media:
+ js = [
+ "path/to/*.js",
+ "another/path/*.js",
+ ]
+ css = "*.css"
+```
+
+How this works is that django-components will detect that the path is a glob, and will try to resolve all files matching the glob pattern relative to the component's directory.
+
+After that, the file paths are handled the same way as if you defined them explicitly.
+
+### Supported types
+
+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__`)
+
+To help with typing the union, use [`ComponentMediaInputPath`](../../../reference/api#django_components.ComponentMediaInputPath).
+
+```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",
+ ]
+```
+
+### Paths as objects
+
+In the example [above](#supported-types), you can see that when we used Django's
+[`mark_safe()`](https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.safestring.mark_safe)
+to mark a string as a [`SafeString`](https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.safestring.SafeString),
+we had to define the URL / path as an HTML `'
+ )
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar/template.html"
+
+ class Media:
+ css = "calendar/style1.css"
+ js = [
+ # ',
+ self.absolute_path(path)
+ )
+ return tags
+
+@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"
+
+ # Override the behavior of Media class
+ media_class = MyMedia
+```
diff --git a/docs/concepts/fundamentals/single_file_components.md b/docs/concepts/fundamentals/single_file_components.md
new file mode 100644
index 00000000..6f9b0765
--- /dev/null
+++ b/docs/concepts/fundamentals/single_file_components.md
@@ -0,0 +1,255 @@
+Components can be defined in a single file, inlining the HTML, JS and CSS within the Python code.
+
+## Writing single file components
+
+To do this, you can use the
+[`template`](../../../reference/api#django_components.Component.template),
+[`js`](../../../reference/api#django_components.Component.js),
+and [`css`](../../../reference/api#django_components.Component.css)
+class attributes instead of the
+[`template_file`](../../../reference/api#django_components.Component.template_file),
+[`js_file`](../../../reference/api#django_components.Component.js_file),
+and [`css_file`](../../../reference/api#django_components.Component.css_file).
+
+For example, here's the calendar component from
+the [Getting started](../../getting_started/your_first_component.md) tutorial:
+
+```py title="calendar.py"
+from django_components import Component
+
+class Calendar(Component):
+ template_file = "calendar.html"
+ js_file = "calendar.js"
+ css_file = "calendar.css"
+```
+
+And here is the same component, rewritten in a single file:
+
+```djc_py title="[project root]/components/calendar.py"
+from django_components import Component, register, types
+
+@register("calendar")
+class Calendar(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"],
+ }
+
+ template: types.django_html = """
+ ` above the variables.
+
+```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["date"],
+ }
+
+ # language=HTML
+ template= """
+ }}`](../../../reference/template_vars#slots) template variable:
+
+```django
+{% if component_vars.slots.my_slot %}
+ {item} {item} "
+
+Table.render(
+ slots={
+ "prepend": "Ice cream selection:",
+ "append": Slot("© 2025"),
+ "row": row_slot,
+ "column_title": Slot(lambda ctx: f"{ctx.data['name']} "),
+ },
+)
+```
+
+Inside the component, these will all be normalized to [`Slot`](../../../reference/api#django_components.Slot) instances:
+
+```py
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ assert isinstance(slots["prepend"], Slot)
+ assert isinstance(slots["row"], Slot)
+ assert isinstance(slots["header"], Slot)
+ assert isinstance(slots["footer"], Slot)
+```
+
+You can render [`Slot`](../../../reference/api#django_components.Slot) instances by simply calling them with data:
+
+```py
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ prepend_slot = slots["prepend"]
+ return {
+ "prepend": prepend_slot({"item": "ice cream"}),
+ }
+```
+
+### Filling slots with functions
+
+You can "fill" slots by passing a string or
+[`Slot`](../../../reference/api#django_components.Slot) instance
+directly to the [`{% fill %}`](../../../reference/template_tags#fill) tag:
+
+```py
+class Table(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ def my_fill(ctx):
+ return f"Hello, {ctx.data['name']}!"
+
+ return {
+ "my_fill": Slot(my_fill),
+ }
+```
+
+```django
+{% component "table" %}
+ {% fill "name" body=my_fill / %}
+{% endcomponent %}
+```
+
+!!! note
+
+ 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),
+ },
+)
+```
+
+Slot class can be instantiated with a function or a string:
+
+```py
+slot1 = Slot(lambda ctx: f"Hello, {ctx.data['name']}!")
+slot2 = Slot("Hello, world!")
+```
+
+!!! warning
+
+ Passing a [`Slot`](../../../reference/api#django_components.Slot) instance to the `Slot`
+ constructor results in an error:
+
+ ```py
+ slot = Slot("Hello")
+
+ # Raises an error
+ slot2 = Slot(slot)
+ ```
+
+### Rendering slots
+
+**Python**
+
+You can render a [`Slot`](../../../reference/api#django_components.Slot) instance by simply calling it with data:
+
+```py
+slot = Slot(lambda ctx: f"Hello, {ctx.data['name']}!")
+
+# Render the slot with data
+html = slot({"name": "John"})
+```
+
+Optionally you can pass the [fallback](#slot-fallback) value to the slot. Fallback should be a string.
+
+```py
+html = slot({"name": "John"}, fallback="Hello, world!")
+```
+
+**Template**
+
+Alternatively, you can pass the [`Slot`](../../../reference/api#django_components.Slot) instance to the
+[`{% fill %}`](../../../reference/template_tags#fill) tag:
+
+```django
+{% fill "name" body=slot / %}
+```
+
+### Slot context
+
+If a slot function is rendered by the [`{% slot %}`](../../../reference/template_tags#slot) tag,
+you can access the current [Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context)
+using the `context` attribute.
+
+```py
+class Table(Component):
+ template = """
+ {% with "abc" as my_var %}
+ {% slot "name" %}
+ Hello!
+ {% endslot %}
+ {% endwith %}
+ """
+
+def slot_func(ctx):
+ return f"Hello, {ctx.context['my_var']}!"
+
+slot = Slot(slot_func)
+html = slot()
+```
+
+!!! warning
+
+ While available, try to avoid using the `context` attribute in slot functions.
+
+ Instead, prefer using the `data` and `fallback` attributes.
+
+
+ Access to `context` may be removed in future versions (v2, v3).
+
+### Slot metadata
+
+When accessing slots from within [`Component`](../../../reference/api#django_components.Component) methods,
+the [`Slot`](../../../reference/api#django_components.Slot) instances are populated
+with extra metadata:
+
+- [`component_name`](../../../reference/api#django_components.Slot.component_name)
+- [`slot_name`](../../../reference/api#django_components.Slot.slot_name)
+- [`nodelist`](../../../reference/api#django_components.Slot.nodelist)
+- [`fill_node`](../../../reference/api#django_components.Slot.fill_node)
+- [`extra`](../../../reference/api#django_components.Slot.extra)
+
+These are populated the first time a slot is passed to a component.
+
+So if you pass the same slot through multiple nested components, the metadata will
+still point to the first component that received the slot.
+
+You can use these for debugging, such as printing out the slot's component name and slot name.
+
+**Fill node**
+
+Components or extensions can use [`Slot.fill_node`](../../../reference/api#django_components.Slot.fill_node)
+to handle slots differently based on whether the slot
+was defined in the template with [`{% fill %}`](../../../reference/template_tags#fill) and
+[`{% component %}`](../../../reference/template_tags#component) tags,
+or in the component's Python code.
+
+If the slot was created from a [`{% fill %}`](../../../reference/template_tags#fill) tag,
+this will be the [`FillNode`](../../../reference/api#django_components.FillNode) instance.
+
+If the slot was a default slot created from a [`{% component %}`](../../../reference/template_tags#component) tag,
+this will be the [`ComponentNode`](../../../reference/api#django_components.ComponentNode) instance.
+
+You can use this to find the [`Component`](../../../reference/api#django_components.Component) in whose
+template the [`{% fill %}`](../../../reference/template_tags#fill) tag was defined:
+
+```python
+class MyTable(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ footer_slot = slots.get("footer")
+ if footer_slot is not None and footer_slot.fill_node is not None:
+ owner_component = footer_slot.fill_node.template_component
+ # ...
+```
+
+**Extra**
+
+You can also pass any additional data along with the slot by setting it in [`Slot.extra`](../../../reference/api#django_components.Slot.extra):
+
+```py
+slot = Slot(
+ lambda ctx: f"Hello, {ctx.data['name']}!",
+ extra={"foo": "bar"},
+)
+```
+
+When you create a slot, you can set any of these fields too:
+
+```py
+# Either at slot creation
+slot = Slot(
+ lambda ctx: f"Hello, {ctx.data['name']}!",
+ # Optional
+ component_name="table",
+ slot_name="name",
+ extra={},
+)
+
+# Or later
+slot.component_name = "table"
+slot.slot_name = "name"
+slot.extra["foo"] = "bar"
+```
+
+Read more in [Pass slot metadata](../../advanced/extensions#pass-slot-metadata).
+
+### Slot contents
+
+Whether you create a slot from a function, a string, or from the [`{% fill %}`](../../../reference/template_tags#fill) tags,
+the [`Slot`](../../../reference/api#django_components.Slot) class normalizes its contents to a function.
+
+Use [`Slot.contents`](../../../reference/api#django_components.Slot.contents) to access the original value that was passed to the Slot constructor.
+
+```py
+slot = Slot("Hello!")
+print(slot.contents) # "Hello!"
+```
+
+If the slot was created from a string or from the [`{% fill %}`](../../../reference/template_tags#fill) tags,
+the contents will be accessible also as a Nodelist under [`Slot.nodelist`](../../../reference/api#django_components.Slot.nodelist).
+
+```py
+slot = Slot("Hello!")
+print(slot.nodelist) #
+```
+
+### Escaping slots content
+
+Slots content are automatically escaped by default to prevent XSS attacks.
+
+In other words, it's as if you would be using Django's [`escape()`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#std-templatefilter-escape) on the slot contents / result:
+
+```python
+from django.utils.html import escape
+
+class Calendar(Component):
+ template = """
+
+
+```
+
+When using the component, you can either set the fill explicitly:
+
+```django
+{% component "table" headers=headers items=items %}
+ {% fill "header-name" data="data" %}
+ {{ data.value }}
+ {% endfill %}
+{% endcomponent %}
+```
+
+Or also use a variable:
+
+```django
+{% component "table" headers=headers items=items %}
+ {% fill "header-{{ active_header_name }}" data="data" %}
+ {{ data.value }}
+ {% endfill %}
+{% endcomponent %}
+```
+
+!!! note
+
+ It's better to use literal slot names whenever possible for clarity.
+ The dynamic slot names should be reserved for advanced use only.
+
+### Spread operator
+
+Lastly, you can also pass the slot name through the [spread operator](../template_tag_syntax#spread-operator).
+
+When you define a slot name, it's actually a shortcut for a `name` keyword argument.
+
+So this:
+
+```django
+{% slot "content" / %}
+```
+
+is the same as:
+
+```django
+{% slot name="content" / %}
+```
+
+So it's possible to define a `name` key on a dictionary, and then spread that onto the slot tag:
+
+```django
+{# slot_props = {"name": "content"} #}
+{% slot ...slot_props / %}
+```
+
+Full example:
+
+```djc_py
+class MyTable(Component):
+ template = """
+ {% slot ...slot_props / %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "slot_props": {"name": "content", "extra_field": 123},
+ }
+```
+
+!!! info
+
+ This applies for both [`{% slot %}`](../../../reference/template_tags#slot)
+ and [`{% fill %}`](../../../reference/template_tags#fill) tags.
+
+
+
+## Legacy conditional slots
+
+> Since version 0.70, you could check if a slot was filled with
+>
+> `{{ component_vars.is_filled. }}`
+>
+> Since version 0.140, this has been deprecated and superseded with
+>
+> [`{% component_vars.slots. %}`](../../../reference/template_vars#slots)
+>
+> The `component_vars.is_filled` variable is still available, but will be removed in v1.0.
+>
+> NOTE: `component_vars.slots` no longer escapes special characters in slot names.
+
+You can use `{{ component_vars.is_filled. }}` 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
+ %}`/`{% endslot %}`: Declares a new slot in the component template.
+- `{% fill %}`/`{% endfill %}`: (Used inside a [`{% component %}`](../../reference/template_tags#component)
+ tag pair.) Fills a declared slot with the specified content.
+
+### 2. Add a slot tag
+
+Let's update our calendar component to support more customization. We'll add
+[`{% slot %}`](../../reference/template_tags#slot) tag to the template:
+
+```htmldjango
+My example calendar
+
+
+ {% component "calendar" / %}
+
+
+```
+
+### 1. Register component
+
+First, however, we need to register our component class with [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry).
+
+To register a component with a [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry),
+we will use the [`@register`](../../reference/api#django_components.register)
+decorator, and give it a name under which the component will be accessible from within the template:
+
+```python title="[project root]/components/calendar/calendar.py"
+from django_components import Component, register # <--- new
+
+@register("calendar") # <--- new
+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": "1970-01-01",
+ }
+```
+
+This will register the component to the default registry. Default registry is loaded into the template
+by calling `{% load component_tags %}` inside the template.
+
+!!! info
+
+ **Why do we have to register components?**
+
+ We want to use our component as a template tag (`{% ... %}`) in Django template.
+
+ In Django, template tags are managed by the `Library` instances. Whenever you include `{% load xxx %}`
+ in your template, you are loading a `Library` instance into your template.
+
+ [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry) acts like a router
+ and connects the registered components with the associated `Library`.
+
+ That way, when you include `{% load component_tags %}` in your template, you are able to "call" components
+ like `{% component "calendar" / %}`.
+
+ `ComponentRegistries` also make it possible to group and share components as standalone packages.
+ [Learn more here](../../concepts/advanced/component_libraries).
+
+!!! note
+
+ You can create custom [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry)
+ instances, which will use different `Library` instances.
+ In that case you will have to load different libraries depending on which components you want to use:
+
+ Example 1 - Using component defined in the default registry
+ ```htmldjango
+ {% load component_tags %}
+ My example calendar
+
+
+ {% component "calendar" / %} {# Render the component #}
+
+
+```
+
+!!! info
+
+ Component tags should end with `/` if they do not contain any [Slot fills](../../concepts/fundamentals/slots).
+ But you can also use `{% endcomponent %}` instead:
+
+ ```htmldjango
+ {% component "calendar" %}{% endcomponent %}
+ ```
+
+We defined the Calendar's template as
+
+```htmldjango
+My example calendar
+
+
+
+ ".format(
- self.name,
- getattr(self, "nodelist", None), # 'nodelist' attribute only assigned later.
- )
-
- def render(self, context: Context) -> str:
- trace_msg("RENDR", "COMP", self.name, self.node_id)
-
- component_cls: Type[Component] = self.registry.get(self.name)
-
- # Resolve FilterExpressions and Variables that were passed as args to the
- # component, then call component's context method
- # to get values to insert into the context
- args = safe_resolve_list(context, self.args)
- kwargs = self.kwargs.resolve(context)
-
- is_default_slot = len(self.fill_nodes) == 1 and self.fill_nodes[0].is_implicit
- if is_default_slot:
- fill_content: Dict[str, FillContent] = {
- DEFAULT_SLOT_KEY: FillContent(
- content_func=_nodelist_to_slot_render_func(self.fill_nodes[0].nodelist),
- slot_data_var=None,
- slot_default_var=None,
- ),
- }
- else:
- fill_content = resolve_fill_nodes(context, self.fill_nodes, self.name)
-
- component: Component = component_cls(
- registered_name=self.name,
- outer_context=context,
- fill_content=fill_content,
- component_id=self.node_id,
- registry=self.registry,
- )
-
- # Prevent outer context from leaking into the template of the component
- if self.isolated_context or self.registry.settings.CONTEXT_BEHAVIOR == ContextBehavior.ISOLATED:
- context = make_isolated_context_copy(context)
-
- output = component._render(
+ return cls._render_with_error_trace(
context=context,
args=args,
kwargs=kwargs,
+ slots=slots,
+ deps_strategy=deps_strategy,
+ request=request,
+ outer_context=outer_context,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry=registry,
+ registered_name=registered_name,
+ node=node,
+ )
+
+ # This is the internal entrypoint for the render function
+ @classmethod
+ def _render_with_error_trace(
+ cls,
+ context: Optional[Union[Dict[str, Any], Context]] = None,
+ args: Optional[Any] = None,
+ kwargs: Optional[Any] = None,
+ slots: Optional[Any] = None,
+ deps_strategy: DependenciesStrategy = "document",
+ request: Optional[HttpRequest] = None,
+ outer_context: Optional[Context] = None,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry: Optional[ComponentRegistry] = None,
+ registered_name: Optional[str] = None,
+ node: Optional["ComponentNode"] = None,
+ ) -> str:
+ component_name = _get_component_name(cls, registered_name)
+
+ # Modify the error to display full component path (incl. slots)
+ with component_error_message([component_name]):
+ return cls._render_impl(
+ context=context,
+ args=args,
+ kwargs=kwargs,
+ slots=slots,
+ deps_strategy=deps_strategy,
+ request=request,
+ outer_context=outer_context,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry=registry,
+ registered_name=registered_name,
+ node=node,
+ )
+
+ @classmethod
+ def _render_impl(
+ comp_cls,
+ context: Optional[Union[Dict[str, Any], Context]] = None,
+ args: Optional[Any] = None,
+ kwargs: Optional[Any] = None,
+ slots: Optional[Any] = None,
+ deps_strategy: DependenciesStrategy = "document",
+ request: Optional[HttpRequest] = None,
+ outer_context: Optional[Context] = None,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry: Optional[ComponentRegistry] = None,
+ registered_name: Optional[str] = None,
+ node: Optional["ComponentNode"] = None,
+ ) -> str:
+ ######################################
+ # 1. Handle inputs
+ ######################################
+
+ # Allow to pass down Request object via context.
+ # `context` may be passed explicitly via `Component.render()` and `Component.render_to_response()`,
+ # or implicitly via `{% component %}` tag.
+ if request is None and context:
+ # If the context is `RequestContext`, it has `request` attribute
+ request = getattr(context, "request", None)
+ # Check if this is a nested component and whether parent has request
+ if request is None:
+ _, parent_comp_ctx = _get_parent_component_context(context)
+ if parent_comp_ctx:
+ request = parent_comp_ctx.component.request
+
+ component_name = _get_component_name(comp_cls, registered_name)
+
+ # Allow to provide no args/kwargs/slots/context
+ # NOTE: We make copies of args / kwargs / slots, so that plugins can modify them
+ # without affecting the original values.
+ args_list: List[Any] = list(default(args, []))
+ kwargs_dict = to_dict(default(kwargs, {}))
+ slots_dict = normalize_slot_fills(
+ to_dict(default(slots, {})),
+ component_name=component_name,
+ )
+ # Use RequestContext if request is provided, so that child non-component template tags
+ # can access the request object too.
+ context = context if context is not None else (RequestContext(request) if request else Context())
+
+ # Allow to provide a dict instead of Context
+ # NOTE: This if/else is important to avoid nested Contexts,
+ # See https://github.com/django-components/django-components/issues/414
+ if not isinstance(context, (Context, RequestContext)):
+ context = RequestContext(request, context) if request else Context(context)
+
+ render_id = _gen_component_id()
+
+ component = comp_cls(
+ id=render_id,
+ args=args_list,
+ kwargs=kwargs_dict,
+ slots=slots_dict,
+ context=context,
+ request=request,
+ deps_strategy=deps_strategy,
+ outer_context=outer_context,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry=registry,
+ registered_name=registered_name,
+ node=node,
+ )
+
+ # Allow plugins to modify or validate the inputs
+ result_override = extensions.on_component_input(
+ OnComponentInputContext(
+ component=component,
+ component_cls=comp_cls,
+ component_id=render_id,
+ args=args_list,
+ kwargs=kwargs_dict,
+ slots=slots_dict,
+ context=context,
+ )
+ )
+
+ # The component rendering was short-circuited by an extension, skipping
+ # the rest of the rendering process. This may be for example a cached content.
+ if result_override is not None:
+ return result_override
+
+ # If user doesn't specify `Args`, `Kwargs`, `Slots` types, then we pass them in as plain
+ # dicts / lists.
+ component.args = comp_cls.Args(*args_list) if comp_cls.Args is not None else args_list
+ component.kwargs = comp_cls.Kwargs(**kwargs_dict) if comp_cls.Kwargs is not None else kwargs_dict
+ component.slots = comp_cls.Slots(**slots_dict) if comp_cls.Slots is not None else slots_dict
+
+ ######################################
+ # 2. Prepare component state
+ ######################################
+
+ # Required for compatibility with Django's {% extends %} tag
+ # See https://github.com/django-components/django-components/pull/859
+ context.render_context.push( # type: ignore[union-attr]
+ {BLOCK_CONTEXT_KEY: context.render_context.get(BLOCK_CONTEXT_KEY, BlockContext())} # type: ignore
+ )
+
+ # We pass down the components the info about the component's parent.
+ # This is used for correctly resolving slot fills, correct rendering order,
+ # or CSS scoping.
+ parent_id, parent_comp_ctx = _get_parent_component_context(context)
+ if parent_comp_ctx is not None:
+ component_path = [*parent_comp_ctx.component_path, component_name]
+ post_render_callbacks = parent_comp_ctx.post_render_callbacks
+ else:
+ component_path = [component_name]
+ post_render_callbacks = {}
+
+ trace_component_msg(
+ "COMP_PREP_START",
+ component_name=component_name,
+ component_id=render_id,
+ slot_name=None,
+ component_path=component_path,
+ extra=(
+ f"Received {len(args_list)} args, {len(kwargs_dict)} kwargs, {len(slots_dict)} slots,"
+ f" Available slots: {slots_dict}"
+ ),
+ )
+
+ # Register the component to provide
+ register_provide_reference(context, render_id)
+
+ # This is data that will be accessible (internally) from within the component's template
+ component_ctx = ComponentContext(
+ component=component,
+ component_path=component_path,
+ # Template name is set only once we've resolved the component's Template instance.
+ template_name=None,
+ # This field will be modified from within `SlotNodes.render()`:
+ # - The `default_slot` will be set to the first slot that has the `default` attribute set.
+ # - If multiple slots have the `default` attribute set, yet have different name, then
+ # we will raise an error.
+ default_slot=None,
+ # NOTE: This is only a SNAPSHOT of the outer context.
+ outer_context=snapshot_context(outer_context) if outer_context is not None else None,
+ post_render_callbacks=post_render_callbacks,
+ )
+
+ # Instead of passing the ComponentContext directly through the Context, the entry on the Context
+ # contains only a key to retrieve the ComponentContext from `component_context_cache`.
+ #
+ # This way, the flow is easier to debug. Because otherwise, if you tried to print out
+ # or inspect the Context object, your screen would be filled with the deeply nested ComponentContext objects.
+ # But now, the printed Context may simply look like this:
+ # `[{ "True": True, "False": False, "None": None }, {"_DJC_COMPONENT_CTX": "c1A2b3c"}]`
+ component_context_cache[render_id] = component_ctx
+
+ ######################################
+ # 3. Call data methods
+ ######################################
+
+ template_data, js_data, css_data = component._call_data_methods(context, args_list, kwargs_dict)
+
+ extensions.on_component_data(
+ OnComponentDataContext(
+ component=component,
+ component_cls=comp_cls,
+ component_id=render_id,
+ # TODO_V1 - Remove `context_data`
+ context_data=template_data,
+ template_data=template_data,
+ js_data=js_data,
+ css_data=css_data,
+ )
+ )
+
+ # Cache component's JS and CSS scripts, in case they have been evicted from the cache.
+ cache_component_js(comp_cls, force=False)
+ cache_component_css(comp_cls, force=False)
+
+ # Create JS/CSS scripts that will load the JS/CSS variables into the page.
+ js_input_hash = cache_component_js_vars(comp_cls, js_data) if js_data else None
+ css_input_hash = cache_component_css_vars(comp_cls, css_data) if css_data else None
+
+ #############################################################################
+ # 4. Make Context copy
+ #
+ # NOTE: To support infinite recursion, we make a copy of the context.
+ # This way we don't have to call the whole component tree in one go recursively,
+ # but instead can render one component at a time.
+ #############################################################################
+
+ # TODO_v1 - Currently we have to pass `template_data` to `prepare_component_template()`,
+ # so that `get_template_string()`, `get_template_name()`, and `get_template()`
+ # have access to the data from `get_template_data()`.
+ #
+ # Because of that there is one layer of `Context.update()` called inside `prepare_component_template()`.
+ #
+ # Once `get_template_string()`, `get_template_name()`, and `get_template()` are removed,
+ # we can remove that layer of `Context.update()`, and NOT pass `template_data`
+ # to `prepare_component_template()`.
+ #
+ # Then we can simply apply `template_data` to the context in the same layer
+ # where we apply `context_processor_data` and `component_vars`.
+ with prepare_component_template(component, template_data) as template:
+ # Set `_DJC_COMPONENT_IS_NESTED` based on whether we're currently INSIDE
+ # the `{% extends %}` tag.
+ # Part of fix for https://github.com/django-components/django-components/issues/508
+ # See django_monkeypatch.py
+ if template is not None:
+ comp_is_nested = bool(context.render_context.get(BLOCK_CONTEXT_KEY)) # type: ignore[union-attr]
+ else:
+ comp_is_nested = False
+
+ # Capture the template name so we can print better error messages (currently used in slots)
+ component_ctx.template_name = template.name if template else None
+
+ with context.update( # type: ignore[union-attr]
+ {
+ # Make data from context processors available inside templates
+ **component.context_processors_data,
+ # Private context fields
+ _COMPONENT_CONTEXT_KEY: render_id,
+ COMPONENT_IS_NESTED_KEY: comp_is_nested,
+ # NOTE: Public API for variables accessible from within a component's template
+ # See https://github.com/django-components/django-components/issues/280#issuecomment-2081180940
+ "component_vars": ComponentVars(
+ args=component.args,
+ kwargs=component.kwargs,
+ slots=component.slots,
+ # TODO_v1 - Remove this, superseded by `component_vars.slots`
+ #
+ # For users, we expose boolean variables that they may check
+ # to see if given slot was filled, e.g.:
+ # `{% if variable > 8 and component_vars.is_filled.header %}`
+ is_filled=component.is_filled,
+ ),
+ }
+ ):
+ # Make a "snapshot" of the context as it was at the time of the render call.
+ #
+ # Previously, we recursively called `Template.render()` as this point, but due to recursion
+ # this was limiting the number of nested components to only about 60 levels deep.
+ #
+ # Now, we make a flat copy, so that the context copy is static and doesn't change even if
+ # we leave the `with context.update` blocks.
+ #
+ # This makes it possible to render nested components with a queue, avoiding recursion limits.
+ context_snapshot = snapshot_context(context)
+
+ # Cleanup
+ context.render_context.pop() # type: ignore[union-attr]
+
+ ######################################
+ # 5. Render component
+ #
+ # NOTE: To support infinite recursion, we don't directly call `Template.render()`.
+ # Instead, we defer rendering of the component - we prepare a callback that will
+ # be called when the rendering process reaches this component.
+ ######################################
+
+ # Instead of rendering component at the time we come across the `{% component %}` tag
+ # in the template, we defer rendering in order to scalably handle deeply nested components.
+ #
+ # See `_gen_component_renderer()` for more details.
+ deferred_render = component._gen_component_renderer(
+ template=template,
+ context=context_snapshot,
+ component_path=component_path,
+ css_input_hash=css_input_hash,
+ js_input_hash=js_input_hash,
+ )
+
+ # This is triggered when a component is rendered, but the component's parents
+ # may not have been rendered yet.
+ def on_component_rendered(
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> OnComponentRenderedResult:
+ # Allow the user to either:
+ # - Override/modify the rendered HTML by returning new value
+ # - Raise an exception to discard the HTML and bubble up error
+ # - Or don't return anything (or return `None`) to use the original HTML / error
+ try:
+ maybe_output = component.on_render_after(context_snapshot, template, html, error)
+ if maybe_output is not None:
+ html = maybe_output
+ error = None
+ except Exception as new_error:
+ error = new_error
+ html = None
+
+ # Remove component from caches
+ del component_context_cache[render_id] # type: ignore[arg-type]
+ unregister_provide_reference(render_id) # type: ignore[arg-type]
+
+ # Allow extensions to either:
+ # - Override/modify the rendered HTML by returning new value
+ # - Raise an exception to discard the HTML and bubble up error
+ # - Or don't return anything (or return `None`) to use the original HTML / error
+ result = extensions.on_component_rendered(
+ OnComponentRenderedContext(
+ component=component,
+ component_cls=comp_cls,
+ component_id=render_id,
+ result=html,
+ error=error,
+ )
+ )
+
+ if result is not None:
+ html, error = result
+
+ return html, error
+
+ post_render_callbacks[render_id] = on_component_rendered
+
+ # This is triggered after a full component tree was rendered, we resolve
+ # all inserted HTML comments into "),
+ ]
+ css = [
+ Path("path/to/style.css"),
+ lambda: "path/to/style.css",
+ lambda: Path("path/to/style.css"),
+ ]
+```
+"""
+
+
+# This is the interface of the class that user is expected to define on the component class, e.g.:
+# ```py
+# class MyComponent(Component):
+# class Media:
+# js = "path/to/script.js"
+# css = "path/to/style.css"
+# ```
+class ComponentMediaInput(Protocol):
"""
- Metaclass for handling media files for components.
+ Defines JS and CSS media files associated with a [`Component`](../api#django_components.Component).
- Similar to `MediaDefiningClass`, this class supports the use of `Media` attribute
- to define associated JS/CSS files, which are then available under `media`
- attribute as a instance of `Media` class.
+ ```py
+ class MyTable(Component):
+ class Media:
+ js = [
+ "path/to/script.js",
+ "https://unpkg.com/alpinejs@3.14.7/dist/cdn.min.js", # AlpineJS
+ ]
+ css = {
+ "all": [
+ "path/to/style.css",
+ "https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css", # TailwindCSS
+ ],
+ "print": ["path/to/style2.css"],
+ }
+ ```
+ """
- This subclass has following changes:
+ css: Optional[
+ Union[
+ ComponentMediaInputPath,
+ List[ComponentMediaInputPath],
+ Dict[str, ComponentMediaInputPath],
+ Dict[str, List[ComponentMediaInputPath]],
+ ]
+ ] = None
+ """
+ CSS files associated with a [`Component`](../api#django_components.Component).
- ### 1. Support for multiple interfaces of JS/CSS
+ - If a string, it's assumed to be a path to a CSS file.
+
+ - If a list, each entry is assumed to be a path to a CSS file.
+
+ - If a dict, the keys are media types (e.g. "all", "print", "screen", etc.), and the values are either:
+ - A string, assumed to be a path to a CSS file.
+ - A list, each entry is assumed to be a path to a CSS file.
+
+ Each entry can be a string, bytes, SafeString, PathLike, or a callable that returns one of the former
+ (see [`ComponentMediaInputPath`](../api#django_components.ComponentMediaInputPath)).
+
+ Examples:
+ ```py
+ class MyComponent(Component):
+ class Media:
+ css = "path/to/style.css"
+ ```
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ css = ["path/to/style1.css", "path/to/style2.css"]
+ ```
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ css = {
+ "all": "path/to/style.css",
+ "print": "path/to/print.css",
+ }
+ ```
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ css = {
+ "all": ["path/to/style1.css", "path/to/style2.css"],
+ "print": "path/to/print.css",
+ }
+ ```
+ """
+
+ js: Optional[Union[ComponentMediaInputPath, List[ComponentMediaInputPath]]] = None
+ """
+ JS files associated with a [`Component`](../api#django_components.Component).
+
+ - If a string, it's assumed to be a path to a JS file.
+
+ - If a list, each entry is assumed to be a path to a JS file.
+
+ Each entry can be a string, bytes, SafeString, PathLike, or a callable that returns one of the former
+ (see [`ComponentMediaInputPath`](../api#django_components.ComponentMediaInputPath)).
+
+ Examples:
+ ```py
+ class MyComponent(Component):
+ class Media:
+ js = "path/to/script.js"
+ ```
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ js = ["path/to/script1.js", "path/to/script2.js"]
+ ```
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ js = lambda: ["path/to/script1.js", "path/to/script2.js"]
+ ```
+ """
+
+ extend: Union[bool, List[Type["Component"]]] = True
+ """
+ Configures whether the component should inherit the media files from the parent component.
+
+ - If `True`, the component inherits the media files from the parent component.
+ - If `False`, the component does not inherit the media files from the parent component.
+ - If a list of components classes, the component inherits the media files ONLY from these specified components.
+
+ Read more in [Media inheritance](../../concepts/fundamentals/secondary_js_css_files/#media-inheritance) section.
+
+ **Example:**
+
+ Disable media inheritance:
+
+ ```python
+ class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+ class MyComponent(ParentComponent):
+ class Media:
+ extend = False # Don't inherit parent media
+ js = ["script.js"]
+
+ print(MyComponent.media._js) # ["script.js"]
+ ```
+
+ Specify which components to inherit from. In this case, the media files are inherited ONLY
+ from the specified components, and NOT from the original parent components:
+
+ ```python
+ class ParentComponent(Component):
+ class Media:
+ js = ["parent.js"]
+
+ class MyComponent(ParentComponent):
+ class Media:
+ # Only inherit from these, ignoring the files from the parent
+ extend = [OtherComponent1, OtherComponent2]
+
+ js = ["script.js"]
+
+ print(MyComponent.media._js) # ["script.js", "other1.js", "other2.js"]
+ ```
+ """ # noqa: E501
+
+
+@dataclass
+class ComponentMedia:
+ comp_cls: Type["Component"]
+ resolved: bool = False
+ resolved_relative_files: bool = False
+ Media: Union[Type[ComponentMediaInput], Unset, None] = UNSET
+ template: Union[str, Unset, None] = UNSET
+ template_file: Union[str, Unset, None] = UNSET
+ js: Union[str, Unset, None] = UNSET
+ js_file: Union[str, Unset, None] = UNSET
+ css: Union[str, Unset, None] = UNSET
+ css_file: Union[str, Unset, None] = UNSET
+ # Template instance that was loaded for this component
+ _template: Union[Template, Unset, None] = UNSET
+
+ def __post_init__(self) -> None:
+ for inlined_attr in ("template", "js", "css"):
+ file_attr = f"{inlined_attr}_file"
+
+ inlined_val = getattr(self, inlined_attr)
+ file_val = getattr(self, file_attr)
+ # NOTE: We raise if Component class received both inlined and file values:
+ # ```py
+ # class MyComp(Component):
+ # js = "..."
+ # js_file = "..."
+ # ```
+ #
+ # But both `None` are allowed:
+ # ```py
+ # class MyComp(Component):
+ # js = None
+ # js_file = None
+ # ```
+ if (inlined_val is not UNSET and file_val is not UNSET) and not (inlined_val is None and file_val is None):
+ raise ImproperlyConfigured(
+ f"Received non-empty value from both '{inlined_attr}' and '{file_attr}' in"
+ f" Component {self.comp_cls.__name__}. Only one of the two must be set."
+ )
+ # Make a copy of the original state, so we can reset it in tests
+ self._original = copy(self)
+
+ # Return ComponentMedia to its original state before the media was resolved
+ def reset(self) -> None:
+ self.__dict__.update(self._original.__dict__)
+ self.resolved = False
+ self.resolved_relative_files = False
+
+
+# This metaclass is all about one thing - lazily resolving the media files.
+#
+# All the CSS/JS/HTML associated with a component - e.g. the `js`, `js_file`, `template_file` or `Media` class,
+# are all class attributes. And some of these attributes need to be resolved, e.g. to find the files
+# that `js_file`, `css_file` and `template_file` point to.
+#
+# Some of the resolutions we need to do is:
+# - Component's HTML/JS/CSS files can be defined as relative to the component class file. So for each file,
+# we check the relative path points to an actual file, and if so, we use that path.
+# - If the component defines `js_file` or `css_file`, we load the content of the file and set it to `js` or `css`.
+# - Note 1: These file paths still may be relative to the component, so the paths are resolved as above,
+# before we load the content.
+# - Note 2: We don't support both `js` and `js_file` being set at the same time.
+#
+# At the same time, we need to do so lazily, otherwise we hit a problem with circular imports when trying to
+# use Django settings. This is because the settings are not available at the time when the component class is defined
+# (Assuming that components are defined at the top-level of modules).
+#
+# We achieve this by:
+# 1. At class creation, we define a private `ComponentMedia` object that holds all the media-related attributes.
+# 2. At the same time, we replace the actual media-related attributes (like `js`) with descriptors that intercept
+# the access to them.
+# 3. When the user tries to access the media-related attributes, we resolve the media files if they haven't been
+# resolved yet.
+# 4. Any further access to the media-related attributes will return the resolved values.
+class ComponentMediaMeta(type):
+ def __new__(mcs, name: str, bases: Tuple[Type, ...], attrs: Dict[str, Any]) -> Type:
+ # Normalize the various forms of Media inputs we allow
+ if "Media" in attrs:
+ _normalize_media(attrs["Media"])
+
+ cls = super().__new__(mcs, name, bases, attrs)
+ comp_cls = cast(Type["Component"], cls)
+
+ _setup_lazy_media_resolve(comp_cls, attrs)
+
+ return comp_cls
+
+ # `__setattr__` on metaclass allows to intercept when user tries to set an attribute on the class.
+ #
+ # NOTE: All of attributes likes `Media`, `js`, `js_file`, etc, they are all class attributes.
+ # If they were instance attributes, we could use `@property` decorator.
+ #
+ # Because we lazily resolve the media, there's a possibility that the user may try to set some media fields
+ # after the media fields were already resolved. This is currently not supported, and we do the resolution
+ # only once.
+ #
+ # Thus, we print a warning when user sets the media fields after they were resolved.
+ def __setattr__(cls, name: str, value: Any) -> None:
+ if name in COMP_MEDIA_LAZY_ATTRS:
+ comp_media: Optional[ComponentMedia] = getattr(cls, "_component_media", None)
+ if comp_media is not None and comp_media.resolved:
+ print(
+ f"WARNING: Setting attribute '{name}' on component '{cls.__name__}' after the media files were"
+ " already resolved. This may lead to unexpected behavior."
+ )
+
+ # NOTE: When a metaclass specifies a `__setattr__` method, this overrides the normal behavior of
+ # setting an attribute on the class with Descriptors. So we need to call the normal behavior explicitly.
+ # NOTE 2: `__dict__` is used to access the class attributes directly, without triggering the descriptors.
+ desc = cls.__dict__.get(name, None)
+ if hasattr(desc, "__set__"):
+ desc.__set__(cls, value)
+ else:
+ super().__setattr__(name, value)
+
+
+# This sets up the lazy resolution of the media attributes.
+def _setup_lazy_media_resolve(comp_cls: Type["Component"], attrs: Dict[str, Any]) -> None:
+ # Collect all the original values of the lazy attributes, so we can access them from the getter
+ comp_cls._component_media = ComponentMedia(
+ comp_cls=comp_cls,
+ resolved=False,
+ # NOTE: We take the values from `attrs` so we consider only the values that were set on THIS class,
+ # and not the values that were inherited from the parent classes.
+ Media=attrs.get("Media", UNSET),
+ template=attrs.get("template", UNSET),
+ template_file=attrs.get("template_file", UNSET),
+ js=attrs.get("js", UNSET),
+ js_file=attrs.get("js_file", UNSET),
+ css=attrs.get("css", UNSET),
+ css_file=attrs.get("css_file", UNSET),
+ )
+
+ def get_comp_media_attr(attr: str) -> Any:
+ if attr == "media":
+ return _get_comp_cls_media(comp_cls)
+ else:
+ return _get_comp_cls_attr(comp_cls, attr)
+
+ # Because of the lazy resolution, we want to know when the user tries to access the media attributes.
+ # And because these fields are class attributes, we can't use `@property` decorator.
+ #
+ # Instead, we define a descriptor for each of the media attributes, and set it on the class.
+ # Read more on descriptors https://docs.python.org/3/howto/descriptor.html
+ class InterceptDescriptor:
+ def __init__(self, name: str) -> None:
+ self._attr_name = name
+
+ # `__get__` runs when a class/instance attribute is being accessed
+ def __get__(self, instance: Optional["Component"], cls: Type["Component"]) -> Any:
+ return get_comp_media_attr(self._attr_name)
+
+ for attr in COMP_MEDIA_LAZY_ATTRS:
+ setattr(comp_cls, attr, InterceptDescriptor(attr))
+
+
+# Because the media values are not defined directly on the instance, but held in `_component_media`,
+# then simply accessing `_component_media.js` will NOT get the values from parent classes.
+#
+# So this function is like `getattr`, but for searching for values inside `_component_media`.
+def _get_comp_cls_attr(comp_cls: Type["Component"], attr: str) -> Any:
+ for base in comp_cls.mro():
+ comp_media: Optional[ComponentMedia] = getattr(base, "_component_media", None)
+ if comp_media is None:
+ continue
+ if not comp_media.resolved:
+ _resolve_media(base, comp_media)
+
+ # NOTE: We differentiate between `None` and `UNSET`, so that users can set `None` to
+ # override parent class's value and set it to `None`.
+ value = getattr(comp_media, attr, UNSET)
+
+ # For each of the pairs of inlined_content + file (e.g. `js` + `js_file`), if at least one of the two
+ # is defined, we interpret it such that this (sub)class has overridden what was set by the parent class(es),
+ # and we won't search further up the MRO.
+ def resolve_pair(inline_attr: str, file_attr: str) -> Any:
+ inline_attr_empty = getattr(comp_media, inline_attr, UNSET) is UNSET
+ file_attr_empty = getattr(comp_media, file_attr, UNSET) is UNSET
+
+ is_pair_empty = inline_attr_empty and file_attr_empty
+ if is_pair_empty:
+ return UNSET
+ else:
+ return value
+
+ if attr in ("js", "js_file"):
+ value = resolve_pair("js", "js_file")
+ elif attr in ("css", "css_file"):
+ value = resolve_pair("css", "css_file")
+ elif attr in ("template", "template_file"):
+ value = resolve_pair("template", "template_file")
+
+ if value is UNSET:
+ continue
+ else:
+ return value
+ return None
+
+
+# NOTE: We use weakref to avoid issues with lingering references.
+if sys.version_info >= (3, 9):
+ media_cache: WeakKeyDictionary[Type["Component"], MediaCls] = WeakKeyDictionary()
+else:
+ media_cache: WeakKeyDictionary = WeakKeyDictionary()
+
+
+def _get_comp_cls_media(comp_cls: Type["Component"]) -> Any:
+ # Component's `media` attribute is a special case, because it should inherit all the JS/CSS files
+ # from the parent classes. So we need to walk up the MRO and merge all the Media classes.
+ #
+ # But before we do that, we need to ensure that all parent classes have resolved their `media` attributes.
+ # Because to be able to construct `media` for a Component class, all its parent classes must have resolved
+ # their `media`.
+ #
+ # So we will:
+ # 0. Cache the resolved media, so we don't have to resolve it again, and so we can store it even for classes
+ # that don't have `Media` attribute.
+ # 1. If the current class HAS `media` in the cache, we used that
+ # 2. Otherwise, we check if its parent bases have `media` in the cache,
+ # 3. If ALL parent bases have `media` in the cache, we can resolve the child class's `media`,
+ # and put it in the cache.
+ # 4. If ANY of the parent bases DOESN'T, then we add those parent bases to the stack (so they are processed
+ # right after this. And we add the child class right after that.
+ #
+ # E.g. `stack = [*cls.__bases__, cls, *stack]`
+ #
+ # That way, we go up one level of the bases, and then we eventually come back down to the
+ # class that we tried to resolve. But the second time, we will have `media` resolved for all its parent bases.
+ bases_stack = deque([comp_cls])
+ while bases_stack:
+ curr_cls = bases_stack.popleft()
+
+ if curr_cls in media_cache:
+ continue
+
+ comp_media: Optional[ComponentMedia] = getattr(curr_cls, "_component_media", None)
+ if comp_media is not None and not comp_media.resolved:
+ _resolve_media(curr_cls, comp_media)
+
+ # Prepare base classes
+ # NOTE: If the `Component.Media` class is explicitly set to `None`, then we should not inherit
+ # from any parent classes.
+ # ```py
+ # class MyComponent(Component):
+ # Media = None
+ # ```
+ # But if the `Component.Media` class is NOT set, then we inherit from the parent classes.
+ # ```py
+ # class MyComponent(Component):
+ # pass
+ # ```
+ media_input = getattr(curr_cls, "Media", UNSET)
+ default_extend = True if media_input is not None else False
+ media_extend = getattr(media_input, "extend", default_extend)
+
+ # This ensures the same behavior as Django's Media class, where:
+ # - If `Media.extend == True`, then the media files are inherited from the parent classes.
+ # - If `Media.extend == False`, then the media files are NOT inherited from the parent classes.
+ # - If `Media.extend == [Component1, Component2, ...]`, then the media files are inherited only
+ # from the specified classes.
+ if media_extend is True:
+ bases = curr_cls.__bases__
+ elif media_extend is False:
+ bases = tuple()
+ else:
+ bases = media_extend
+
+ unresolved_bases = [base for base in bases if base not in media_cache]
+ if unresolved_bases:
+ # Put the current class's bases at the FRONT of the queue, and put the current class back right after that.
+ # E.g. `[parentCls1, parentCls2, currCls, ...]`
+ # That way, we first resolve the parent classes, and then the current class.
+ bases_stack.extendleft(reversed([*unresolved_bases, curr_cls]))
+ continue
+
+ # Now, if we got here, then either all the bases of the current class have had their `media` resolved,
+ # or the current class has NO bases. So now we construct the `media` for the current class.
+ media_cls = getattr(curr_cls, "media_class", MediaCls)
+ # NOTE: If the class is a component and and it was not yet resolved, accessing `Media` should resolve it.
+ media_js = getattr(media_input, "js", [])
+ media_css = getattr(media_input, "css", {})
+ media: MediaCls = media_cls(js=media_js, css=media_css)
+
+ # We have the current class's `media`, now we add the JS and CSS from the parent classes.
+ # NOTE: Django's implementation of `Media` should ensure that duplicate files are not added.
+ for base in bases:
+ base_media = media_cache.get(base, None)
+ if base_media is None:
+ continue
+
+ # Add JS / CSS from the base class's Media to the current class's Media.
+ # We make use of the fact that Django's Media class does this with `__add__` method.
+ #
+ # However, the `__add__` converts our `media_cls` to Django's Media class.
+ # So we also have to convert it back to `media_cls`.
+ merged_media = media + base_media
+ media = media_cls(js=merged_media._js, css=merged_media._css)
+
+ # Lastly, cache the merged-up Media, so we don't have to search further up the MRO the next time
+ media_cache[curr_cls] = media
+
+ return media_cache[comp_cls]
+
+
+def _resolve_media(comp_cls: Type["Component"], comp_media: ComponentMedia) -> None:
+ """
+ Resolve the media files associated with the component.
+
+ ### 1. Media are resolved relative to class definition file
+
+ E.g. if in a directory `my_comp` you have `script.js` and `my_comp.py`,
+ and `my_comp.py` looks like this:
+
+ ```py
+ class MyComponent(Component):
+ class Media:
+ js = "script.js"
+ ```
+
+ Then `script.js` will be understood as relative to the component file.
+ To obtain the final path, we make it relative to a component directory (as set in `COMPONENTS.dirs`
+ and `COMPONENTS.app_dirs`; and `STATICFILES_DIRS` for JS and CSS). So if the parent directory is `components/`,
+ and the component file is inside `components/my_comp/my_comp.py`, then the final path will be relative
+ to `components/`, thus `./my_comp/script.js`.
+
+ If the relative path does not point to an actual file, the path is kept as is.
+
+ ### 2. Subclass `Media` class with `media_class`
+
+ Django's `MediaDefiningClass` creates an instance of `Media` class under the `media` attribute.
+ We do the same, but we allow to override the class that will be instantiated with `media_class` attribute:
+
+ ```py
+ class MyMedia(Media):
+ def render_js(self):
+ ...
+
+ class MyComponent(Component):
+ media_class = MyMedia
+ def get_template_data(self, args, kwargs, slots, context):
+ assert isinstance(self.media, MyMedia)
+ ```
+ """
+ if comp_media.resolved:
+ return
+
+ comp_media.resolved = True
+
+ # Do not resolve if this is a base class
+ if get_import_path(comp_cls) == "django_components.component.Component":
+ return
+
+ comp_dirs = get_component_dirs()
+
+ # Once the inputs are normalized, attempt to resolve the HTML/JS/CSS filepaths
+ # as relative to the directory where the component class is defined.
+ _resolve_component_relative_files(comp_cls, comp_media, comp_dirs=comp_dirs)
+
+ # If the component defined `template_file`, `js_file` or `css_file`, instead of `template`/`js`/`css`,
+ # we resolve them now.
+ # Effectively, even if the Component class defined `js_file` (or others), at "runtime" the `js` attribute
+ # will be set to the content of the file.
+ # So users can access `Component.js` even if they defined `Component.js_file`.
+ template_str, template_obj = _get_asset(
+ comp_cls,
+ comp_media,
+ inlined_attr="template",
+ file_attr="template_file",
+ comp_dirs=comp_dirs,
+ )
+ comp_media.template = template_str
+
+ js_str, _ = _get_asset(comp_cls, comp_media, inlined_attr="js", file_attr="js_file", comp_dirs=comp_dirs)
+ comp_media.js = js_str
+
+ css_str, _ = _get_asset(comp_cls, comp_media, inlined_attr="css", file_attr="css_file", comp_dirs=comp_dirs)
+ comp_media.css = css_str
+
+ # If `Component.template` or `Component.template_file` were explicitly set on this class,
+ # then Template instance was already created.
+ #
+ # Otherwise, search for Template instance in parent classes, and make a copy of it.
+ if not isinstance(template_obj, Unset):
+ comp_media._template = template_obj
+ else:
+ parent_template = _get_comp_cls_attr(comp_cls, "_template")
+
+ # One of base classes has set `template` or `template_file` to `None`,
+ # or none of the base classes had set `template` or `template_file`
+ if parent_template is None:
+ comp_media._template = parent_template
+
+ # One of base classes has set `template` or `template_file` to string.
+ # Make a copy of the Template instance.
+ else:
+ comp_media._template = ensure_unique_template(comp_cls, parent_template)
+
+
+def _normalize_media(media: Type[ComponentMediaInput]) -> None:
+ """
+ Resolve the `Media` class associated with the component.
+
+ We support following cases:
1. As plain strings
```py
@@ -58,32 +687,8 @@ class MediaMeta(MediaDefiningClass):
}
```
- 4. [CSS ONLY] Dicts of lists
- ```py
- class MyComponent(Component):
- class Media:
- css = {
- "all": ["path/to/style1.css"],
- "print": ["path/to/style2.css"],
- }
- ```
-
- ### 2. Media are first resolved relative to class definition file
-
- E.g. if in a directory `my_comp` you have `script.js` and `my_comp.py`,
- and `my_comp.py` looks like this:
-
- ```py
- class MyComponent(Component):
- class Media:
- js = "script.js"
- ```
-
- Then `script.js` will be resolved as `my_comp/script.js`.
-
- ### 3. Media can be defined as str, bytes, PathLike, SafeString, or function of thereof
-
- E.g.:
+ Moreover, unlike Django's Media class, here, the JS/CSS files can be defined as str, bytes, PathLike, SafeString,
+ or function of thereof. E.g.:
```py
def lazy_eval_css():
@@ -95,108 +700,62 @@ class MediaMeta(MediaDefiningClass):
js = b"script.js"
css = lazy_eval_css
```
-
- ### 4. Subclass `Media` class with `media_class`
-
- Normal `MediaDefiningClass` creates an instance of `Media` class under the `media` attribute.
- This class allows to override which class will be instantiated with `media_class` attribute:
-
- ```py
- class MyMedia(Media):
- def render_js(self):
- ...
-
- class MyComponent(Component):
- media_class = MyMedia
- def get_context_data(self):
- assert isinstance(self.media, MyMedia)
- ```
"""
-
- def __new__(mcs, name: str, bases: Tuple[Type, ...], attrs: Dict[str, Any]) -> Type:
- if "Media" in attrs:
- media_data: ComponentMediaInput = attrs["Media"]
- # Normalize the various forms of Media inputs we allow
- _normalize_media(media_data)
- # Given a predictable structure of Media class, get all the various JS/CSS paths
- # that user has defined, and normalize them too.
- #
- # Because we can accept:
- # str, bytes, PathLike, SafeData (AKA Django's "path as object") or a callable
- #
- # And we want to convert that to:
- # str and SafeData
- _map_media_filepaths(media_data, _normalize_media_filepath)
-
- # Once the inputs are normalized, attempt to resolve the JS/CSS filepaths
- # as relative to the directory where the component class is defined.
- _resolve_component_relative_files(attrs)
-
- # Since we're inheriting from `MediaDefiningClass`, it should take the inputs
- # from `cls.Media`, and set the `cls.media` to an instance of Django's `Media` class
- cls = super().__new__(mcs, name, bases, attrs)
-
- # Lastly, if the class defines `media_class` attribute, transform `cls.media`
- # to the instance of `media_class`.
- _monkeypatch_media_property(cls)
-
- return cls
-
-
-# Allow users to provide custom subclasses of Media via `media_class`.
-# `MediaDefiningClass` defines `media` as a getter (defined in django.forms.widgets.media_property).
-# So we reused that and convert it to user-defined Media class
-def _monkeypatch_media_property(comp_cls: Type["Component"]) -> None:
- if not hasattr(comp_cls, "media_class"):
- return
-
- media_prop: property = comp_cls.media
- media_getter = media_prop.fget
-
- def media_wrapper(self: "Component") -> Any:
- if not media_getter:
- return None
- media: Media = media_getter(self)
- return self.media_class(js=media._js, css=media._css)
-
- comp_cls.media = property(media_wrapper)
-
-
-def _normalize_media(media: ComponentMediaInput) -> None:
if hasattr(media, "css") and media.css:
# Allow: class Media: css = "style.css"
if _is_media_filepath(media.css):
- media.css = [media.css] # type: ignore[list-item]
+ media.css = {"all": [media.css]} # type: ignore[assignment]
# Allow: class Media: css = ["style.css"]
- if isinstance(media.css, (list, tuple)):
+ elif isinstance(media.css, (list, tuple)):
media.css = {"all": media.css}
# Allow: class Media: css = {"all": "style.css"}
- if isinstance(media.css, dict):
- for media_type, path_list in media.css.items():
- if _is_media_filepath(path_list):
- media.css[media_type] = [path_list] # type: ignore
+ # class Media: css = {"all": ["style.css"]}
+ elif isinstance(media.css, dict):
+ for media_type, path_or_list in media.css.items():
+ # {"all": "style.css"}
+ if _is_media_filepath(path_or_list):
+ media.css[media_type] = [path_or_list] # type: ignore
+ # {"all": ["style.css"]}
+ else:
+ media.css[media_type] = path_or_list # type: ignore
+ else:
+ raise ValueError(f"Media.css must be str, list, or dict, got {type(media.css)}")
if hasattr(media, "js") and media.js:
# Allow: class Media: js = "script.js"
if _is_media_filepath(media.js):
- media.js = [media.js] # type: ignore[list-item]
+ media.js = [media.js] # type: ignore
+ # Allow: class Media: js = ["script.js"]
+ else:
+ # JS is already a list, no action needed
+ pass
+
+ # Now that the Media class has a predictable shape, get all the various JS/CSS paths
+ # that user has defined, and normalize them too.
+ #
+ # Because we can accept:
+ # str, bytes, PathLike, SafeData (AKA Django's "path as object") or a callable
+ #
+ # And we want to convert that to:
+ # str and SafeData
+ _map_media_filepaths(media, _normalize_media_filepath)
-def _map_media_filepaths(media: ComponentMediaInput, map_fn: Callable[[Any], Any]) -> None:
+def _map_media_filepaths(media: Type[ComponentMediaInput], map_fn: Callable[[Sequence[Any]], Iterable[Any]]) -> None:
if hasattr(media, "css") and media.css:
if not isinstance(media.css, dict):
raise ValueError(f"Media.css must be a dict, got {type(media.css)}")
for media_type, path_list in media.css.items():
- media.css[media_type] = list(map(map_fn, path_list)) # type: ignore[assignment]
+ media.css[media_type] = list(map_fn(path_list)) # type: ignore[assignment]
if hasattr(media, "js") and media.js:
if not isinstance(media.js, (list, tuple)):
raise ValueError(f"Media.css must be a list, got {type(media.css)}")
- media.js = list(map(map_fn, media.js))
+ media.js = list(map_fn(media.js))
def _is_media_filepath(filepath: Any) -> bool:
@@ -218,133 +777,380 @@ def _is_media_filepath(filepath: Any) -> bool:
return False
-def _normalize_media_filepath(filepath: Any) -> Union[str, SafeData]:
- if callable(filepath):
- filepath = filepath()
+def _normalize_media_filepath(filepaths: Sequence[ComponentMediaInputPath]) -> List[Union[str, SafeData]]:
+ normalized: List[Union[str, SafeData]] = []
+ for filepath in filepaths:
+ if callable(filepath):
+ filepath = filepath()
- if isinstance(filepath, SafeData) or hasattr(filepath, "__html__"):
- return filepath
+ if isinstance(filepath, SafeData) or hasattr(filepath, "__html__"):
+ normalized.append(filepath)
+ continue
- if isinstance(filepath, (Path, os.PathLike)) or hasattr(filepath, "__fspath__"):
- filepath = filepath.__fspath__()
+ if isinstance(filepath, (Path, os.PathLike)) or hasattr(filepath, "__fspath__"):
+ # In case of Windows OS, convert to forward slashes
+ filepath = Path(filepath.__fspath__()).as_posix()
- if isinstance(filepath, bytes):
- filepath = filepath.decode("utf-8")
+ if isinstance(filepath, bytes):
+ filepath = filepath.decode("utf-8")
- if isinstance(filepath, str):
- return filepath
+ if isinstance(filepath, str):
+ normalized.append(filepath)
+ continue
- raise ValueError(
- "Unknown filepath. Must be str, bytes, PathLike, SafeString, or a function that returns one of the former"
- )
+ raise ValueError(
+ f"Unknown filepath {filepath} of type {type(filepath)}. Must be str, bytes, PathLike, SafeString,"
+ " or a function that returns one of the former"
+ )
+
+ return normalized
-def _resolve_component_relative_files(attrs: MutableMapping) -> None:
+def _resolve_component_relative_files(
+ comp_cls: Type["Component"], comp_media: ComponentMedia, comp_dirs: List[Path]
+) -> None:
"""
Check if component's HTML, JS and CSS files refer to files in the same directory
as the component class. If so, modify the attributes so the class Django's rendering
will pick up these files correctly.
"""
+ if comp_media.resolved_relative_files:
+ return
+
+ comp_media.resolved_relative_files = True
+
# First check if we even need to resolve anything. If the class doesn't define any
- # JS/CSS files, just skip.
+ # HTML/JS/CSS files, just skip.
will_resolve_files = False
- if attrs.get("template_name", None):
+ if is_set(comp_media.template_file) or is_set(comp_media.js_file) or is_set(comp_media.css_file):
will_resolve_files = True
- if not will_resolve_files and "Media" in attrs:
- media: ComponentMediaInput = attrs["Media"]
- if getattr(media, "css", None) or getattr(media, "js", None):
+ elif not will_resolve_files and is_set(comp_media.Media):
+ if getattr(comp_media.Media, "css", None) or getattr(comp_media.Media, "js", None):
will_resolve_files = True
if not will_resolve_files:
return
- component_name = attrs["__qualname__"]
- # Derive the full path of the file where the component was defined
- module_name = attrs["__module__"]
- module_obj = sys.modules[module_name]
- file_path = module_obj.__file__
-
- if not file_path:
+ component_name = comp_cls.__qualname__
+ # Get the full path of the file where the component was defined
+ module, module_name, module_file_path = get_module_info(comp_cls)
+ if not module_file_path:
logger.debug(
f"Could not resolve the path to the file for component '{component_name}'."
" Paths for HTML, JS or CSS templates will NOT be resolved relative to the component file."
)
return
- # Prepare all possible directories we need to check when searching for
- # component's template and media files
- components_dirs = get_dirs()
-
# Get the directory where the component class is defined
- try:
- comp_dir_abs, comp_dir_rel = _get_dir_path_from_component_path(file_path, components_dirs)
- except RuntimeError:
- # If no dir was found, we assume that the path is NOT relative to the component dir
+ matched_component_dir = _find_component_dir_containing_file(comp_dirs, module_file_path)
+
+ # If no dir was found (e.g. the component was defined at runtime), we assume that the media paths
+ # are NOT relative.
+ if matched_component_dir is None:
logger.debug(
- f"No component directory found for component '{component_name}' in {file_path}"
+ f"No component directory found for component '{component_name}' in {module_file_path}"
" If this component defines HTML, JS or CSS templates relatively to the component file,"
" then check that the component's directory is accessible from one of the paths"
- " specified in the Django's 'STATICFILES_DIRS' settings."
+ " specified in the Django's 'COMPONENTS.dirs' settings."
)
return
+ matched_component_dir_abs = os.path.abspath(matched_component_dir)
+ # Derive the path from matched `COMPONENTS.dirs` to the dir where the current component file is.
+ component_module_dir_path_abs = os.path.dirname(module_file_path)
+
# Check if filepath refers to a file that's in the same directory as the component class.
# If yes, modify the path to refer to the relative file.
# If not, don't modify anything.
- def resolve_file(filepath: Union[str, SafeData]) -> Union[str, SafeData]:
- if isinstance(filepath, str):
- maybe_resolved_filepath = os.path.join(comp_dir_abs, filepath)
- component_import_filepath = os.path.join(comp_dir_rel, filepath)
-
- if os.path.isfile(maybe_resolved_filepath):
- # NOTE: It's important to use `repr`, so we don't trigger __str__ on SafeStrings
- logger.debug(
- f"Interpreting template '{repr(filepath)}' of component '{module_name}'"
- " relatively to component file"
- )
-
- return component_import_filepath
- return filepath
-
- logger.debug(
- f"Interpreting template '{repr(filepath)}' of component '{module_name}'"
- " relatively to components directory"
+ def resolve_relative_media_file(
+ filepath: Union[str, SafeData],
+ allow_glob: bool,
+ ) -> List[Union[str, SafeData]]:
+ resolved_filepaths, has_matched = resolve_media_file(
+ filepath,
+ allow_glob,
+ static_files_dir=matched_component_dir_abs,
+ media_root_dir=component_module_dir_path_abs,
)
- return filepath
+
+ # NOTE: It's important to use `repr`, so we don't trigger __str__ on SafeStrings
+ if has_matched:
+ logger.debug(
+ f"Interpreting file '{repr(filepath)}' of component '{module_name}'" " relatively to component file"
+ )
+ else:
+ logger.debug(
+ f"Interpreting file '{repr(filepath)}' of component '{module_name}'"
+ " relatively to components directory"
+ )
+
+ return resolved_filepaths
+
+ # Check if filepath is a glob pattern that points to files relative to the components directory
+ # (as defined by `COMPONENTS.dirs` and `COMPONENTS.app_dirs` settings) in which the component is defined.
+ # If yes, modify the path to refer to the globbed files.
+ # If not, don't modify anything.
+ def resolve_static_media_file(
+ filepath: Union[str, SafeData],
+ allow_glob: bool,
+ ) -> List[Union[str, SafeData]]:
+ resolved_filepaths, _ = resolve_media_file(
+ filepath,
+ allow_glob,
+ static_files_dir=matched_component_dir_abs,
+ media_root_dir=matched_component_dir_abs,
+ )
+ return resolved_filepaths
# Check if template name is a local file or not
- if "template_name" in attrs and attrs["template_name"]:
- attrs["template_name"] = resolve_file(attrs["template_name"])
+ if is_set(comp_media.template_file):
+ comp_media.template_file = resolve_relative_media_file(comp_media.template_file, False)[0]
+ if is_set(comp_media.js_file):
+ comp_media.js_file = resolve_relative_media_file(comp_media.js_file, False)[0]
+ if is_set(comp_media.css_file):
+ comp_media.css_file = resolve_relative_media_file(comp_media.css_file, False)[0]
- if "Media" in attrs:
- media = attrs["Media"]
- _map_media_filepaths(media, resolve_file)
-
-
-def _get_dir_path_from_component_path(
- abs_component_file_path: str,
- candidate_dirs: Union[List[str], List[Path]],
-) -> Tuple[str, str]:
- comp_dir_path_abs = os.path.dirname(abs_component_file_path)
-
- # From all dirs defined in settings.STATICFILES_DIRS, find one that's the parent
- # to the component file.
- root_dir_abs = None
- for candidate_dir in candidate_dirs:
- candidate_dir_abs = os.path.abspath(candidate_dir)
- if comp_dir_path_abs.startswith(candidate_dir_abs):
- root_dir_abs = candidate_dir_abs
- break
-
- if root_dir_abs is None:
- raise RuntimeError(
- f"Failed to resolve template directory for component file '{abs_component_file_path}'",
+ if is_set(comp_media.Media):
+ _map_media_filepaths(
+ comp_media.Media,
+ # Media files can be defined as a glob patterns that match multiple files.
+ # Thus, flatten the list of lists returned by `resolve_relative_media_file`.
+ lambda filepaths: flatten(resolve_relative_media_file(f, True) for f in filepaths),
)
- # Derive the path from matched STATICFILES_DIRS to the dir where the current component file is.
- comp_dir_path_rel = os.path.relpath(comp_dir_path_abs, candidate_dir_abs)
+ # Go over the JS / CSS media files again, but this time, if there are still any globs,
+ # try to resolve them relative to the root directory (as defined by `COMPONENTS.dirs
+ # and `COMPONENTS.app_dirs` settings).
+ _map_media_filepaths(
+ comp_media.Media,
+ # Media files can be defined as a glob patterns that match multiple files.
+ # Thus, flatten the list of lists returned by `resolve_static_media_file`.
+ lambda filepaths: flatten(resolve_static_media_file(f, True) for f in filepaths),
+ )
- # Return both absolute and relative paths:
- # - Absolute path is used to check if the file exists
- # - Relative path is used for defining the import on the component class
- return comp_dir_path_abs, comp_dir_path_rel
+
+# Check if filepath refers to a file that's in the same directory as the component class.
+# If yes, modify the path to refer to the relative file.
+# If not, don't modify anything.
+def resolve_media_file(
+ filepath: Union[str, SafeData],
+ allow_glob: bool,
+ static_files_dir: str,
+ media_root_dir: str,
+) -> Tuple[List[Union[str, SafeData]], bool]:
+ # If filepath is NOT a string, then return as is
+ if not isinstance(filepath, str):
+ return [filepath], False
+
+ filepath_abs_or_glob = os.path.join(media_root_dir, filepath)
+
+ # If the path is a URL, don't resolve it
+ # (e.g. https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.0.2/chart.min.js)
+ # This is defined based on Django's `Media.absolute_path()` method.
+ is_url_path = filepath.startswith(("http://", "https://", "://", "/"))
+
+ # If the path is a URL, don't resolve it
+ if is_url_path:
+ return [filepath], False
+
+ # The path may be a glob, which we need to resolve
+ if allow_glob and is_glob(filepath_abs_or_glob):
+ # Since globs are matched against the files, then we know that these files exist.
+ matched_abs_filepaths = glob.glob(filepath_abs_or_glob)
+ else:
+ # But if we were given non-glob file path, then we need to check if it exists.
+ if Path(filepath_abs_or_glob).exists():
+ matched_abs_filepaths = [filepath_abs_or_glob]
+ else:
+ matched_abs_filepaths = []
+
+ # If there are no matches, return the original filepath
+ if not matched_abs_filepaths:
+ return [filepath], False
+
+ resolved_filepaths: List[str] = []
+ for matched_filepath_abs in matched_abs_filepaths:
+ # Derive the path from matched `COMPONENTS.dirs` to the media file.
+ # NOTE: The paths to resources need to use POSIX (forward slashes) for Django to work
+ # See https://github.com/django-components/django-components/issues/796
+ # NOTE: Since these paths matched the glob, we know that these files exist.
+ filepath_rel_to_comp_dir = Path(os.path.relpath(matched_filepath_abs, static_files_dir)).as_posix()
+ resolved_filepaths.append(filepath_rel_to_comp_dir)
+
+ return resolved_filepaths, True
+
+
+def _find_component_dir_containing_file(
+ component_dirs: Sequence[Union[str, Path]],
+ target_file_path: str,
+) -> Optional[Union[str, Path]]:
+ """
+ From all directories that may contain components (such as those defined in `COMPONENTS.dirs`),
+ find the one that's the parent to the given file.
+ """
+ abs_target_file_path = os.path.abspath(target_file_path)
+
+ for component_dir in component_dirs:
+ component_dir_abs = os.path.abspath(component_dir)
+ if abs_target_file_path.startswith(component_dir_abs):
+ return component_dir
+
+ return None
+
+
+def _get_asset(
+ comp_cls: Type["Component"],
+ comp_media: ComponentMedia,
+ inlined_attr: Literal["template", "js", "css"],
+ file_attr: Literal["template_file", "js_file", "css_file"],
+ comp_dirs: List[Path],
+) -> Tuple[Union[str, Unset, None], Union[Template, Unset, None]]: # Tuple of (content, Template)
+ """
+ In case of Component's JS or CSS, one can either define that as "inlined" or as a file.
+
+ E.g.
+ ```python
+ class MyComp(Component):
+ js = '''
+ console.log('Hello, world!');
+ '''
+ ```
+ or
+ ```python
+ class MyComp(Component):
+ js_file = "my_comp.js"
+ ```
+
+ This method resolves the content like above.
+
+ - `inlined_attr` - The attribute name for the inlined content.
+ - `file_attr` - The attribute name for the file name.
+
+ These are mutually exclusive, so only one of the two can be set at class creation.
+ """
+ asset_content = getattr(comp_media, inlined_attr, UNSET)
+ asset_file = getattr(comp_media, file_attr, UNSET)
+
+ # No inlined content, nor file name
+ # ```py
+ # class MyComp(Component):
+ # pass
+ # ```
+ if asset_content is UNSET and asset_file is UNSET:
+ return UNSET, UNSET
+
+ # Either file or content attr was set to `None`
+ # ```py
+ # class MyComp(Component):
+ # js_file = None
+ # ```
+ # or
+ # ```py
+ # class MyComp(Component):
+ # js = None
+ # ```
+ # or
+ # ```py
+ # class MyComp(Component):
+ # js = None
+ # js_file = None
+ # ```
+ if (asset_content in (UNSET, None) and asset_file is None) or (
+ asset_content is None and asset_file in (UNSET, None)
+ ):
+ return None, None
+
+ # Received both inlined content and file name
+ # ```py
+ # class MyComp(Component):
+ # js = "..."
+ # js_file = "..."
+ # ```
+ #
+ # Or received file name / content AND explicit `None`
+ # ```py
+ # class MyComp(Component):
+ # js = "..."
+ # js_file = None
+ # ```
+ # or
+ # ```py
+ # class MyComp(Component):
+ # js = None
+ # js_file = "..."
+ # ```
+ if asset_content is not UNSET and asset_file is not UNSET:
+ raise ValueError(
+ f"Received both '{inlined_attr}' and '{file_attr}' in Component {comp_cls.__qualname__}."
+ " Only one of the two must be set."
+ )
+
+ # At this point we can tell that only EITHER `asset_content` OR `asset_file` is set.
+
+ # If the content was inlined into the component (e.g. `Component.template = "..."`)
+ # then there's nothing to resolve. Use it as is.
+ if not isinstance(asset_content, Unset):
+ if asset_content is None:
+ return None, None
+
+ content: str = asset_content
+
+ # If we got inlined `Component.template`, then create a Template instance from it
+ # to trigger the extension hooks that may modify the template string.
+ if inlined_attr == "template":
+ # NOTE: `load_component_template()` applies `on_template_loaded()` and `on_template_compiled()` hooks.
+ template = load_component_template(comp_cls, filepath=None, content=content)
+ return template.source, template
+
+ # This else branch assumes that we were given a file name (possibly None)
+ # Load the contents of the file.
+ else:
+ if asset_file is None:
+ return None, None
+
+ asset_file = cast(str, asset_file)
+
+ if inlined_attr == "template":
+ # NOTE: `load_component_template()` applies `on_template_loaded()` and `on_template_compiled()` hooks.
+ template = load_component_template(comp_cls, filepath=asset_file, content=None)
+ return template.source, template
+
+ # Following code concerns with loading JS / CSS files.
+ # Here we have a few options:
+ #
+ # 1. Check if the file is in one of the components' directories
+ full_path = resolve_file(asset_file, comp_dirs)
+
+ # 2. If not, check if it's in the static files
+ if full_path is None:
+ full_path = finders.find(asset_file)
+
+ if full_path is None:
+ # NOTE: The short name, e.g. `js` or `css` is used in the error message for convenience
+ raise ValueError(f"Could not find {inlined_attr} file {asset_file}")
+
+ # NOTE: Use explicit encoding for compat with Windows, see #1074
+ content = Path(full_path).read_text(encoding="utf8")
+
+ # NOTE: `on_template_loaded()` is already applied inside `load_component_template()`
+ # but we still need to call extension hooks for JS / CSS content (whether inlined or not).
+ if inlined_attr == "js":
+ content = extensions.on_js_loaded(
+ OnJsLoadedContext(
+ component_cls=comp_cls,
+ content=content,
+ )
+ )
+ elif inlined_attr == "css":
+ content = extensions.on_css_loaded(
+ OnCssLoadedContext(
+ component_cls=comp_cls,
+ content=content,
+ )
+ )
+
+ return content, None
+
+
+def is_set(value: Union[T, Unset, None]) -> TypeGuard[T]:
+ return value is not None and value is not UNSET
diff --git a/src/django_components/component_registry.py b/src/django_components/component_registry.py
index 588e29b9..f0d902b7 100644
--- a/src/django_components/component_registry.py
+++ b/src/django_components/component_registry.py
@@ -1,22 +1,53 @@
-from typing import TYPE_CHECKING, Callable, Dict, NamedTuple, Optional, Set, Type, TypeVar, Union
+import sys
+from typing import TYPE_CHECKING, Callable, Dict, List, NamedTuple, Optional, Set, Type, TypeVar, Union
+from weakref import ReferenceType, finalize
from django.template import Library
+from django.template.base import Parser, Token
-from django_components.app_settings import ContextBehavior, app_settings
-from django_components.library import is_tag_protected, mark_protected_tags, register_tag_from_formatter
+from django_components.app_settings import ContextBehaviorType, app_settings
+from django_components.extension import (
+ OnComponentRegisteredContext,
+ OnComponentUnregisteredContext,
+ OnRegistryCreatedContext,
+ OnRegistryDeletedContext,
+ extensions,
+)
+from django_components.library import is_tag_protected, mark_protected_tags, register_tag
from django_components.tag_formatter import TagFormatterABC, get_tag_formatter
+from django_components.util.weakref import cached_ref
if TYPE_CHECKING:
from django_components.component import Component
-_TComp = TypeVar("_TComp", bound=Type["Component"])
+
+# NOTE: `ReferenceType` is NOT a generic pre-3.9
+if sys.version_info >= (3, 9):
+ AllRegistries = List[ReferenceType["ComponentRegistry"]]
+else:
+ AllRegistries = List[ReferenceType]
+
+
+TComponent = TypeVar("TComponent", bound="Component")
class AlreadyRegistered(Exception):
+ """
+ Raised when you try to register a [Component](../api#django_components#Component),
+ but it's already registered with given
+ [ComponentRegistry](../api#django_components.ComponentRegistry).
+ """
+
pass
class NotRegistered(Exception):
+ """
+ Raised when you try to access a [Component](../api#django_components#Component),
+ but it's NOT registered with given
+ [ComponentRegistry](../api#django_components.ComponentRegistry).
+ """
+
pass
@@ -35,32 +66,136 @@ class ComponentRegistryEntry(NamedTuple):
class RegistrySettings(NamedTuple):
- CONTEXT_BEHAVIOR: Optional[ContextBehavior] = None
+ """
+ Configuration for a [`ComponentRegistry`](../api#django_components.ComponentRegistry).
+
+ These settings define how the components registered with this registry will behave when rendered.
+
+ ```python
+ from django_components import ComponentRegistry, RegistrySettings
+
+ registry_settings = RegistrySettings(
+ context_behavior="django",
+ tag_formatter="django_components.component_shorthand_formatter",
+ )
+
+ registry = ComponentRegistry(settings=registry_settings)
+ ```
+ """
+
+ context_behavior: Optional[ContextBehaviorType] = None
+ """
+ Same as the global
+ [`COMPONENTS.context_behavior`](../settings#django_components.app_settings.ComponentsSettings.context_behavior)
+ setting, but for this registry.
+
+ If omitted, defaults to the global
+ [`COMPONENTS.context_behavior`](../settings#django_components.app_settings.ComponentsSettings.context_behavior)
+ setting.
+ """
+
+ # TODO_REMOVE_IN_V1
+ CONTEXT_BEHAVIOR: Optional[ContextBehaviorType] = None
+ """
+ _Deprecated. Use `context_behavior` instead. Will be removed in v1._
+
+ Same as the global
+ [`COMPONENTS.context_behavior`](../settings#django_components.app_settings.ComponentsSettings.context_behavior)
+ setting, but for this registry.
+
+ If omitted, defaults to the global
+ [`COMPONENTS.context_behavior`](../settings#django_components.app_settings.ComponentsSettings.context_behavior)
+ setting.
+ """
+
+ tag_formatter: Optional[Union["TagFormatterABC", str]] = None
+ """
+ Same as the global
+ [`COMPONENTS.tag_formatter`](../settings#django_components.app_settings.ComponentsSettings.tag_formatter)
+ setting, but for this registry.
+
+ If omitted, defaults to the global
+ [`COMPONENTS.tag_formatter`](../settings#django_components.app_settings.ComponentsSettings.tag_formatter)
+ setting.
+ """
+
+ # TODO_REMOVE_IN_V1
TAG_FORMATTER: Optional[Union["TagFormatterABC", str]] = None
+ """
+ _Deprecated. Use `tag_formatter` instead. Will be removed in v1._
+
+ Same as the global
+ [`COMPONENTS.tag_formatter`](../settings#django_components.app_settings.ComponentsSettings.tag_formatter)
+ setting, but for this registry.
+
+ If omitted, defaults to the global
+ [`COMPONENTS.tag_formatter`](../settings#django_components.app_settings.ComponentsSettings.tag_formatter)
+ setting.
+ """
class InternalRegistrySettings(NamedTuple):
- CONTEXT_BEHAVIOR: ContextBehavior
- TAG_FORMATTER: Union["TagFormatterABC", str]
+ context_behavior: ContextBehaviorType
+ tag_formatter: Union["TagFormatterABC", str]
+
+
+# We keep track of all registries that exist so that, when users want to
+# dynamically resolve component name to component class, they would be able
+# to search across all registries.
+ALL_REGISTRIES: AllRegistries = []
+
+
+def all_registries() -> List["ComponentRegistry"]:
+ """
+ Get a list of all created [`ComponentRegistry`](../api#django_components.ComponentRegistry) instances.
+ """
+ registries: List["ComponentRegistry"] = []
+ for reg_ref in ALL_REGISTRIES:
+ reg = reg_ref()
+ if reg is not None:
+ registries.append(reg)
+ return registries
class ComponentRegistry:
"""
- Manages which components can be used in the template tags.
+ Manages [components](../api#django_components.Component) and makes them available
+ in the template, by default as [`{% component %}`](../template_tags#component)
+ tags.
- Each ComponentRegistry instance is associated with an instance
- of Django's Library. So when you register or unregister a component
- to/from a component registry, behind the scenes the registry
- automatically adds/removes the component's template tag to/from
- the Library.
+ ```django
+ {% component "my_comp" key=value %}
+ {% endcomponent %}
+ ```
- The Library instance can be set at instantiation. If omitted, then
- the default Library instance from django_components is used. The
- Library instance can be accessed under `library` attribute.
+ To enable a component to be used in a template, the component must be registered with a component registry.
- Example:
+ When you register a component to a registry, behind the scenes the registry
+ automatically adds the component's template tag (e.g. `{% component %}` to
+ the [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#code-layout).
+ And the opposite happens when you unregister a component - the tag is removed.
- ```py
+ See [Registering components](../../concepts/advanced/component_registry).
+
+ Args:
+ library (Library, optional): Django\
+ [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#code-layout)\
+ associated with this registry. If omitted, the default Library instance from django_components is used.
+ settings (Union[RegistrySettings, Callable[[ComponentRegistry], RegistrySettings]], optional): Configure\
+ how the components registered with this registry will behave when rendered.\
+ See [`RegistrySettings`](../api#django_components.RegistrySettings). Can be either\
+ a static value or a callable that returns the settings. If omitted, the settings from\
+ [`COMPONENTS`](../settings#django_components.app_settings.ComponentsSettings) are used.
+
+ **Notes:**
+
+ - The default registry is available as [`django_components.registry`](../api#django_components.registry).
+ - The default registry is used when registering components with [`@register`](../api#django_components.register)
+ decorator.
+
+ **Example:**
+
+ ```python
# Use with default Library
registry = ComponentRegistry()
@@ -73,8 +208,36 @@ class ComponentRegistry:
registry.register("card", CardComponent)
registry.all()
registry.clear()
- registry.get()
+ registry.get("button")
+ registry.has("button")
```
+
+ # Using registry to share components
+
+ You can use component registry for isolating or "packaging" components:
+
+ 1. Create new instance of `ComponentRegistry` and Library:
+ ```django
+ my_comps = Library()
+ my_comps_reg = ComponentRegistry(library=my_comps)
+ ```
+
+ 2. Register components to the registry:
+ ```django
+ my_comps_reg.register("my_button", ButtonComponent)
+ my_comps_reg.register("my_card", CardComponent)
+ ```
+
+ 3. In your target project, load the Library associated with the registry:
+ ```django
+ {% load my_comps %}
+ ```
+
+ 4. Use the registered components in your templates:
+ ```django
+ {% component "button" %}
+ {% endcomponent %}
+ ```
"""
def __init__(
@@ -85,13 +248,41 @@ class ComponentRegistry:
self._registry: Dict[str, ComponentRegistryEntry] = {} # component name -> component_entry mapping
self._tags: Dict[str, Set[str]] = {} # tag -> list[component names]
self._library = library
- self._settings_input = settings
- self._settings: Optional[Callable[[], InternalRegistrySettings]] = None
+ self._settings = settings
+
+ ALL_REGISTRIES.append(cached_ref(self))
+
+ extensions.on_registry_created(
+ OnRegistryCreatedContext(
+ registry=self,
+ )
+ )
+
+ def __del__(self) -> None:
+ # Skip if `extensions` was deleted before this registry
+ if not extensions:
+ return
+
+ extensions.on_registry_deleted(
+ OnRegistryDeletedContext(
+ registry=self,
+ )
+ )
+
+ # Unregister all components when the registry is deleted
+ self.clear()
+
+ def __copy__(self) -> "ComponentRegistry":
+ new_registry = ComponentRegistry(self.library, self._settings)
+ new_registry._registry = self._registry.copy()
+ new_registry._tags = self._tags.copy()
+ return new_registry
@property
def library(self) -> Library:
"""
- The template tag library with which the component registry is associated.
+ The template tag [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#code-layout)
+ that is associated with the registry.
"""
# Lazily use the default library if none was passed
if self._library is not None:
@@ -110,55 +301,56 @@ class ComponentRegistry:
@property
def settings(self) -> InternalRegistrySettings:
- # This is run on subsequent calls
- if self._settings is not None:
- # NOTE: Registry's settings can be a function, so we always take
- # the latest value from Django's settings.
- settings = self._settings()
-
- # First-time initialization
+ """
+ [Registry settings](../api#django_components.RegistrySettings) configured for this registry.
+ """
# NOTE: We allow the settings to be given as a getter function
# so the settings can respond to changes.
- # So we wrapp that in our getter, which assigns default values from the settings.
+ if callable(self._settings):
+ settings_input: Optional[RegistrySettings] = self._settings(self)
else:
+ settings_input = self._settings
- def get_settings() -> InternalRegistrySettings:
- if callable(self._settings_input):
- settings_input: Optional[RegistrySettings] = self._settings_input(self)
- else:
- settings_input = self._settings_input
+ if settings_input:
+ context_behavior = settings_input.context_behavior or settings_input.CONTEXT_BEHAVIOR
+ tag_formatter = settings_input.tag_formatter or settings_input.TAG_FORMATTER
+ else:
+ context_behavior = None
+ tag_formatter = None
- return InternalRegistrySettings(
- CONTEXT_BEHAVIOR=(settings_input and settings_input.CONTEXT_BEHAVIOR)
- or app_settings.CONTEXT_BEHAVIOR,
- TAG_FORMATTER=(settings_input and settings_input.TAG_FORMATTER) or app_settings.TAG_FORMATTER,
- )
-
- self._settings = get_settings
- settings = self._settings()
-
- return settings
+ return InternalRegistrySettings(
+ context_behavior=context_behavior or app_settings.CONTEXT_BEHAVIOR.value,
+ tag_formatter=tag_formatter or app_settings.TAG_FORMATTER,
+ )
def register(self, name: str, component: Type["Component"]) -> None:
"""
- Register a component with this registry under the given name.
+ Register a [`Component`](../api#django_components.Component) class
+ with this registry under the given name.
A component MUST be registered before it can be used in a template such as:
```django
- {% component "my_comp" %}{% endcomponent %}
+ {% component "my_comp" %}
+ {% endcomponent %}
```
- Raises `AlreadyRegistered` if a different component was already registered
- under the same name.
+ Args:
+ name (str): The name under which the component will be registered. Required.
+ component (Type[Component]): The component class to register. Required.
- Example:
+ **Raises:**
- ```py
+ - [`AlreadyRegistered`](../exceptions#django_components.AlreadyRegistered)
+ if a different component was already registered under the same name.
+
+ **Example:**
+
+ ```python
registry.register("button", ButtonComponent)
```
"""
existing_component = self._registry.get(name)
- if existing_component and existing_component.cls._class_hash != component._class_hash:
+ if existing_component and existing_component.cls.class_id != component.class_id:
raise AlreadyRegistered('The component "%s" has already been registered' % name)
entry = self._register_to_library(name, component)
@@ -172,21 +364,35 @@ class ComponentRegistry:
self._registry[name] = entry
+ # If the component class is deleted, unregister it from this registry.
+ finalize(entry.cls, lambda: self.unregister(name) if name in self._registry else None)
+
+ extensions.on_component_registered(
+ OnComponentRegisteredContext(
+ registry=self,
+ name=name,
+ component_cls=entry.cls,
+ )
+ )
+
def unregister(self, name: str) -> None:
"""
- Unlinks a previously-registered component from the registry under the given name.
+ Unregister the [`Component`](../api#django_components.Component) class
+ that was registered under the given name.
- Once a component is unregistered, it CANNOT be used in a template anymore.
- Following would raise an error:
- ```django
- {% component "my_comp" %}{% endcomponent %}
- ```
+ Once a component is unregistered, it is no longer available in the templates.
- Raises `NotRegistered` if the given name is not registered.
+ Args:
+ name (str): The name under which the component is registered. Required.
- Example:
+ **Raises:**
- ```py
+ - [`NotRegistered`](../exceptions#django_components.NotRegistered)
+ if the given name is not registered.
+
+ **Example:**
+
+ ```python
# First register component
registry.register("button", ButtonComponent)
# Then unregister
@@ -199,33 +405,56 @@ class ComponentRegistry:
entry = self._registry[name]
tag = entry.tag
- # Unregister the tag from library if this was the last component using this tag
- # Unlink component from tag
- self._tags[tag].remove(name)
+ # Unregister the tag from library.
+ # If this was the last component using this tag, unlink component from tag.
+ if tag in self._tags:
+ if name in self._tags[tag]:
+ self._tags[tag].remove(name)
- # Cleanup
- is_tag_empty = not len(self._tags[tag])
- if is_tag_empty:
- del self._tags[tag]
+ # Cleanup
+ is_tag_empty = not len(self._tags[tag])
+ if is_tag_empty:
+ self._tags.pop(tag, None)
+ else:
+ is_tag_empty = True
# Only unregister a tag if it's NOT protected
is_protected = is_tag_protected(self.library, tag)
if not is_protected:
# Unregister the tag from library if this was the last component using this tag
if is_tag_empty and tag in self.library.tags:
- del self.library.tags[tag]
+ self.library.tags.pop(tag, None)
+ entry = self._registry[name]
del self._registry[name]
+ extensions.on_component_unregistered(
+ OnComponentUnregisteredContext(
+ registry=self,
+ name=name,
+ component_cls=entry.cls,
+ )
+ )
+
def get(self, name: str) -> Type["Component"]:
"""
- Retrieve a component class registered under the given name.
+ Retrieve a [`Component`](../api#django_components.Component)
+ class registered under the given name.
- Raises `NotRegistered` if the given name is not registered.
+ Args:
+ name (str): The name under which the component was registered. Required.
- Example:
+ Returns:
+ Type[Component]: The component class registered under the given name.
- ```py
+ **Raises:**
+
+ - [`NotRegistered`](../exceptions#django_components.NotRegistered)
+ if the given name is not registered.
+
+ **Example:**
+
+ ```python
# First register component
registry.register("button", ButtonComponent)
# Then get
@@ -238,13 +467,39 @@ class ComponentRegistry:
return self._registry[name].cls
+ def has(self, name: str) -> bool:
+ """
+ Check if a [`Component`](../api#django_components.Component)
+ class is registered under the given name.
+
+ Args:
+ name (str): The name under which the component was registered. Required.
+
+ Returns:
+ bool: `True` if the component is registered, `False` otherwise.
+
+ **Example:**
+
+ ```python
+ # First register component
+ registry.register("button", ButtonComponent)
+ # Then check
+ registry.has("button")
+ # > True
+ ```
+ """
+ return name in self._registry
+
def all(self) -> Dict[str, Type["Component"]]:
"""
- Retrieve all registered component classes.
+ Retrieve all registered [`Component`](../api#django_components.Component) classes.
- Example:
+ Returns:
+ Dict[str, Type[Component]]: A dictionary of component names to component classes
- ```py
+ **Example:**
+
+ ```python
# First register components
registry.register("button", ButtonComponent)
registry.register("card", CardComponent)
@@ -265,7 +520,7 @@ class ComponentRegistry:
Example:
- ```py
+ ```python
# First register components
registry.register("button", ButtonComponent)
registry.register("card", CardComponent)
@@ -289,30 +544,66 @@ class ComponentRegistry:
component: Type["Component"],
) -> ComponentRegistryEntry:
# Lazily import to avoid circular dependencies
- from django_components.templatetags.component_tags import component as do_component
+ from django_components.component import ComponentNode
- formatter = get_tag_formatter(self)
- tag = register_tag_from_formatter(self, do_component, formatter, comp_name)
+ registry = self
- return ComponentRegistryEntry(cls=component, tag=tag)
+ # Define a tag function that pre-processes the tokens, extracting
+ # the component name and passing the rest to the actual tag function.
+ def tag_fn(parser: Parser, token: Token) -> ComponentNode:
+ # Let the TagFormatter pre-process the tokens
+ bits = token.split_contents()
+ formatter = get_tag_formatter(registry)
+ result = formatter.parse([*bits])
+ start_tag = formatter.start_tag(result.component_name)
+ end_tag = formatter.end_tag(result.component_name)
+
+ # NOTE: The tokens returned from TagFormatter.parse do NOT include the tag itself,
+ # so we add it back in.
+ bits = [bits[0], *result.tokens]
+ token.contents = " ".join(bits)
+
+ return ComponentNode.parse(
+ parser,
+ token,
+ registry=registry,
+ name=result.component_name,
+ start_tag=start_tag,
+ end_tag=end_tag,
+ )
+
+ formatter = get_tag_formatter(registry)
+ start_tag = formatter.start_tag(comp_name)
+ register_tag(self.library, start_tag, tag_fn)
+
+ return ComponentRegistryEntry(cls=component, tag=start_tag)
# This variable represents the global component registry
registry: ComponentRegistry = ComponentRegistry()
"""
-The default and global component registry. Use this instance to directly
-register or remove components:
+The default and global [component registry](./#django_components.ComponentRegistry).
+Use this instance to directly register or remove components:
-```py
+See [Registering components](../../concepts/advanced/component_registry).
+
+```python
# Register components
registry.register("button", ButtonComponent)
registry.register("card", CardComponent)
+
# Get single
registry.get("button")
+
# Get all
registry.all()
+
+# Check if component is registered
+registry.has("button")
+
# Unregister single
registry.unregister("button")
+
# Unregister all
registry.clear()
```
@@ -322,23 +613,43 @@ registry.clear()
_the_registry = registry
-def register(name: str, registry: Optional[ComponentRegistry] = None) -> Callable[[_TComp], _TComp]:
+def register(name: str, registry: Optional[ComponentRegistry] = None) -> Callable[
+ [Type[TComponent]],
+ Type[TComponent],
+]:
"""
- Class decorator to register a component.
+ Class decorator for registering a [component](./#django_components.Component)
+ to a [component registry](./#django_components.ComponentRegistry).
- Usage:
+ See [Registering components](../../concepts/advanced/component_registry).
+
+ Args:
+ name (str): Registered name. This is the name by which the component will be accessed\
+ from within a template when using the [`{% component %}`](../template_tags#component) tag. Required.
+ registry (ComponentRegistry, optional): Specify the [registry](./#django_components.ComponentRegistry)\
+ to which to register this component. If omitted, component is registered to the default registry.
+
+ Raises:
+ AlreadyRegistered: If there is already a component registered under the same name.
+
+ **Examples**:
+
+ ```python
+ from django_components import Component, register
- ```py
@register("my_component")
class MyComponent(Component):
...
```
- Optionally specify which `ComponentRegistry` the component should be registered to by
- setting the `registry` kwarg:
+ Specifing [`ComponentRegistry`](./#django_components.ComponentRegistry) the component
+ should be registered to by setting the `registry` kwarg:
- ```py
- my_lib = django.template.Library()
+ ```python
+ from django.template import Library
+ from django_components import Component, ComponentRegistry, register
+
+ my_lib = Library()
my_reg = ComponentRegistry(library=my_lib)
@register("my_component", registry=my_reg)
@@ -349,7 +660,7 @@ def register(name: str, registry: Optional[ComponentRegistry] = None) -> Callabl
if registry is None:
registry = _the_registry
- def decorator(component: _TComp) -> _TComp:
+ def decorator(component: Type[TComponent]) -> Type[TComponent]:
registry.register(name=name, component=component)
return component
diff --git a/src/django_components/components/__init__.py b/src/django_components/components/__init__.py
new file mode 100644
index 00000000..941cbf34
--- /dev/null
+++ b/src/django_components/components/__init__.py
@@ -0,0 +1,4 @@
+# NOTE: Components exported here are documented in the API reference
+from django_components.components.dynamic import DynamicComponent
+
+__all__ = ["DynamicComponent"]
diff --git a/src/django_components/components/dynamic.py b/src/django_components/components/dynamic.py
new file mode 100644
index 00000000..70b9e32f
--- /dev/null
+++ b/src/django_components/components/dynamic.py
@@ -0,0 +1,171 @@
+import inspect
+from typing import Any, Optional, Type, Union, cast
+
+from django.template import Context, Template
+
+from django_components import Component, ComponentRegistry, NotRegistered
+from django_components.component_registry import ALL_REGISTRIES
+
+
+class DynamicComponent(Component):
+ """
+ This component is given a registered name or a reference to another component,
+ and behaves as if the other component was in its place.
+
+ The args, kwargs, and slot fills are all passed down to the underlying component.
+
+ Args:
+ is (str | Type[Component]): Component that should be rendered. Either a registered name of a component,
+ or a [Component](../api#django_components.Component) class directly. Required.
+ registry (ComponentRegistry, optional): Specify the [registry](../api#django_components.ComponentRegistry)\
+ to search for the registered name. If omitted, all registries are searched until the first match.
+ *args: Additional data passed to the component.
+ **kwargs: Additional data passed to the component.
+
+ **Slots:**
+
+ * Any slots, depending on the actual component.
+
+ **Examples:**
+
+ Django
+ ```django
+ {% component "dynamic" is=table_comp data=table_data headers=table_headers %}
+ {% fill "pagination" %}
+ {% component "pagination" / %}
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+ Or in case you use the `django_components.component_shorthand_formatter` tag formatter:
+
+ ```django
+ {% dynamic is=table_comp data=table_data headers=table_headers %}
+ {% fill "pagination" %}
+ {% component "pagination" / %}
+ {% endfill %}
+ {% enddynamic %}
+ ```
+
+ Python
+ ```py
+ from django_components import DynamicComponent
+
+ DynamicComponent.render(
+ kwargs={
+ "is": table_comp,
+ "data": table_data,
+ "headers": table_headers,
+ },
+ slots={
+ "pagination": PaginationComponent.render(
+ deps_strategy="ignore",
+ ),
+ },
+ )
+ ```
+
+ ## Use cases
+
+ Dynamic components are suitable if you are writing something like a form component. You may design
+ it such that users give you a list of input types, and you render components depending on the input types.
+
+ While you could handle this with a series of if / else statements, that's not an extensible approach.
+ Instead, you can use the dynamic component in place of normal components.
+
+ ## Component name
+
+ By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict,
+ you can set the
+ [`COMPONENTS.dynamic_component_name`](../settings#django_components.app_settings.ComponentsSettings.dynamic_component_name)
+ setting to change the name used for the dynamic components.
+
+ ```py
+ # settings.py
+ COMPONENTS = ComponentsSettings(
+ dynamic_component_name="my_dynamic",
+ )
+ ```
+
+ After which you will be able to use the dynamic component with the new name:
+ ```django
+ {% component "my_dynamic" is=table_comp data=table_data headers=table_headers %}
+ {% fill "pagination" %}
+ {% component "pagination" / %}
+ {% endfill %}
+ {% endcomponent %}
+ ```
+ """
+
+ _is_dynamic_component = True
+
+ # NOTE: The inner component is rendered in `on_render`, so that the `Context` object
+ # is already configured as if the inner component was rendered inside the template.
+ # E.g. the `_COMPONENT_CONTEXT_KEY` is set, which means that the child component
+ # will know that it's a child of this component.
+ def on_render(
+ self,
+ context: Context,
+ template: Optional[Template],
+ ) -> str:
+ # Make a copy of kwargs so we pass to the child only the kwargs that are
+ # actually used by the child component.
+ cleared_kwargs = self.raw_kwargs.copy()
+
+ registry: Optional[ComponentRegistry] = cleared_kwargs.pop("registry", None)
+ comp_name_or_class: Union[str, Type[Component]] = cleared_kwargs.pop("is", None)
+ if not comp_name_or_class:
+ raise TypeError(f"Component '{self.name}' is missing a required argument 'is'")
+
+ # Resolve the component class
+ comp_class = self._resolve_component(comp_name_or_class, registry)
+
+ output = comp_class.render(
+ context=self.context,
+ args=self.raw_args,
+ kwargs=cleared_kwargs,
+ slots=self.raw_slots,
+ deps_strategy=self.deps_strategy,
+ registered_name=self.registered_name,
+ outer_context=self.outer_context,
+ registry=self.registry,
+ )
+ return output
+
+ def _resolve_component(
+ self,
+ comp_name_or_class: Union[str, Type[Component], Any],
+ registry: Optional[ComponentRegistry] = None,
+ ) -> Type[Component]:
+ component_cls: Optional[Type[Component]] = None
+
+ if not isinstance(comp_name_or_class, str):
+ # NOTE: When Django template is resolving the variable that refers to the
+ # component class, it may see that it's callable and evaluate it. Hence, we need
+ # get check if we've got class or instance.
+ if inspect.isclass(comp_name_or_class):
+ component_cls = comp_name_or_class
+ else:
+ component_cls = cast(Type[Component], comp_name_or_class.__class__)
+
+ else:
+ if registry:
+ component_cls = registry.get(comp_name_or_class)
+ else:
+ # Search all registries for the first match
+ for reg_ref in ALL_REGISTRIES:
+ reg = reg_ref()
+ if not reg:
+ continue
+
+ try:
+ component_cls = reg.get(comp_name_or_class)
+ break
+ except NotRegistered:
+ continue
+
+ # Raise if none found
+ if not component_cls:
+ raise NotRegistered(f"The component '{comp_name_or_class}' was not found")
+
+ return component_cls
diff --git a/src/django_components/constants.py b/src/django_components/constants.py
new file mode 100644
index 00000000..498464d6
--- /dev/null
+++ b/src/django_components/constants.py
@@ -0,0 +1,3 @@
+UID_LENGTH = 6
+COMP_ID_PREFIX = "c"
+COMP_ID_LENGTH = len(COMP_ID_PREFIX) + UID_LENGTH
diff --git a/src/django_components/context.py b/src/django_components/context.py
index 4e5fb033..71cb0c61 100644
--- a/src/django_components/context.py
+++ b/src/django_components/context.py
@@ -2,46 +2,31 @@
This file centralizes various ways we use Django's Context class
pass data across components, nodes, slots, and contexts.
-You can think of the Context as our storage system.
+Compared to `django_components/util/context.py`, this file contains the "business" logic
+and the list of all internal keys that we define on the `Context` object.
"""
-from collections import namedtuple
-from typing import Any, Dict, Optional
+from django.template import Context
-from django.template import Context, TemplateSyntaxError
+from django_components.util.misc import get_last_index
-from django_components.utils import find_last_index
-
-_FILLED_SLOTS_CONTENT_CONTEXT_KEY = "_DJANGO_COMPONENTS_FILLED_SLOTS"
-_ROOT_CTX_CONTEXT_KEY = "_DJANGO_COMPONENTS_ROOT_CTX"
-_REGISTRY_CONTEXT_KEY = "_DJANGO_COMPONENTS_REGISTRY"
-_PARENT_COMP_CONTEXT_KEY = "_DJANGO_COMPONENTS_PARENT_COMP"
-_CURRENT_COMP_CONTEXT_KEY = "_DJANGO_COMPONENTS_CURRENT_COMP"
-_INJECT_CONTEXT_KEY_PREFIX = "_DJANGO_COMPONENTS_INJECT__"
-
-
-def prepare_context(
- context: Context,
- component_id: str,
-) -> None:
- """Initialize the internal context state."""
- # Initialize mapping dicts within this rendering run.
- # This is shared across the whole render chain, thus we set it only once.
- if _FILLED_SLOTS_CONTENT_CONTEXT_KEY not in context:
- context[_FILLED_SLOTS_CONTENT_CONTEXT_KEY] = {}
-
- set_component_id(context, component_id)
+_COMPONENT_CONTEXT_KEY = "_DJC_COMPONENT_CTX"
+COMPONENT_IS_NESTED_KEY = "_DJC_COMPONENT_IS_NESTED"
+_STRATEGY_CONTEXT_KEY = "DJC_DEPS_STRATEGY"
+_INJECT_CONTEXT_KEY_PREFIX = "_DJC_INJECT__"
def make_isolated_context_copy(context: Context) -> Context:
context_copy = context.new()
- copy_forloop_context(context, context_copy)
+ _copy_forloop_context(context, context_copy)
+
+ # Required for compatibility with Django's {% extends %} tag
+ # See https://github.com/django-components/django-components/pull/859
+ context_copy.render_context = context.render_context
# Pass through our internal keys
- context_copy[_FILLED_SLOTS_CONTENT_CONTEXT_KEY] = context.get(_FILLED_SLOTS_CONTENT_CONTEXT_KEY, {})
- context_copy[_REGISTRY_CONTEXT_KEY] = context.get(_REGISTRY_CONTEXT_KEY, None)
- if _ROOT_CTX_CONTEXT_KEY in context:
- context_copy[_ROOT_CTX_CONTEXT_KEY] = context[_ROOT_CTX_CONTEXT_KEY]
+ if _COMPONENT_CONTEXT_KEY in context:
+ context_copy[_COMPONENT_CONTEXT_KEY] = context[_COMPONENT_CONTEXT_KEY]
# Make inject/provide to work in isolated mode
context_keys = context.flatten().keys()
@@ -52,87 +37,14 @@ def make_isolated_context_copy(context: Context) -> Context:
return context_copy
-def set_component_id(context: Context, component_id: str) -> None:
- """
- We use the Context object to pass down info on inside of which component
- we are currently rendering.
- """
- # Store the previous component so we can detect if the current component
- # is the top-most or not. If it is, then "_parent_component_id" is None
- context[_PARENT_COMP_CONTEXT_KEY] = context.get(_CURRENT_COMP_CONTEXT_KEY, None)
- context[_CURRENT_COMP_CONTEXT_KEY] = component_id
-
-
-def copy_forloop_context(from_context: Context, to_context: Context) -> None:
+def _copy_forloop_context(from_context: Context, to_context: Context) -> None:
"""Forward the info about the current loop"""
- # Note that the ForNode (which implements for loop behavior) does not
+ # Note that the ForNode (which implements `{% for %}`) does not
# only add the `forloop` key, but also keys corresponding to the loop elements
# So if the loop syntax is `{% for my_val in my_lists %}`, then ForNode also
# sets a `my_val` key.
# For this reason, instead of copying individual keys, we copy the whole stack layer
# set by ForNode.
if "forloop" in from_context:
- forloop_dict_index = find_last_index(from_context.dicts, lambda d: "forloop" in d)
+ forloop_dict_index = get_last_index(from_context.dicts, lambda d: "forloop" in d) or -1
to_context.update(from_context.dicts[forloop_dict_index])
-
-
-def get_injected_context_var(
- component_name: str,
- context: Context,
- key: str,
- default: Optional[Any] = None,
-) -> Any:
- """
- Retrieve a 'provided' field. The field MUST have been previously 'provided'
- by the component's ancestors using the `{% provide %}` template tag.
- """
- # NOTE: For simplicity, we keep the provided values directly on the context.
- # This plays nicely with Django's Context, which behaves like a stack, so "newer"
- # values overshadow the "older" ones.
- internal_key = _INJECT_CONTEXT_KEY_PREFIX + key
-
- # Return provided value if found
- if internal_key in context:
- return context[internal_key]
-
- # If a default was given, return that
- if default is not None:
- return default
-
- # Otherwise raise error
- raise KeyError(
- f"Component '{component_name}' tried to inject a variable '{key}' before it was provided."
- f" To fix this, make sure that at least one ancestor of component '{component_name}' has"
- f" the variable '{key}' in their 'provide' attribute."
- )
-
-
-def set_provided_context_var(
- context: Context,
- key: str,
- provided_kwargs: Dict[str, Any],
-) -> None:
- """
- 'Provide' given data under given key. In other words, this data can be retrieved
- using `self.inject(key)` inside of `get_context_data()` method of components that
- are nested inside the `{% provide %}` tag.
- """
- # NOTE: We raise TemplateSyntaxError since this func should be called only from
- # within template.
- if not key:
- raise TemplateSyntaxError(
- "Provide tag received an empty string. Key must be non-empty and a valid identifier."
- )
- if not key.isidentifier():
- raise TemplateSyntaxError(
- "Provide tag received a non-identifier string. Key must be non-empty and a valid identifier."
- )
-
- # We turn the kwargs into a NamedTuple so that the object that's "provided"
- # is immutable. This ensures that the data returned from `inject` will always
- # have all the keys that were passed to the `provide` tag.
- tpl_cls = namedtuple("DepInject", provided_kwargs.keys()) # type: ignore[misc]
- payload = tpl_cls(**provided_kwargs)
-
- internal_key = _INJECT_CONTEXT_KEY_PREFIX + key
- context[internal_key] = payload
diff --git a/src/django_components/dependencies.py b/src/django_components/dependencies.py
new file mode 100644
index 00000000..4f4a8830
--- /dev/null
+++ b/src/django_components/dependencies.py
@@ -0,0 +1,1058 @@
+"""All code related to management of component dependencies (JS and CSS scripts)"""
+
+import base64
+import json
+import re
+from hashlib import md5
+from typing import (
+ TYPE_CHECKING,
+ Dict,
+ List,
+ Literal,
+ Mapping,
+ Optional,
+ Sequence,
+ Set,
+ Tuple,
+ Type,
+ TypeVar,
+ Union,
+ cast,
+)
+
+from django.forms import Media
+from django.http import HttpRequest, HttpResponse, HttpResponseNotAllowed, HttpResponseNotFound
+from django.template import Context, TemplateSyntaxError
+from django.templatetags.static import static
+from django.urls import path, reverse
+from django.utils.safestring import SafeString, mark_safe
+from djc_core_html_parser import set_html_attributes
+
+from django_components.cache import get_component_media_cache
+from django_components.constants import COMP_ID_LENGTH
+from django_components.node import BaseNode
+from django_components.util.misc import is_nonempty_str
+
+if TYPE_CHECKING:
+ from django_components.component import Component
+
+
+ScriptType = Literal["css", "js"]
+DependenciesStrategy = Literal["document", "fragment", "simple", "prepend", "append", "ignore"]
+"""
+Type for the available strategies for rendering JS and CSS dependencies.
+
+Read more about the [dependencies strategies](../../concepts/advanced/rendering_js_css).
+"""
+
+DEPS_STRATEGIES = ("document", "fragment", "simple", "prepend", "append", "ignore")
+
+
+#########################################################
+# 1. Cache the inlined component JS and CSS scripts (`Component.js` and `Component.css`).
+#
+# To support HTML fragments, when a fragment is loaded on a page,
+# we on-demand request the JS and CSS files of the components that are
+# referenced in the fragment.
+#
+# Thus, we need to persist the JS and CSS files across requests. These are then accessed
+# via `cached_script_view` endpoint.
+#########################################################
+
+
+# Generate keys like
+# `__components:MyButton_a78y37:js:df7c6d10`
+# `__components:MyButton_a78y37:css`
+def _gen_cache_key(
+ comp_cls_id: str,
+ script_type: ScriptType,
+ input_hash: Optional[str],
+) -> str:
+ if input_hash:
+ return f"__components:{comp_cls_id}:{script_type}:{input_hash}"
+ else:
+ return f"__components:{comp_cls_id}:{script_type}"
+
+
+def _is_script_in_cache(
+ comp_cls: Type["Component"],
+ script_type: ScriptType,
+ input_hash: Optional[str],
+) -> bool:
+ cache_key = _gen_cache_key(comp_cls.class_id, script_type, input_hash)
+ cache = get_component_media_cache()
+ return cache.has_key(cache_key)
+
+
+def _cache_script(
+ comp_cls: Type["Component"],
+ script: str,
+ script_type: ScriptType,
+ input_hash: Optional[str],
+) -> None:
+ """
+ Given a component and it's inlined JS or CSS, store the JS/CSS in a cache,
+ so it can be retrieved via URL endpoint.
+ """
+
+ # E.g. `__components:MyButton:js:df7c6d10`
+ if script_type in ("js", "css"):
+ cache_key = _gen_cache_key(comp_cls.class_id, script_type, input_hash)
+ else:
+ raise ValueError(f"Unexpected script_type '{script_type}'")
+
+ # NOTE: By setting the script in the cache, we will be able to retrieve it
+ # via the endpoint, e.g. when we make a request to `/components/cache/MyComp_ab0c2d.js`.
+ cache = get_component_media_cache()
+ cache.set(cache_key, script.strip())
+
+
+def cache_component_js(comp_cls: Type["Component"], force: bool) -> None:
+ """
+ Cache the content from `Component.js`. This is the common JS that's shared
+ among all instances of the same component. So even if the component is rendered multiple
+ times, this JS is loaded only once.
+ """
+ if not comp_cls.js or not is_nonempty_str(comp_cls.js):
+ return None
+
+ if not force and _is_script_in_cache(comp_cls, "js", None):
+ return None
+
+ _cache_script(
+ comp_cls=comp_cls,
+ script=comp_cls.js,
+ script_type="js",
+ input_hash=None,
+ )
+
+
+# NOTE: In CSS, we link the CSS vars to the component via a stylesheet that defines
+# the CSS vars under `[data-djc-css-a1b2c3]`. Because of this we define the variables
+# separately from the rest of the CSS definition.
+#
+# We use conceptually similar approach for JS, except in JS we have to manually associate
+# the JS variables ("stylesheet") with the target HTML element ("component").
+#
+# It involves 3 steps:
+# 1. Register the common logic (equivalent to registering common CSS).
+# with `Components.manager.registerComponent`.
+# 2. Register the unique set of JS variables (equivalent to defining CSS vars)
+# with `Components.manager.registerComponentData`.
+# 3. Actually run a component's JS instance with `Components.manager.callComponent`,
+# specifying the components HTML elements with `component_id`, and JS vars with `input_hash`.
+def cache_component_js_vars(comp_cls: Type["Component"], js_vars: Mapping) -> Optional[str]:
+ if not is_nonempty_str(comp_cls.js):
+ return None
+
+ # The hash for the file that holds the JS variables is derived from the variables themselves.
+ json_data = json.dumps(js_vars)
+ input_hash = md5(json_data.encode()).hexdigest()[0:6]
+
+ # Generate and cache a JS script that contains the JS variables.
+ if not _is_script_in_cache(comp_cls, "js", input_hash):
+ _cache_script(
+ comp_cls=comp_cls,
+ script="", # TODO - enable JS and CSS vars
+ script_type="js",
+ input_hash=input_hash,
+ )
+
+ return input_hash
+
+
+def wrap_component_js(comp_cls: Type["Component"], content: str) -> str:
+ if "' end tag. "
+ "This is not allowed, as it would break the HTML."
+ )
+ return f""
+
+
+def cache_component_css(comp_cls: Type["Component"], force: bool) -> None:
+ """
+ Cache the content from `Component.css`. This is the common CSS that's shared
+ among all instances of the same component. So even if the component is rendered multiple
+ times, this CSS is loaded only once.
+ """
+ if not comp_cls.css or not is_nonempty_str(comp_cls.css):
+ return None
+
+ if not force and _is_script_in_cache(comp_cls, "css", None):
+ return None
+
+ _cache_script(
+ comp_cls=comp_cls,
+ script=comp_cls.css,
+ script_type="css",
+ input_hash=None,
+ )
+
+
+# NOTE: In CSS, we link the CSS vars to the component via a stylesheet that defines
+# the CSS vars under the CSS selector `[data-djc-css-a1b2c3]`. We define the stylesheet
+# with variables separately from `Component.css`, because different instances may return different
+# data from `get_css_data()`, which will live in different stylesheets.
+def cache_component_css_vars(comp_cls: Type["Component"], css_vars: Mapping) -> Optional[str]:
+ if not is_nonempty_str(comp_cls.css):
+ return None
+
+ # The hash for the file that holds the CSS variables is derived from the variables themselves.
+ json_data = json.dumps(css_vars)
+ input_hash = md5(json_data.encode()).hexdigest()[0:6]
+
+ # Generate and cache a CSS stylesheet that contains the CSS variables.
+ if not _is_script_in_cache(comp_cls, "css", input_hash):
+ _cache_script(
+ comp_cls=comp_cls,
+ script="", # TODO - enable JS and CSS vars
+ script_type="css",
+ input_hash=input_hash,
+ )
+
+ return input_hash
+
+
+def wrap_component_css(comp_cls: Type["Component"], content: str) -> str:
+ if "' end tag. "
+ "This is not allowed, as it would break the HTML."
+ )
+ return f""
+
+
+#########################################################
+# 2. Modify the HTML to use the same IDs defined in previous
+# step for the inlined CSS and JS scripts, so the scripts
+# can be applied to the correct HTML elements. And embed
+# component + JS/CSS relationships as HTML comments.
+#########################################################
+
+
+def set_component_attrs_for_js_and_css(
+ html_content: Union[str, SafeString],
+ component_id: Optional[str],
+ css_input_hash: Optional[str],
+ root_attributes: Optional[List[str]] = None,
+) -> Tuple[Union[str, SafeString], Dict[str, List[str]]]:
+ # These are the attributes that we want to set on the root element.
+ all_root_attributes = [*root_attributes] if root_attributes else []
+
+ # Component ID is used for executing JS script, e.g. `data-djc-id-ca1b2c3`
+ #
+ # NOTE: We use `data-djc-css-a1b2c3` and `data-djc-id-ca1b2c3` instead of
+ # `data-djc-css="a1b2c3"` and `data-djc-id="a1b2c3"`, to allow
+ # multiple values to be associated with the same element, which may happen if
+ # one component renders another.
+ if component_id:
+ all_root_attributes.append(f"data-djc-id-{component_id}")
+
+ # Attribute by which we bind the CSS variables to the component's CSS,
+ # e.g. `data-djc-css-a1b2c3`
+ if css_input_hash:
+ all_root_attributes.append(f"data-djc-css-{css_input_hash}")
+
+ is_safestring = isinstance(html_content, SafeString)
+ updated_html, child_components = set_html_attributes(
+ html_content,
+ root_attributes=all_root_attributes,
+ all_attributes=[],
+ # Setting this means that set_html_attributes will check for HTML elemetnts with this
+ # attribute, and return a dictionary of {attribute_value: [attributes_set_on_this_tag]}.
+ #
+ # So if HTML contains tag ,
+ # and we set on that tag `data-djc-id-123`, then we will get
+ # {
+ # "123": ["data-djc-id-123"],
+ # }
+ #
+ # This is a minor optimization. Without this, when we're rendering components in
+ # component_post_render(), we'd have to parse each ``
+ # to find the HTML attribute that were set on it.
+ watch_on_attribute="djc-render-id",
+ )
+ updated_html = mark_safe(updated_html) if is_safestring else updated_html
+
+ return updated_html, child_components
+
+
+# NOTE: To better understand the next section, consider this:
+#
+# We define and cache the component's JS and CSS at the same time as
+# when we render the HTML. However, the resulting HTML MAY OR MAY NOT
+# be used in another component.
+#
+# IF the component's HTML IS used in another component, and the other
+# component want to render the JS or CSS dependencies (e.g. inside ),
+# then it's only at that point when we want to access the data about
+# which JS and CSS scripts is the component's HTML associated with.
+#
+# This happens AFTER the rendering context, so there's no Context to rely on.
+#
+# Hence, we store the info about associated JS and CSS right in the HTML itself.
+# As an HTML comment ``. Thus, the inner component can be used as many times
+# and in different components, and they will all know to fetch also JS and CSS of the
+# inner components.
+def insert_component_dependencies_comment(
+ content: str,
+ # NOTE: We pass around the component CLASS, so the dependencies logic is not
+ # dependent on ComponentRegistries
+ component_cls: Type["Component"],
+ component_id: str,
+ js_input_hash: Optional[str],
+ css_input_hash: Optional[str],
+) -> SafeString:
+ """
+ Given some textual content, prepend it with a short string that
+ will be used by the `render_dependencies()` function to collect all
+ declared JS / CSS scripts.
+ """
+ data = f"{component_cls.class_id},{component_id},{js_input_hash or ''},{css_input_hash or ''}"
+
+ # NOTE: It's important that we put the comment BEFORE the content, so we can
+ # use the order of comments to evaluate components' instance JS code in the correct order.
+ output = mark_safe(COMPONENT_DEPS_COMMENT.format(data=data) + content)
+ return output
+
+
+#########################################################
+# 3. Given a FINAL HTML composed of MANY components,
+# process all the HTML dependency comments (created in
+# previous step), obtaining ALL JS and CSS scripts
+# required by this HTML document. And post-process them,
+# so the scripts are either inlined into the HTML, or
+# fetched when the HTML is loaded in the browser.
+#########################################################
+
+
+TContent = TypeVar("TContent", bound=Union[bytes, str])
+
+
+CSS_PLACEHOLDER_NAME = "CSS_PLACEHOLDER"
+CSS_PLACEHOLDER_NAME_B = CSS_PLACEHOLDER_NAME.encode()
+JS_PLACEHOLDER_NAME = "JS_PLACEHOLDER"
+JS_PLACEHOLDER_NAME_B = JS_PLACEHOLDER_NAME.encode()
+
+CSS_DEPENDENCY_PLACEHOLDER = f''
+JS_DEPENDENCY_PLACEHOLDER = f''
+COMPONENT_DEPS_COMMENT = ""
+
+# E.g. ``
+COMPONENT_COMMENT_REGEX = re.compile(rb"")
+# E.g. `table,123,a92ef298,bd002c3`
+# - comp_cls_id - Cache key of the component class that was rendered
+# - id - Component render ID
+# - js - Cache key for the JS data from `get_js_data()`
+# - css - Cache key for the CSS data from `get_css_data()`
+SCRIPT_NAME_REGEX = re.compile(
+ rb"^(?P[\w\-\./]+?),(?P[\w]+?),(?P[0-9a-f]*?),(?P[0-9a-f]*?)$"
+)
+# E.g. `data-djc-id-ca1b2c3`
+MAYBE_COMP_ID = r'(?: data-djc-id-\w{{{COMP_ID_LENGTH}}}="")?'.format(COMP_ID_LENGTH=COMP_ID_LENGTH)
+# E.g. `data-djc-css-99914b`
+MAYBE_COMP_CSS_ID = r'(?: data-djc-css-\w{6}="")?'
+
+PLACEHOLDER_REGEX = re.compile(
+ r"{css_placeholder}|{js_placeholder}".format(
+ css_placeholder=f'',
+ js_placeholder=f'',
+ ).encode()
+)
+
+
+def render_dependencies(content: TContent, strategy: DependenciesStrategy = "document") -> TContent:
+ """
+ Given a string that contains parts that were rendered by components,
+ this function inserts all used JS and CSS.
+
+ By default, the string is parsed as an HTML and:
+ - CSS is inserted at the end of `` (if present)
+ - JS is inserted at the end of `` (if present)
+
+ If you used `{% component_js_dependencies %}` or `{% component_css_dependencies %}`,
+ then the JS and CSS will be inserted only at these locations.
+
+ Example:
+ ```python
+ def my_view(request):
+ template = Template('''
+ {% load components %}
+
+
+
+
+ ..", cached_script_view, name=CACHE_ENDPOINT_NAME),
+ path("cache/.", cached_script_view, name=CACHE_ENDPOINT_NAME),
+]
+
+
+#########################################################
+# 5. Template tags
+#########################################################
+
+
+def _component_dependencies(type: Literal["js", "css"]) -> SafeString:
+ """Marks location where CSS link and JS script tags should be rendered."""
+ if type == "css":
+ placeholder = CSS_DEPENDENCY_PLACEHOLDER
+ elif type == "js":
+ placeholder = JS_DEPENDENCY_PLACEHOLDER
+ else:
+ raise TemplateSyntaxError(
+ f"Unknown dependency type in {{% component_dependencies %}}. Must be one of 'css' or 'js', got {type}"
+ )
+
+ return mark_safe(placeholder)
+
+
+class ComponentCssDependenciesNode(BaseNode):
+ """
+ Marks location where CSS link tags should be rendered after the whole HTML has been generated.
+
+ Generally, this should be inserted into the `` tag of the HTML.
+
+ If the generated HTML does NOT contain any `{% component_css_dependencies %}` tags, CSS links
+ are by default inserted into the `` tag of the HTML. (See
+ [Default JS / CSS locations](../../concepts/advanced/rendering_js_css/#default-js-css-locations))
+
+ Note that there should be only one `{% component_css_dependencies %}` for the whole HTML document.
+ If you insert this tag multiple times, ALL CSS links will be duplicately inserted into ALL these places.
+ """
+
+ tag = "component_css_dependencies"
+ end_tag = None # inline-only
+ allowed_flags = []
+
+ def render(self, context: Context) -> str:
+ return _component_dependencies("css")
+
+
+class ComponentJsDependenciesNode(BaseNode):
+ """
+ Marks location where JS link tags should be rendered after the whole HTML has been generated.
+
+ Generally, this should be inserted at the end of the `` tag of the HTML.
+
+ If the generated HTML does NOT contain any `{% component_js_dependencies %}` tags, JS scripts
+ are by default inserted at the end of the `` tag of the HTML. (See
+ [Default JS / CSS locations](../../concepts/advanced/rendering_js_css/#default-js-css-locations))
+
+ Note that there should be only one `{% component_js_dependencies %}` for the whole HTML document.
+ If you insert this tag multiple times, ALL JS scripts will be duplicately inserted into ALL these places.
+ """
+
+ tag = "component_js_dependencies"
+ end_tag = None # inline-only
+ allowed_flags = []
+
+ def render(self, context: Context) -> str:
+ return _component_dependencies("js")
diff --git a/src/django_components/expression.py b/src/django_components/expression.py
index a2773056..9afcbc80 100644
--- a/src/django_components/expression.py
+++ b/src/django_components/expression.py
@@ -1,42 +1,45 @@
import re
-from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Mapping, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List
from django.template import Context, Node, NodeList, TemplateSyntaxError
-from django.template.base import FilterExpression, Lexer, Parser, VariableNode
+from django.template.base import Parser, VariableNode
-Expression = Union[FilterExpression, "DynamicFilterExpression"]
-RuntimeKwargsInput = Dict[str, Union[Expression, "Operator"]]
-RuntimeKwargPairsInput = List[Tuple[str, Union[Expression, "Operator"]]]
+from django_components.util.template_parser import parse_template
-
-class Operator(ABC):
- """
- Operator describes something that somehow changes the inputs
- to template tags (the `{% %}`).
-
- For example, a SpreadOperator inserts one or more kwargs at the
- specified location.
- """
-
- @abstractmethod
- def resolve(self, context: Context) -> Any: ... # noqa E704
-
-
-class SpreadOperator(Operator):
- """Operator that inserts one or more kwargs at the specified location."""
-
- def __init__(self, expr: Expression) -> None:
- self.expr = expr
-
- def resolve(self, context: Context) -> Dict[str, Any]:
- data = self.expr.resolve(context)
- if not isinstance(data, dict):
- raise RuntimeError(f"Spread operator expression must resolve to a Dict, got {data}")
- return data
+if TYPE_CHECKING:
+ from django_components.util.template_tag import TagParam
class DynamicFilterExpression:
+ """
+ To make working with Django templates easier, we allow to use (nested) template tags `{% %}`
+ inside of strings that are passed to our template tags, e.g.:
+
+ ```django
+ {% component "my_comp" value_from_tag="{% gen_dict %}" %}
+ ```
+
+ We call this the "dynamic" or "nested" expression.
+
+ A string is marked as a dynamic expression only if it contains any one
+ of `{{ }}`, `{% %}`, or `{# #}`.
+
+ If the expression consists of a single tag, with no extra text, we return the tag's
+ value directly. E.g.:
+
+ ```django
+ {% component "my_comp" value_from_tag="{% gen_dict %}" %}
+ ```
+
+ will pass a dictionary to the component input `value_from_tag`.
+
+ But if the text already contains spaces or more tags, e.g.
+
+ `{% component "my_comp" value_from_tag=" {% gen_dict %} " %}`
+
+ Then we treat it as a regular template and pass it as string.
+ """
+
def __init__(self, parser: Parser, expr_str: str) -> None:
if not is_dynamic_expression(expr_str):
raise TemplateSyntaxError(f"Not a valid dynamic expression: '{expr_str}'")
@@ -47,8 +50,7 @@ class DynamicFilterExpression:
# Copy the Parser, and pass through the tags and filters available
# in the current context. Thus, if user calls `{% load %}` inside
# the expression, it won't spill outside.
- lexer = Lexer(self.expr)
- tokens = lexer.tokenize()
+ tokens = parse_template(self.expr)
expr_parser = Parser(tokens=tokens)
expr_parser.tags = {**parser.tags}
expr_parser.filters = {**parser.filters}
@@ -103,80 +105,17 @@ class StringifiedNode(Node):
return str(result)
-class RuntimeKwargs:
- def __init__(self, kwargs: RuntimeKwargsInput) -> None:
- self.kwargs = kwargs
-
- def resolve(self, context: Context) -> Dict[str, Any]:
- resolved_kwargs = safe_resolve_dict(context, self.kwargs)
- return process_aggregate_kwargs(resolved_kwargs)
-
-
-class RuntimeKwargPairs:
- def __init__(self, kwarg_pairs: RuntimeKwargPairsInput) -> None:
- self.kwarg_pairs = kwarg_pairs
-
- def resolve(self, context: Context) -> List[Tuple[str, Any]]:
- resolved_kwarg_pairs: List[Tuple[str, Any]] = []
- for key, kwarg in self.kwarg_pairs:
- if isinstance(kwarg, SpreadOperator):
- spread_kwargs = kwarg.resolve(context)
- for spread_key, spread_value in spread_kwargs.items():
- resolved_kwarg_pairs.append((spread_key, spread_value))
- else:
- resolved_kwarg_pairs.append((key, kwarg.resolve(context)))
-
- return resolved_kwarg_pairs
-
-
-def is_identifier(value: Any) -> bool:
- if not isinstance(value, str):
- return False
- if not value.isidentifier():
- return False
- return True
-
-
-def safe_resolve_list(context: Context, args: List[Expression]) -> List:
- return [arg.resolve(context) for arg in args]
-
-
-def safe_resolve_dict(
- context: Context,
- kwargs: Dict[str, Union[Expression, "Operator"]],
-) -> Dict[str, Any]:
- result = {}
-
- for key, kwarg in kwargs.items():
- # If we've come across a Spread Operator (...), we insert the kwargs from it here
- if isinstance(kwarg, SpreadOperator):
- spread_dict = kwarg.resolve(context)
- if spread_dict is not None:
- for spreadkey, spreadkwarg in spread_dict.items():
- result[spreadkey] = spreadkwarg
- else:
- result[key] = kwarg.resolve(context)
- return result
-
-
-def resolve_string(
- s: str,
- parser: Optional[Parser] = None,
- context: Optional[Mapping[str, Any]] = None,
-) -> str:
- parser = parser or Parser([])
- context = Context(context or {})
- return parser.compile_filter(s).resolve(context)
-
-
-def is_kwarg(key: str) -> bool:
- return "=" in key
-
-
def is_aggregate_key(key: str) -> bool:
+ key = key.strip()
# NOTE: If we get a key that starts with `:`, like `:class`, we do not split it.
# This syntax is used by Vue and AlpineJS.
- return ":" in key and not key.startswith(":")
+ return (
+ ":" in key
+ # `:` or `:class` is NOT ok
+ and not key.startswith(":")
+ # `attrs:class` is OK, but `attrs:` is NOT ok
+ and bool(key.split(":", maxsplit=1)[1])
+ )
# A string that must start and end with quotes, and somewhere inside includes
@@ -194,7 +133,7 @@ DYNAMIC_EXPR_RE = re.compile(
def is_dynamic_expression(value: Any) -> bool:
# NOTE: Currently dynamic expression need at least 6 characters
- # for the opening and closing tags, and quotes
+ # for the opening and closing tags, and quotes, e.g. `"`, `{%`, `%}` in `" some text {% ... %}"`
MIN_EXPR_LEN = 6
if not isinstance(value, str) or not value or len(value) < MIN_EXPR_LEN:
@@ -207,32 +146,8 @@ def is_dynamic_expression(value: Any) -> bool:
return True
-def is_spread_operator(value: Any) -> bool:
- if not isinstance(value, str) or not value:
- return False
-
- return value.startswith("...")
-
-
-# A string that starts with `...1=`, `...29=`, etc.
-# We convert the spread syntax to this, so Django parses
-# it as a kwarg, so it remains in the original position.
-#
-# So from `...dict`, we make `...1=dict`
-#
-# That way it's trivial to merge the kwargs after the spread
-# operator is replaced with actual values.
-INTERNAL_SPREAD_OPERATOR_RE = re.compile(r"^\.\.\.\d+=")
-
-
-def is_internal_spread_operator(value: Any) -> bool:
- if not isinstance(value, str) or not value:
- return False
-
- return bool(INTERNAL_SPREAD_OPERATOR_RE.match(value))
-
-
-def process_aggregate_kwargs(kwargs: Mapping[str, Any]) -> Dict[str, Any]:
+# TODO - Move this out into a plugin?
+def process_aggregate_kwargs(params: List["TagParam"]) -> List["TagParam"]:
"""
This function aggregates "prefixed" kwargs into dicts. "Prefixed" kwargs
start with some prefix delimited with `:` (e.g. `attrs:`).
@@ -286,26 +201,65 @@ def process_aggregate_kwargs(kwargs: Mapping[str, Any]) -> Dict[str, Any]:
"fallthrough attributes", and sufficiently easy for component authors to process
that input while still being able to provide their own keys.
"""
- processed_kwargs = {}
+ from django_components.util.template_tag import TagParam
+
+ _check_kwargs_for_agg_conflict(params)
+
+ processed_params = []
+ seen_keys = set()
nested_kwargs: Dict[str, Dict[str, Any]] = {}
- for key, val in kwargs.items():
- if not is_aggregate_key(key):
- processed_kwargs[key] = val
+ for param in params:
+ # Positional args
+ if param.key is None:
+ processed_params.append(param)
continue
- # NOTE: Trim off the prefix from keys
- prefix, sub_key = key.split(":", 1)
- if prefix not in nested_kwargs:
- nested_kwargs[prefix] = {}
- nested_kwargs[prefix][sub_key] = val
+ # Regular kwargs without `:` prefix
+ if not is_aggregate_key(param.key):
+ outer_key = param.key
+ inner_key = None
+ seen_keys.add(outer_key)
+ processed_params.append(param)
+ continue
+
+ # NOTE: Trim off the outer_key from keys
+ outer_key, inner_key = param.key.split(":", 1)
+ if outer_key not in nested_kwargs:
+ nested_kwargs[outer_key] = {}
+ nested_kwargs[outer_key][inner_key] = param.value
# Assign aggregated values into normal input
for key, val in nested_kwargs.items():
- if key in processed_kwargs:
+ if key in seen_keys:
raise TemplateSyntaxError(
f"Received argument '{key}' both as a regular input ({key}=...)"
f" and as an aggregate dict ('{key}:key=...'). Must be only one of the two"
)
- processed_kwargs[key] = val
+ processed_params.append(TagParam(key=key, value=val))
- return processed_kwargs
+ return processed_params
+
+
+def _check_kwargs_for_agg_conflict(params: List["TagParam"]) -> None:
+ seen_regular_kwargs = set()
+ seen_agg_kwargs = set()
+
+ for param in params:
+ # Ignore positional args
+ if param.key is None:
+ continue
+
+ is_agg_kwarg = is_aggregate_key(param.key)
+ if (
+ (is_agg_kwarg and (param.key in seen_regular_kwargs))
+ or (not is_agg_kwarg and (param.key in seen_agg_kwargs))
+ ): # fmt: skip
+ raise TemplateSyntaxError(
+ f"Received argument '{param.key}' both as a regular input ({param.key}=...)"
+ f" and as an aggregate dict ('{param.key}:key=...'). Must be only one of the two"
+ )
+
+ if is_agg_kwarg:
+ seen_agg_kwargs.add(param.key)
+ else:
+ seen_regular_kwargs.add(param.key)
diff --git a/src/django_components/extension.py b/src/django_components/extension.py
new file mode 100644
index 00000000..a95d9755
--- /dev/null
+++ b/src/django_components/extension.py
@@ -0,0 +1,1369 @@
+from functools import wraps
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Callable,
+ ClassVar,
+ Dict,
+ List,
+ NamedTuple,
+ Optional,
+ Set,
+ Tuple,
+ Type,
+ TypeVar,
+ Union,
+)
+
+import django.urls
+from django.template import Context, Origin, Template
+from django.urls import URLPattern, URLResolver, get_resolver, get_urlconf
+
+from django_components.app_settings import app_settings
+from django_components.compat.django import routes_to_django
+from django_components.util.command import ComponentCommand
+from django_components.util.misc import snake_to_pascal
+from django_components.util.routing import URLRoute
+
+if TYPE_CHECKING:
+ from django_components import Component
+ from django_components.component_registry import ComponentRegistry
+ from django_components.perfutil.component import OnComponentRenderedResult
+ from django_components.slots import Slot, SlotNode, SlotResult
+
+
+TCallable = TypeVar("TCallable", bound=Callable)
+TClass = TypeVar("TClass", bound=Type[Any])
+
+
+################################################
+# HOOK TYPES
+#
+# This is the source of truth for what data is available in each hook.
+# NOTE: These types are also used in docs generation, see `docs/scripts/reference.py`.
+################################################
+
+
+# Mark a class as an extension hook context so we can place these in
+# a separate documentation section
+def mark_extension_hook_api(cls: TClass) -> TClass:
+ cls._extension_hook_api = True
+ return cls
+
+
+@mark_extension_hook_api
+class OnComponentClassCreatedContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The created Component class"""
+
+
+@mark_extension_hook_api
+class OnComponentClassDeletedContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The to-be-deleted Component class"""
+
+
+@mark_extension_hook_api
+class OnRegistryCreatedContext(NamedTuple):
+ registry: "ComponentRegistry"
+ """The created ComponentRegistry instance"""
+
+
+@mark_extension_hook_api
+class OnRegistryDeletedContext(NamedTuple):
+ registry: "ComponentRegistry"
+ """The to-be-deleted ComponentRegistry instance"""
+
+
+@mark_extension_hook_api
+class OnComponentRegisteredContext(NamedTuple):
+ registry: "ComponentRegistry"
+ """The registry the component was registered to"""
+ name: str
+ """The name the component was registered under"""
+ component_cls: Type["Component"]
+ """The registered Component class"""
+
+
+@mark_extension_hook_api
+class OnComponentUnregisteredContext(NamedTuple):
+ registry: "ComponentRegistry"
+ """The registry the component was unregistered from"""
+ name: str
+ """The name the component was registered under"""
+ component_cls: Type["Component"]
+ """The unregistered Component class"""
+
+
+@mark_extension_hook_api
+class OnComponentInputContext(NamedTuple):
+ component: "Component"
+ """The Component instance that received the input and is being rendered"""
+ component_cls: Type["Component"]
+ """The Component class"""
+ component_id: str
+ """The unique identifier for this component instance"""
+ args: List
+ """List of positional arguments passed to the component"""
+ kwargs: Dict
+ """Dictionary of keyword arguments passed to the component"""
+ slots: Dict[str, "Slot"]
+ """Dictionary of slot definitions"""
+ context: Context
+ """The Django template Context object"""
+
+
+@mark_extension_hook_api
+class OnComponentDataContext(NamedTuple):
+ component: "Component"
+ """The Component instance that is being rendered"""
+ component_cls: Type["Component"]
+ """The Component class"""
+ component_id: str
+ """The unique identifier for this component instance"""
+ # TODO_V1 - Remove `context_data`
+ context_data: Dict
+ """Deprecated. Use `template_data` instead. Will be removed in v1.0."""
+ template_data: Dict
+ """Dictionary of template data from `Component.get_template_data()`"""
+ js_data: Dict
+ """Dictionary of JavaScript data from `Component.get_js_data()`"""
+ css_data: Dict
+ """Dictionary of CSS data from `Component.get_css_data()`"""
+
+
+@mark_extension_hook_api
+class OnComponentRenderedContext(NamedTuple):
+ component: "Component"
+ """The Component instance that is being rendered"""
+ component_cls: Type["Component"]
+ """The Component class"""
+ component_id: str
+ """The unique identifier for this component instance"""
+ result: Optional[str]
+ """The rendered component, or `None` if rendering failed"""
+ error: Optional[Exception]
+ """The error that occurred during rendering, or `None` if rendering was successful"""
+
+
+@mark_extension_hook_api
+class OnSlotRenderedContext(NamedTuple):
+ component: "Component"
+ """The Component instance that contains the `{% slot %}` tag"""
+ component_cls: Type["Component"]
+ """The Component class that contains the `{% slot %}` tag"""
+ component_id: str
+ """The unique identifier for this component instance"""
+ slot: "Slot"
+ """The Slot instance that was rendered"""
+ slot_name: str
+ """The name of the `{% slot %}` tag"""
+ slot_node: "SlotNode"
+ """The node instance of the `{% slot %}` tag"""
+ slot_is_required: bool
+ """Whether the slot is required"""
+ slot_is_default: bool
+ """Whether the slot is default"""
+ result: "SlotResult"
+ """The rendered result of the slot"""
+
+
+@mark_extension_hook_api
+class OnTemplateLoadedContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The Component class whose template was loaded"""
+ content: str
+ """The template string"""
+ origin: Optional[Origin]
+ """The origin of the template"""
+ name: Optional[str]
+ """The name of the template"""
+
+
+@mark_extension_hook_api
+class OnTemplateCompiledContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The Component class whose template was loaded"""
+ template: Template
+ """The compiled template object"""
+
+
+@mark_extension_hook_api
+class OnCssLoadedContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The Component class whose CSS was loaded"""
+ content: str
+ """The CSS content (string)"""
+
+
+@mark_extension_hook_api
+class OnJsLoadedContext(NamedTuple):
+ component_cls: Type["Component"]
+ """The Component class whose JS was loaded"""
+ content: str
+ """The JS content (string)"""
+
+
+################################################
+# EXTENSIONS CORE
+################################################
+
+
+class ExtensionComponentConfig:
+ """
+ `ExtensionComponentConfig` is the base class for all extension component configs.
+
+ Extensions can define nested classes on the component class,
+ such as [`Component.View`](../api#django_components.Component.View) or
+ [`Component.Cache`](../api#django_components.Component.Cache):
+
+ ```py
+ class MyComp(Component):
+ class View:
+ def get(self, request):
+ ...
+
+ class Cache:
+ ttl = 60
+ ```
+
+ This allows users to configure extension behavior per component.
+
+ Behind the scenes, the nested classes that users define on their components
+ are merged with the extension's "base" class.
+
+ So the example above is the same as:
+
+ ```py
+ class MyComp(Component):
+ class View(ViewExtension.ComponentConfig):
+ def get(self, request):
+ ...
+
+ class Cache(CacheExtension.ComponentConfig):
+ ttl = 60
+ ```
+
+ Where both `ViewExtension.ComponentConfig` and `CacheExtension.ComponentConfig` are
+ subclasses of `ExtensionComponentConfig`.
+ """
+
+ component_cls: Type["Component"]
+ """The [`Component`](../api#django_components.Component) class that this extension is defined on."""
+
+ # TODO_v1 - Remove, superseded by `component_cls`
+ component_class: Type["Component"]
+ """The [`Component`](../api#django_components.Component) class that this extension is defined on."""
+
+ component: "Component"
+ """
+ When a [`Component`](../api#django_components.Component) is instantiated,
+ also the nested extension classes (such as `Component.View`) are instantiated,
+ receiving the component instance as an argument.
+
+ This attribute holds the owner [`Component`](../api#django_components.Component) instance
+ that this extension is defined on.
+ """
+
+ def __init__(self, component: "Component") -> None:
+ self.component = component
+
+
+# TODO_v1 - Delete
+BaseExtensionClass = ExtensionComponentConfig
+"""
+Deprecated. Will be removed in v1.0. Use
+[`ComponentConfig`](../api#django_components.ExtensionComponentConfig) instead.
+"""
+
+
+# TODO_V1 - Delete, meta class was needed only for backwards support for ExtensionClass.
+class ExtensionMeta(type):
+ def __new__(mcs, name: Any, bases: Tuple, attrs: Dict) -> Any:
+ # Rename `ExtensionClass` to `ComponentConfig`
+ if "ExtensionClass" in attrs:
+ attrs["ComponentConfig"] = attrs.pop("ExtensionClass")
+
+ return super().__new__(mcs, name, bases, attrs)
+
+
+# NOTE: This class is used for generating documentation for the extension hooks API.
+# To be recognized, all hooks must start with `on_` prefix.
+class ComponentExtension(metaclass=ExtensionMeta):
+ """
+ Base class for all extensions.
+
+ Read more on [Extensions](../../concepts/advanced/extensions).
+
+ **Example:**
+
+ ```python
+ class ExampleExtension(ComponentExtension):
+ name = "example"
+
+ # Component-level behavior and settings. User will be able to override
+ # the attributes and methods defined here on the component classes.
+ class ComponentConfig(ComponentExtension.ComponentConfig):
+ foo = "1"
+ bar = "2"
+
+ def baz(cls):
+ return "3"
+
+ # URLs
+ urls = [
+ URLRoute(path="dummy-view/", handler=dummy_view, name="dummy"),
+ URLRoute(path="dummy-view-2///", handler=dummy_view_2, name="dummy-2"),
+ ]
+
+ # Commands
+ commands = [
+ HelloWorldCommand,
+ ]
+
+ # Hooks
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ print(ctx.component_cls.__name__)
+
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ print(ctx.component_cls.__name__)
+ ```
+
+ Which users then can override on a per-component basis. E.g.:
+
+ ```python
+ class MyComp(Component):
+ class Example:
+ foo = "overridden"
+
+ def baz(self):
+ return "overridden baz"
+ ```
+ """
+
+ ###########################
+ # USER INPUT
+ ###########################
+
+ name: ClassVar[str]
+ """
+ Name of the extension.
+
+ Name must be lowercase, and must be a valid Python identifier (e.g. `"my_extension"`).
+
+ The extension may add new features to the [`Component`](../api#django_components.Component)
+ class by allowing users to define and access a nested class in
+ the [`Component`](../api#django_components.Component) class.
+
+ The extension name determines the name of the nested class in
+ the [`Component`](../api#django_components.Component) class, and the attribute
+ under which the extension will be accessible.
+
+ E.g. if the extension name is `"my_extension"`, then the nested class in
+ the [`Component`](../api#django_components.Component) class will be
+ `MyExtension`, and the extension will be accessible as `MyComp.my_extension`.
+
+ ```python
+ class MyComp(Component):
+ class MyExtension:
+ ...
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "my_extension": self.my_extension.do_something(),
+ }
+ ```
+
+ !!! info
+
+ The extension class name can be customized by setting
+ the [`class_name`](../api#django_components.ComponentExtension.class_name) attribute.
+ """
+
+ class_name: ClassVar[str]
+ """
+ Name of the extension class.
+
+ By default, this is set automatically at class creation. The class name is the same as
+ the [`name`](../api#django_components.ComponentExtension.name) attribute, but with snake_case
+ converted to PascalCase.
+
+ So if the extension name is `"my_extension"`, then the extension class name will be `"MyExtension"`.
+
+ ```python
+ class MyComp(Component):
+ class MyExtension: # <--- This is the extension class
+ ...
+ ```
+
+ To customize the class name, you can manually set the `class_name` attribute.
+
+ The class name must be a valid Python identifier.
+
+ **Example:**
+
+ ```python
+ class MyExt(ComponentExtension):
+ name = "my_extension"
+ class_name = "MyCustomExtension"
+ ```
+
+ This will make the extension class name `"MyCustomExtension"`.
+
+ ```python
+ class MyComp(Component):
+ class MyCustomExtension: # <--- This is the extension class
+ ...
+ ```
+ """
+
+ ComponentConfig: ClassVar[Type[ExtensionComponentConfig]] = ExtensionComponentConfig
+ """
+ Base class that the "component-level" extension config nested within
+ a [`Component`](../api#django_components.Component) class will inherit from.
+
+ This is where you can define new methods and attributes that will be available to the component
+ instance.
+
+ Background:
+
+ The extension may add new features to the [`Component`](../api#django_components.Component) class
+ by allowing users to define and access a nested class in
+ the [`Component`](../api#django_components.Component) class. E.g.:
+
+ ```python
+ class MyComp(Component):
+ class MyExtension:
+ ...
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "my_extension": self.my_extension.do_something(),
+ }
+ ```
+
+ When rendering a component, the nested extension class will be set as a subclass of
+ `ComponentConfig`. So it will be same as if the user had directly inherited from extension's
+ `ComponentConfig`. E.g.:
+
+ ```python
+ class MyComp(Component):
+ class MyExtension(ComponentExtension.ComponentConfig):
+ ...
+ ```
+
+ This setting decides what the extension class will inherit from.
+ """
+
+ commands: ClassVar[List[Type[ComponentCommand]]] = []
+ """
+ List of commands that can be run by the extension.
+
+ These commands will be available to the user as `components ext run `.
+
+ Commands are defined as subclasses of
+ [`ComponentCommand`](../extension_commands#django_components.ComponentCommand).
+
+ **Example:**
+
+ This example defines an extension with a command that prints "Hello world". To run the command,
+ the user would run `components ext run hello_world hello`.
+
+ ```python
+ from django_components import ComponentCommand, ComponentExtension, CommandArg, CommandArgGroup
+
+ class HelloWorldCommand(ComponentCommand):
+ name = "hello"
+ help = "Hello world command."
+
+ # Allow to pass flags `--foo`, `--bar` and `--baz`.
+ # Argument parsing is managed by `argparse`.
+ arguments = [
+ CommandArg(
+ name_or_flags="--foo",
+ help="Foo description.",
+ ),
+ # 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.",
+ ),
+ ],
+ ),
+ ]
+
+ # Callback that receives the parsed arguments and options.
+ def handle(self, *args, **kwargs):
+ print(f"HelloWorldCommand.handle: args={args}, kwargs={kwargs}")
+
+ # Associate the command with the extension
+ class HelloWorldExtension(ComponentExtension):
+ name = "hello_world"
+
+ commands = [
+ HelloWorldCommand,
+ ]
+ ```
+ """
+
+ urls: ClassVar[List[URLRoute]] = []
+
+ ###########################
+ # Misc
+ ###########################
+
+ def __init_subclass__(cls) -> None:
+ if not cls.name.isidentifier():
+ raise ValueError(f"Extension name must be a valid Python identifier, got {cls.name}")
+ if not cls.name.islower():
+ raise ValueError(f"Extension name must be lowercase, got {cls.name}")
+
+ if not getattr(cls, "class_name", None):
+ cls.class_name = snake_to_pascal(cls.name)
+
+ ###########################
+ # Component lifecycle hooks
+ ###########################
+
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ """
+ Called when a new [`Component`](../api#django_components.Component) class is created.
+
+ This hook is called after the [`Component`](../api#django_components.Component) class
+ is fully defined but before it's registered.
+
+ Use this hook to perform any initialization or validation of the
+ [`Component`](../api#django_components.Component) class.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentClassCreatedContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ # Add a new attribute to the Component class
+ ctx.component_cls.my_attr = "my_value"
+ ```
+ """
+ pass
+
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ """
+ Called when a [`Component`](../api#django_components.Component) class is being deleted.
+
+ This hook is called before the [`Component`](../api#django_components.Component) class
+ is deleted from memory.
+
+ Use this hook to perform any cleanup related to the [`Component`](../api#django_components.Component) class.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentClassDeletedContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ # Remove Component class from the extension's cache on deletion
+ self.cache.pop(ctx.component_cls, None)
+ ```
+ """
+ pass
+
+ def on_registry_created(self, ctx: OnRegistryCreatedContext) -> None:
+ """
+ Called when a new [`ComponentRegistry`](../api#django_components.ComponentRegistry) is created.
+
+ This hook is called after a new
+ [`ComponentRegistry`](../api#django_components.ComponentRegistry) instance is initialized.
+
+ Use this hook to perform any initialization needed for the registry.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnRegistryCreatedContext
+
+ class MyExtension(ComponentExtension):
+ def on_registry_created(self, ctx: OnRegistryCreatedContext) -> None:
+ # Add a new attribute to the registry
+ ctx.registry.my_attr = "my_value"
+ ```
+ """
+ pass
+
+ def on_registry_deleted(self, ctx: OnRegistryDeletedContext) -> None:
+ """
+ Called when a [`ComponentRegistry`](../api#django_components.ComponentRegistry) is being deleted.
+
+ This hook is called before
+ a [`ComponentRegistry`](../api#django_components.ComponentRegistry) instance is deleted.
+
+ Use this hook to perform any cleanup related to the registry.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnRegistryDeletedContext
+
+ class MyExtension(ComponentExtension):
+ def on_registry_deleted(self, ctx: OnRegistryDeletedContext) -> None:
+ # Remove registry from the extension's cache on deletion
+ self.cache.pop(ctx.registry, None)
+ ```
+ """
+ pass
+
+ def on_component_registered(self, ctx: OnComponentRegisteredContext) -> None:
+ """
+ Called when a [`Component`](../api#django_components.Component) class is
+ registered with a [`ComponentRegistry`](../api#django_components.ComponentRegistry).
+
+ This hook is called after a [`Component`](../api#django_components.Component) class
+ is successfully registered.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentRegisteredContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_registered(self, ctx: OnComponentRegisteredContext) -> None:
+ print(f"Component {ctx.component_cls} registered to {ctx.registry} as '{ctx.name}'")
+ ```
+ """
+ pass
+
+ def on_component_unregistered(self, ctx: OnComponentUnregisteredContext) -> None:
+ """
+ Called when a [`Component`](../api#django_components.Component) class is
+ unregistered from a [`ComponentRegistry`](../api#django_components.ComponentRegistry).
+
+ This hook is called after a [`Component`](../api#django_components.Component) class
+ is removed from the registry.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentUnregisteredContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_unregistered(self, ctx: OnComponentUnregisteredContext) -> None:
+ print(f"Component {ctx.component_cls} unregistered from {ctx.registry} as '{ctx.name}'")
+ ```
+ """
+ pass
+
+ ###########################
+ # Component render hooks
+ ###########################
+
+ def on_component_input(self, ctx: OnComponentInputContext) -> Optional[str]:
+ """
+ Called when a [`Component`](../api#django_components.Component) was triggered to render,
+ but before a component's context and data methods are invoked.
+
+ Use this hook to modify or validate component inputs before they're processed.
+
+ This is the first hook that is called when rendering a component. As such this hook is called before
+ [`Component.get_template_data()`](../api#django_components.Component.get_template_data),
+ [`Component.get_js_data()`](../api#django_components.Component.get_js_data),
+ and [`Component.get_css_data()`](../api#django_components.Component.get_css_data) methods,
+ and the
+ [`on_component_data`](../extension_hooks#django_components.extension.ComponentExtension.on_component_data)
+ hook.
+
+ This hook also allows to skip the rendering of a component altogether. If the hook returns
+ a non-null value, this value will be used instead of rendering the component.
+
+ You can use this to implement a caching mechanism for components, or define components
+ that will be rendered conditionally.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentInputContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_input(self, ctx: OnComponentInputContext) -> None:
+ # Add extra kwarg to all components when they are rendered
+ ctx.kwargs["my_input"] = "my_value"
+ ```
+
+ !!! warning
+
+ In this hook, the components' inputs are still mutable.
+
+ As such, if a component defines [`Args`](../api#django_components.Component.Args),
+ [`Kwargs`](../api#django_components.Component.Kwargs),
+ [`Slots`](../api#django_components.Component.Slots) types, these types are NOT yet instantiated.
+
+ Instead, component fields like [`Component.args`](../api#django_components.Component.args),
+ [`Component.kwargs`](../api#django_components.Component.kwargs),
+ [`Component.slots`](../api#django_components.Component.slots)
+ are plain `list` / `dict` objects.
+ """
+ pass
+
+ def on_component_data(self, ctx: OnComponentDataContext) -> None:
+ """
+ Called when a [`Component`](../api#django_components.Component) was triggered to render,
+ after a component's context and data methods have been processed.
+
+ This hook is called after
+ [`Component.get_template_data()`](../api#django_components.Component.get_template_data),
+ [`Component.get_js_data()`](../api#django_components.Component.get_js_data)
+ and [`Component.get_css_data()`](../api#django_components.Component.get_css_data).
+
+ This hook runs after [`on_component_input`](../api#django_components.ComponentExtension.on_component_input).
+
+ Use this hook to modify or validate the component's data before rendering.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnComponentDataContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_data(self, ctx: OnComponentDataContext) -> None:
+ # Add extra template variable to all components when they are rendered
+ ctx.template_data["my_template_var"] = "my_value"
+ ```
+ """
+ pass
+
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> Optional[str]:
+ """
+ Called when a [`Component`](../api#django_components.Component) was rendered, including
+ all its child components.
+
+ Use this hook to access or post-process the component's rendered output.
+
+ This hook works similarly to
+ [`Component.on_render_after()`](../api#django_components.Component.on_render_after):
+
+ 1. To modify the output, return a new string from this hook. The original output or error will be ignored.
+
+ 2. To cause this component to return a new error, raise that error. The original output and error
+ will be ignored.
+
+ 3. If you neither raise nor return string, the original output or error will be used.
+
+ **Examples:**
+
+ Change the final output of a component:
+
+ ```python
+ from django_components import ComponentExtension, OnComponentRenderedContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> Optional[str]:
+ # Append a comment to the component's rendered output
+ return ctx.result + ""
+ ```
+
+ Cause the component to raise a new exception:
+
+ ```python
+ from django_components import ComponentExtension, OnComponentRenderedContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> Optional[str]:
+ # Raise a new exception
+ raise Exception("Error message")
+ ```
+
+ Return nothing (or `None`) to handle the result as usual:
+
+ ```python
+ from django_components import ComponentExtension, OnComponentRenderedContext
+
+ class MyExtension(ComponentExtension):
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> Optional[str]:
+ if ctx.error is not None:
+ # The component raised an exception
+ print(f"Error: {ctx.error}")
+ else:
+ # The component rendered successfully
+ print(f"Result: {ctx.result}")
+ ```
+ """
+ pass
+
+ ##########################
+ # Template / JS / CSS hooks
+ ##########################
+
+ def on_template_loaded(self, ctx: OnTemplateLoadedContext) -> Optional[str]:
+ """
+ Called when a Component's template is loaded as a string.
+
+ This hook runs only once per [`Component`](../api#django_components.Component) class and works for both
+ [`Component.template`](../api#django_components.Component.template) and
+ [`Component.template_file`](../api#django_components.Component.template_file).
+
+ Use this hook to read or modify the template before it's compiled.
+
+ To modify the template, return a new string from this hook.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnTemplateLoadedContext
+
+ class MyExtension(ComponentExtension):
+ def on_template_loaded(self, ctx: OnTemplateLoadedContext) -> Optional[str]:
+ # Modify the template
+ return ctx.content.replace("Hello", "Hi")
+ ```
+ """
+ pass
+
+ def on_template_compiled(self, ctx: OnTemplateCompiledContext) -> None:
+ """
+ Called when a Component's template is compiled
+ into a [`Template`](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Template) object.
+
+ This hook runs only once per [`Component`](../api#django_components.Component) class and works for both
+ [`Component.template`](../api#django_components.Component.template) and
+ [`Component.template_file`](../api#django_components.Component.template_file).
+
+ Use this hook to read or modify the template (in-place) after it's compiled.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnTemplateCompiledContext
+
+ class MyExtension(ComponentExtension):
+ def on_template_compiled(self, ctx: OnTemplateCompiledContext) -> None:
+ print(f"Template origin: {ctx.template.origin.name}")
+ ```
+ """
+ pass
+
+ def on_css_loaded(self, ctx: OnCssLoadedContext) -> Optional[str]:
+ """
+ Called when a Component's CSS is loaded as a string.
+
+ This hook runs only once per [`Component`](../api#django_components.Component) class and works for both
+ [`Component.css`](../api#django_components.Component.css) and
+ [`Component.css_file`](../api#django_components.Component.css_file).
+
+ Use this hook to read or modify the CSS.
+
+ To modify the CSS, return a new string from this hook.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnCssLoadedContext
+
+ class MyExtension(ComponentExtension):
+ def on_css_loaded(self, ctx: OnCssLoadedContext) -> Optional[str]:
+ # Modify the CSS
+ return ctx.content.replace("Hello", "Hi")
+ ```
+ """
+ pass
+
+ def on_js_loaded(self, ctx: OnJsLoadedContext) -> Optional[str]:
+ """
+ Called when a Component's JS is loaded as a string.
+
+ This hook runs only once per [`Component`](../api#django_components.Component) class and works for both
+ [`Component.js`](../api#django_components.Component.js) and
+ [`Component.js_file`](../api#django_components.Component.js_file).
+
+ Use this hook to read or modify the JS.
+
+ To modify the JS, return a new string from this hook.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnCssLoadedContext
+
+ class MyExtension(ComponentExtension):
+ def on_js_loaded(self, ctx: OnJsLoadedContext) -> Optional[str]:
+ # Modify the JS
+ return ctx.content.replace("Hello", "Hi")
+ ```
+ """
+ pass
+
+ ##########################
+ # Tags lifecycle hooks
+ ##########################
+
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> Optional[str]:
+ """
+ Called when a [`{% slot %}`](../template_tags#slot) tag was rendered.
+
+ Use this hook to access or post-process the slot's rendered output.
+
+ To modify the output, return a new string from this hook.
+
+ **Example:**
+
+ ```python
+ from django_components import ComponentExtension, OnSlotRenderedContext
+
+ class MyExtension(ComponentExtension):
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> Optional[str]:
+ # Append a comment to the slot's rendered output
+ return ctx.result + ""
+ ```
+
+ **Access slot metadata:**
+
+ You can access the [`{% slot %}` tag](../template_tags#slot)
+ node ([`SlotNode`](../api#django_components.SlotNode)) and its metadata using `ctx.slot_node`.
+
+ For example, to find the [`Component`](../api#django_components.Component) class to which
+ belongs the template where the [`{% slot %}`](../template_tags#slot) tag is defined, you can use
+ [`ctx.slot_node.template_component`](../api#django_components.SlotNode.template_component):
+
+ ```python
+ from django_components import ComponentExtension, OnSlotRenderedContext
+
+ class MyExtension(ComponentExtension):
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> Optional[str]:
+ # Access slot metadata
+ slot_node = ctx.slot_node
+ slot_owner = slot_node.template_component
+ print(f"Slot owner: {slot_owner}")
+ ```
+ """
+ pass
+
+
+# Decorator to store events in `ExtensionManager._events` when django_components is not yet initialized.
+def store_events(func: TCallable) -> TCallable:
+ fn_name = func.__name__
+
+ @wraps(func)
+ def wrapper(self: "ExtensionManager", ctx: Any) -> Any:
+ if not self._initialized:
+ self._events.append((fn_name, ctx))
+ return
+
+ return func(self, ctx)
+
+ return wrapper # type: ignore[return-value]
+
+
+# Manage all extensions from a single place
+class ExtensionManager:
+ ###########################
+ # Internal
+ ###########################
+
+ def __init__(self) -> None:
+ self._initialized = False
+ self._events: List[Tuple[str, Any]] = []
+ self._url_resolvers: Dict[str, URLResolver] = {}
+ # Keep track of which URLRoute (framework-agnostic) maps to which URLPattern (Django-specific)
+ self._route_to_url: Dict[URLRoute, Union[URLPattern, URLResolver]] = {}
+
+ @property
+ def extensions(self) -> List[ComponentExtension]:
+ return app_settings.EXTENSIONS
+
+ def _init_component_class(self, component_cls: Type["Component"]) -> None:
+ # If not yet initialized, this class will be initialized later once we run `_init_app`
+ if not self._initialized:
+ return
+
+ for extension in self.extensions:
+ ext_class_name = extension.class_name
+
+ # If a Component class has a nested extension class, e.g.
+ # ```python
+ # class MyComp(Component):
+ # class MyExtension:
+ # ...
+ # ```
+ # then create a dummy class to make `MyComp.MyExtension` extend
+ # the base class `extension.ComponentConfig`.
+ #
+ # So it will be same as if the user had directly inherited from `extension.ComponentConfig`.
+ # ```python
+ # class MyComp(Component):
+ # class MyExtension(MyExtension.ComponentConfig):
+ # ...
+ # ```
+ component_ext_subclass = getattr(component_cls, ext_class_name, None)
+
+ # Add escape hatch, so that user can override the extension class
+ # from within the component class. E.g.:
+ # ```python
+ # class MyExtDifferentButStillSame(MyExtension.ComponentConfig):
+ # ...
+ #
+ # class MyComp(Component):
+ # my_extension_class = MyExtDifferentButStillSame
+ # class MyExtension:
+ # ...
+ # ```
+ #
+ # Will be effectively the same as:
+ # ```python
+ # class MyComp(Component):
+ # class MyExtension(MyExtDifferentButStillSame):
+ # ...
+ # ```
+ ext_class_override_attr = extension.name + "_class" # "my_extension_class"
+ ext_base_class = getattr(component_cls, ext_class_override_attr, extension.ComponentConfig)
+
+ # Extensions have 3 levels of configuration:
+ # 1. Factory defaults - The values that the extension author set on the extension class
+ # 2. User global defaults with `COMPONENTS.extensions_defaults`
+ # 3. User component-level settings - The values that the user set on the component class
+ #
+ # The component-level settings override the global defaults, which in turn override
+ # the factory defaults.
+ #
+ # To apply these defaults, we set them as bases for our new extension class.
+ #
+ # The final class will look like this:
+ # ```
+ # class MyExtension(MyComp.MyExtension, MyExtensionDefaults, MyExtensionBase):
+ # component_cls = MyComp
+ # ...
+ # ```
+ # Where:
+ # - `MyComp.MyExtension` is the extension class that the user defined on the component class.
+ # - `MyExtensionDefaults` is a dummy class that holds the extension defaults from settings.
+ # - `MyExtensionBase` is the base class that the extension class inherits from.
+ bases_list = [ext_base_class]
+
+ all_extensions_defaults = app_settings.EXTENSIONS_DEFAULTS or {}
+ extension_defaults = all_extensions_defaults.get(extension.name, None)
+ if extension_defaults:
+ # Create dummy class that holds the extension defaults
+ defaults_class = type(f"{ext_class_name}Defaults", tuple(), extension_defaults.copy())
+ bases_list.insert(0, defaults_class)
+
+ if component_ext_subclass:
+ bases_list.insert(0, component_ext_subclass)
+
+ bases: tuple[Type, ...] = tuple(bases_list)
+
+ # Allow component-level extension class to access the owner `Component` class that via
+ # `component_cls`.
+ component_ext_subclass = type(
+ ext_class_name,
+ bases,
+ # TODO_v1 - Remove `component_class`, superseded by `component_cls`
+ {"component_cls": component_cls, "component_class": component_cls},
+ )
+
+ # Finally, reassign the new class extension class on the component class.
+ setattr(component_cls, ext_class_name, component_ext_subclass)
+
+ def _init_component_instance(self, component: "Component") -> None:
+ # Each extension has different class defined nested on the Component class:
+ # ```python
+ # class MyComp(Component):
+ # class MyExtension:
+ # ...
+ # class MyOtherExtension:
+ # ...
+ # ```
+ #
+ # We instantiate them all, passing the component instance to each. These are then
+ # available under the extension name on the component instance.
+ # ```python
+ # component.my_extension
+ # component.my_other_extension
+ # ```
+ for extension in self.extensions:
+ # NOTE: `_init_component_class` creates extension-specific nested classes
+ # on the created component classes, e.g.:
+ # ```py
+ # class MyComp(Component):
+ # class MyExtension:
+ # ...
+ # ```
+ # It should NOT happen in production, but in tests it may happen, if some extensions
+ # are test-specific, then the built-in component classes (like DynamicComponent) will
+ # be initialized BEFORE the extension is set in the settings. As such, they will be missing
+ # the nested class. In that case, we retroactively create the extension-specific nested class,
+ # so that we may proceed.
+ if not hasattr(component, extension.class_name):
+ self._init_component_class(component.__class__)
+
+ used_ext_class = getattr(component, extension.class_name)
+ extension_instance = used_ext_class(component)
+ setattr(component, extension.name, extension_instance)
+
+ def _init_app(self) -> None:
+ if self._initialized:
+ return
+
+ self._initialized = True
+
+ # Populate the `urlpatterns` with URLs specified by the extensions
+ # TODO_V3 - Django-specific logic - replace with hook
+ urls: List[URLResolver] = []
+ seen_names: Set[str] = set()
+
+ from django_components import Component
+
+ for extension in self.extensions:
+ # Ensure that the extension name won't conflict with existing Component class API
+ if hasattr(Component, extension.name) or hasattr(Component, extension.class_name):
+ raise ValueError(f"Extension name '{extension.name}' conflicts with existing Component class API")
+
+ if extension.name.lower() in seen_names:
+ raise ValueError(f"Multiple extensions cannot have the same name '{extension.name}'")
+
+ seen_names.add(extension.name.lower())
+
+ # NOTE: The empty list is a placeholder for the URLs that will be added later
+ curr_ext_url_resolver = django.urls.path(f"{extension.name}/", django.urls.include([]))
+ urls.append(curr_ext_url_resolver)
+
+ # Remember which extension the URLResolver belongs to
+ self._url_resolvers[extension.name] = curr_ext_url_resolver
+
+ self.add_extension_urls(extension.name, extension.urls)
+
+ # NOTE: `urlconf_name` is the actual source of truth that holds either a list of URLPatterns
+ # or an import string thereof.
+ # However, Django's `URLResolver` caches the resolved value of `urlconf_name`
+ # under the key `url_patterns`.
+ # So we set both:
+ # - `urlconf_name` to update the source of truth
+ # - `url_patterns` to override the caching
+ extensions_url_resolver.urlconf_name = urls
+ extensions_url_resolver.url_patterns = urls
+
+ # Rebuild URL resolver cache to be able to resolve the new routes by their names.
+ urlconf = get_urlconf()
+ resolver = get_resolver(urlconf)
+ resolver._populate()
+
+ # Flush stored events
+ #
+ # The triggers for following hooks may occur before the `apps.py` `ready()` hook is called.
+ # - on_component_class_created
+ # - on_component_class_deleted
+ # - on_registry_created
+ # - on_registry_deleted
+ # - on_component_registered
+ # - on_component_unregistered
+ #
+ # The problem is that the extensions are set up only at the initialization (`ready()` hook in `apps.py`).
+ #
+ # So in the case that these hooks are triggered before initialization,
+ # we store these "events" in a list, and then "flush" them all when `ready()` is called.
+ #
+ # This way, we can ensure that all extensions are present before any hooks are called.
+ for hook, data in self._events:
+ if hook == "on_component_class_created":
+ on_component_created_data: OnComponentClassCreatedContext = data
+ self._init_component_class(on_component_created_data.component_cls)
+ getattr(self, hook)(data)
+ self._events = []
+
+ def get_extension(self, name: str) -> ComponentExtension:
+ for extension in self.extensions:
+ if extension.name == name:
+ return extension
+ raise ValueError(f"Extension {name} not found")
+
+ def get_extension_command(self, name: str, command_name: str) -> Type[ComponentCommand]:
+ extension = self.get_extension(name)
+ for command in extension.commands:
+ if command.name == command_name:
+ return command
+ raise ValueError(f"Command {command_name} not found in extension {name}")
+
+ def add_extension_urls(self, name: str, urls: List[URLRoute]) -> None:
+ if not self._initialized:
+ raise RuntimeError("Cannot add extension URLs before initialization")
+
+ url_resolver = self._url_resolvers[name]
+ all_urls = url_resolver.url_patterns
+ new_urls = routes_to_django(urls)
+
+ did_add_urls = False
+
+ # Allow to add only those routes that are not yet added
+ for route, urlpattern in zip(urls, new_urls):
+ if route in self._route_to_url:
+ raise ValueError(f"URLRoute {route} already exists")
+ self._route_to_url[route] = urlpattern
+ all_urls.append(urlpattern)
+ did_add_urls = True
+
+ # Force Django's URLResolver to update its lookups, so things like `reverse()` work
+ if did_add_urls:
+ # Django's root URLResolver
+ urlconf = get_urlconf()
+ root_resolver = get_resolver(urlconf)
+ root_resolver._populate()
+
+ def remove_extension_urls(self, name: str, urls: List[URLRoute]) -> None:
+ if not self._initialized:
+ raise RuntimeError("Cannot remove extension URLs before initialization")
+
+ url_resolver = self._url_resolvers[name]
+ urls_to_remove = routes_to_django(urls)
+ all_urls = url_resolver.url_patterns
+
+ # Remove the URLs in reverse order, so that we don't have to deal with index shifting
+ for index in reversed(range(len(all_urls))):
+ if not urls_to_remove:
+ break
+
+ # Instead of simply checking if the URL is in the `urls_to_remove` list, we search for
+ # the index of the URL within the `urls_to_remove` list, so we can remove it from there.
+ # That way, in theory, the iteration should be faster as the list gets smaller.
+ try:
+ found_index = urls_to_remove.index(all_urls[index])
+ except ValueError:
+ found_index = -1
+
+ if found_index != -1:
+ all_urls.pop(index)
+ urls_to_remove.pop(found_index)
+
+ #############################
+ # Component lifecycle hooks
+ #############################
+
+ @store_events
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ for extension in self.extensions:
+ extension.on_component_class_created(ctx)
+
+ @store_events
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ for extension in self.extensions:
+ extension.on_component_class_deleted(ctx)
+
+ @store_events
+ def on_registry_created(self, ctx: OnRegistryCreatedContext) -> None:
+ for extension in self.extensions:
+ extension.on_registry_created(ctx)
+
+ @store_events
+ def on_registry_deleted(self, ctx: OnRegistryDeletedContext) -> None:
+ for extension in self.extensions:
+ extension.on_registry_deleted(ctx)
+
+ @store_events
+ def on_component_registered(self, ctx: OnComponentRegisteredContext) -> None:
+ for extension in self.extensions:
+ extension.on_component_registered(ctx)
+
+ @store_events
+ def on_component_unregistered(self, ctx: OnComponentUnregisteredContext) -> None:
+ for extension in self.extensions:
+ extension.on_component_unregistered(ctx)
+
+ ###########################
+ # Component render hooks
+ ###########################
+
+ def on_component_input(self, ctx: OnComponentInputContext) -> Optional[str]:
+ for extension in self.extensions:
+ result = extension.on_component_input(ctx)
+ # The extension short-circuited the rendering process to return this
+ if result is not None:
+ return result
+ return None
+
+ def on_component_data(self, ctx: OnComponentDataContext) -> None:
+ for extension in self.extensions:
+ extension.on_component_data(ctx)
+
+ def on_component_rendered(
+ self,
+ ctx: OnComponentRenderedContext,
+ ) -> Optional["OnComponentRenderedResult"]:
+ for extension in self.extensions:
+ try:
+ result = extension.on_component_rendered(ctx)
+ except Exception as error:
+ # Error from `on_component_rendered()` - clear HTML and set error
+ ctx = ctx._replace(result=None, error=error)
+ else:
+ # No error from `on_component_rendered()` - set HTML and clear error
+ if result is not None:
+ ctx = ctx._replace(result=result, error=None)
+ return ctx.result, ctx.error
+
+ ##########################
+ # Template / JS / CSS hooks
+ ##########################
+
+ def on_template_loaded(self, ctx: OnTemplateLoadedContext) -> str:
+ for extension in self.extensions:
+ content = extension.on_template_loaded(ctx)
+ if content is not None:
+ ctx = ctx._replace(content=content)
+ return ctx.content
+
+ def on_template_compiled(self, ctx: OnTemplateCompiledContext) -> None:
+ for extension in self.extensions:
+ extension.on_template_compiled(ctx)
+
+ def on_css_loaded(self, ctx: OnCssLoadedContext) -> str:
+ for extension in self.extensions:
+ content = extension.on_css_loaded(ctx)
+ if content is not None:
+ ctx = ctx._replace(content=content)
+ return ctx.content
+
+ def on_js_loaded(self, ctx: OnJsLoadedContext) -> str:
+ for extension in self.extensions:
+ content = extension.on_js_loaded(ctx)
+ if content is not None:
+ ctx = ctx._replace(content=content)
+ return ctx.content
+
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> Optional[str]:
+ for extension in self.extensions:
+ result = extension.on_slot_rendered(ctx)
+ if result is not None:
+ ctx = ctx._replace(result=result)
+ return ctx.result
+
+
+# NOTE: This is a singleton which is takes the extensions from `app_settings.EXTENSIONS`
+extensions = ExtensionManager()
+
+
+################################
+# VIEW
+################################
+
+# Extensions can define their own URLs, which will be added to the `urlpatterns` list.
+# These will be available under the `/components/ext//` path, e.g.:
+# `/components/ext/my_extension/path/to/route///`
+urlpatterns = [
+ django.urls.path("ext/", django.urls.include([])),
+]
+
+# NOTE: Normally we'd pass all the routes introduced by extensions to `django.urls.include()` and
+# `django.urls.path()` to construct the `URLResolver` objects that would take care of the rest.
+#
+# However, Django's `urlpatterns` are constructed BEFORE the `ready()` hook is called,
+# and so before the extensions are ready.
+#
+# As such, we lazily set the extensions' routes to the `URLResolver` object. And we use the `include()
+# and `path()` funtions above to ensure that the `URLResolver` object is created correctly.
+extensions_url_resolver: URLResolver = urlpatterns[0]
diff --git a/src/django_components/extensions/__init__.py b/src/django_components/extensions/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/django_components/extensions/cache.py b/src/django_components/extensions/cache.py
new file mode 100644
index 00000000..5f07dede
--- /dev/null
+++ b/src/django_components/extensions/cache.py
@@ -0,0 +1,205 @@
+from hashlib import md5
+from typing import Any, Dict, List, Optional
+
+from django.core.cache import BaseCache, caches
+
+from django_components.extension import (
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentInputContext,
+ OnComponentRenderedContext,
+)
+from django_components.slots import Slot
+
+# NOTE: We allow users to override cache key generation, but then we internally
+# still prefix their key with our own prefix, so it's clear where it comes from.
+CACHE_KEY_PREFIX = "components:cache:"
+
+
+class ComponentCache(ExtensionComponentConfig):
+ """
+ The interface for `Component.Cache`.
+
+ The fields of this class are used to configure the component caching.
+
+ Read more about [Component caching](../../concepts/advanced/component_caching).
+
+ **Example:**
+
+ ```python
+ from django_components import Component
+
+ class MyComponent(Component):
+ class Cache:
+ enabled = True
+ ttl = 60 * 60 * 24 # 1 day
+ cache_name = "my_cache"
+ ```
+ """
+
+ enabled: bool = False
+ """
+ Whether this Component should be cached. Defaults to `False`.
+ """
+ include_slots: bool = False
+ """
+ Whether the slots should be hashed into the cache key.
+
+ If enabled, the following two cases will be treated as different entries:
+
+ ```django
+ {% component "mycomponent" name="foo" %}
+ FILL ONE
+ {% endcomponent %}
+
+ {% component "mycomponent" name="foo" %}
+ FILL TWO
+ {% endcomponent %}
+ ```
+
+ !!! warning
+
+ Passing slots as functions to cached components with `include_slots=True` will raise an error.
+
+ !!! warning
+
+ Slot caching DOES NOT account for context variables within the `{% fill %}` tag.
+
+ For example, the following two cases will be treated as the same entry:
+
+ ```django
+ {% with my_var="foo" %}
+ {% component "mycomponent" name="foo" %}
+ {{ my_var }}
+ {% endcomponent %}
+ {% endwith %}
+
+ {% with my_var="bar" %}
+ {% component "mycomponent" name="bar" %}
+ {{ my_var }}
+ {% endcomponent %}
+ {% endwith %}
+ ```
+
+ Currently it's impossible to capture used variables. This will be addressed in v2.
+ Read more about it in https://github.com/django-components/django-components/issues/1164.
+ """
+
+ ttl: Optional[int] = None
+ """
+ The time-to-live (TTL) in seconds, i.e. for how long should an entry be valid in the cache.
+
+ - If `> 0`, the entries will be cached for the given number of seconds.
+ - If `-1`, the entries will be cached indefinitely.
+ - If `0`, the entries won't be cached.
+ - If `None`, the default TTL will be used.
+ """
+
+ cache_name: Optional[str] = None
+ """
+ The name of the cache to use. If `None`, the default cache will be used.
+ """
+
+ def get_entry(self, cache_key: str) -> Any:
+ cache = self.get_cache()
+ return cache.get(cache_key)
+
+ def set_entry(self, cache_key: str, value: Any) -> None:
+ cache = self.get_cache()
+ cache.set(cache_key, value, timeout=self.ttl)
+
+ def get_cache(self) -> BaseCache:
+ cache_name = self.cache_name or "default"
+ cache = caches[cache_name]
+ return cache
+
+ def get_cache_key(self, args: List, kwargs: Dict, slots: Dict) -> str:
+ # Allow user to override how the input is hashed into a cache key with `hash()`,
+ # but then still prefix it wih our own prefix, so it's clear where it comes from.
+ cache_key = self.hash(args, kwargs)
+ if self.include_slots:
+ cache_key += ":" + self.hash_slots(slots)
+ cache_key = self.component._class_hash + ":" + cache_key
+ cache_key = CACHE_KEY_PREFIX + md5(cache_key.encode()).hexdigest()
+ return cache_key
+
+ def hash(self, args: List, kwargs: Dict) -> str:
+ """
+ Defines how the input (both args and kwargs) is hashed into a cache key.
+
+ By default, `hash()` serializes the input into a string. As such, the default
+ implementation might NOT be suitable if you need to hash complex objects.
+ """
+ args_hash = ",".join(str(arg) for arg in args)
+ # Sort keys to ensure consistent ordering
+ sorted_items = sorted(kwargs.items())
+ kwargs_hash = ",".join(f"{k}-{v}" for k, v in sorted_items)
+ return f"{args_hash}:{kwargs_hash}"
+
+ def hash_slots(self, slots: Dict[str, Slot]) -> str:
+ sorted_items = sorted(slots.items())
+ hash_parts = []
+ for key, slot in sorted_items:
+ if callable(slot.contents):
+ raise ValueError(
+ f"Cannot hash slot '{key}' of component '{self.component.name}' - Slot functions are unhashable."
+ " Instead define the slot as a string or `{% fill %}` tag, or disable slot caching"
+ " with `Cache.include_slots=False`."
+ )
+ hash_parts.append(f"{key}-{slot.contents}")
+ return ",".join(hash_parts)
+
+
+class CacheExtension(ComponentExtension):
+ """
+ This extension adds a nested `Cache` class to each `Component`.
+
+ This nested `Cache` class is used to configure component caching.
+
+ **Example:**
+
+ ```python
+ from django_components import Component
+
+ class MyComponent(Component):
+ class Cache:
+ enabled = True
+ ttl = 60 * 60 * 24 # 1 day
+ cache_name = "my_cache"
+ ```
+
+ This extension is automatically added to all components.
+ """
+
+ name = "cache"
+
+ ComponentConfig = ComponentCache
+
+ def __init__(self, *args: Any, **kwargs: Any):
+ self.render_id_to_cache_key: dict[str, str] = {}
+
+ def on_component_input(self, ctx: OnComponentInputContext) -> Optional[Any]:
+ cache_instance = ctx.component.cache
+ if not cache_instance.enabled:
+ return None
+
+ cache_key = cache_instance.get_cache_key(ctx.args, ctx.kwargs, ctx.slots)
+ self.render_id_to_cache_key[ctx.component_id] = cache_key
+
+ # If cache entry exists, return it. This will short-circuit the rendering process.
+ cached_result = cache_instance.get_entry(cache_key)
+ if cached_result is not None:
+ return cached_result
+ return None
+
+ # Save the rendered component to cache
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> None:
+ cache_instance = ctx.component.cache
+ if not cache_instance.enabled:
+ return None
+
+ if ctx.error is not None:
+ return
+
+ cache_key = self.render_id_to_cache_key[ctx.component_id]
+ cache_instance.set_entry(cache_key, ctx.result)
diff --git a/src/django_components/extensions/debug_highlight.py b/src/django_components/extensions/debug_highlight.py
new file mode 100644
index 00000000..acaf1f5c
--- /dev/null
+++ b/src/django_components/extensions/debug_highlight.py
@@ -0,0 +1,140 @@
+from typing import Any, Literal, NamedTuple, Optional, Type
+
+from django_components.app_settings import app_settings
+from django_components.extension import (
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentRenderedContext,
+ OnSlotRenderedContext,
+)
+from django_components.util.misc import gen_id
+
+
+class HighlightColor(NamedTuple):
+ text_color: str
+ border_color: str
+
+
+COLORS = {
+ "component": HighlightColor(text_color="#2f14bb", border_color="blue"),
+ "slot": HighlightColor(text_color="#bb1414", border_color="#e40c0c"),
+}
+
+
+def apply_component_highlight(type: Literal["component", "slot"], output: str, name: str) -> str:
+ """
+ Wrap HTML (string) in a div with a border and a highlight color.
+
+ This is part of the component / slot highlighting feature. User can toggle on
+ to see the component / slot boundaries.
+ """
+ color = COLORS[type]
+
+ # Because the component / slot name is set via styling as a `::before` pseudo-element,
+ # we need to generate a unique ID for each component / slot to avoid conflicts.
+ highlight_id = gen_id()
+
+ output = f"""
+
+
+
+ ' + 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 "calender" / %}
+
+```
+
+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_template_data(self, args, kwargs, slots, context):
+ outer_field = self.outer_context["date"]
+ return {
+ "date": outer_fields,
+ }
+```
+
+However, as a best practice, it’s recommended not to rely on accessing the outer context directly through `self.outer_context`. Instead, explicitly pass the variables to the component. For instance, continue passing the variables in the component tag as shown in the previous examples.
+
+## Context behavior
+
+django_components supports both Django and Vue-like behavior when it comes to passing data to and through
+components. This can be configured in [context_behavior](../../../reference/settings#context_behavior).
+
+This has two modes:
+
+- `"django"`
+
+ The default Django template behavior.
+
+ Inside the [`{% fill %}`](../../../reference/template_tags#fill) tag, the context variables
+ 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.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_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+ of the component that owns the fill tag.
+
+- `"isolated"`
+
+ Similar behavior to [Vue](https://vuejs.org/guide/components/slots.html#render-scope) or React,
+ this is useful if you want to make sure that components don't accidentally access variables defined outside
+ of the component.
+
+ Inside the [`{% fill %}`](../../../reference/template_tags#fill) tag, you can ONLY access variables from 2 places:
+
+ - Any loops ([`{% for ... %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#cycle))
+ that the `{% fill %}` tag is part of.
+ - [`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_template_data()` we use inside
+ [`{% fill %}`](../../../reference/template_tags#fill)
+ is NOT the same across the two modes!
+
+ Consider this example:
+
+ ```djc_py
+ class Outer(Component):
+ template = """
+
+ {% component "inner" %}
+ {% fill "content" %}
+ {{ my_var }}
+ {% endfill %}
+ {% endcomponent %}
+
+ """
+ ```
+
+ - `"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_template_data()` of ONLY `Outer`.
+
+
+### Example "django"
+
+Given this template:
+
+```djc_py
+@register("root_comp")
+class RootComp(Component):
+ template = """
+ {% with cheese="feta" %}
+ {% component 'my_comp' %}
+ {{ my_var }} # my_var
+ {{ cheese }} # cheese
+ {% endcomponent %}
+ {% endwith %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return { "my_var": 123 }
+```
+
+Then if [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+of the component `"my_comp"` returns following data:
+
+```py
+{ "my_var": 456 }
+```
+
+Then the template will be rendered as:
+
+```django
+456 # my_var
+feta # cheese
+```
+
+Because `"my_comp"` overshadows the outer variable `"my_var"`,
+so `{{ my_var }}` equals `456`.
+
+And variable `"cheese"` equals `feta`, because the fill CAN access
+all the data defined in the outer layers, like the `{% with %}` tag.
+
+### Example "isolated"
+
+Given this template:
+
+```djc_py
+class RootComp(Component):
+ template = """
+ {% with cheese="feta" %}
+ {% component 'my_comp' %}
+ {{ my_var }} # my_var
+ {{ cheese }} # cheese
+ {% endcomponent %}
+ {% endwith %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return { "my_var": 123 }
+```
+
+Then if [`get_template_data()`](../../../reference/api#django_components.Component.get_template_data)
+of the component `"my_comp"` returns following data:
+
+```py
+{ "my_var": 456 }
+```
+
+Then the template will be rendered as:
+
+```django
+123 # my_var
+ # cheese
+```
+
+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.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/component_libraries.md b/docs/concepts/advanced/component_libraries.md
new file mode 100644
index 00000000..44aa4577
--- /dev/null
+++ b/docs/concepts/advanced/component_libraries.md
@@ -0,0 +1,244 @@
+You can publish and share your components for others to use. Below you will find the steps to do so.
+
+For live examples, see the [Community examples](../../overview/community.md#community-examples).
+
+## Writing component libraries
+
+1. Create a Django project with a similar structure:
+
+ ```txt
+ project/
+ |-- myapp/
+ |-- __init__.py
+ |-- apps.py
+ |-- templates/
+ |-- table/
+ |-- table.py
+ |-- table.js
+ |-- table.css
+ |-- table.html
+ |-- menu.py <--- single-file component
+ |-- templatetags/
+ |-- __init__.py
+ |-- mytags.py
+ ```
+
+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.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
+ from django_components import ComponentRegistry, RegistrySettings
+
+ register = library = django.template.Library()
+ comp_registry = ComponentRegistry(
+ library=library,
+ settings=RegistrySettings(
+ context_behavior="isolated",
+ tag_formatter="django_components.component_formatter",
+ ),
+ )
+ ```
+
+ As you can see above, this is also the place where we configure how our components should behave,
+ using the [`settings`](django_components.component_registry.ComponentRegistry.settings) argument.
+ If omitted, default settings are used.
+
+ For library authors, we recommend setting [`context_behavior`](django_components.app_settings.ComponentsSettings.context_behavior)
+ to [`"isolated"`](django_components.app_settings.ContextBehavior.ISOLATED), so that the state cannot leak into the components,
+ and so the components' behavior is configured solely through the inputs. This means that the components will be more predictable and easier to debug.
+
+ Next, you can decide how will others use your components by setting the
+ [`tag_formatter`](django_components.app_settings.ComponentsSettings.tag_formatter)
+ options.
+
+ If omitted or set to `"django_components.component_formatter"`,
+ your components will be used like this:
+
+ ```django
+ {% component "table" items=items headers=headers %}
+ {% endcomponent %}
+ ```
+
+ Or you can use `"django_components.component_shorthand_formatter"`
+ to use components like so:
+
+ ```django
+ {% table items=items headers=headers %}
+ {% endtable %}
+ ```
+
+ Or you can define a [custom TagFormatter](#tagformatter).
+
+ Either way, these settings will be scoped only to your components. So, in the user code,
+ there may be components side-by-side that use different formatters:
+
+ ```django
+ {% load mytags %}
+
+ {# Component from your library "mytags", using the "shorthand" formatter #}
+ {% table items=items headers=header %}
+ {% endtable %}
+
+ {# User-created components using the default settings #}
+ {% component "my_comp" title="Abc..." %}
+ {% endcomponent %}
+ ```
+
+3. Write your components and register them with your instance of [`ComponentRegistry`](../../reference/api#ComponentRegistry)
+
+ There's one difference when you are writing components that are to be shared, and that's
+ that the components must be explicitly registered with your instance of
+ [`ComponentRegistry`](../../reference/api#ComponentRegistry) from the previous step.
+
+ For better user experience, you can also define the types for the args, kwargs, slots and data.
+
+ 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`.
+
+ ```djc_py
+ from typing import NamedTuple, Optional
+ from django_components import Component, SlotInput, register, types
+
+ from myapp.templatetags.mytags import comp_registry
+
+ # Define the component
+ # NOTE: Don't forget to set the `registry`!
+ @register("my_menu", registry=comp_registry)
+ 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,
+ }
+
+ template: types.django_html = """
+ {# Load django_components template tags #}
+ {% load component_tags %}
+
+
+ """
+ ```
+
+4. Import the components in `apps.py`
+
+ Normally, users rely on [autodiscovery](../../concepts/autodiscovery) and [`COMPONENTS.dirs`](../../reference/settings#dirs)
+ to load the component files.
+
+ Since you, as the library author, are not in control of the file system, it is recommended to load the components manually.
+
+ We recommend doing this in the [`AppConfig.ready()`](https://docs.djangoproject.com/en/5.2/ref/applications/#django.apps.AppConfig.ready)
+ hook of your `apps.py`:
+
+ ```py
+ from django.apps import AppConfig
+
+ class MyAppConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "myapp"
+
+ # This is the code that gets run when user adds myapp
+ # to Django's INSTALLED_APPS
+ def ready(self) -> None:
+ # Import the components that you want to make available
+ # inside the templates.
+ from myapp.templates import (
+ menu,
+ table,
+ )
+ ```
+
+ Note that you can also include any other startup logic within
+ [`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.
+
+## Publishing component libraries
+
+Once you are ready to share your library, you need to build
+a distribution and then publish it to PyPI.
+
+django_components uses the [`build`](https://build.pypa.io/en/stable/) utility to build a distribution:
+
+```bash
+python -m build --sdist --wheel --outdir dist/ .
+```
+
+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
+twine upload --repository pypi dist/* -u __token__ -p + hello from tab 1 +
+ {% component "button" %} + Click me! + {% endcomponent %} + {% endcomponent %} + + {% component "tab_item" header="Tab 2" %} + Hello this is tab 2 + {% endcomponent %} +{% endcomponent %} +``` diff --git a/docs/concepts/advanced/html_fragments.md b/docs/concepts/advanced/html_fragments.md new file mode 100644 index 00000000..3ac8ea4b --- /dev/null +++ b/docs/concepts/advanced/html_fragments.md @@ -0,0 +1,383 @@ +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. + +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 + +!!! info + + **What are HTML fragments and "HTML over the wire"?** + + It is one of the methods for updating the state in the browser UI upon user interaction. + + How it works is that: + + 1. User makes an action - clicks a button or submits a form + 2. The action causes a request to be made from the client to the server. + 3. Server processes the request (e.g. form submission), and responds with HTML + of some part of the UI (e.g. a new entry in a table). + 4. A library like HTMX, AlpineJS, or custom function inserts the new HTML into + the correct place. + +## Document and fragment strategies + +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 strategy + +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 ` + + +OLD
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+```
+
+### 2. Define fragment HTML
+
+The fragment to be inserted into the document.
+
+IMPORTANT: Don't forget to set `deps_strategy="fragment"`
+
+```djc_py title="[root]/components/demo.py"
+class Frag(Component):
+ template = """
+
+ 123
+
+
+ """
+
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(
+ request=request,
+ # IMPORTANT: Don't forget `deps_strategy="fragment"`
+ deps_strategy="fragment",
+ )
+```
+
+### 3. Create view and URLs
+
+```py title="[app]/urls.py"
+from django.urls import path
+
+from components.demo import MyPage, Frag
+
+urlpatterns = [
+ path("mypage/", MyPage.as_view())
+ path("mypage/frag", Frag.as_view()),
+]
+```
+
+## Example - AlpineJS
+
+### 1. Define document HTML
+
+This is the HTML into which a fragment will be loaded using AlpineJS.
+
+```djc_py title="[root]/components/demo.py"
+from django_components import Component, types
+
+class MyPage(Component):
+ template = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+
+ OLD
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+```
+
+### 2. Define fragment HTML
+
+The fragment to be inserted into the document.
+
+IMPORTANT: Don't forget to set `deps_strategy="fragment"`
+
+```djc_py title="[root]/components/demo.py"
+class Frag(Component):
+ # NOTE: We wrap the actual fragment in a template tag with x-if="false" to prevent it
+ # from being rendered until we have registered the component with AlpineJS.
+ template = """
+
+
+ 123
+
+
+
+
+ """
+
+ js = """
+ Alpine.data('frag', () => ({
+ fragVal: 'xxx',
+ }));
+
+ // Now that the component has been defined in AlpineJS, we can "activate"
+ // all instances where we use the `x-data="frag"` directive.
+ document.querySelectorAll('[data-name="frag"]').forEach((el) => {
+ el.setAttribute('x-if', 'true');
+ });
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(
+ request=request,
+ # IMPORTANT: Don't forget `deps_strategy="fragment"`
+ deps_strategy="fragment",
+ )
+```
+
+### 3. Create view and URLs
+
+```py title="[app]/urls.py"
+from django.urls import path
+
+from components.demo import MyPage, Frag
+
+urlpatterns = [
+ path("mypage/", MyPage.as_view())
+ path("mypage/frag", Frag.as_view()),
+]
+```
+
+## Example - Vanilla JS
+
+### 1. Define document HTML
+
+This is the HTML into which a fragment will be loaded using vanilla JS.
+
+```djc_py title="[root]/components/demo.py"
+from django_components import Component, types
+
+class MyPage(Component):
+ template = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ OLD
+
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+```
+
+### 2. Define fragment HTML
+
+The fragment to be inserted into the document.
+
+IMPORTANT: Don't forget to set `deps_strategy="fragment"`
+
+```djc_py title="[root]/components/demo.py"
+class Frag(Component):
+ template = """
+
+ 123
+
+
+ """
+
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(
+ request=request,
+ # IMPORTANT: Don't forget `deps_strategy="fragment"`
+ deps_strategy="fragment",
+ )
+```
+
+### 3. Create view and URLs
+
+```py title="[app]/urls.py"
+from django.urls import path
+
+from components.demo import MyPage, Frag
+
+urlpatterns = [
+ path("mypage/", MyPage.as_view())
+ path("mypage/frag", Frag.as_view()),
+]
+```
diff --git a/docs/concepts/advanced/provide_inject.md b/docs/concepts/advanced/provide_inject.md
new file mode 100644
index 00000000..62fe32de
--- /dev/null
+++ b/docs/concepts/advanced/provide_inject.md
@@ -0,0 +1,137 @@
+_New in version 0.80_:
+
+`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).
+
+This is achieved with the combination of:
+
+- [`{% provide %}`](../../../reference/template_tags/#provide) tag
+- [`Component.inject()`](../../../reference/api/#django_components.Component.inject) method
+
+## What is "prop drilling"
+
+Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
+
+Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
+
+This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
+
+A neat solution to avoid prop drilling is using the "provide and inject" technique.
+
+With provide / inject, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
+
+This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/components/provide-inject) and React's [Context / useContext](https://react.dev/learn/passing-data-deeply-with-context).
+
+As the name suggest, using provide / inject consists of 2 steps
+
+1. Providing data
+2. Injecting provided data
+
+For examples of advanced uses of provide / inject, [see this discussion](https://github.com/django-components/django-components/pull/506#issuecomment-2132102584).
+
+## Providing data
+
+First we use the [`{% provide %}`](../../../reference/template_tags/#provide) tag to define the data we want to "provide" (make available).
+
+```django
+{% provide "my_data" hello="hi" another=123 %}
+ {% component "child" / %} <--- Can access "my_data"
+{% endprovide %}
+
+{% component "child" / %} <--- Cannot access "my_data"
+```
+
+The first argument to the [`{% provide %}`](../../../reference/template_tags/#provide) tag is the _key_ by which we can later access the data passed to this tag. The key in this case is `"my_data"`.
+
+The key must resolve to a valid identifier (AKA a valid Python variable name).
+
+Next you define the data you want to "provide" by passing them as keyword arguments. This is similar to how you pass data to the [`{% with %}`](https://docs.djangoproject.com/en/5.2/ref/templates/builtins/#with) tag or the [`{% slot %}`](../../../reference/template_tags/#slot) tag.
+
+!!! note
+
+ Kwargs passed to `{% provide %}` are NOT added to the context.
+ In the example below, the `{{ hello }}` won't render anything:
+
+ ```django
+ {% provide "my_data" hello="hi" another=123 %}
+ {{ hello }}
+ {% endprovide %}
+ ```
+
+Similarly to [slots and fills](../../fundamentals/slots/#dynamic-slots-and-fills), also provide's name argument can be set dynamically via a variable, a template expression, or a spread operator:
+
+```django
+{% with my_name="my_name" %}
+ {% provide name=my_name ... %}
+ ...
+ {% endprovide %}
+{% endwith %}
+```
+
+## Injecting data
+
+To "inject" (access) the data defined on the [`{% provide %}`](../../../reference/template_tags/#provide) tag,
+you can use the [`Component.inject()`](../../../reference/api/#django_components.Component.inject) method from within any other component methods.
+
+For a component to be able to "inject" some data, the component ([`{% component %}`](../../../reference/template_tags/#component) tag) must be nested inside the [`{% provide %}`](../../../reference/template_tags/#provide) tag.
+
+In the example from previous section, we've defined two kwargs: `hello="hi" another=123`. That means that if we now inject `"my_data"`, we get an object with 2 attributes - `hello` and `another`.
+
+```py
+class ChildComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ my_data = self.inject("my_data")
+ print(my_data.hello) # hi
+ print(my_data.another) # 123
+```
+
+First argument to [`Component.inject()`](../../../reference/api/#django_components.Component.inject) is the _key_ (or _name_) of the provided data. This
+must match the string that you used in the [`{% provide %}`](../../../reference/template_tags/#provide) tag.
+
+If no provider with given key is found, [`inject()`](../../../reference/api/#django_components.Component.inject) raises a `KeyError`.
+
+To avoid the error, you can pass a second argument to [`inject()`](../../../reference/api/#django_components.Component.inject). This will act as a default value similar to `dict.get(key, default)`:
+
+```py
+class ChildComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ my_data = self.inject("invalid_key", DEFAULT_DATA)
+ assert my_data == DEFAULT_DATA
+```
+
+!!! note
+
+ The instance returned from [`inject()`](../../../reference/api/#django_components.Component.inject) is immutable (subclass of [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)). This ensures that the data returned from [`inject()`](../../../reference/api/#django_components.Component.inject) will always
+ have all the keys that were passed to the [`{% provide %}`](../../../reference/template_tags/#provide) tag.
+
+!!! warning
+
+ [`inject()`](../../../reference/api/#django_components.Component.inject) works strictly only during render execution. If you try to call `inject()` from outside, it will raise an error.
+
+## Full example
+
+```djc_py
+@register("child")
+class ChildComponent(Component):
+ template = """
+ {{ my_data.hello }}
+ {{ my_data.another }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ my_data = self.inject("my_data", "default")
+ return {"my_data": my_data}
+
+template_str = """
+ {% load component_tags %}
+ {% provide "my_data" hello="hi" another=123 %}
+ {% component "child" / %}
+ {% endprovide %}
+"""
+```
+
+renders:
+
+```html
+hi
+123
+```
diff --git a/docs/concepts/advanced/rendering_js_css.md b/docs/concepts/advanced/rendering_js_css.md
new file mode 100644
index 00000000..21621cca
--- /dev/null
+++ b/docs/concepts/advanced/rendering_js_css.md
@@ -0,0 +1,431 @@
+## Introduction
+
+Components consist of 3 parts - HTML, JS and CSS.
+
+Handling of HTML is straightforward - it is rendered as is, and inserted where
+the [`{% component %}`](../../../reference/template_tags#component) tag is.
+
+However, handling of JS and CSS is more complex:
+
+- JS and CSS is are inserted elsewhere in the HTML. As a best practice, JS is placed in the `` HTML tag, and CSS in the ``.
+- Multiple components may use the same JS and CSS files. We don't want to load the same files multiple times.
+- Fetching of JS and CSS may block the page, so the JS / CSS should be embedded in the HTML.
+- Components inserted as HTML fragments need different handling for JS and CSS.
+
+## Default JS / CSS locations
+
+If your components use JS and CSS then, by default, the JS and CSS will be automatically inserted into the HTML:
+
+- CSS styles will be inserted at the end of the ``
+- JS scripts will be inserted at the end of the ``
+
+If you want to place the dependencies elsewhere in the HTML, you can override
+the locations by inserting following Django template tags:
+
+- [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies) - Set new location(s) for JS scripts
+- [`{% component_css_dependencies %}`](../../../reference/template_tags#component_css_dependencies) - Set new location(s) for CSS styles
+
+So if you have a component with JS and CSS:
+
+```djc_py
+from django_components import Component, types
+
+class MyButton(Component):
+ template: types.django_html = """
+
+ """
+
+ js: types.js = """
+ for (const btnEl of document.querySelectorAll(".my-button")) {
+ btnEl.addEventListener("click", () => {
+ console.log("BUTTON CLICKED!");
+ });
+ }
+ """
+
+ css: types.css """
+ .my-button {
+ background: green;
+ }
+ """
+
+ class Media:
+ js = ["/extra/script.js"]
+ css = ["/extra/style.css"]
+```
+
+Then:
+
+- JS from `MyButton.js` and `MyButton.Media.js` will be rendered at the default place (``),
+ or in [`{% component_js_dependencies %}`](../../../reference/template_tags#component_js_dependencies).
+
+- CSS from `MyButton.css` and `MyButton.Media.css` will be rendered at the default place (``),
+or in [`{% component_css_dependencies %}`](../../../reference/template_tags#component_css_dependencies).
+
+And if you don't specify `{% component_dependencies %}` tags, it is the equivalent of:
+
+```django
+
+
+
+
+ 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/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/autodiscovery.md b/docs/concepts/fundamentals/autodiscovery.md
new file mode 100644
index 00000000..452db11a
--- /dev/null
+++ b/docs/concepts/fundamentals/autodiscovery.md
@@ -0,0 +1,80 @@
+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.
+
+### 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
+
+@register("calendar")
+class Calendar(Component):
+ ...
+```
+
+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`:
+
+```python
+from django.apps import AppConfig
+
+class MyAppConfig(AppConfig):
+ name = "my_app"
+
+ def ready(self) -> None:
+ from components.card.card import Card
+ from components.list.list import List
+ from components.menu.menu import Menu
+ from components.button.button import Button
+ ...
+```
+
+However, there's a simpler way!
+
+### Autodiscovery
+
+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 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 with [`autodiscover=False`](../../../reference/settings#django_components.app_settings.ComponentsSettings.autodiscover).
+
+### Manually trigger autodiscovery
+
+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
+
+autodiscover()
+```
+
+To get the same list of modules that [`autodiscover()`](../../../reference/api#django_components.autodiscover) would return,
+but without importing them, use [`get_component_files()`](../../../reference/api#django_components.get_component_files):
+
+```python
+from django_components import get_component_files
+
+modules = get_component_files(".py")
+```
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 = """
+
+
+ """
+
+ 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/html_attributes.md b/docs/concepts/fundamentals/html_attributes.md
new file mode 100644
index 00000000..22b111d3
--- /dev/null
+++ b/docs/concepts/fundamentals/html_attributes.md
@@ -0,0 +1,697 @@
+_New in version 0.74_:
+
+You can use the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag to render various data
+as `key="value"` HTML attributes.
+
+[`{% 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 }}
+
+
+
+```
+
+You can rewrite it with the [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag:
+
+```django
+
+
+```
+
+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
+
+```
+
+### Removing attributes
+
+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:
+
+```py
+attrs = {
+ "class": "text-green",
+ "required": False,
+ "data-id": None,
+}
+```
+
+And template:
+
+```django
+
+
+```
+
+Then this renders:
+
+```html
+
+```
+
+### Default attributes
+
+Sometimes you may want to specify default values for attributes. You can pass a second positional argument to set the defaults.
+
+```django
+
+ ...
+
+```
+
+In the example above, if `attrs` contains a certain key, e.g. the `class` key, [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) will render:
+
+```html
+
+ ...
+
+```
+
+Otherwise, [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) will render:
+
+```html
+
+ ...
+
+```
+
+### 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
+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 `class` attribute.
+
+We can achieve this by adding extra kwargs. These values
+will be appended, instead of overwriting the previous value.
+
+So if we have a variable `attrs`:
+
+```py
+attrs = {
+ "class": "my-class pa-4",
+}
+```
+
+And on [`{% html_attrs %}`](../../../reference/template_tags#html_attrs) tag, we set the key `class`:
+
+```django
+
+
+```
+
+Then these will be merged and rendered as:
+
+```html
+
+```
+
+To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
+
+```django
+{# my_var = "class-from-var text-red" #}
+
+
+```
+
+Renders:
+
+```html
+
+```
+
+### Merging `class` attributes
+
+The `class` attribute can be specified as a string of class names as usual.
+
+If you want granular control over individual class names, you can use a dictionary.
+
+- **String**: Used as is.
+
+ ```django
+ {% html_attrs class="my-class other-class" %}
+ ```
+
+ Renders:
+
+ ```html
+
+ ```
+
+- **Dictionary**: Keys are the class names, and values are booleans. Only keys with truthy values are rendered.
+
+ ```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:
+
+```py
+class_from_var = "from-var"
+
+attrs = {
+ "class": "from-attrs",
+ "type": "submit",
+}
+
+defaults = {
+ "class": "from-defaults",
+ "role": "button",
+}
+```
+
+Then:
+
+- **Empty tag**
+
+ ```django
+
+ ```
+
+ renders nothing:
+
+ ```html
+
+ ```
+
+- **Only kwargs**
+
+ ```django
+
+ ```
+
+ renders:
+
+ ```html
+
+ ```
+
+- **Only attrs**
+
+ ```django
+
+ ```
+
+ renders:
+
+ ```html
+
+ ```
+
+- **Attrs as kwarg**
+
+ ```django
+
+ ```
+
+ renders:
+
+ ```html
+
+ ```
+
+- **Only defaults (as kwarg)**
+
+ ```django
+
+ ```
+
+ renders:
+
+ ```html
+
+ ```
+
+- **Attrs using the `prefix:key=value` construct**
+
+ ```django
+
+ ```
+
+ renders:
+
+ ```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 = """
+
+ Today's date is {{ date }}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ date = kwargs.pop("date")
+ return {
+ "date": date,
+ "attrs": kwargs,
+ "class_from_var": "extra-class"
+ }
+
+@register("parent")
+class Parent(Component):
+ template: t.django_html = """
+ {% component "my_comp"
+ date=date
+ attrs:class="pa-0 border-solid border-red"
+ attrs:data-json=json_data
+ attrs:@click="(e) => onClick(e, 'from_parent')"
+ / %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": datetime.now(),
+ "json_data": json.dumps({"value": 456})
+ }
+```
+
+Note: For readability, we've split the tags across multiple lines.
+
+Inside `MyComp`, we defined a default attribute
+
+```
+defaults:class="pa-4 text-red"
+```
+
+So if `attrs` includes key `class`, the default above will be ignored.
+
+`MyComp` also defines `class` key twice. It means that whether the `class`
+attribute is taken from `attrs` or `defaults`, the two `class` values
+will be appended to it.
+
+So by default, `MyComp` renders:
+
+```html
+...
+```
+
+Next, let's consider what will be rendered when we call `MyComp` from `Parent`
+component.
+
+`MyComp` accepts a `attrs` dictionary, that is passed to `html_attrs`, so the
+contents of that dictionary are rendered as the HTML attributes.
+
+In `Parent`, we make use of passing dictionary key-value pairs as kwargs to define
+individual attributes as if they were regular kwargs.
+
+So all kwargs that start with `attrs:` will be collected into an `attrs` dict.
+
+```django
+ attrs:class="pa-0 border-solid border-red"
+ attrs:data-json=json_data
+ attrs:@click="(e) => onClick(e, 'from_parent')"
+```
+
+And `get_template_data` of `MyComp` will receive a kwarg named `attrs` with following keys:
+
+```py
+attrs = {
+ "class": "pa-0 border-solid",
+ "data-json": '{"value": 456}',
+ "@click": "(e) => onClick(e, 'from_parent')",
+}
+```
+
+`attrs["class"]` overrides the default value for `class`, whereas other keys
+will be merged.
+
+So in the end `MyComp` will render:
+
+```html
+
+ ...
+
+```
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 = """
+
+ 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 }}
+
+ """
+
+ css: types.css = """
+ .calendar {
+ width: 200px;
+ background: pink;
+ }
+ .calendar span {
+ font-weight: bold;
+ }
+ """
+
+ js: types.js = """
+ (function(){
+ if (document.querySelector(".calendar")) {
+ document.querySelector(".calendar").onclick = () => {
+ alert("Clicked calendar!");
+ };
+ }
+ })()
+ """
+```
+
+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 = """
+ (function(){
+ if (document.querySelector(".calendar-component")) {
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
+ }
+ })()
+ """
+```
+
+### Pycharm (or other Jetbrains IDEs)
+
+With PyCharm (or any other editor from Jetbrains), you don't need to use `types.django_html`, `types.css`, `types.js` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
+
+You only need to write the comments `# language=
+ Today's date is {{ date }}
+
+ """
+
+ # language=CSS
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+
+ # language=JS
+ js = """
+ (function(){
+ if (document.querySelector(".calendar-component")) {
+ document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
+ }
+ })()
+ """
+```
+
+### Markdown code blocks with Pygments
+
+[Pygments](https://pygments.org/) is a syntax highlighting library written in Python. It's also what's used by this documentation site ([mkdocs-material](https://squidfunk.github.io/mkdocs-material/)) to highlight code blocks.
+
+To write code blocks with syntax highlighting, you need to install the [`pygments-djc`](https://pypi.org/project/pygments-djc/) package.
+
+```bash
+pip install pygments-djc
+```
+
+And then initialize it by importing `pygments_djc` somewhere in your project:
+
+```python
+import pygments_djc
+```
+
+Now you can use the `djc_py` code block to write code blocks with syntax highlighting for components.
+
+```txt
+\```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template = """
+
+ Today's date is {{ date }}
+
+ """
+
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+\```
+```
+
+Will be rendered as below. Notice that the CSS and HTML are highlighted correctly:
+
+```djc_py
+from django_components import Component, register
+
+@register("calendar")
+class Calendar(Component):
+ template= """
+
+ Today's date is {{ date }}
+
+ """
+
+ css = """
+ .calendar-component {
+ width: 200px;
+ background: pink;
+ }
+ .calendar-component span {
+ font-weight: bold;
+ }
+ """
+```
diff --git a/docs/concepts/fundamentals/slots.md b/docs/concepts/fundamentals/slots.md
new file mode 100644
index 00000000..7a65dcc4
--- /dev/null
+++ b/docs/concepts/fundamentals/slots.md
@@ -0,0 +1,1094 @@
+django-components has the most extensive slot system of all the popular Python templating engines.
+
+The slot system is based on [Vue](https://vuejs.org/guide/components/slots.html), and works across both Django templates and Python code.
+
+## What are slots?
+
+Components support something called 'slots'.
+
+When you write a component, you define its template. The template will always be
+the same each time you render the component.
+
+However, sometimes you may want to customize the component slightly to change the
+content of the component. This is where slots come in.
+
+Slots allow you to insert parts of HTML into the component.
+This makes components more reusable and composable.
+
+```django
+
+
+```
+
+## Slot anatomy
+
+Slots consists of two parts:
+
+1. [`{% slot %}`](../../../reference/template_tags#slot) tag - Inside your component you decide where you want to insert the content.
+2. [`{% fill %}`](../../../reference/template_tags#fill) tag - In the parent template (outside the component) you decide what content to insert into the slot.
+ It "fills" the slot with the specified content.
+
+Let's look at an example:
+
+First, we define the component template. This component contains two slots, `header` and `body`.
+
+```htmldjango
+
+
+ {# 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 }}??
+ {% endfill %}
+{% endcomponent %}
+```
+
+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 %}
+
+
+
+```
+
+## Slots overview
+
+### Slot definition
+
+Slots are defined with the [`{% slot %}`](../../../reference/template_tags#slot) tag:
+
+```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
+
+ Calendar header
+
+
+ Can you believe it's already 2020-06-06??
+
+
+ {% 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 "other_name" %}
+ Filled content
+ {% endfill %}
+{% endcomponent %}
+```
+
+Or in Python with the [`slots`](../../../reference/api#django_components.Component.render) argument:
+
+```py
+Calendar.render(
+ slots={
+ "name": "Filled content",
+ "other_name": "Filled content",
+ },
+)
+```
+
+### Default slot
+
+You can make the syntax shorter by marking the slot as [`default`](../../../reference/template_tags#slot):
+
+```django
+{% slot "name" default %}
+ Default content
+{% endslot %}
+```
+
+This allows you to fill the slot directly in the [`{% component %}`](../../../reference/template_tags#component) tag,
+omitting the `{% fill %}` tag:
+
+```django
+{% component "calendar" %}
+ Filled content
+{% endcomponent %}
+```
+
+To target the default slot in Python, you can use the `"default"` slot name:
+
+```py
+Calendar.render(
+ slots={"default": "Filled content"},
+)
+```
+
+!!! info "Accessing default slot in Python"
+
+ Since the default slot is stored under the slot name `default`, you can access the default slot
+ in Python under the `"default"` key:
+
+ ```py
+ class MyTable(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ default_slot = slots["default"]
+ return {
+ "default_slot": default_slot,
+ }
+ ```
+
+!!! 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.
+ {% slot "image" default required %}Image here{% endslot %}
+
+
+ {% slot "image" default required %}Image here{% endslot %}
+
+
+ {% 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 %} +``` + +To access the slot data in Python, use the `data` attribute in [slot functions](#slot-functions). + +```py +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"
+ {% 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.
+
+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.
+
+```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 %}
+
+```
+
+### Dynamic slots in table component
+
+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.
+
+So if you pass columns named `name` and `age` to the table component:
+
+```py
+[
+ {"key": "name", "title": "Name"},
+ {"key": "age", "title": "Age"},
+]
+```
+
+Then the component will accept fills named `header-name` and `header-age` (among others):
+
+```django
+{% fill "header-name" data="data" %}
+ {{ data.value }}
+{% endfill %}
+
+{% fill "header-age" data="data" %}
+ {{ data.value }}
+{% endfill %}
+```
+
+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
+
+ {{ name_initials }}
+
+ {% endslot %}
+
+ {# Neither image nor initials given, so slot is required #}
+ {% else %}
+ {% slot "image" default required / %}
+ {% endif %}
+| + {% slot "header-{{ header.key }}" value=header.title %} + {{ header.title }} + {% endslot %} + | + {% endfor %} +
|---|
+ %}
+ ...
+ {% 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.:
+
+```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
+```
diff --git a/docs/concepts/fundamentals/subclassing_components.md b/docs/concepts/fundamentals/subclassing_components.md
new file mode 100644
index 00000000..3d1f0dcb
--- /dev/null
+++ b/docs/concepts/fundamentals/subclassing_components.md
@@ -0,0 +1,155 @@
+In larger projects, you might need to write multiple components with similar behavior.
+In such cases, you can extract shared behavior into a standalone component class to keep things
+[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
+
+When subclassing a component, there's a couple of things to keep in mind:
+
+## Template, JS, and CSS inheritance
+
+When it comes to the pairs:
+
+- [`Component.template`](../../reference/api.md#django_components.Component.template)/[`Component.template_file`](../../reference/api.md#django_components.Component.template_file)
+- [`Component.js`](../../reference/api.md#django_components.Component.js)/[`Component.js_file`](../../reference/api.md#django_components.Component.js_file)
+- [`Component.css`](../../reference/api.md#django_components.Component.css)/[`Component.css_file`](../../reference/api.md#django_components.Component.css_file)
+
+inheritance follows these rules:
+
+- If a child component class defines either member of a pair (e.g., either [`template`](../../reference/api.md#django_components.Component.template) or [`template_file`](../../reference/api.md#django_components.Component.template_file)), it takes precedence and the parent's definition is ignored completely.
+- For example, if a child component defines [`template_file`](../../reference/api.md#django_components.Component.template_file), the parent's [`template`](../../reference/api.md#django_components.Component.template) or [`template_file`](../../reference/api.md#django_components.Component.template_file) will be ignored.
+- This applies independently to each pair - you can inherit the JS while overriding the template, for instance.
+
+For example:
+
+```djc_py
+class BaseCard(Component):
+ template = """
+
+ {% 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.
+
+ """
+ css = """
+ .card {
+ border: 1px solid gray;
+ }
+ """
+ js = """console.log('Base card loaded');"""
+
+# This class overrides parent's template, but inherits CSS and JS
+class SpecialCard(BaseCard):
+ template = """
+ {{ content }}
+
+
+ """
+
+# This class overrides parent's template and CSS, but inherits JS
+class CustomCard(BaseCard):
+ template_file = "custom_card.html"
+ css = """
+ .card {
+ border: 2px solid gold;
+ }
+ """
+```
+
+## Media inheritance
+
+The [`Component.Media`](../../reference/api.md#django_components.Component.Media) nested class follows Django's media inheritance rules:
+
+- If both parent and child define a `Media` class, the child's media will automatically include both its own and the parent's JS and CSS files.
+- This behavior can be configured using the [`extend`](../../reference/api.md#django_components.Component.Media.extend) attribute in the Media class, similar to Django's forms.
+ Read more on this in [Media inheritance](./secondary_js_css_files/#media-inheritance).
+
+For example:
+
+```python
+class BaseModal(Component):
+ template = "✨ {{ content }} ✨
+ Modal content
"
+
+ class Media:
+ css = ["base_modal.css"]
+ js = ["base_modal.js"] # Contains core modal functionality
+
+class FancyModal(BaseModal):
+ class Media:
+ # Will include both base_modal.css/js AND fancy_modal.css/js
+ css = ["fancy_modal.css"] # Additional styling
+ js = ["fancy_modal.js"] # Additional animations
+
+class SimpleModal(BaseModal):
+ class Media:
+ extend = False # Don't inherit parent's media
+ css = ["simple_modal.css"] # Only this CSS will be included
+ js = ["simple_modal.js"] # Only this JS will be included
+```
+
+## Opt out of inheritance
+
+For the following media attributes, when you don't want to inherit from the parent,
+but you also don't need to set the template / JS / CSS to any specific value,
+you can set these attributes to `None`.
+
+- [`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)
+- [`Media`](../../reference/api.md#django_components.Component.Media) class
+
+For example:
+
+```djc_py
+class BaseForm(Component):
+ template = "..."
+ css = "..."
+ js = "..."
+
+ class Media:
+ js = ["form.js"]
+
+# Use parent's template and CSS, but no JS
+class ContactForm(BaseForm):
+ js = None
+ Media = None
+```
+
+## Regular Python inheritance
+
+All other attributes and methods (including the [`Component.View`](../../reference/api.md#django_components.ComponentView) class and its methods) follow standard Python inheritance rules.
+
+For example:
+
+```djc_py
+class BaseForm(Component):
+ template = """
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "form_content": self.get_form_content(),
+ "submit_text": "Submit"
+ }
+
+ def get_form_content(self):
+ return ""
+
+class ContactForm(BaseForm):
+ # Extend parent's "context"
+ # but override "submit_text"
+ def get_template_data(self, args, kwargs, slots, context):
+ context = super().get_template_data(args, kwargs, slots, context)
+ context["submit_text"] = "Send Message"
+ return context
+
+ # Completely override parent's get_form_content
+ def get_form_content(self):
+ return """
+
+
+
+ """
+```
diff --git a/docs/concepts/fundamentals/template_tag_syntax.md b/docs/concepts/fundamentals/template_tag_syntax.md
new file mode 100644
index 00000000..54f59697
--- /dev/null
+++ b/docs/concepts/fundamentals/template_tag_syntax.md
@@ -0,0 +1,279 @@
+All template tags in django_component, like `{% component %}` or `{% slot %}`, and so on,
+support extra syntax that makes it possible to write components like in Vue or React (JSX).
+
+## Self-closing tags
+
+When you have a tag like `{% component %}` or `{% slot %}`, but it has no content, you can simply append a forward slash `/` at the end, instead of writing out the closing tags like `{% endcomponent %}` or `{% endslot %}`:
+
+So this:
+
+```django
+{% component "button" %}{% endcomponent %}
+```
+
+becomes
+
+```django
+{% component "button" / %}
+```
+
+## Special characters
+
+_New in version 0.71_:
+
+Keyword arguments can contain special characters `# @ . - _`, so keywords like
+so are still valid:
+
+```django
+
+ {% component "calendar" my-date="2015-06-19" @click.native=do_something #some_id=True / %}
+
+```
+
+These can then be accessed inside `get_template_data` so:
+
+```py
+@register("calendar")
+class Calendar(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "date": kwargs["my-date"],
+ "id": kwargs["#some_id"],
+ "on_click": kwargs["@click.native"]
+ }
+```
+
+## Spread operator
+
+_New in version 0.93_:
+
+Instead of passing keyword arguments one-by-one:
+
+```django
+{% component "calendar" title="How to abc" date="2015-06-19" author="John Wick" / %}
+```
+
+You can use a spread operator `...dict` to apply key-value pairs from a dictionary:
+
+```py
+post_data = {
+ "title": "How to...",
+ "date": "2015-06-19",
+ "author": "John Wick",
+}
+```
+
+```django
+{% component "calendar" ...post_data / %}
+```
+
+This behaves similar to [JSX's spread operator](https://kevinyckim33.medium.com/jsx-spread-operator-component-props-meaning-3c9bcadd2493)
+or [Vue's `v-bind`](https://vuejs.org/api/built-in-directives.html#v-bind).
+
+Spread operators are treated as keyword arguments, which means that:
+
+1. Spread operators must come after positional arguments.
+2. You cannot use spread operators for [positional-only arguments](https://martinxpn.medium.com/positional-only-and-keyword-only-arguments-in-python-37-100-days-of-python-310c311657b0).
+
+Other than that, you can use spread operators multiple times, and even put keyword arguments in-between or after them:
+
+```django
+{% component "calendar" ...post_data id=post.id ...extra / %}
+```
+
+In a case of conflicts, the values added later (right-most) overwrite previous values.
+
+## Template tags inside literal strings
+
+_New in version 0.93_
+
+When passing data around, sometimes you may need to do light transformations, like negating booleans or filtering lists.
+
+Normally, what you would have to do is to define ALL the variables
+inside `get_template_data()`. But this can get messy if your components contain a lot of logic.
+
+```py
+@register("calendar")
+class Calendar(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "editable": kwargs["editable"],
+ "readonly": not kwargs["editable"],
+ "input_id": f"input-{kwargs['id']}",
+ "icon_id": f"icon-{kwargs['id']}",
+ ...
+ }
+```
+
+Instead, template tags in django_components (`{% component %}`, `{% slot %}`, `{% provide %}`, etc) allow you to treat literal string values as templates:
+
+```django
+{% component 'blog_post'
+ "As positional arg {# yay #}"
+ title="{{ person.first_name }} {{ person.last_name }}"
+ id="{% random_int 10 20 %}"
+ readonly="{{ editable|not }}"
+ author="John Wick {# TODO: parametrize #}"
+/ %}
+```
+
+In the example above, the component receives:
+
+- Positional argument `"As positional arg "` (Comment omitted)
+- `title` - passed as `str`, e.g. `John Doe`
+- `id` - passed as `int`, e.g. `15`
+- `readonly` - passed as `bool`, e.g. `False`
+- `author` - passed as `str`, e.g. `John Wick ` (Comment omitted)
+
+This is inspired by [django-cotton](https://github.com/wrabit/django-cotton#template-expressions-in-attributes).
+
+### Passing data as string vs original values
+
+In the example above, the kwarg `id` was passed as an integer, NOT a string.
+
+When the string literal contains only a single template tag, with no extra text (and no extra whitespace),
+then the value is passed as the original type instead of a string.
+
+Here, `page` is an integer:
+
+```django
+{% component 'blog_post' page="{% random_int 10 20 %}" / %}
+```
+
+Here, `page` is a string:
+
+```django
+{% component 'blog_post' page=" {% random_int 10 20 %} " / %}
+```
+
+And same applies to the `{{ }}` variable tags:
+
+Here, `items` is a list:
+
+```django
+{% component 'cat_list' items="{{ cats|slice:':2' }}" / %}
+```
+
+Here, `items` is a string:
+
+```django
+{% component 'cat_list' items="{{ cats|slice:':2' }} See more" / %}
+```
+
+### Evaluating Python expressions in template
+
+You can even go a step further and have a similar experience to Vue or React,
+where you can evaluate arbitrary code expressions:
+
+```jsx
+
+ Today's date is {{ date }}
+
+```
+
+There's many ways we could approach this:
+
+- Expose the date in a slot
+- Style `.calendar > span` differently on different pages
+- Pass a variable to the component that decides how the date is rendered
+- Create a new component
+
+First two options are more flexible, because the custom styling is not baked into a component's
+implementation. And for the sake of demonstration, we'll solve this challenge with slots.
+
+### 1. What are slots
+
+Components support something called [Slots](../../concepts/fundamentals/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 tags that work hand in hand to make this work. These are...
+
+- `{% slot
+ Today's date is
+ {% slot "date" default %} {# <--- new #}
+ {{ date }}
+ {% endslot %}
+
+```
+
+Notice that:
+
+1. We named the slot `date` - so we can fill this slot by using `{% fill "date" %}`
+
+2. We also made it the [default slot](../../concepts/fundamentals/slots#default-slot).
+
+3. We placed our original implementation inside the [`{% slot %}`](../../reference/template_tags#slot)
+ tag - this is what will be rendered when the slot is NOT overriden.
+
+### 3. Add fill tag
+
+Now we can use [`{% fill %}`](../../reference/template_tags#fill) tags inside the
+[`{% component %}`](../../reference/template_tags#component) tags to override the `date` slot
+to generate the bold and italics variants:
+
+```htmldjango
+{# Default #}
+{% component "calendar" date="2024-12-13" / %}
+
+{# Bold #}
+{% component "calendar" date="2024-12-13" %}
+ 2024-12-13
+{% endcomponent %}
+
+{# Italics #}
+{% component "calendar" date="2024-12-13" %}
+ 2024-12-13
+{% endcomponent %}
+```
+
+Which will render as:
+
+```html
+
+
+ Today's date is 2024-12-13
+
+
+
+
+ Today's date is 2024-12-13
+
+
+
+
+ Today's date is 2024-12-13
+
+```
+
+!!! info
+
+ Since we used the `default` flag on `{% slot "date" %}` inside our calendar component,
+ we can target the `date` component in multiple ways:
+
+ 1. Explicitly by it's name
+ ```htmldjango
+ {% component "calendar" date="2024-12-13" %}
+ {% fill "date" %}
+ 2024-12-13
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+ 2. Implicitly as the [default slot](../../concepts/fundamentals/slots#default-slot) (Omitting the
+ [`{% fill %}`](../../reference/template_tags#fill) tag)
+ ```htmldjango
+ {% component "calendar" date="2024-12-13" %}
+ 2024-12-13
+ {% endcomponent %}
+ ```
+
+ 3. Explicitly as the [default slot](../../concepts/fundamentals/slots#default-slot) (Setting fill name to `default`)
+ ```htmldjango
+ {% component "calendar" date="2024-12-13" %}
+ {% fill "default" %}
+ 2024-12-13
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+### 4. Wait, there's a bug
+
+There is a mistake in our code! `2024-12-13` is Friday, so that's fine. But if we updated
+the to `2024-12-14`, which is Saturday, our template from previous step would render this:
+
+```html
+
+
+ Today's date is 2024-12-16
+
+
+
+
+ Today's date is 2024-12-14
+
+
+
+
+ Today's date is 2024-12-14
+
+```
+
+The first instance rendered `2024-12-16`, while the rest rendered `2024-12-14`!
+
+Why? Remember that in the [`get_template_data()`](../../reference/api#django_components.Component.get_template_data)
+method of our Calendar component, we pre-process the date. If the date falls on Saturday or Sunday, we shift it to next Monday:
+
+```python title="[project root]/components/calendar/calendar.py"
+from datetime import date
+
+from django_components import Component, register
+
+# If date is Sat or Sun, shift it to next Mon, so the date is always workweek.
+def to_workweek_date(d: date):
+ ...
+
+@register("calendar")
+class Calendar(Component):
+ template_file = "calendar.html"
+ ...
+ def get_template_data(self, args, kwargs, slots, context):
+ workweek_date = to_workweek_date(kwargs["date"])
+ return {
+ "date": workweek_date,
+ "extra_class": kwargs.get("extra_class", "text-blue"),
+ }
+```
+
+And the issue is that in our template, we used the `date` value that we used _as input_,
+which is NOT the same as the `date` variable used inside Calendar's template.
+
+### 5. Adding data to slots
+
+We want to use the same `date` variable that's used inside Calendar's template.
+
+Luckily, django-components allows [passing data to slots](../../concepts/fundamentals/slots#slot-data),
+also known as [Scoped slots](https://vuejs.org/guide/components/slots#scoped-slots).
+
+This consists of two steps:
+
+1. Pass the `date` variable to the [`{% slot %}`](../../reference/template_tags#slot) tag
+2. Access the `date` variable in the [`{% fill %}`](../../reference/template_tags#fill)
+ tag by using the special `data` kwarg
+
+Let's update the Calendar's template:
+
+```htmldjango
+
+ Today's date is
+ {% slot "date" default date=date %} {# <--- changed #}
+ {{ date }}
+ {% endslot %}
+
+```
+
+!!! info
+
+ The [`{% slot %}`](../../reference/template_tags#slot) tag has one special kwarg, `name`. When you write
+
+ ```htmldjango
+ {% slot "date" / %}
+ ```
+
+ It's the same as:
+
+ ```htmldjango
+ {% slot name="date" / %}
+ ```
+
+ Other than the `name` kwarg, you can pass any extra kwargs to the [`{% slot %}`](../../reference/template_tags#slot) tag,
+ and these will be exposed as the slot's data.
+
+ ```htmldjango
+ {% slot name="date" kwarg1=123 kwarg2="text" kwarg3=my_var / %}
+ ```
+
+### 6. Accessing slot data in fills
+
+Now, on the [`{% fill %}`](../../reference/template_tags#fill) tags, we can use the `data` kwarg to specify the variable under which
+the slot data will be available.
+
+The variable from the `data` kwarg contains all the extra kwargs passed to the [`{% slot %}`](../../reference/template_tags#slot) tag.
+
+So if we set `data="slot_data"`, then we can access the date variable under `slot_data.date`:
+
+```htmldjango
+{# Default #}
+{% component "calendar" date="2024-12-13" / %}
+
+{# Bold #}
+{% component "calendar" date="2024-12-13" %}
+ {% fill "date" data="slot_data" %}
+ {{ slot_data.date }}
+ {% endfill %}
+{% endcomponent %}
+
+{# Italics #}
+{% component "calendar" date="2024-12-13" %}
+ {% fill "date" data="slot_data" %}
+ {{ slot_data.date }}
+ {% endfill %}
+{% endcomponent %}
+```
+
+By using the `date` variable from the slot, we'll render the correct date
+each time:
+
+```html
+
+
+ Today's date is 2024-12-16
+
+
+
+
+ Today's date is 2024-12-16
+
+
+
+
+ Today's date is 2024-12-16
+
+```
+
+!!! info
+
+ **When to use slots vs variables?**
+
+ Generally, slots are more flexible - you can access the slot data, even the original slot content.
+ Thus, slots behave more like functions that render content based on their context.
+
+ On the other hand, variables are simpler - the variable you pass to a component is what will be used.
+
+ Moreover, slots are treated as part of the template - for example the CSS scoping (work in progress)
+ is applied to the slot content too.
+
+---
+
+So far we've rendered components using template tag. [Next, let’s explore other ways to render components ➡️]
+(./rendering_components.md)
diff --git a/docs/getting_started/components_in_templates.md b/docs/getting_started/components_in_templates.md
new file mode 100644
index 00000000..ae798a8d
--- /dev/null
+++ b/docs/getting_started/components_in_templates.md
@@ -0,0 +1,193 @@
+By the end of this section, we want to be able to use our components in Django templates like so:
+
+```htmldjango
+{% load component_tags %}
+
+
+
+
+ {% component "calendar" / %}
+
+ ```
+
+ Example 2 - Using component defined in a custom registry
+ ```htmldjango
+ {% load my_custom_tags %}
+
+ {% my_component "table" / %}
+
+ ```
+
+ Note that, because the tag name `component` is use by the default ComponentRegistry,
+ the custom registry was configured to use the tag `my_component` instead. [Read more here](../../concepts/advanced/component_registry)
+
+### 2. Load and use the component in template
+
+The component is now registered under the name `calendar`. All that remains to do is to load
+and render the component inside a template:
+
+```htmldjango
+{% load component_tags %} {# Load the default registry #}
+
+
+
+
+ Today's date is {{ date }}
+
+```
+
+and the variable `date` as `"1970-01-01"`.
+
+Thus, the final output will look something like this:
+
+```htmldjango
+
+
+
+
+ Today's date is 1970-01-01
+
+
+
+
+```
+
+This makes it possible to organize your front-end around reusable components, instead of relying on template tags
+and keeping your CSS and Javascript in the static directory.
+
+!!! info
+
+ Remember that you can use
+ [`{% component_js_dependencies %}`](../../reference/template_tags#component_js_dependencies)
+ and [`{% component_css_dependencies %}`](../../reference/template_tags#component_css_dependencies)
+ to change where the `
+
+ ```
+
+ But this has a number of issues:
+
+ - The JS scripts would run for each instance of the component.
+ - Bloating of the HTML file, as each inlined JS or CSS would be included fully for each component.
+ - While this sound OK, this could really bloat the HTML files if we used a UI component library for the basic building blocks like buttons, lists, cards, etc.
+
+## Flow
+
+So the solution should address all the points above. To achieve that, we manage the JS / CSS dependencies ourselves in the browser. So when a full HTML document is loaded, we keep track of which JS and CSS have been loaded. And when an HTML fragment is inserted, we check which JS / CSS dependencies it has, and load only those that have NOT been loaded yet.
+
+This is how we achieve that:
+
+1. When a component is rendered, it inserts an HTML comment containing metadata about the rendered component.
+
+ So a template like this
+
+ ```django
+ {% load component_tags %}
+
+ {% component "my_table" / %}
+
+ {% component "button" %}
+ Click me!
+ {% endcomponent %}
+ ```
+
+ May actually render:
+
+ ```html
+
+
+
+ ...
+
+
+
+
+ ```
+
+ Each `` comment includes comma-separated data - a unique hash for the component class, e.g. `my_table_10bc2c`, and the component ID, e.g. `c020ad`.
+
+ This way, we or the user can freely pass the rendered around or transform it, treating it as a string to add / remove / replace bits. As long as the `` comments remain in the rendered string, we will be able to deduce which JS and CSS dependencies the component needs.
+
+2. Post-process the rendered HTML, extracting the `` comments, and instead inserting the corresponding JS and CSS dependencies.
+
+ If we dealt only with JS, then we could get away with processing the `` comments on the client (browser). However, the CSS needs to be processed still on the server, so the browser receives CSS styles already inserted as `")
- return mark_safe("\n".join(self.media.render_css()))
-
- def render_js_dependencies(self) -> SafeString:
- """Render only JS dependencies available in the media class or provided as a string."""
- if self.js is not None:
- return mark_safe(f"")
- return mark_safe("\n".join(self.media.render_js()))
+ # #####################################
+ # MISC
+ # #####################################
def inject(self, key: str, default: Optional[Any] = None) -> Any:
"""
- Use this method to retrieve the data that was passed to a `{% provide %}` tag
+ Use this method to retrieve the data that was passed to a [`{% provide %}`](../template_tags#provide) tag
with the corresponding key.
To retrieve the data, `inject()` must be called inside a component that's
- inside the `{% provide %}` tag.
+ inside the [`{% provide %}`](../template_tags#provide) tag.
- You may also pass a default that will be used if the `provide` tag with given
- key was NOT found.
+ You may also pass a default that will be used if the [`{% provide %}`](../template_tags#provide) tag
+ with given key was NOT found.
- This method mut be used inside the `get_context_data()` method and raises
- an error if called elsewhere.
+ This method is part of the [Render API](../../concepts/fundamentals/render_api), and
+ raises an error if called from outside the rendering execution.
- Example:
+ Read more about [Provide / Inject](../../concepts/advanced/provide_inject).
+
+ **Example:**
Given this template:
```django
- {% provide "provider" hello="world" %}
- {% component "my_comp" %}
- {% endcomponent %}
+ {% provide "my_provide" message="hello" %}
+ {% component "my_comp" / %}
{% endprovide %}
```
@@ -297,418 +2919,1095 @@ class Component(Generic[ArgsType, KwargsType, DataType, SlotsType], metaclass=Co
@register("my_comp")
class MyComp(Component):
- template = "hi {{ data.hello }}!"
- def get_context_data(self):
- data = self.inject("provider")
- return {"data": data}
+ template = "hi {{ message }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ data = self.inject("my_provide")
+ message = data.message
+ return {"message": message}
```
This renders into:
```
- hi world!
+ hi hello!
```
- As the `{{ data.hello }}` is taken from the "provider".
+ As the `{{ message }}` is taken from the "my_provide" provider.
"""
- if self.input is None:
- raise RuntimeError(
- f"Method 'inject()' of component '{self.name}' was called outside of 'get_context_data()'"
- )
-
- return get_injected_context_var(self.name, self.input.context, key, default)
+ return get_injected_context_var(self.name, self.context, key, default)
@classmethod
def as_view(cls, **initkwargs: Any) -> ViewFn:
"""
Shortcut for calling `Component.View.as_view` and passing component instance to it.
+
+ Read more on [Component views and URLs](../../concepts/fundamentals/component_views_urls).
"""
- # Allow the View class to access this component via `self.component`
- component = cls()
- return component.View.as_view(**initkwargs, component=component)
+
+ # NOTE: `Component.View` may not be available at the time that URLs are being
+ # defined. So we return a view that calls `View.as_view()` only once it's actually called.
+ def outer_view(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ # `view` is a built-in extension defined in `extensions.view`. It subclasses
+ # from Django's `View` class, and adds the `component` attribute to it.
+ view_cls = cast(View, cls.View) # type: ignore[attr-defined]
+
+ # TODO_v1 - Remove `component` and use only `component_cls` instead.
+ inner_view = view_cls.as_view(**initkwargs, component=cls(), component_cls=cls)
+ return inner_view(request, *args, **kwargs)
+
+ return outer_view
+
+ # #####################################
+ # RENDERING
+ # #####################################
@classmethod
def render_to_response(
cls,
context: Optional[Union[Dict[str, Any], Context]] = None,
- slots: Optional[SlotsType] = None,
- escape_slots_content: bool = True,
- args: Optional[ArgsType] = None,
- kwargs: Optional[KwargsType] = None,
- *response_args: Any,
+ args: Optional[Any] = None,
+ kwargs: Optional[Any] = None,
+ slots: Optional[Any] = None,
+ deps_strategy: DependenciesStrategy = "document",
+ # TODO_v1 - Remove, superseded by `deps_strategy`
+ type: Optional[DependenciesStrategy] = None,
+ # TODO_v1 - Remove, superseded by `deps_strategy="ignore"`
+ render_dependencies: bool = True,
+ request: Optional[HttpRequest] = None,
+ outer_context: Optional[Context] = None,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry: Optional[ComponentRegistry] = None,
+ registered_name: Optional[str] = None,
+ node: Optional["ComponentNode"] = None,
**response_kwargs: Any,
) -> HttpResponse:
"""
- Render the component and wrap the content in the response class.
+ Render the component and wrap the content in an HTTP response class.
- The response class is taken from `Component.response_class`. Defaults to `django.http.HttpResponse`.
+ `render_to_response()` takes the same inputs as
+ [`Component.render()`](../api/#django_components.Component.render).
+ See that method for more information.
- This is the interface for the `django.views.View` class which allows us to
- use components as Django views with `component.as_view()`.
+ After the component is rendered, the HTTP response class is instantiated with the rendered content.
- Inputs:
- - `args` - Positional args for the component. This is the same as calling the component
- as `{% component "my_comp" arg1 arg2 ... %}`
- - `kwargs` - Kwargs 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 render function.
- - `escape_slots_content` - Whether the content from `slots` should be escaped.
- - `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.
+ Any additional kwargs are passed to the response class.
- Any additional args and kwargs are passed to the `response_class`.
+ **Example:**
- Example:
- ```py
- MyComponent.render_to_response(
- args=[1, "two", {}],
+ ```python
+ Button.render_to_response(
+ args=["John"],
kwargs={
- "key": 123,
+ "surname": "Doe",
+ "age": 30,
},
slots={
- "header": 'STATIC TEXT HERE',
- "footer": lambda ctx, slot_kwargs, slot_ref: f'CTX: {ctx['hello']} SLOT_DATA: {slot_kwargs['abc']}',
+ "footer": "i AM A SLOT",
},
- escape_slots_content=False,
- # HttpResponse input
+ # HttpResponse kwargs
status=201,
headers={...},
)
# HttpResponse(content=..., status=201, headers=...)
```
+
+ **Custom response class:**
+
+ You can set a custom response class on the component via
+ [`Component.response_class`](../api/#django_components.Component.response_class).
+ Defaults to
+ [`django.http.HttpResponse`](https://docs.djangoproject.com/en/5.2/ref/request-response/#httpresponse-objects).
+
+ ```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)
+ ```
"""
content = cls.render(
args=args,
kwargs=kwargs,
context=context,
slots=slots,
- escape_slots_content=escape_slots_content,
+ deps_strategy=deps_strategy,
+ # TODO_v1 - Remove, superseded by `deps_strategy`
+ type=type,
+ # TODO_v1 - Remove, superseded by `deps_strategy`
+ render_dependencies=render_dependencies,
+ request=request,
+ outer_context=outer_context,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry=registry,
+ registered_name=registered_name,
+ node=node,
)
- return cls.response_class(content, *response_args, **response_kwargs)
+ return cls.response_class(content, **response_kwargs)
@classmethod
def render(
cls,
context: Optional[Union[Dict[str, Any], Context]] = None,
- args: Optional[ArgsType] = None,
- kwargs: Optional[KwargsType] = None,
- slots: Optional[SlotsType] = None,
- escape_slots_content: bool = True,
+ args: Optional[Any] = None,
+ kwargs: Optional[Any] = None,
+ slots: Optional[Any] = None,
+ deps_strategy: DependenciesStrategy = "document",
+ # TODO_v1 - Remove, superseded by `deps_strategy`
+ type: Optional[DependenciesStrategy] = None,
+ # TODO_v1 - Remove, superseded by `deps_strategy="ignore"`
+ render_dependencies: bool = True,
+ request: Optional[HttpRequest] = None,
+ outer_context: Optional[Context] = None,
+ # TODO_v2 - Remove `registered_name` and `registry`
+ registry: Optional[ComponentRegistry] = None,
+ registered_name: Optional[str] = None,
+ node: Optional["ComponentNode"] = None,
) -> str:
"""
- Render the component into a string.
+ Render the component into a string. This is the equivalent of calling
+ the [`{% component %}`](../template_tags#component) tag.
- Inputs:
- - `args` - Positional args for the component. This is the same as calling the component
- as `{% component "my_comp" arg1 arg2 ... %}`
- - `kwargs` - Kwargs 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 render function.
- - `escape_slots_content` - Whether the content from `slots` should be escaped.
- - `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.
-
- Example:
- ```py
- MyComponent.render(
- args=[1, "two", {}],
+ ```python
+ Button.render(
+ args=["John"],
kwargs={
- "key": 123,
+ "surname": "Doe",
+ "age": 30,
},
slots={
- "header": 'STATIC TEXT HERE',
- "footer": lambda ctx, slot_kwargs, slot_ref: f'CTX: {ctx['hello']} SLOT_DATA: {slot_kwargs['abc']}',
+ "footer": "i AM A SLOT",
},
- escape_slots_content=False,
)
```
- """
- # This method may be called as class method or as instance method.
- # If called as class method, create a new instance.
- if isinstance(cls, Component):
- comp: Component = cls
- else:
- comp = cls()
- return comp._render(context, args, kwargs, slots, escape_slots_content)
+ **Inputs:**
- # This is the internal entrypoint for the render function
- def _render(
- self,
- context: Optional[Union[Dict[str, Any], Context]] = None,
- args: Optional[ArgsType] = None,
- kwargs: Optional[KwargsType] = None,
- slots: Optional[SlotsType] = None,
- escape_slots_content: bool = True,
- ) -> str:
- try:
- return self._render_impl(context, args, kwargs, slots, escape_slots_content)
- except Exception as err:
- raise type(err)(f"An error occured while rendering component '{self.name}':\n{repr(err)}") from err
+ - `args` - Optional. A list of positional args for the component. This is the same as calling the component
+ as:
- def _render_impl(
- self,
- context: Optional[Union[Dict[str, Any], Context]] = None,
- args: Optional[ArgsType] = None,
- kwargs: Optional[KwargsType] = None,
- slots: Optional[SlotsType] = None,
- escape_slots_content: bool = True,
- ) -> str:
- has_slots = slots is not None
+ ```django
+ {% component "button" arg1 arg2 ... %}
+ ```
- # Allow to provide no args/kwargs/slots/context
- args = cast(ArgsType, args or ())
- kwargs = cast(KwargsType, kwargs or {})
- slots = cast(SlotsType, slots or {})
- context = context or Context()
+ - `kwargs` - Optional. A dictionary of keyword arguments for the component. This is the same as calling
+ the component as:
- # Allow to provide a dict instead of Context
- # NOTE: This if/else is important to avoid nested Contexts,
- # See https://github.com/EmilStenstrom/django-components/issues/414
- context = context if isinstance(context, Context) else Context(context)
- prepare_context(context, self.component_id)
+ ```django
+ {% component "button" key1=val1 key2=val2 ... %}
+ ```
- # By adding the current input to the stack, we temporarily allow users
- # to access the provided context, slots, etc. Also required so users can
- # call `self.inject()` from within `get_context_data()`.
- self._render_stack.append(
- RenderInput(
- context=context,
- slots=slots,
- args=args,
- kwargs=kwargs,
- escape_slots_content=escape_slots_content,
+ - `slots` - Optional. A dictionary of slot fills. This is the same as passing [`{% fill %}`](../template_tags#fill)
+ tags to the component.
+
+ ```django
+ {% component "button" %}
+ {% fill "content" %}
+ Click me!
+ {% endfill %}
+ {% endcomponent %}
+ ```
+
+ Dictionary keys are the slot names. Dictionary values are the slot fills.
+
+ Slot fills can be strings, render functions, or [`Slot`](../api/#django_components.Slot) instances:
+
+ ```python
+ Button.render(
+ slots={
+ "content": "Click me!"
+ "content2": lambda ctx: "Click me!",
+ "content3": Slot(lambda ctx: "Click me!"),
+ },
)
+ ```
+
+ - `context` - Optional. Plain dictionary or Django's
+ [Context](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context).
+ The context within which the component is rendered.
+
+ When a component is rendered within a template with the [`{% component %}`](../template_tags#component)
+ tag, this will be 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()` directly from Python, you can ignore this input most of the time.
+ Instead use `args`, `kwargs`, and `slots` to pass data to the component.
+
+ 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](../../concepts/fundamentals/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 %}`](../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)
+ ```
+
+ Whether the variables defined in `context` are available to the template depends on the
+ [context behavior mode](../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.
+
+ - `deps_strategy` - Optional. Configure how to handle JS and CSS dependencies. Read more about
+ [Dependencies rendering](../../concepts/fundamentals/rendering_components#dependencies-rendering).
+
+ There are six strategies:
+
+ - [`"document"`](../../concepts/advanced/rendering_js_css#document) (default)
+ - Smartly inserts JS / CSS into placeholders or into `` and `` tags.
+ - Inserts extra script to allow `fragment` types to work.
+ - Assumes the HTML will be rendered in a JS-enabled browser.
+ - [`"fragment"`](../../concepts/advanced/rendering_js_css#fragment)
+ - A lightweight HTML fragment to be inserted into a document with AJAX.
+ - No JS / CSS included.
+ - [`"simple"`](../../concepts/advanced/rendering_js_css#simple)
+ - Smartly insert JS / CSS into placeholders or into `` and `` tags.
+ - No extra script loaded.
+ - [`"prepend"`](../../concepts/advanced/rendering_js_css#prepend)
+ - Insert JS / CSS before the rendered HTML.
+ - No extra script loaded.
+ - [`"append"`](../../concepts/advanced/rendering_js_css#append)
+ - Insert JS / CSS after the rendered HTML.
+ - No extra script loaded.
+ - [`"ignore"`](../../concepts/advanced/rendering_js_css#ignore)
+ - HTML is left as-is. You can still process it with a different strategy later with
+ [`render_dependencies()`](../api/#django_components.render_dependencies).
+ - Used for inserting rendered HTML into other components.
+
+ - `request` - Optional. HTTPRequest object. Pass a request object directly to the component to apply
+ [context processors](https://docs.djangoproject.com/en/5.2/ref/templates/api/#django.template.Context.update).
+
+ Read more about [Working with HTTP requests](../../concepts/fundamentals/http_request).
+
+ **Type hints:**
+
+ `Component.render()` is NOT typed. To add type hints, you can wrap the inputs
+ in component's [`Args`](../api/#django_components.Component.Args),
+ [`Kwargs`](../api/#django_components.Component.Kwargs),
+ and [`Slots`](../api/#django_components.Component.Slots) classes.
+
+ Read more on [Typing and validation](../../concepts/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!"),
+ ),
)
+ ```
+ """ # noqa: 501
- context_data = self.get_context_data(*args, **kwargs)
-
- with context.update(context_data):
- template = self.get_template(context)
- _monkeypatch_template(template)
-
- if context.template is None:
- # Associate the newly-created Context with a Template, otherwise we get
- # an error when we try to use `{% include %}` tag inside the template?
- # See https://github.com/EmilStenstrom/django-components/issues/580
- context.template = template
- context.template_name = template.name
-
- # Set `Template._dc_is_component_nested` based on whether we're currently INSIDE
- # the `{% extends %}` tag.
- # Part of fix for https://github.com/EmilStenstrom/django-components/issues/508
- template._dc_is_component_nested = bool(context.render_context.get(BLOCK_CONTEXT_KEY))
-
- # Support passing slots explicitly to `render` method
- if has_slots:
- fill_content = self._fills_from_slots_data(
- slots,
- escape_slots_content,
+ # TODO_v1 - Remove, superseded by `deps_strategy`
+ if type is not None:
+ if deps_strategy != "document":
+ raise ValueError(
+ "Component.render() received both `type` and `deps_strategy` arguments. "
+ "Only one should be given. The `type` argument is deprecated. Use `deps_strategy` instead."
)
- else:
- fill_content = self.fill_content
+ deps_strategy = type
- # If this is top-level component and it has no parent, use outer context instead
- slot_context_data = context_data
- if not context[_PARENT_COMP_CONTEXT_KEY]:
- slot_context_data = self.outer_context.flatten()
+ # TODO_v1 - Remove, superseded by `deps_strategy="ignore"`
+ if not render_dependencies:
+ deps_strategy = "ignore"
- _, resolved_fills = resolve_slots(
- context,
- template,
- component_name=self.name,
- context_data=slot_context_data,
- fill_content=fill_content,
- )
-
- # Available slot fills - this is internal to us
- updated_slots = {
- **context.get(_FILLED_SLOTS_CONTENT_CONTEXT_KEY, {}),
- **resolved_fills,
- }
-
- # For users, we expose boolean variables that they may check
- # to see if given slot was filled, e.g.:
- # `{% if variable > 8 and component_vars.is_filled.header %}`
- slot_bools = {slot_fill.escaped_name: slot_fill.is_filled for slot_fill in resolved_fills.values()}
-
- with context.update(
- {
- # Private context fields
- _ROOT_CTX_CONTEXT_KEY: self.outer_context,
- _FILLED_SLOTS_CONTENT_CONTEXT_KEY: updated_slots,
- _REGISTRY_CONTEXT_KEY: self.registry,
- # NOTE: Public API for variables accessible from within a component's template
- # See https://github.com/EmilStenstrom/django-components/issues/280#issuecomment-2081180940
- "component_vars": {
- "is_filled": slot_bools,
- },
- }
- ):
- rendered_component = template.render(context)
-
- if is_dependency_middleware_active():
- output = RENDERED_COMMENT_TEMPLATE.format(name=self.name) + rendered_component
- else:
- output = rendered_component
-
- # After rendering is done, remove the current state from the stack, which means
- # properties like `self.context` will no longer return the current state.
- self._render_stack.pop()
-
- return output
-
- def _fills_from_slots_data(
- self,
- slots_data: Mapping[SlotName, SlotContent],
- escape_content: bool = True,
- ) -> Dict[SlotName, FillContent]:
- """Fill component slots outside of template rendering."""
- slot_fills = {}
- for slot_name, content in slots_data.items():
- if isinstance(content, (str, SafeString)):
- content_func = _nodelist_to_slot_render_func(
- NodeList([TextNode(conditional_escape(content) if escape_content else content)])
- )
- else:
-
- def content_func( # type: ignore[misc]
- ctx: Context,
- kwargs: Dict[str, Any],
- slot_ref: SlotRef,
- ) -> SlotResult:
- rendered = content(ctx, kwargs, slot_ref)
- return conditional_escape(rendered) if escape_content else rendered
-
- slot_fills[slot_name] = FillContent(
- content_func=content_func,
- slot_default_var=None,
- slot_data_var=None,
- )
- return slot_fills
-
-
-class ComponentNode(BaseNode):
- """Django.template.Node subclass that renders a django-components component"""
-
- def __init__(
- self,
- name: str,
- args: List[Expression],
- kwargs: RuntimeKwargs,
- registry: ComponentRegistry, # noqa F811
- isolated_context: bool = False,
- fill_nodes: Optional[List[FillNode]] = None,
- node_id: Optional[str] = None,
- ) -> None:
- super().__init__(nodelist=NodeList(fill_nodes), args=args, kwargs=kwargs, node_id=node_id)
-
- self.name = name
- self.isolated_context = isolated_context
- self.fill_nodes = fill_nodes or []
- self.registry = registry
-
- def __repr__(self) -> str:
- return "{{ table_name }}
+ {% component "table" name=table_name / %} + + + ''') + + html = template.render( + Context({ + "table_name": request.GET["name"], + }) + ) + + # This inserts components' JS and CSS + processed_html = render_dependencies(html) + + return HttpResponse(processed_html) + ``` + """ + if strategy not in DEPS_STRATEGIES: + raise ValueError(f"Invalid strategy '{strategy}'") + elif strategy == "ignore": + return content + + is_safestring = isinstance(content, SafeString) + + if isinstance(content, str): + content_ = content.encode() + else: + content_ = cast(bytes, content) + + content_, js_dependencies, css_dependencies = _process_dep_declarations(content_, strategy) + + # Replace the placeholders with the actual content + # If strategy in (`document`, 'simple'), we insert the JS and CSS directly into the HTML, + # where the placeholders were. + # If strategy == `fragment`, we let the client-side manager load the JS and CSS, + # and remove the placeholders. + did_find_js_placeholder = False + did_find_css_placeholder = False + css_replacement = css_dependencies if strategy in ("document", "simple") else b"" + js_replacement = js_dependencies if strategy in ("document", "simple") else b"" + + def on_replace_match(match: "re.Match[bytes]") -> bytes: + nonlocal did_find_css_placeholder + nonlocal did_find_js_placeholder + + if CSS_PLACEHOLDER_NAME_B in match[0]: + replacement = css_replacement + did_find_css_placeholder = True + elif JS_PLACEHOLDER_NAME_B in match[0]: + replacement = js_replacement + did_find_js_placeholder = True + else: + raise RuntimeError( + "Unexpected error: Regex for component dependencies processing" + f" matched unknown string '{match[0].decode()}'" + ) + return replacement + + content_ = PLACEHOLDER_REGEX.sub(on_replace_match, content_) + + # By default ("document") and for "simple" strategy, if user didn't specify any `{% component_dependencies %}`, + # then try to insert the JS scripts at the end of and CSS sheets at the end + # of . + if strategy in ("document", "simple") and (not did_find_js_placeholder or not did_find_css_placeholder): + maybe_transformed = _insert_js_css_to_default_locations( + content_.decode(), + css_content=None if did_find_css_placeholder else css_dependencies.decode(), + js_content=None if did_find_js_placeholder else js_dependencies.decode(), + ) + + if maybe_transformed is not None: + content_ = maybe_transformed.encode() + + # In case of a fragment, we only append the JS (actually JSON) to trigger the call of dependency-manager + elif strategy == "fragment": + content_ += js_dependencies + # For prepend / append, we insert the JS and CSS before / after the content + elif strategy == "prepend": + content_ = js_dependencies + css_dependencies + content_ + elif strategy == "append": + content_ = content_ + js_dependencies + css_dependencies + + # Return the same type as we were given + output = content_.decode() if isinstance(content, str) else content_ + output = mark_safe(output) if is_safestring else output + return cast(TContent, output) + + +# Renamed so we can access use this function where there's kwarg of the same name +_render_dependencies = render_dependencies + + +# Overview of this function: +# 1. We extract all HTML comments like ``. +# 2. We look up the corresponding component classes +# 3. For each component class we get the component's inlined JS and CSS, +# and the JS and CSS from `Media.js/css` +# 4. We add our client-side JS logic into the mix (`django_components/django_components.min.js`) +# - For fragments, we would skip this step. +# 5. For all the above JS and CSS, we figure out which JS / CSS needs to be inserted directly +# into the HTML, and which can be loaded with the client-side manager. +# - Components' inlined JS is inserted directly into the HTML as `` tags in the content + exec_script_data = { + "loadedCssUrls": map_to_base64(loaded_css_urls), + "loadedJsUrls": map_to_base64(loaded_js_urls), + "toLoadCssTags": map_to_base64(to_load_css_tags), + "toLoadJsTags": map_to_base64(to_load_js_tags), + } + + # NOTE: This data is embedded into the HTML as JSON. It is the responsibility of + # the client-side code to detect that this script was inserted, and to load the + # corresponding assets + # See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#embedding_data_in_html + exec_script = json.dumps(exec_script_data) + exec_script = f'' + return exec_script + + +head_or_body_end_tag_re = re.compile(r"<\/(?:head|body)\s*>", re.DOTALL) + + +def _insert_js_css_to_default_locations( + html_content: str, + js_content: Optional[str], + css_content: Optional[str], +) -> Optional[str]: + """ + This function tries to insert the JS and CSS content into the default locations. + + JS is inserted at the end of ``, and CSS is inserted at the end of ``. + + We find these tags by looking for the first `` and last `` tags. + """ + if css_content is None and js_content is None: + return None + + did_modify_html = False + + first_end_head_tag_index = None + last_end_body_tag_index = None + + # First check the content for the first `` and last `` tags + for match in head_or_body_end_tag_re.finditer(html_content): + tag_name = match[0][2:6] + + # We target the first ``, thus, after we set it, we skip the rest + if tag_name == "head": + if css_content is not None and first_end_head_tag_index is None: + first_end_head_tag_index = match.start() + + # But for ``, we want the last occurrence, so we insert the content only + # after the loop. + elif tag_name == "body": + if js_content is not None: + last_end_body_tag_index = match.start() + + else: + raise ValueError(f"Unexpected tag name '{tag_name}'") + + # Then do two string insertions. First the CSS, because we assume that is before . + index_offset = 0 + updated_html = html_content + if css_content is not None and first_end_head_tag_index is not None: + updated_html = updated_html[:first_end_head_tag_index] + css_content + updated_html[first_end_head_tag_index:] + index_offset = len(css_content) + did_modify_html = True + + if js_content is not None and last_end_body_tag_index is not None: + js_index = last_end_body_tag_index + index_offset + updated_html = updated_html[:js_index] + js_content + updated_html[js_index:] + did_modify_html = True + + if did_modify_html: + return updated_html + else: + return None # No changes made + + +######################################################### +# 4. Endpoints for fetching the JS / CSS scripts from within +# the browser, as defined from previous steps. +######################################################### + + +CACHE_ENDPOINT_NAME = "components_cached_script" +_CONTENT_TYPES = {"js": "text/javascript", "css": "text/css"} + + +def _get_content_types(script_type: ScriptType) -> str: + if script_type not in _CONTENT_TYPES: + raise ValueError(f"Unknown script_type '{script_type}'") + + return _CONTENT_TYPES[script_type] + + +def cached_script_view( + req: HttpRequest, + comp_cls_id: str, + script_type: ScriptType, + input_hash: Optional[str] = None, +) -> HttpResponse: + from django_components.component import get_component_by_class_id + + if req.method != "GET": + return HttpResponseNotAllowed(["GET"]) + + try: + comp_cls = get_component_by_class_id(comp_cls_id) + except KeyError: + return HttpResponseNotFound() + + script = get_script_content(script_type, comp_cls, input_hash) + if script is None: + return HttpResponseNotFound() + + content_type = _get_content_types(script_type) + return HttpResponse(content=script, content_type=content_type) + + +urlpatterns = [ + # E.g. `/components/cache/MyTable_a1b2c3.js` or `/components/cache/MyTable_a1b2c3.0ab2c3.js` + path("cache/
+ {output}
+
+ """
+
+ return output
+
+
+class HighlightComponentsDescriptor:
+ def __get__(self, obj: Optional[Any], objtype: Type) -> bool:
+ return app_settings.DEBUG_HIGHLIGHT_COMPONENTS
+
+
+class HighlightSlotsDescriptor:
+ def __get__(self, obj: Optional[Any], objtype: Type) -> bool:
+ return app_settings.DEBUG_HIGHLIGHT_SLOTS
+
+
+class ComponentDebugHighlight(ExtensionComponentConfig):
+ """
+ The interface for `Component.DebugHighlight`.
+
+ The fields of this class are used to configure the component debug highlighting for this component
+ and its direct slots.
+
+ Read more about [Component debug highlighting](../../guides/other/troubleshooting#component-and-slot-highlighting).
+
+ **Example:**
+
+ ```python
+ from django_components import Component
+
+ class MyComponent(Component):
+ class DebugHighlight:
+ highlight_components = True
+ highlight_slots = True
+ ```
+
+ To highlight ALL components and slots, set
+ [extension defaults](../../reference/settings/#django_components.app_settings.ComponentsSettings.extensions_defaults)
+ in your settings:
+
+ ```python
+ from django_components import ComponentsSettings
+
+ COMPONENTS = ComponentsSettings(
+ extensions_defaults={
+ "debug_highlight": {
+ "highlight_components": True,
+ "highlight_slots": True,
+ },
+ },
+ )
+ ```
+ """ # noqa: E501
+
+ # TODO_v1 - Remove `DEBUG_HIGHLIGHT_COMPONENTS` and `DEBUG_HIGHLIGHT_SLOTS`
+ # Instead set this as plain boolean fields.
+ highlight_components = HighlightComponentsDescriptor()
+ """Whether to highlight this component in the rendered output."""
+ highlight_slots = HighlightSlotsDescriptor()
+ """Whether to highlight slots of this component in the rendered output."""
+
+
+# TODO_v1 - Move into standalone extension (own repo?) and ask people to manually add this extension in settings.
+class DebugHighlightExtension(ComponentExtension):
+ """
+ This extension adds the ability to highlight components and slots in the rendered output.
+
+ To highlight slots, set `ComponentsSettings.DEBUG_HIGHLIGHT_SLOTS` to `True` in your settings.
+
+ To highlight components, set `ComponentsSettings.DEBUG_HIGHLIGHT_COMPONENTS` to `True`.
+
+ Highlighting is done by wrapping the content in a `` with a border and a highlight color.
+
+ This extension is automatically added to all components.
+ """
+
+ name = "debug_highlight"
+ ComponentConfig = ComponentDebugHighlight
+
+ # Apply highlight to the slot's rendered output
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> Optional[str]:
+ debug_cls: Optional[ComponentDebugHighlight] = getattr(ctx.component_cls, "DebugHighlight", None)
+ if not debug_cls or not debug_cls.highlight_slots:
+ return None
+
+ return apply_component_highlight("slot", ctx.result, f"{ctx.component_cls.__name__} - {ctx.slot_name}")
+
+ # Apply highlight to the rendered component
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> Optional[str]:
+ debug_cls: Optional[ComponentDebugHighlight] = getattr(ctx.component_cls, "DebugHighlight", None)
+ if not debug_cls or not debug_cls.highlight_components or ctx.result is None:
+ return None
+
+ return apply_component_highlight("component", ctx.result, f"{ctx.component.name} ({ctx.component_id})")
diff --git a/src/django_components/extensions/defaults.py b/src/django_components/extensions/defaults.py
new file mode 100644
index 00000000..a2781d92
--- /dev/null
+++ b/src/django_components/extensions/defaults.py
@@ -0,0 +1,187 @@
+import sys
+from dataclasses import MISSING, Field, dataclass
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, NamedTuple, Optional, Type
+from weakref import WeakKeyDictionary
+
+from django_components.extension import (
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentClassCreatedContext,
+ OnComponentInputContext,
+)
+
+if TYPE_CHECKING:
+ from django_components.component import Component
+
+
+# NOTE: `WeakKeyDictionary` is NOT a generic pre-3.9
+if sys.version_info >= (3, 9):
+ ComponentDefaultsCache = WeakKeyDictionary[Type["Component"], List["ComponentDefaultField"]]
+else:
+ ComponentDefaultsCache = WeakKeyDictionary
+
+
+defaults_by_component: ComponentDefaultsCache = WeakKeyDictionary()
+
+
+@dataclass
+class Default:
+ """
+ Use this class to mark a field on the `Component.Defaults` class as a factory.
+
+ Read more about [Component defaults](../../concepts/fundamentals/component_defaults).
+
+ **Example:**
+
+ ```py
+ from django_components import Default
+
+ class MyComponent(Component):
+ class Defaults:
+ # Plain value doesn't need a factory
+ position = "left"
+ # Lists and dicts need to be wrapped in `Default`
+ # Otherwise all instances will share the same value
+ selected_items = Default(lambda: [1, 2, 3])
+ ```
+ """
+
+ value: Callable[[], Any]
+
+
+class ComponentDefaultField(NamedTuple):
+ """Internal representation of a field on the `Defaults` class."""
+
+ key: str
+ value: Any
+ is_factory: bool
+
+
+# Figure out which defaults are factories and which are not, at class creation,
+# so that the actual creation of the defaults dictionary is simple.
+def _extract_defaults(defaults: Optional[Type]) -> List[ComponentDefaultField]:
+ defaults_fields: List[ComponentDefaultField] = []
+ if defaults is None:
+ return defaults_fields
+
+ for default_field_key in dir(defaults):
+ # Iterate only over fields set by the user (so non-dunder fields).
+ # Plus ignore `component_class` because that was set by the extension system.
+ # TODO_V1 - Remove `component_class`
+ if default_field_key.startswith("__") or default_field_key in {"component_class", "component_cls"}:
+ continue
+
+ default_field = getattr(defaults, default_field_key)
+
+ # If the field was defined with dataclass.field(), take the default / factory from there.
+ if isinstance(default_field, Field):
+ if default_field.default is not MISSING:
+ field_value = default_field.default
+ is_factory = False
+ elif default_field.default_factory is not MISSING:
+ field_value = default_field.default_factory
+ is_factory = True
+ else:
+ field_value = None
+ is_factory = False
+
+ # If the field was defined with our `Default` class, it defined a factory
+ elif isinstance(default_field, Default):
+ field_value = default_field.value
+ is_factory = True
+
+ # If the field was defined with a simple assignment, assume it's NOT a factory.
+ else:
+ field_value = default_field
+ is_factory = False
+
+ field_data = ComponentDefaultField(
+ key=default_field_key,
+ value=field_value,
+ is_factory=is_factory,
+ )
+ defaults_fields.append(field_data)
+
+ return defaults_fields
+
+
+def _apply_defaults(kwargs: Dict, defaults: List[ComponentDefaultField]) -> None:
+ """
+ Apply the defaults from `Component.Defaults` to the given `kwargs`.
+
+ Defaults are applied only to missing or `None` values.
+ """
+ for default_field in defaults:
+ # Defaults are applied only to missing or `None` values
+ given_value = kwargs.get(default_field.key, None)
+ if given_value is not None:
+ continue
+
+ if default_field.is_factory:
+ default_value = default_field.value()
+ else:
+ default_value = default_field.value
+
+ kwargs[default_field.key] = default_value
+
+
+class ComponentDefaults(ExtensionComponentConfig):
+ """
+ The interface for `Component.Defaults`.
+
+ The fields of this class are used to set default values for the component's kwargs.
+
+ Read more about [Component defaults](../../concepts/fundamentals/component_defaults).
+
+ **Example:**
+
+ ```python
+ from django_components import Component, Default
+
+ class MyComponent(Component):
+ class Defaults:
+ position = "left"
+ selected_items = Default(lambda: [1, 2, 3])
+ ```
+ """
+
+ pass
+
+
+class DefaultsExtension(ComponentExtension):
+ """
+ This extension adds a nested `Defaults` class to each `Component`.
+
+ This nested `Defaults` class is used to set default values for the component's kwargs.
+
+ **Example:**
+
+ ```py
+ from django_components import Component, Default
+
+ class MyComponent(Component):
+ class Defaults:
+ position = "left"
+ # Factory values need to be wrapped in `Default`
+ selected_items = Default(lambda: [1, 2, 3])
+ ```
+
+ This extension is automatically added to all components.
+ """
+
+ name = "defaults"
+ ComponentConfig = ComponentDefaults
+
+ # Preprocess the `Component.Defaults` class, if given, so we don't have to do it
+ # each time a component is rendered.
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ defaults_cls = getattr(ctx.component_cls, "Defaults", None)
+ defaults_by_component[ctx.component_cls] = _extract_defaults(defaults_cls)
+
+ # Apply defaults to missing or `None` values in `kwargs`
+ def on_component_input(self, ctx: OnComponentInputContext) -> None:
+ defaults = defaults_by_component.get(ctx.component_cls, None)
+ if defaults is None:
+ return
+
+ _apply_defaults(ctx.kwargs, defaults)
diff --git a/src/django_components/extensions/dependencies.py b/src/django_components/extensions/dependencies.py
new file mode 100644
index 00000000..20c4d444
--- /dev/null
+++ b/src/django_components/extensions/dependencies.py
@@ -0,0 +1,21 @@
+from django_components.dependencies import cache_component_css, cache_component_js
+from django_components.extension import (
+ ComponentExtension,
+ OnComponentClassCreatedContext,
+)
+
+
+class DependenciesExtension(ComponentExtension):
+ """
+ This extension adds a nested `Dependencies` class to each `Component`.
+
+ This extension is automatically added to all components.
+ """
+
+ name = "dependencies"
+
+ # Cache the component's JS and CSS scripts when the class is created, so that
+ # components' JS/CSS files are accessible even before having to render the component first.
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ cache_component_js(ctx.component_cls, force=True)
+ cache_component_css(ctx.component_cls, force=True)
diff --git a/src/django_components/extensions/view.py b/src/django_components/extensions/view.py
new file mode 100644
index 00000000..68b7d47f
--- /dev/null
+++ b/src/django_components/extensions/view.py
@@ -0,0 +1,300 @@
+import sys
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, Optional, Protocol, Type, Union, cast
+from weakref import WeakKeyDictionary
+
+import django.urls
+from django.http import HttpRequest, HttpResponse
+from django.views.generic import View
+
+from django_components.extension import (
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentClassCreatedContext,
+ OnComponentClassDeletedContext,
+ URLRoute,
+ extensions,
+)
+from django_components.util.misc import format_url
+
+if TYPE_CHECKING:
+ from django_components.component import Component
+
+# NOTE: `WeakKeyDictionary` is NOT a generic pre-3.9
+if sys.version_info >= (3, 9):
+ ComponentRouteCache = WeakKeyDictionary[Type["Component"], URLRoute]
+else:
+ ComponentRouteCache = WeakKeyDictionary
+
+
+class ViewFn(Protocol):
+ def __call__(self, request: HttpRequest, *args: Any, **kwargs: Any) -> Any: ... # noqa: E704
+
+
+def _get_component_route_name(component: Union[Type["Component"], "Component"]) -> str:
+ return f"__component_url__{component.class_id}"
+
+
+def get_component_url(
+ component: Union[Type["Component"], "Component"],
+ query: Optional[Dict] = None,
+ fragment: Optional[str] = None,
+) -> str:
+ """
+ Get the URL for a [`Component`](../api#django_components.Component).
+
+ Raises `RuntimeError` if the component is not public.
+
+ Read more about [Component views and URLs](../../concepts/fundamentals/component_views_urls).
+
+ `get_component_url()` optionally accepts `query` and `fragment` arguments.
+
+ **Example:**
+
+ ```py
+ from django_components import Component, get_component_url
+
+ class MyComponent(Component):
+ class View:
+ public = True
+
+ # Get the URL for the component
+ url = get_component_url(
+ MyComponent,
+ query={"foo": "bar"},
+ fragment="baz",
+ )
+ # /components/ext/view/components/c1ab2c3?foo=bar#baz
+ ```
+ """
+ view_cls: Optional[Type[ComponentView]] = getattr(component, "View", None)
+ if not _is_view_public(view_cls):
+ raise RuntimeError("Component URL is not available - Component is not public")
+
+ route_name = _get_component_route_name(component)
+ url = django.urls.reverse(route_name)
+ return format_url(url, query=query, fragment=fragment)
+
+
+class ComponentView(ExtensionComponentConfig, View):
+ """
+ The interface for `Component.View`.
+
+ The fields of this class are used to configure the component views and URLs.
+
+ This class is a subclass of
+ [`django.views.View`](https://docs.djangoproject.com/en/5.2/ref/class-based-views/base/#view).
+ The [`Component`](../api#django_components.Component) class is available
+ via `self.component_cls`.
+
+ Override the methods of this class to define the behavior of the component.
+
+ Read more about [Component views and URLs](../../concepts/fundamentals/component_views_urls).
+
+ **Example:**
+
+ ```python
+ class MyComponent(Component):
+ class View:
+ def get(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return HttpResponse("Hello, world!")
+ ```
+
+ **Component URL:**
+
+ If the `public` attribute is set to `True`, the component will have its own URL
+ that will point to the Component's View.
+
+ ```py
+ from django_components import Component
+
+ class MyComponent(Component):
+ class View:
+ public = True
+
+ def get(self, request, *args, **kwargs):
+ return HttpResponse("Hello, world!")
+ ```
+
+ Will create a URL route like `/components/ext/view/components/a1b2c3/`.
+
+ To get the URL for the component, use [`get_component_url()`](../api#django_components.get_component_url):
+
+ ```py
+ url = get_component_url(MyComponent)
+ ```
+ """
+
+ # NOTE: The `component` / `component_cls` attributes are NOT user input, but still must be declared
+ # on this class for Django's `View.as_view()` to allow us to pass `component` kwarg.
+
+ # TODO_v1 - Remove. Superseded by `component_cls` attribute because we don't actually have access to an instance.
+ component = cast("Component", None)
+ """
+ DEPRECATED: Will be removed in v1.0.
+ Use [`component_cls`](../api#django_components.ComponentView.component_cls) instead.
+
+ This is a dummy instance created solely for the View methods.
+
+ It is the same as if you instantiated the component class directly:
+
+ ```py
+ component = Calendar()
+ component.render_to_response(request=request)
+ ```
+ """
+
+ component_cls = cast(Type["Component"], None)
+ """
+ The parent component class.
+
+ **Example:**
+
+ ```py
+ class MyComponent(Component):
+ class View:
+ def get(self, request):
+ return self.component_cls.render_to_response(request=request)
+ ```
+ """
+
+ def __init__(self, component: "Component", **kwargs: Any) -> None:
+ ComponentExtension.ComponentConfig.__init__(self, component)
+ View.__init__(self, **kwargs)
+
+ @property
+ def url(self) -> str:
+ """
+ The URL for the component.
+
+ Raises `RuntimeError` if the component is not public.
+
+ This is the same as calling [`get_component_url()`](../api#django_components.get_component_url)
+ with the parent [`Component`](../api#django_components.Component) class:
+
+ ```py
+ class MyComponent(Component):
+ class View:
+ def get(self, request):
+ assert self.url == get_component_url(self.component_cls)
+ ```
+ """
+ return get_component_url(self.component_cls)
+
+ # #####################################
+ # PUBLIC API (Configurable by users)
+ # #####################################
+
+ public: ClassVar[bool] = False
+ """
+ Whether the component should be available via a URL.
+
+ **Example:**
+
+ ```py
+ from django_components import Component
+
+ class MyComponent(Component):
+ class View:
+ public = True
+ ```
+
+ Will create a URL route like `/components/ext/view/components/a1b2c3/`.
+
+ To get the URL for the component, use [`get_component_url()`](../api#django_components.get_component_url):
+
+ ```py
+ url = get_component_url(MyComponent)
+ ```
+ """
+
+ # NOTE: The methods below are defined to satisfy the `View` class. All supported methods
+ # are defined in `View.http_method_names`.
+ #
+ # Each method actually delegates to the component's method of the same name.
+ # E.g. When `get()` is called, it delegates to `component.get()`.
+
+ # TODO_V1 - In v1 handlers like `get()` should be defined on the Component.View class,
+ # not the Component class directly. This is to align Views with the extensions API
+ # where each extension should keep its methods in the extension class.
+ # Instead, the defaults for these methods should be something like
+ # `return self.component_cls.render_to_response(request, *args, **kwargs)` or similar
+ # or raise NotImplementedError.
+ def get(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "get")(request, *args, **kwargs)
+
+ def post(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "post")(request, *args, **kwargs)
+
+ def put(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "put")(request, *args, **kwargs)
+
+ def patch(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "patch")(request, *args, **kwargs)
+
+ def delete(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "delete")(request, *args, **kwargs)
+
+ def head(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "head")(request, *args, **kwargs)
+
+ def options(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "options")(request, *args, **kwargs)
+
+ def trace(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+ return getattr(self.component_cls(), "trace")(request, *args, **kwargs)
+
+
+class ViewExtension(ComponentExtension):
+ """
+ This extension adds a nested `View` class to each `Component`.
+
+ This nested class is a subclass of `django.views.View`, and allows the component
+ to be used as a view by calling `ComponentView.as_view()`.
+
+ This extension also allows the component to be available via a unique URL.
+
+ This extension is automatically added to all components.
+ """
+
+ name = "view"
+
+ ComponentConfig = ComponentView
+
+ def __init__(self) -> None:
+ # Remember which route belongs to which component
+ self.routes_by_component: ComponentRouteCache = WeakKeyDictionary()
+
+ # Create URL route on creation
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ comp_cls = ctx.component_cls
+ view_cls: Optional[Type[ComponentView]] = getattr(comp_cls, "View", None)
+ if not _is_view_public(view_cls):
+ return
+
+ # Create a URL route like `components/MyTable_a1b2c3/`
+ # And since this is within the `view` extension, the full URL path will then be:
+ # `/components/ext/view/components/MyTable_a1b2c3/`
+ route_path = f"components/{comp_cls.class_id}/"
+ route_name = _get_component_route_name(comp_cls)
+ route = URLRoute(
+ path=route_path,
+ handler=comp_cls.as_view(),
+ name=route_name,
+ )
+
+ self.routes_by_component[comp_cls] = route
+ extensions.add_extension_urls(self.name, [route])
+
+ # Remove URL route on deletion
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ comp_cls = ctx.component_cls
+ route = self.routes_by_component.pop(comp_cls, None)
+ if route is None:
+ return
+ extensions.remove_extension_urls(self.name, [route])
+
+
+def _is_view_public(view_cls: Optional[Type[ComponentView]]) -> bool:
+ if view_cls is None:
+ return False
+ return getattr(view_cls, "public", False)
diff --git a/src/django_components/finders.py b/src/django_components/finders.py
new file mode 100644
index 00000000..c91b7382
--- /dev/null
+++ b/src/django_components/finders.py
@@ -0,0 +1,170 @@
+import os
+import re
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+from django import VERSION as DJANGO_VERSION
+from django.contrib.staticfiles.finders import BaseFinder
+from django.contrib.staticfiles.utils import get_files
+from django.core.checks import CheckMessage, Error, Warning
+from django.core.files.storage import FileSystemStorage
+from django.utils._os import safe_join
+
+from django_components.app_settings import app_settings
+from django_components.util.loader import get_component_dirs
+from django_components.util.misc import any_regex_match, no_regex_match
+
+# To keep track on which directories the finder has searched the static files.
+searched_locations = []
+
+
+# Custom Finder for staticfiles that searches for all files within the directories
+# defined by `COMPONENTS.dirs`.
+#
+# This is what makes it possible to define JS and CSS files in the directories as
+# defined by `COMPONENTS.dirs`, but still use the JS / CSS files with `static()` or
+# `collectstatic` command.
+class ComponentsFileSystemFinder(BaseFinder):
+ """
+ A static files finder based on `FileSystemFinder`.
+
+ Differences:
+ - This finder uses `COMPONENTS.dirs` setting to locate files instead of `STATICFILES_DIRS`.
+ - Whether a file within `COMPONENTS.dirs` is considered a STATIC file is configured
+ by `COMPONENTS.static_files_allowed` and `COMPONENTS.static_files_forbidden`.
+ - If `COMPONENTS.dirs` is not set, defaults to `settings.BASE_DIR / "components"`
+ """
+
+ def __init__(self, app_names: Any = None, *args: Any, **kwargs: Any) -> None:
+ component_dirs = [str(p) for p in get_component_dirs()]
+
+ # NOTE: The rest of the __init__ is the same as `django.contrib.staticfiles.finders.FileSystemFinder`,
+ # but using our locations instead of STATICFILES_DIRS.
+
+ # List of locations with static files
+ self.locations: List[Tuple[str, str]] = []
+
+ # Maps dir paths to an appropriate storage instance
+ self.storages: Dict[str, FileSystemStorage] = {}
+ for root in component_dirs:
+ if isinstance(root, (list, tuple)):
+ prefix, root = root
+ else:
+ prefix = ""
+ if (prefix, root) not in self.locations:
+ self.locations.append((prefix, root))
+ for prefix, root in self.locations:
+ filesystem_storage = FileSystemStorage(location=root)
+ filesystem_storage.prefix = prefix
+ self.storages[root] = filesystem_storage
+
+ super().__init__(*args, **kwargs)
+
+ # NOTE: Based on `FileSystemFinder.check`
+ def check(self, **kwargs: Any) -> List[CheckMessage]:
+ errors: List[CheckMessage] = []
+ if not isinstance(app_settings.DIRS, (list, tuple)):
+ errors.append(
+ Error(
+ "The COMPONENTS.dirs setting is not a tuple or list.",
+ hint="Perhaps you forgot a trailing comma?",
+ id="components.E001",
+ )
+ )
+ return errors
+ for root in app_settings.DIRS:
+ if isinstance(root, (list, tuple)):
+ prefix, root = root
+ if prefix.endswith("/"):
+ errors.append(
+ Error(
+ "The prefix %r in the COMPONENTS.dirs setting must not end with a slash." % prefix,
+ id="staticfiles.E003",
+ )
+ )
+ elif not os.path.isdir(root):
+ errors.append(
+ Warning(
+ f"The directory '{root}' in the COMPONENTS.dirs setting does not exist.",
+ id="components.W004",
+ )
+ )
+ return errors
+
+ # NOTE: Same as `FileSystemFinder.find`
+ def find(self, path: str, **kwargs: Any) -> Union[List[str], str]:
+ """
+ Look for files in the extra locations as defined in COMPONENTS.dirs.
+ """
+ # Handle deprecated `all` parameter:
+ # - In Django 5.2, the `all` parameter was deprecated in favour of `find_all`.
+ # - Between Django 5.2 (inclusive) and 6.1 (exclusive), the `all` parameter was still
+ # supported, but an error was raised if both were provided.
+ # - In Django 6.1, the `all` parameter was removed.
+ #
+ # See https://github.com/django/django/blob/5.2/django/contrib/staticfiles/finders.py#L58C9-L58C37
+ # And https://github.com/django-components/django-components/issues/1119
+ if DJANGO_VERSION >= (5, 2) and DJANGO_VERSION < (6, 1):
+ find_all = self._check_deprecated_find_param(**kwargs) # type: ignore
+ elif DJANGO_VERSION >= (6, 1):
+ find_all = kwargs.get("find_all", False)
+ else:
+ find_all = kwargs.get("all", False)
+
+ matches: List[str] = []
+ for prefix, root in self.locations:
+ if root not in searched_locations:
+ searched_locations.append(root)
+ matched_path = self.find_location(root, path, prefix)
+ if matched_path:
+ if not find_all:
+ return matched_path
+ matches.append(matched_path)
+ return matches
+
+ # NOTE: Same as `FileSystemFinder.find_local`, but we exclude Python/HTML files
+ def find_location(self, root: str, path: str, prefix: Optional[str] = None) -> Optional[str]:
+ """
+ Find a requested static file in a location and return the found
+ absolute path (or ``None`` if no match).
+ """
+ if prefix:
+ prefix = "%s%s" % (prefix, os.sep)
+ if not path.startswith(prefix):
+ return None
+ path = path.removeprefix(prefix)
+ path = safe_join(root, path)
+
+ if os.path.exists(path) and self._is_path_valid(path):
+ return path
+ return None
+
+ # `Finder.list` is called from `collectstatic` command,
+ # see https://github.com/django/django/blob/bc9b6251e0b54c3b5520e3c66578041cc17e4a28/django/contrib/staticfiles/management/commands/collectstatic.py#L126C23-L126C30 # noqa E501
+ #
+ # NOTE: This is same as `FileSystemFinder.list`, but we exclude Python/HTML files
+ # NOTE 2: Yield can be annotated as Iterable, see https://stackoverflow.com/questions/38419654
+ def list(self, ignore_patterns: List[str]) -> Iterable[Tuple[str, FileSystemStorage]]:
+ """
+ List all files in all locations.
+ """
+ for prefix, root in self.locations:
+ # Skip nonexistent directories.
+ if os.path.isdir(root):
+ storage = self.storages[root]
+ for path in get_files(storage, ignore_patterns):
+ if self._is_path_valid(path):
+ yield path, storage
+
+ def _is_path_valid(self, path: str) -> bool:
+ # Normalize patterns to regexes
+ allowed_patterns = [
+ # Convert suffixes like `.html` to regex `\.html$`
+ re.compile(rf"\{p}$") if isinstance(p, str) else p
+ for p in app_settings.STATIC_FILES_ALLOWED
+ ]
+ forbidden_patterns = [
+ # Convert suffixes like `.html` to regex `\.html$`
+ re.compile(rf"\{p}$") if isinstance(p, str) else p
+ for p in app_settings.STATIC_FILES_FORBIDDEN
+ ]
+ return any_regex_match(path, allowed_patterns) and no_regex_match(path, forbidden_patterns)
diff --git a/src/django_components/library.py b/src/django_components/library.py
index 54dc0aac..5cff7d5f 100644
--- a/src/django_components/library.py
+++ b/src/django_components/library.py
@@ -1,22 +1,42 @@
"""Module for interfacing with Django's Library (`django.template.library`)"""
-from typing import TYPE_CHECKING, Callable, List, Optional
+from typing import Callable, List, Optional
from django.template.base import Node, Parser, Token
from django.template.library import Library
-from django_components.tag_formatter import InternalTagFormatter
-
-if TYPE_CHECKING:
- from django_components.component_registry import ComponentRegistry
-
class TagProtectedError(Exception):
+ """
+ The way the [`TagFormatter`](../../concepts/advanced/tag_formatter) works is that,
+ based on which start and end tags are used for rendering components,
+ the [`ComponentRegistry`](../api#django_components.ComponentRegistry) behind the scenes
+ [un-/registers the template tags](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#registering-the-tag)
+ with the associated instance of Django's
+ [`Library`](https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/#code-layout).
+
+ In other words, if I have registered a component `"table"`, and I use the shorthand
+ syntax:
+
+ ```django
+ {% table ... %}
+ {% endtable %}
+ ```
+
+ Then [`ComponentRegistry`](../api#django_components.ComponentRegistry)
+ registers the tag `table` onto the Django's Library instance.
+
+ However, that means that if we registered a component `"slot"`, then we would overwrite
+ the [`{% slot %}`](../template_tags#slot) tag from django_components.
+
+ Thus, this exception is raised when a component is attempted to be registered under
+ a forbidden name, such that it would overwrite one of django_component's own template tags.
+ """ # noqa: E501
+
pass
PROTECTED_TAGS = [
- "component_dependencies",
"component_css_dependencies",
"component_js_dependencies",
"fill",
@@ -31,26 +51,15 @@ as they would conflict with other tags in the Library.
def register_tag(
- registry: "ComponentRegistry",
+ library: Library,
tag: str,
- tag_fn: Callable[[Parser, Token, "ComponentRegistry", str], Node],
+ tag_fn: Callable[[Parser, Token], Node],
) -> None:
# Register inline tag
- if is_tag_protected(registry.library, tag):
+ if is_tag_protected(library, tag):
raise TagProtectedError('Cannot register tag "%s", this tag name is protected' % tag)
else:
- registry.library.tag(tag, lambda parser, token: tag_fn(parser, token, registry, tag))
-
-
-def register_tag_from_formatter(
- registry: "ComponentRegistry",
- tag_fn: Callable[[Parser, Token, "ComponentRegistry", str], Node],
- formatter: InternalTagFormatter,
- component_name: str,
-) -> str:
- tag = formatter.start_tag(component_name)
- register_tag(registry, tag, tag_fn)
- return tag
+ library.tag(tag, tag_fn)
def mark_protected_tags(lib: Library, tags: Optional[List[str]] = None) -> None:
diff --git a/src/django_components/management/commands/components.py b/src/django_components/management/commands/components.py
new file mode 100644
index 00000000..70424d71
--- /dev/null
+++ b/src/django_components/management/commands/components.py
@@ -0,0 +1,5 @@
+from django_components.commands.components import ComponentsRootCommand
+from django_components.compat.django import load_as_django_command
+
+# TODO_V3
+Command = load_as_django_command(ComponentsRootCommand)
diff --git a/src/django_components/management/commands/startcomponent.py b/src/django_components/management/commands/startcomponent.py
index fb6d6003..d750ef0f 100644
--- a/src/django_components/management/commands/startcomponent.py
+++ b/src/django_components/management/commands/startcomponent.py
@@ -1,151 +1,5 @@
-import os
-from textwrap import dedent
-from typing import Any
+from django_components.commands.startcomponent import StartComponentCommand
+from django_components.compat.django import load_as_django_command
-from django.conf import settings
-from django.core.management.base import BaseCommand, CommandError, CommandParser
-
-
-class Command(BaseCommand):
- help = "Creates a new component"
-
- def add_arguments(self, parser: CommandParser) -> None:
- parser.add_argument("name", type=str, help="The name of the component to create")
- parser.add_argument(
- "--path",
- type=str,
- help="The path to the components directory",
- default=None,
- )
- parser.add_argument(
- "--js",
- type=str,
- help="The name of the javascript file",
- default="script.js",
- )
- parser.add_argument(
- "--css",
- type=str,
- help="The name of the style file",
- default="style.css",
- )
- parser.add_argument(
- "--template",
- type=str,
- help="The name of the template file",
- default="template.html",
- )
- parser.add_argument(
- "--force",
- action="store_true",
- help="Overwrite existing files if they exist",
- )
- parser.add_argument(
- "--verbose",
- action="store_true",
- help="Print additional information during component creation",
- )
- parser.add_argument(
- "--dry-run",
- action="store_true",
- help="Simulate component creation without actually creating any files",
- default=False,
- )
-
- def handle(self, *args: Any, **kwargs: Any) -> None:
- name = kwargs["name"]
-
- if name:
- path = kwargs["path"]
- js_filename = kwargs["js"]
- css_filename = kwargs["css"]
- template_filename = kwargs["template"]
- base_dir = getattr(settings, "BASE_DIR", None)
- force = kwargs["force"]
- verbose = kwargs["verbose"]
- dry_run = kwargs["dry_run"]
-
- if path:
- component_path = os.path.join(path, name)
- elif base_dir:
- component_path = os.path.join(base_dir, "components", name)
- else:
- raise CommandError("You must specify a path or set BASE_DIR in your django settings")
-
- if os.path.exists(component_path):
- if force:
- if verbose:
- self.stdout.write(
- self.style.WARNING(
- f'The component "{name}" already exists at {component_path}. Overwriting...'
- )
- )
- else:
- self.stdout.write(self.style.WARNING(f'The component "{name}" already exists. Overwriting...'))
- else:
- raise CommandError(
- f'The component "{name}" already exists at {component_path}. Use --force to overwrite.'
- )
-
- if not dry_run:
- os.makedirs(component_path, exist_ok=force)
-
- with open(os.path.join(component_path, js_filename), "w") as f:
- script_content = dedent(
- f"""
- window.addEventListener('load', (event) => {{
- console.log("{name} component is fully loaded");
- }});
- """
- )
- f.write(script_content.strip())
-
- with open(os.path.join(component_path, css_filename), "w") as f:
- style_content = dedent(
- f"""
- .component-{name} {{
- background: red;
- }}
- """
- )
- f.write(style_content.strip())
-
- with open(os.path.join(component_path, template_filename), "w") as f:
- template_content = dedent(
- f"""
- [\w\-/]+?) -->")
-PLACEHOLDER_REGEX = re.compile(
- rb""
- rb'|'
- rb'|'
-)
-
-
-@sync_and_async_middleware
-class ComponentDependencyMiddleware:
- """Middleware that inserts CSS/JS dependencies for all rendered components at points marked with template tags."""
-
- dependency_regex = COMPONENT_COMMENT_REGEX
-
- def __init__(self, get_response: "Callable[[HttpRequest], HttpResponse]") -> None:
- self.get_response = get_response
-
- if iscoroutinefunction(self.get_response):
- markcoroutinefunction(self)
-
- def __call__(self, request: HttpRequest) -> HttpResponseBase:
-
- if iscoroutinefunction(self):
- return self.__acall__(request)
-
- response = self.get_response(request)
- response = self.process_response(response)
- return response
-
- async def __acall__(self, request: HttpRequest) -> HttpResponseBase:
-
- response = await self.get_response(request)
- response = self.process_response(response)
- return response
-
- def process_response(self, response: HttpResponse) -> HttpResponse:
- if (
- getattr(settings, "COMPONENTS", {}).get("RENDER_DEPENDENCIES", False)
- and not isinstance(response, StreamingHttpResponse)
- and response.get("Content-Type", "").startswith("text/html")
- ):
- response.content = process_response_content(response.content)
-
- return response
-
-
-def process_response_content(content: bytes) -> bytes:
- component_names_seen = {match.group("name") for match in COMPONENT_COMMENT_REGEX.finditer(content)}
- all_components = [registry.get(name.decode("utf-8"))("") for name in component_names_seen]
- all_media = join_media(all_components)
- js_dependencies = b"".join(media.encode("utf-8") for media in all_media.render_js())
- css_dependencies = b"".join(media.encode("utf-8") for media in all_media.render_css())
- return PLACEHOLDER_REGEX.sub(DependencyReplacer(css_dependencies, js_dependencies), content)
-
-
-def add_module_attribute_to_scripts(scripts: str) -> str:
- return re.sub(SCRIPT_TAG_REGEX, '');
+ * ```
+ *
+ * ```js
+ * Components.loadCss('');
+ * ```
+ *
+ * ```js
+ * Components.markScriptLoaded("js", '/abc/def');
+ * ```
+ */
+export const createComponentsManager = () => {
+ const loadedJs = new Set();
+ const loadedCss = new Set();
+ const components: Record = {};
+ const componentInputs: Record = {};
+
+ const parseScriptTag = (tag: string) => {
+ const scriptNode = new DOMParser().parseFromString(tag, 'text/html').querySelector('script');
+ if (!scriptNode) {
+ throw Error(
+ '[Components] Failed to extract and is a valid HTML'
+ );
+ }
+ return scriptNode;
+ };
+
+ const parseLinkTag = (tag: string) => {
+ const linkNode = new DOMParser().parseFromString(tag, 'text/html').querySelector('link');
+ if (!linkNode) {
+ throw Error(
+ '[Components] Failed to extract tag. Make sure that the string contains' +
+ ' and is a valid HTML'
+ );
+ }
+ return linkNode;
+ };
+
+ // NOTE: The way we turn the string into an HTMLElement, if we then try to
+ // insert the node into the Document, it will NOT load. So instead we create
+ // a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
- Hello from {name} component!
-
- This is {{ param }} context value. -
- """
- )
- f.write(template_content.strip())
-
- with open(os.path.join(component_path, f"{name}.py"), "w") as f:
- py_content = dedent(
- f"""
- from django_components import Component, register
-
- @register("{name}")
- class {name.capitalize()}(Component):
- template_name = "{name}/{template_filename}"
-
- def get_context_data(self, value):
- return {{
- "param": "sample value",
- }}
-
- class Media:
- css = "{name}/{css_filename}"
- js = "{name}/{js_filename}"
- """
- )
- f.write(py_content.strip())
-
- if verbose:
- self.stdout.write(self.style.SUCCESS(f"Successfully created {name} component at {component_path}"))
- else:
- self.stdout.write(self.style.SUCCESS(f"Successfully created {name} component"))
- else:
- raise CommandError("You must specify a component name")
+# TODO_V3
+Command = load_as_django_command(StartComponentCommand)
diff --git a/src/django_components/management/commands/upgradecomponent.py b/src/django_components/management/commands/upgradecomponent.py
index 1f14de07..3c5f5ce7 100644
--- a/src/django_components/management/commands/upgradecomponent.py
+++ b/src/django_components/management/commands/upgradecomponent.py
@@ -1,69 +1,5 @@
-import os
-import re
-from pathlib import Path
-from typing import Any
+from django_components.commands.upgradecomponent import UpgradeComponentCommand
+from django_components.compat.django import load_as_django_command
-from django.conf import settings
-from django.core.management.base import BaseCommand, CommandParser
-from django.template.engine import Engine
-
-from django_components.template_loader import Loader
-
-
-class Command(BaseCommand):
- help = "Updates component and component_block tags to the new syntax"
-
- def add_arguments(self, parser: CommandParser) -> None:
- parser.add_argument("--path", type=str, help="Path to search for components")
-
- def handle(self, *args: Any, **options: Any) -> None:
- current_engine = Engine.get_default()
- loader = Loader(current_engine)
- dirs = loader.get_dirs()
-
- if settings.BASE_DIR:
- dirs.append(Path(settings.BASE_DIR) / "templates")
-
- if options["path"]:
- dirs = [options["path"]]
-
- for dir_path in dirs:
- self.stdout.write(f"Searching for components in {dir_path}...")
- for root, _, files in os.walk(dir_path):
- for file in files:
- if file.endswith((".html", ".py")):
- file_path = os.path.join(root, file)
- with open(file_path, "r+", encoding="utf-8") as f:
- content = f.read()
- content_with_closed_components, step0_count = re.subn(
- r'({%\s*component\s*"(\w+?)"(.*?)%})(?!.*?{%\s*endcomponent\s*%})',
- r"\1{% endcomponent %}",
- content,
- flags=re.DOTALL,
- )
- updated_content, step1_count_opening = re.subn(
- r'{%\s*component_block\s*"(\w+?)"\s*(.*?)%}',
- r'{% component "\1" \2%}',
- content_with_closed_components,
- flags=re.DOTALL,
- )
- updated_content, step2_count_closing = re.subn(
- r'{%\s*endcomponent_block\s*"(\w+?)"\s*%}',
- r"{% endcomponent %}",
- updated_content,
- flags=re.DOTALL,
- )
- updated_content, step2_count_closing_no_name = re.subn(
- r"{%\s*endcomponent_block\s*%}",
- r"{% endcomponent %}",
- updated_content,
- flags=re.DOTALL,
- )
- total_updates = (
- step0_count + step1_count_opening + step2_count_closing + step2_count_closing_no_name
- )
- if total_updates > 0:
- f.seek(0)
- f.write(updated_content)
- f.truncate()
- self.stdout.write(f"Updated {file_path}: {total_updates} changes made")
+# TODO_V3
+Command = load_as_django_command(UpgradeComponentCommand)
diff --git a/src/django_components/middleware.py b/src/django_components/middleware.py
deleted file mode 100644
index 44fc32e8..00000000
--- a/src/django_components/middleware.py
+++ /dev/null
@@ -1,109 +0,0 @@
-import re
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Iterable
-
-from asgiref.sync import iscoroutinefunction, markcoroutinefunction
-from django.conf import settings
-from django.forms import Media
-from django.http import HttpRequest, HttpResponse, StreamingHttpResponse
-from django.http.response import HttpResponseBase
-from django.utils.decorators import sync_and_async_middleware
-
-from django_components.component_registry import registry
-
-if TYPE_CHECKING:
- from django_components.component import Component
-
-RENDERED_COMPONENTS_CONTEXT_KEY = "_COMPONENT_DEPENDENCIES"
-CSS_DEPENDENCY_PLACEHOLDER = ''
-JS_DEPENDENCY_PLACEHOLDER = ''
-
-SCRIPT_TAG_REGEX = re.compile("- This is {{ param }} context value. -
+ Attachments:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Edit
+
+
+
+
+
+ -
+
+
-
+
+ + + + + + + + + Homepage + + + + ++ +
+
+
+
+
-
+
+ + + + + + + + + Projects + + + + ++ +
+
+
+
- + + + + + + + + Project Name + + + + + + + + +
-
+
+ + + + + + + + + Page 3 + + + + ++ +
+
+
+
+
-
+
+ + + + + + + + + Page 4 + + + + ++ +
+
+
+
+
-
+
+ + + + + + + + + Page 5 + + + + ++ +
+
+
+
+
-
+
+ + + + + + + + + FAQ + + + + ++ +
+
+
+
+
+
+
+
+
+
+
+
+ FAQ
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Feedback
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Project Name
+
+ 2022-02-06 - 2024-02-07
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
-
+ +++ + + + ++
+ Phase 1 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 2 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 3 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 4 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 5 +
+ + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
+
- + + Project Info + + + + + +
- + + Notes 1 + + + + + +
- + + Notes 2 + + + + + +
- + + Notes 3 + + + + + +
- + + Outputs + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Project Info
+ + + + + + + + + + Edit Project + + + + + + +| + Org: + | ++ Org Name + | +
| + Duration: + | ++ 2022-02-06 - 2024-02-07 + | +
| + Status: + | ++ INPROGRESS + | +
| + Tags: + | ++ - + | +
+
+
+
+
+
+ Status Updates
+ + + + + + + + + Add status update + + + + + + +
+
+
+
+
+
+
+
+
+
+
+ Team
+ + + + + + + + + + Edit Team + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ | + + + Name + + + | + ++ + + Role + + + | + ++ + + + + + | + +
|---|---|---|
| + + + + UserName + + + + | + + + ++ + + + Assistant + + + + | + + + ++ + + + + + + + | + +
| + + + + UserName + + + + | + + + ++ + + + Owner + + + + | + + + ++ + + + + + + + | + +
+
+
+
+
+
+ Contacts
+ + + + + + + + + + Edit Contacts + + + + + + +No entries
+ +
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+ 2025-02-07T08:59:58.689Z
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ + Test note 1 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+ 2025-02-07T08:59:58.689Z
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ + Test note 2 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+ 2024-02-07T11:20:49.085Z
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ + Test note x +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+ 2024-02-07T11:20:49.085Z
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ + Test note 2 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+ <h3 class="m-0">
+ Phase 1
+ </h3>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 12
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+ <h3 class="m-0">
+ Phase 2
+ </h3>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 16
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ Missing '' from
+
+
+
+
+
+
+
+
+ Phase_3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This output does not have any attachments.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 9
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 8
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 7
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 6
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 16
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+ Missing '' from
+
+
+
+
+
+
+
+
+ Phase_3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This output does not have any attachments.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+ <h3 class="m-0">
+ Phase 3
+ </h3>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 16
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 15
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 14
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 13
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+ <h3 class="m-0">
+ Phase 4
+ </h3>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 5
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 4
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+ <h3 class="m-0">
+ Phase 5
+ </h3>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <div>
+ Lorem ipsum 3
+ </div>
+
+
+
+
+
+
+
+
+
+
+
+
+
+ None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ '''
+# ---
diff --git a/tests/__snapshots__/test_benchmark_djc_small.ambr b/tests/__snapshots__/test_benchmark_djc_small.ambr
new file mode 100644
index 00000000..e2df3350
--- /dev/null
+++ b/tests/__snapshots__/test_benchmark_djc_small.ambr
@@ -0,0 +1,21 @@
+# serializer version: 1
+# name: test_render
+ '''
+
+
+
+
+
+
+
+ Click me!
+
+
+
+
+
+ '''
+# ---
diff --git a/tests/components/_ignored_dir/__init__.py b/tests/components/_ignored_dir/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/components/_ignored_dir/ignored_file.py b/tests/components/_ignored_dir/ignored_file.py
new file mode 100644
index 00000000..e3565370
--- /dev/null
+++ b/tests/components/_ignored_dir/ignored_file.py
@@ -0,0 +1,2 @@
+# This file checks that the autodiscovery does not load files from
+# subdirs that start with an underscore.
diff --git a/tests/components/_ignored_file.py b/tests/components/_ignored_file.py
new file mode 100644
index 00000000..4cc290af
--- /dev/null
+++ b/tests/components/_ignored_file.py
@@ -0,0 +1 @@
+# This file checks that the autodiscovery does not load files that start with an underscore.
diff --git a/tests/components/glob/glob.py b/tests/components/glob/glob.py
new file mode 100644
index 00000000..803a32e8
--- /dev/null
+++ b/tests/components/glob/glob.py
@@ -0,0 +1,77 @@
+
+from django_components import Component
+
+
+# The Media JS / CSS glob and are relative to the component directory
+class GlobComponent(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
+ class Media:
+ css = "glob_*.css"
+ js = "glob_*.js"
+
+
+# The Media JS / CSS glob and are relative to the directory given in
+# `COMPONENTS.dirs` and `COMPONENTS.app_dirs`
+class GlobComponentRootDir(GlobComponent):
+ class Media:
+ css = "glob/glob_*.css"
+ js = "glob/glob_*.js"
+
+
+# The Media JS / CSS are NOT globs and are relative to the directory given in
+# `COMPONENTS.dirs` and `COMPONENTS.app_dirs`. These should NOT be modified.
+class NonGlobComponentRootDir(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
+ class Media:
+ css = "glob/glob_1.css"
+ js = "glob/glob_1.js"
+
+
+# The Media JS / CSS are NOT globs. While relative to the directory given in
+# `COMPONENTS.dirs` and `COMPONENTS.app_dirs`, these files do not exist.
+# These paths should NOT be modified.
+class NonGlobNonexistComponentRootDir(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
+ class Media:
+ css = "glob/glob_nonexist.css"
+ js = "glob/glob_nonexist.js"
+
+
+# The Media JS / CSS are NOT globs, but URLs.
+class UrlComponent(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
+ class Media:
+ css = [
+ "https://example.com/example/style.min.css",
+ "http://example.com/example/style.min.css",
+ # :// is not a valid URL - will be resolved as static path
+ "://example.com/example/style.min.css",
+ "/path/to/style.css",
+ ]
+ js = [
+ "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.0.2/chart.min.js",
+ "http://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.0.2/chart.min.js",
+ # :// is not a valid URL - will be resolved as static path
+ "://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.0.2/chart.min.js",
+ "/path/to/script.js",
+ ]
diff --git a/tests/components/safer_staticfiles/safer_staticfiles.css b/tests/components/glob/glob_1.css
similarity index 100%
rename from tests/components/safer_staticfiles/safer_staticfiles.css
rename to tests/components/glob/glob_1.css
diff --git a/tests/components/safer_staticfiles/safer_staticfiles.js b/tests/components/glob/glob_1.js
similarity index 100%
rename from tests/components/safer_staticfiles/safer_staticfiles.js
rename to tests/components/glob/glob_1.js
diff --git a/tests/components/glob/glob_2.css b/tests/components/glob/glob_2.css
new file mode 100644
index 00000000..3b07560d
--- /dev/null
+++ b/tests/components/glob/glob_2.css
@@ -0,0 +1,3 @@
+.html-css-only {
+ color: blue;
+}
diff --git a/tests/components/glob/glob_2.js b/tests/components/glob/glob_2.js
new file mode 100644
index 00000000..5a73c14a
--- /dev/null
+++ b/tests/components/glob/glob_2.js
@@ -0,0 +1 @@
+console.log("JS file");
diff --git a/tests/components/multi_file/multi_file.py b/tests/components/multi_file/multi_file.py
index e6e7135b..167d6cec 100644
--- a/tests/components/multi_file/multi_file.py
+++ b/tests/components/multi_file/multi_file.py
@@ -7,14 +7,21 @@ from django_components import Component, register
@register("multi_file_component")
class MultFileComponent(Component):
- template_name = "multi_file/multi_file.html"
+ template_file = "multi_file/multi_file.html"
- def post(self, request, *args, **kwargs) -> HttpResponse:
- variable = request.POST.get("variable")
- return self.render_to_response({"variable": variable})
+ class View:
+ def post(self, request, *args, **kwargs) -> HttpResponse:
+ variable = request.POST.get("variable")
+ return MultFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": variable},
+ )
- def get(self, request, *args, **kwargs) -> HttpResponse:
- return self.render_to_response({"variable": "GET"})
+ def get(self, request, *args, **kwargs) -> HttpResponse:
+ return MultFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": "GET"},
+ )
- def get_context_data(self, variable, *args, **kwargs) -> Dict[str, Any]:
- return {"variable": variable}
+ def get_template_data(self, args, kwargs, slots, context) -> Dict[str, Any]:
+ return {"variable": kwargs["variable"]}
diff --git a/tests/components/relative_file/relative_file.py b/tests/components/relative_file/relative_file.py
index 2cb93ed5..429827ac 100644
--- a/tests/components/relative_file/relative_file.py
+++ b/tests/components/relative_file/relative_file.py
@@ -7,18 +7,25 @@ from django_components import Component, register
@register("relative_file_component")
class RelativeFileComponent(Component):
- template_name = "relative_file.html"
+ template_file = "relative_file.html"
class Media:
js = "relative_file.js"
css = "relative_file.css"
- def post(self, request, *args, **kwargs) -> HttpResponse:
- variable = request.POST.get("variable")
- return self.render_to_response({"variable": variable})
+ class View:
+ def post(self, request, *args, **kwargs) -> HttpResponse:
+ variable = request.POST.get("variable")
+ return RelativeFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": variable},
+ )
- def get(self, request, *args, **kwargs) -> HttpResponse:
- return self.render_to_response({"variable": "GET"})
+ def get(self, request, *args, **kwargs) -> HttpResponse:
+ return RelativeFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": "GET"},
+ )
- def get_context_data(self, variable, *args, **kwargs) -> Dict[str, Any]:
- return {"variable": variable}
+ def get_template_data(self, args, kwargs, slots, context) -> Dict[str, Any]:
+ return {"variable": kwargs["variable"]}
diff --git a/tests/components/relative_file_pathobj/relative_file_pathobj.html b/tests/components/relative_file_pathobj/relative_file_pathobj.html
index e2f403bd..c63233de 100644
--- a/tests/components/relative_file_pathobj/relative_file_pathobj.html
+++ b/tests/components/relative_file_pathobj/relative_file_pathobj.html
@@ -1,3 +1,6 @@
+{% load component_tags %}
+{% component_js_dependencies %}
+{% component_css_dependencies %}
"""
- def post(self, request, *args, **kwargs) -> HttpResponse:
- variable = request.POST.get("variable")
- return self.render_to_response({"variable": variable})
+ class View:
+ def post(self, request, *args, **kwargs) -> HttpResponse:
+ variable = request.POST.get("variable")
+ return SingleFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": variable},
+ )
- def get(self, request, *args, **kwargs) -> HttpResponse:
- return self.render_to_response({"variable": "GET"})
+ def get(self, request, *args, **kwargs) -> HttpResponse:
+ return SingleFileComponent.render_to_response(
+ request=request,
+ kwargs={"variable": "GET"},
+ )
- def get_context_data(self, variable, *args, **kwargs) -> Dict[str, Any]:
- return {"variable": variable}
+ def get_template_data(self, args, kwargs, slots, context) -> Dict[str, Any]:
+ return {"variable": kwargs["variable"]}
diff --git a/tests/components/staticfiles/staticfiles.css b/tests/components/staticfiles/staticfiles.css
new file mode 100644
index 00000000..3b07560d
--- /dev/null
+++ b/tests/components/staticfiles/staticfiles.css
@@ -0,0 +1,3 @@
+.html-css-only {
+ color: blue;
+}
diff --git a/tests/components/safer_staticfiles/safer_staticfiles.html b/tests/components/staticfiles/staticfiles.html
similarity index 100%
rename from tests/components/safer_staticfiles/safer_staticfiles.html
rename to tests/components/staticfiles/staticfiles.html
diff --git a/tests/components/staticfiles/staticfiles.js b/tests/components/staticfiles/staticfiles.js
new file mode 100644
index 00000000..5a73c14a
--- /dev/null
+++ b/tests/components/staticfiles/staticfiles.js
@@ -0,0 +1 @@
+console.log("JS file");
diff --git a/tests/components/staticfiles/staticfiles.py b/tests/components/staticfiles/staticfiles.py
new file mode 100644
index 00000000..ba4f07fa
--- /dev/null
+++ b/tests/components/staticfiles/staticfiles.py
@@ -0,0 +1,16 @@
+from typing import Any, Dict
+
+from django_components import Component, register
+
+
+# Used for testing the staticfiles finder in `test_staticfiles.py`
+@register("staticfiles_component")
+class RelativeFileWithPathObjComponent(Component):
+ template_file = "staticfiles.html"
+
+ class Media:
+ js = "staticfiles.js"
+ css = "staticfiles.css"
+
+ def get_template_data(self, args, kwargs, slots, context) -> Dict[str, Any]:
+ return {"variable": kwargs["variable"]}
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..53ad1dd6
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,9 @@
+import pytest
+
+from tests.e2e.utils import run_django_dev_server
+
+
+@pytest.fixture(scope="session", autouse=True)
+def django_dev_server():
+ """Fixture to run Django development server in the background."""
+ yield from run_django_dev_server()
diff --git a/tests/django_test_setup.py b/tests/django_test_setup.py
deleted file mode 100644
index 84797f7e..00000000
--- a/tests/django_test_setup.py
+++ /dev/null
@@ -1,37 +0,0 @@
-from pathlib import Path
-from typing import Dict, Optional
-
-import django
-from django.conf import settings
-
-
-def setup_test_config(components: Optional[Dict] = None):
- if settings.configured:
- return
-
- settings.configure(
- BASE_DIR=Path(__file__).resolve().parent,
- INSTALLED_APPS=("django_components",),
- TEMPLATES=[
- {
- "BACKEND": "django.template.backends.django.DjangoTemplates",
- "DIRS": [
- "tests/templates/",
- "tests/components/", # Required for template relative imports in tests
- ],
- }
- ],
- COMPONENTS={
- "template_cache_size": 128,
- **(components or {}),
- },
- MIDDLEWARE=["django_components.middleware.ComponentDependencyMiddleware"],
- DATABASES={
- "default": {
- "ENGINE": "django.db.backends.sqlite3",
- "NAME": ":memory:",
- }
- },
- )
-
- django.setup()
diff --git a/tests/e2e/__init__.py b/tests/e2e/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/e2e/testserver/__init__.py b/tests/e2e/testserver/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/e2e/testserver/manage.py b/tests/e2e/testserver/manage.py
new file mode 100755
index 00000000..41d7d771
--- /dev/null
+++ b/tests/e2e/testserver/manage.py
@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+
+def main():
+ """Run administrative tasks."""
+ os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testserver.settings")
+ try:
+ from django.core.management import execute_from_command_line
+ except ImportError as exc:
+ raise ImportError(
+ "Couldn't import Django. Are you sure it's installed and "
+ "available on your PYTHONPATH environment variable? Did you "
+ "forget to activate a virtual environment?"
+ ) from exc
+ execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/e2e/testserver/testserver/__init__.py b/tests/e2e/testserver/testserver/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/e2e/testserver/testserver/asgi.py b/tests/e2e/testserver/testserver/asgi.py
new file mode 100644
index 00000000..77c6a133
--- /dev/null
+++ b/tests/e2e/testserver/testserver/asgi.py
@@ -0,0 +1,16 @@
+"""
+ASGI config for sampleproject project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/5.2/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testserver.settings")
+
+application = get_asgi_application()
diff --git a/tests/e2e/testserver/testserver/components/__init__.py b/tests/e2e/testserver/testserver/components/__init__.py
new file mode 100644
index 00000000..b44a7170
--- /dev/null
+++ b/tests/e2e/testserver/testserver/components/__init__.py
@@ -0,0 +1,213 @@
+from django_components import Component, register, types
+
+
+@register("inner")
+class SimpleComponent(Component):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ """
+
+ css: types.css = """
+ .inner {
+ font-size: 4px;
+ }
+ """
+
+ js: types.js = """
+ globalThis.testSimpleComponent = 'kapowww!'
+ """
+
+ class Defaults:
+ variable2 = "default"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs["variable"],
+ "variable2": kwargs["variable2"],
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+
+@register("outer")
+class SimpleComponentNested(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+
+
+
+
+
+
+ DEMO
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Project Name
+
+ 2022-02-06 - 2024-02-07
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
-
+ +++ + + + ++
+ Phase 1 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 2 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 3 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 4 +
+ + + + +
+
+ -
+ +++ + + + ++
+ Phase 5 +
+ + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
+
- + + Project Info + + + + + +
- + + Notes 1 + + + + + +
- + + Notes 2 + + + + + +
- + + Notes 3 + + + + + +
- + + Outputs + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Project Info
+ + + + + + + + + + + Edit Project + + + + + + + +| + Org: + | ++ Org Name + | +
| + Duration: + | ++ 2022-02-06 - 2024-02-07 + | +
| + Status: + | ++ INPROGRESS + | +
| + Tags: + | ++ - + | +
+
+
+
+
+
+ Status Updates
+ + + + + + + + + + Add status update + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+ Team
+ + + + + + + + + + + Edit Team + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ | + + + Name + + + | + ++ + + Role + + + | + ++ + + + + + | + +
|---|---|---|
| + + + + UserName + + + + | + + + ++ + + + Assistant + + + + | + + + ++ + + + + + + + | + +
| + + + + UserName + + + + | + + + ++ + + + Owner + + + + | + + + ++ + + + + + + + | + +
+
+
+
+
+
+ Contacts
+ + + + + + + + + + + Edit Contacts + + + + + + + +No entries
+ +
+
+
+
+
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+
+ 2025-02-07T08:59:58.689Z
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Test note 1 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 2025-02-07T08:59:58.689Z
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Test note 2 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+
+ 2024-02-07T11:20:49.085Z
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Test note x +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Notes
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Add Note
+
+
+
+
+
+
+
+
+
+
+
+
+ 2024-02-07T11:20:49.085Z
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Test note 2 +
+ +
+
+ + Comments +
+ + + +
+
+
+
+
+
+
+
+
+
+ Add comment
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Phase 1 +
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 12
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Phase 2 +
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 16
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Missing '' from
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This output does not have any attachments.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 9
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 8
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 7
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 16
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Missing '' from
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This output does not have any attachments.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Phase 3 +
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 16
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 15
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 14
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 13
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Phase 4 +
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 5
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + Phase 5 +
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lorem ipsum 3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {% component "inner" variable=variable / %}
+ {% slot "default" default / %}
+
+ """
+
+ css: types.css = """
+ .outer {
+ font-size: 40px;
+ }
+ """
+
+ js: types.js = """
+ globalThis.testSimpleComponentNested = 'bongo!'
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
+
+ class Media:
+ css = ["style.css", "style2.css"]
+ js = "script2.js"
+
+
+@register("other")
+class OtherComponent(Component):
+ template: types.django_html = """
+ XYZ: {{ variable }}
+ """
+
+ css: types.css = """
+ .other {
+ display: flex;
+ }
+ """
+
+ js: types.js = """
+ globalThis.testOtherComponent = 'wowzee!'
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+
+@register("check_script_order_in_js")
+class CheckScriptOrderInJs(Component):
+ template = "
+ 123
+
+
+ """
+
+ js = """
+ document.querySelector('#frag-text').textContent = 'xxx';
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+
+
+# Fragment where the JS and CSS are defined on the Media class
+@register("frag_media")
+class FragMedia(Component):
+ template = """
+
+ 123
+
+
+ """
+
+ class Media:
+ js = "fragment.js"
+ css = "fragment.css"
+
+
+# Fragment that defines an AlpineJS component
+@register("frag_alpine")
+class FragAlpine(Component):
+ template = """
+
+
+ 123
+
+
+
+
+ """
+
+ js = """
+ Alpine.data('frag', () => ({
+ fragVal: 'xxx',
+ }));
+
+ // Now that the component has been defined in AlpineJS, we can "activate" all instances
+ // where we use the `x-data="frag"` directive.
+ document.querySelectorAll('[data-name="frag"]').forEach((el) => {
+ el.setAttribute('x-if', 'true');
+ });
+ """
+
+ css = """
+ .frag {
+ background: blue;
+ }
+ """
+
+
+@register("alpine_test_in_media")
+class AlpineCompInMedia(Component):
+ template: types.django_html = """
+
+ ALPINE_TEST:
+
+
+ """
+
+ class Media:
+ js = "alpine_test.js"
+
+
+@register("alpine_test_in_js")
+class AlpineCompInJs(Component):
+ template: types.django_html = """
+
+ ALPINE_TEST:
+
+
+ """
+
+ js: types.js = """
+ document.addEventListener('alpine:init', () => {
+ Alpine.data('alpine_test', () => ({
+ somevalue: 123,
+ }))
+ });
+ """
diff --git a/tests/e2e/testserver/testserver/settings.py b/tests/e2e/testserver/testserver/settings.py
new file mode 100644
index 00000000..a9c395ea
--- /dev/null
+++ b/tests/e2e/testserver/testserver/settings.py
@@ -0,0 +1,107 @@
+import os
+import secrets
+from pathlib import Path
+from typing import List
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+# Quick-start development settings - unsuitable for production
+# See https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/
+
+WSGI_APPLICATION = "testserver.wsgi.application"
+
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = os.environ.get("SECRET_KEY", secrets.token_hex(100))
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = True
+
+ALLOWED_HOSTS: List[str] = ["127.0.0.1", "localhost"]
+
+
+INSTALLED_APPS = [
+ "django.contrib.admin",
+ "django.contrib.auth",
+ "django.contrib.contenttypes",
+ "django.contrib.sessions",
+ "django.contrib.messages",
+ "django.contrib.staticfiles",
+ "django_components",
+ "testserver",
+]
+# Application definition
+
+
+MIDDLEWARE = [
+ "django.middleware.security.SecurityMiddleware",
+ "whitenoise.middleware.WhiteNoiseMiddleware",
+ "django.contrib.sessions.middleware.SessionMiddleware",
+ "django.middleware.common.CommonMiddleware",
+ "django.middleware.csrf.CsrfViewMiddleware",
+ "django.contrib.auth.middleware.AuthenticationMiddleware",
+ "django.contrib.messages.middleware.MessageMiddleware",
+ "django.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ROOT_URLCONF = "testserver.urls"
+
+TEMPLATES = [
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [],
+ "APP_DIRS": False,
+ "OPTIONS": {
+ "context_processors": [
+ "django.template.context_processors.debug",
+ "django.template.context_processors.request",
+ "django.contrib.auth.context_processors.auth",
+ "django.contrib.messages.context_processors.messages",
+ ],
+ "loaders": [
+ (
+ "django.template.loaders.cached.Loader",
+ [
+ "django.template.loaders.filesystem.Loader",
+ "django.template.loaders.app_directories.Loader",
+ "django_components.template_loader.Loader",
+ ],
+ )
+ ],
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ],
+ },
+ },
+]
+
+# Static files (CSS, JavaScript, Images)
+# https://docs.djangoproject.com/en/5.2/howto/static-files/
+
+STATIC_URL = "static/"
+
+STATIC_ROOT = "staticfiles"
+
+STATICFILES_FINDERS = [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+]
+
+# Database
+# https://docs.djangoproject.com/en/5.2/ref/settings/#databases
+
+DATABASES = {
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": BASE_DIR / "db.sqlite3",
+ }
+}
+
+# Default primary key field type
+# https://docs.djangoproject.com/en/5.2/ref/settings/#default-auto-field
+
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
diff --git a/tests/e2e/testserver/testserver/static/alpine_test.js b/tests/e2e/testserver/testserver/static/alpine_test.js
new file mode 100644
index 00000000..ce8e4849
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/alpine_test.js
@@ -0,0 +1,5 @@
+document.addEventListener('alpine:init', () => {
+ Alpine.data('alpine_test', () => ({
+ somevalue: 123,
+ }))
+});
diff --git a/tests/e2e/testserver/testserver/static/check_script_order.js b/tests/e2e/testserver/testserver/static/check_script_order.js
new file mode 100644
index 00000000..35c9a2aa
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/check_script_order.js
@@ -0,0 +1,16 @@
+// We should be able to access the global variables set by the previous components:
+// Scripts:
+// - script.js - testMsg
+// - script2.js - testMsg2
+// Components:
+// - SimpleComponent - testSimpleComponent
+// - SimpleComponentNested - testSimpleComponentNested
+// - OtherComponent - testOtherComponent
+
+globalThis.checkVars = {
+ testSimpleComponent: globalThis.testSimpleComponent,
+ testSimpleComponentNested: globalThis.testSimpleComponentNested,
+ testOtherComponent: globalThis.testOtherComponent,
+ testMsg: globalThis.testMsg,
+ testMsg2: globalThis.testMsg2,
+};
diff --git a/tests/e2e/testserver/testserver/static/fragment.css b/tests/e2e/testserver/testserver/static/fragment.css
new file mode 100644
index 00000000..d5ac288b
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/fragment.css
@@ -0,0 +1,3 @@
+.frag {
+ background: blue;
+}
diff --git a/tests/e2e/testserver/testserver/static/fragment.js b/tests/e2e/testserver/testserver/static/fragment.js
new file mode 100644
index 00000000..fad412a5
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/fragment.js
@@ -0,0 +1 @@
+document.querySelector('#frag-text').textContent = 'xxx';
diff --git a/tests/e2e/testserver/testserver/static/script.js b/tests/e2e/testserver/testserver/static/script.js
new file mode 100644
index 00000000..3d243d63
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/script.js
@@ -0,0 +1 @@
+globalThis.testMsg = { hello: "world" };
diff --git a/tests/e2e/testserver/testserver/static/script2.js b/tests/e2e/testserver/testserver/static/script2.js
new file mode 100644
index 00000000..21376912
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/script2.js
@@ -0,0 +1 @@
+globalThis.testMsg2 = { hello2: "world2" };
diff --git a/tests/e2e/testserver/testserver/static/style.css b/tests/e2e/testserver/testserver/static/style.css
new file mode 100644
index 00000000..f8378847
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/style.css
@@ -0,0 +1,3 @@
+.my-style {
+ background: blue;
+}
\ No newline at end of file
diff --git a/tests/e2e/testserver/testserver/static/style2.css b/tests/e2e/testserver/testserver/static/style2.css
new file mode 100644
index 00000000..b8d40997
--- /dev/null
+++ b/tests/e2e/testserver/testserver/static/style2.css
@@ -0,0 +1,3 @@
+.my-style2 {
+ color: red;
+}
\ No newline at end of file
diff --git a/tests/e2e/testserver/testserver/urls.py b/tests/e2e/testserver/testserver/urls.py
new file mode 100644
index 00000000..ab434260
--- /dev/null
+++ b/tests/e2e/testserver/testserver/urls.py
@@ -0,0 +1,37 @@
+from django.http import HttpResponse
+from django.urls import include, path
+from testserver.views import (
+ alpine_in_body_vars_not_available_before_view,
+ alpine_in_body_view,
+ alpine_in_body_view_2,
+ alpine_in_head_view,
+ check_js_order_in_js_view,
+ check_js_order_in_media_view,
+ check_js_order_vars_not_available_before_view,
+ fragment_base_alpine_view,
+ fragment_base_htmx_view,
+ fragment_base_js_view,
+ fragment_view,
+ multiple_components_view,
+ single_component_view,
+)
+
+urlpatterns = [
+ path("", include("django_components.urls")),
+ # Empty response with status 200 to notify other systems when the server has started
+ path("poll/", lambda *args, **kwargs: HttpResponse("")),
+ # Test views
+ path("single/", single_component_view, name="single"),
+ path("multi/", multiple_components_view, name="multi"),
+ path("js-order/js", check_js_order_in_js_view),
+ path("js-order/media", check_js_order_in_media_view),
+ path("js-order/invalid", check_js_order_vars_not_available_before_view),
+ path("fragment/base/alpine", fragment_base_alpine_view),
+ path("fragment/base/htmx", fragment_base_htmx_view),
+ path("fragment/base/js", fragment_base_js_view),
+ path("fragment/frag", fragment_view),
+ path("alpine/head", alpine_in_head_view),
+ path("alpine/body", alpine_in_body_view),
+ path("alpine/body2", alpine_in_body_view_2),
+ path("alpine/invalid", alpine_in_body_vars_not_available_before_view),
+]
diff --git a/tests/e2e/testserver/testserver/views.py b/tests/e2e/testserver/testserver/views.py
new file mode 100644
index 00000000..4618594c
--- /dev/null
+++ b/tests/e2e/testserver/testserver/views.py
@@ -0,0 +1,331 @@
+from django.http import HttpResponse
+from django.template import Context, Template
+from testserver.components import FragComp, FragMedia
+
+from django_components import types
+
+
+def single_component_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'inner' variable='foo' / %}
+ 123
+ xyz
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def multiple_components_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ 123
+ xyz
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def check_js_order_in_js_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ {# check_script_order_in_media is AFTER the other components #}
+ {% component 'check_script_order_in_js' / %}
+ abc
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def check_js_order_in_media_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ {# check_script_order_in_media is AFTER the other components #}
+ {% component 'check_script_order_in_media' / %}
+ abc
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def check_js_order_vars_not_available_before_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {# check_script_order_in_media is BEFORE the other components #}
+ {% component 'check_script_order_in_media' / %}
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
+ abc
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+# HTML into which a fragment will be loaded using vanilla JS
+def fragment_base_js_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'inner' variable='foo' / %}
+
+ OLD
+
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+
+ frag = request.GET["frag"]
+ rendered = template.render(
+ Context(
+ {
+ "frag": frag,
+ }
+ )
+ )
+ return HttpResponse(rendered)
+
+
+# HTML into which a fragment will be loaded using AlpineJS
+def fragment_base_alpine_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+
+ {% component 'inner' variable='foo' / %}
+
+ OLD
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+
+ frag = request.GET["frag"]
+ rendered = template.render(Context({"frag": frag}))
+ return HttpResponse(rendered)
+
+
+# HTML into which a fragment will be loaded using HTMX
+def fragment_base_htmx_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+
+ {% component 'inner' variable='foo' / %}
+
+ OLD
+
+
+
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+
+ frag = request.GET["frag"]
+ rendered = template.render(Context({"frag": frag}))
+ return HttpResponse(rendered)
+
+
+def fragment_view(request):
+ fragment_type = request.GET["frag"]
+ if fragment_type == "comp":
+ return FragComp.render_to_response(deps_strategy="fragment")
+ elif fragment_type == "media":
+ return FragMedia.render_to_response(deps_strategy="fragment")
+ else:
+ raise ValueError("Invalid fragment type")
+
+
+def alpine_in_head_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+
+ {% component 'alpine_test_in_media' / %}
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def alpine_in_body_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'alpine_test_in_media' / %}
+ {% component_js_dependencies %}
+
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+# Same as before, but Alpine component defined in Component.js
+def alpine_in_body_view_2(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'alpine_test_in_js' / %}
+ {% component_js_dependencies %}
+
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
+
+
+def alpine_in_body_vars_not_available_before_view(request):
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component_css_dependencies %}
+
+
+ {% component 'alpine_test_in_js' / %}
+ {# Alpine loaded BEFORE components JS #}
+
+ {% component_js_dependencies %}
+
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+ return HttpResponse(rendered)
diff --git a/tests/e2e/testserver/testserver/wsgi.py b/tests/e2e/testserver/testserver/wsgi.py
new file mode 100644
index 00000000..98c7e1bb
--- /dev/null
+++ b/tests/e2e/testserver/testserver/wsgi.py
@@ -0,0 +1,16 @@
+"""
+WSGI config for testserver project.
+
+It exposes the WSGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/5.2/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testserver.settings")
+
+application = get_wsgi_application()
diff --git a/tests/e2e/utils.py b/tests/e2e/utils.py
new file mode 100644
index 00000000..34248e7b
--- /dev/null
+++ b/tests/e2e/utils.py
@@ -0,0 +1,73 @@
+import functools
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import requests
+from playwright.async_api import async_playwright
+
+TEST_SERVER_PORT = "8000"
+TEST_SERVER_URL = f"http://127.0.0.1:{TEST_SERVER_PORT}"
+
+
+# NOTE: Ideally we'd use Django's setUpClass and tearDownClass methods
+# to instantiate the browser instance only once. But didn't have luck with that.
+# So instead we have to create a browser instance for each test.
+#
+# Additionally, Django's documentation is lacking on async setUp and tearDown,
+# so instead we use a decorator to run async code before/after each test.
+def with_playwright(test_func):
+ """Decorator that sets up and tears down Playwright browser instance."""
+
+ @functools.wraps(test_func)
+ async def wrapper(self, *args, **kwargs):
+ # Setup
+ self.playwright = await async_playwright().start()
+ self.browser = await self.playwright.chromium.launch()
+
+ # Test
+ await test_func(self, *args, **kwargs)
+
+ # Teardown
+ await self.browser.close()
+ await self.playwright.stop()
+
+ return wrapper
+
+
+def run_django_dev_server():
+ """Fixture to run Django development server in the background."""
+ # Get the path where testserver is defined, so the command doesn't depend
+ # on user's current working directory.
+ testserver_dir = (Path(__file__).parent / "testserver").resolve()
+
+ # Start the Django dev server in the background
+ print("Starting Django dev server...")
+ proc = subprocess.Popen(
+ # NOTE: Use `sys.executable` so this works both for Unix and Windows OS
+ [sys.executable, "manage.py", "runserver", f"127.0.0.1:{TEST_SERVER_PORT}", "--noreload"],
+ cwd=testserver_dir,
+ )
+
+ # Wait for the server to start by polling
+ start_time = time.time()
+ while time.time() - start_time < 30: # timeout after 30 seconds
+ try:
+ response = requests.get(f"http://127.0.0.1:{TEST_SERVER_PORT}/poll")
+ if response.status_code == 200:
+ print("Django dev server is up and running.")
+ break
+ except requests.RequestException:
+ time.sleep(0.1)
+ else:
+ proc.terminate()
+ raise RuntimeError("Django server failed to start within the timeout period")
+
+ yield # Hand control back to the test session
+
+ # Teardown: Kill the server process after the tests
+ proc.terminate()
+ proc.wait()
+
+ print("Django dev server stopped.")
diff --git a/tests/static_root/script.js b/tests/static_root/script.js
new file mode 100644
index 00000000..43d7c14d
--- /dev/null
+++ b/tests/static_root/script.js
@@ -0,0 +1,2 @@
+/* Used in `MainMediaTest` tests in `test_component_media.py` */
+console.log("HTML and JS only");
diff --git a/tests/static_root/staticfiles.json b/tests/static_root/staticfiles.json
index d4855888..c5d5d5ae 100644
--- a/tests/static_root/staticfiles.json
+++ b/tests/static_root/staticfiles.json
@@ -1,11 +1,12 @@
{
"__COMMENT__": "This file is used by tests in `test_component_media.py` to test integration with Django's `staticfiles`",
"__COMMENT2__": "Under normal conditions, this JSON would be generated by running Django's `collectstatic` with `ManifestStaticFilesStorage`",
- "__COMMENT3__": "See https://docs.djangoproject.com/en/5.0/ref/contrib/staticfiles/#manifeststaticfilesstorage",
+ "__COMMENT3__": "See https://docs.djangoproject.com/en/5.2/ref/contrib/staticfiles/#manifeststaticfilesstorage",
"paths": {
"calendar/script.js": "calendar/script.e1815e23e0ec.js",
- "calendar/style.css": "calendar/style.0eeb72042b59.css"
+ "calendar/style.css": "calendar/style.0eeb72042b59.css",
+ "django_components/django_components.min.js": "django_components/django_components.min.js"
},
"version": "1.1",
"hash": "f53e7ffd18c4"
diff --git a/tests/static_root/style.css b/tests/static_root/style.css
new file mode 100644
index 00000000..3e8f068c
--- /dev/null
+++ b/tests/static_root/style.css
@@ -0,0 +1,4 @@
+/* Used in `MainMediaTest` tests in `test_component_media.py` */
+.html-css-only {
+ color: blue;
+}
\ No newline at end of file
diff --git a/tests/templates/blocked_and_slotted_template.html b/tests/templates/blocked_and_slotted_template.html
new file mode 100644
index 00000000..94abb18f
--- /dev/null
+++ b/tests/templates/blocked_and_slotted_template.html
@@ -0,0 +1,7 @@
+{% load component_tags %}
+{% block before_custom %}{% endblock %}
+BLOCK OVERRIDEN
+{% endblock %}
diff --git a/tests/templates/mdn_component_template.html b/tests/templates/mdn_component_template.html
deleted file mode 100644
index 992b330f..00000000
--- a/tests/templates/mdn_component_template.html
+++ /dev/null
@@ -1,14 +0,0 @@
-
\ No newline at end of file
diff --git a/tests/templates/relative_extends.html b/tests/templates/relative_extends.html
new file mode 100644
index 00000000..b2d0e936
--- /dev/null
+++ b/tests/templates/relative_extends.html
@@ -0,0 +1,5 @@
+{% extends './block.html' %}
+
+{% block body %}
+ BLOCK OVERRIDEN
+{% endblock %}
diff --git a/tests/test_app/__init__.py b/tests/test_app/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_app/apps.py b/tests/test_app/apps.py
new file mode 100644
index 00000000..538e9ebe
--- /dev/null
+++ b/tests/test_app/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class TestAppConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "tests.test_app"
diff --git a/tests/test_app/components/app_lvl_comp/app_lvl_comp.css b/tests/test_app/components/app_lvl_comp/app_lvl_comp.css
new file mode 100644
index 00000000..3b07560d
--- /dev/null
+++ b/tests/test_app/components/app_lvl_comp/app_lvl_comp.css
@@ -0,0 +1,3 @@
+.html-css-only {
+ color: blue;
+}
diff --git a/tests/test_app/components/app_lvl_comp/app_lvl_comp.html b/tests/test_app/components/app_lvl_comp/app_lvl_comp.html
new file mode 100644
index 00000000..e2f403bd
--- /dev/null
+++ b/tests/test_app/components/app_lvl_comp/app_lvl_comp.html
@@ -0,0 +1,5 @@
+
diff --git a/tests/test_app/components/app_lvl_comp/app_lvl_comp.js b/tests/test_app/components/app_lvl_comp/app_lvl_comp.js
new file mode 100644
index 00000000..5a73c14a
--- /dev/null
+++ b/tests/test_app/components/app_lvl_comp/app_lvl_comp.js
@@ -0,0 +1 @@
+console.log("JS file");
diff --git a/tests/test_app/components/app_lvl_comp/app_lvl_comp.py b/tests/test_app/components/app_lvl_comp/app_lvl_comp.py
new file mode 100644
index 00000000..e775553b
--- /dev/null
+++ b/tests/test_app/components/app_lvl_comp/app_lvl_comp.py
@@ -0,0 +1,16 @@
+from django_components import Component, register
+
+
+# Used for testing the template_loader
+@register("app_lvl_comp")
+class AppLvlCompComponent(Component):
+ template_file = "app_lvl_comp.html"
+ js_file = "app_lvl_comp.js"
+ css_file = "app_lvl_comp.css"
+
+ class Media:
+ js = "app_lvl_comp.js"
+ css = "app_lvl_comp.css"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
diff --git a/tests/test_app/components/test_app_simple_template.html b/tests/test_app/components/test_app_simple_template.html
new file mode 100644
index 00000000..3f2b5995
--- /dev/null
+++ b/tests/test_app/components/test_app_simple_template.html
@@ -0,0 +1 @@
+Variable: {{ variable }}
diff --git a/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.css b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.css
new file mode 100644
index 00000000..3b07560d
--- /dev/null
+++ b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.css
@@ -0,0 +1,3 @@
+.html-css-only {
+ color: blue;
+}
diff --git a/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.html b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.html
new file mode 100644
index 00000000..e2f403bd
--- /dev/null
+++ b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.html
@@ -0,0 +1,5 @@
+
diff --git a/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.js b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.js
new file mode 100644
index 00000000..5a73c14a
--- /dev/null
+++ b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.js
@@ -0,0 +1 @@
+console.log("JS file");
diff --git a/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.py b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.py
new file mode 100644
index 00000000..57b90aa8
--- /dev/null
+++ b/tests/test_app/custom_comps_dir/app_lvl_comp/app_lvl_comp.py
@@ -0,0 +1,14 @@
+from django_components import Component, register
+
+
+# Used for testing the template_loader
+@register("custom_app_lvl_comp")
+class AppLvlCompComponent(Component):
+ template_file = "app_lvl_comp.html"
+
+ class Media:
+ js = "app_lvl_comp.js"
+ css = "app_lvl_comp.css"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
diff --git a/tests/test_app_nested/__init__.py b/tests/test_app_nested/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_app_nested/app/__init__.py b/tests/test_app_nested/app/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_app_nested/app/apps.py b/tests/test_app_nested/app/apps.py
new file mode 100644
index 00000000..c651eb5a
--- /dev/null
+++ b/tests/test_app_nested/app/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class TestAppNestedConfig(AppConfig):
+ default_auto_field = "django.db.models.BigAutoField"
+ name = "tests.test_app_nested.app"
diff --git a/tests/test_app_nested/app/components/__init__.py b/tests/test_app_nested/app/components/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/test_app_nested/app/components/app_lvl_comp.py b/tests/test_app_nested/app/components/app_lvl_comp.py
new file mode 100644
index 00000000..36c2aaaa
--- /dev/null
+++ b/tests/test_app_nested/app/components/app_lvl_comp.py
@@ -0,0 +1,12 @@
+from django_components import Component, register
+
+
+# Used for testing the template_loader
+@register("nested_app_lvl_comp")
+class AppLvlCompComponent(Component):
+ template = """
+ {{ variable }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
diff --git a/tests/test_attributes.py b/tests/test_attributes.py
index f77b1b71..61c5e6cb 100644
--- a/tests/test_attributes.py
+++ b/tests/test_attributes.py
@@ -1,86 +1,140 @@
+import re
+
+import pytest
from django.template import Context, Template, TemplateSyntaxError
from django.utils.safestring import SafeString, mark_safe
+from pytest_django.asserts import assertHTMLEqual
from django_components import Component, register, types
-from django_components.attributes import append_attributes, attributes_to_string
+from django_components.attributes import format_attributes, merge_attributes, parse_string_style
+from django_components.testing import djc_test
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase, parametrize_context_behavior
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
setup_test_config({"autodiscover": False})
-class AttributesToStringTest(BaseTestCase):
+@djc_test
+class TestFormatAttributes:
def test_simple_attribute(self):
- self.assertEqual(
- attributes_to_string({"foo": "bar"}),
- 'foo="bar"',
- )
+ assert format_attributes({"foo": "bar"}) == 'foo="bar"'
def test_multiple_attributes(self):
- self.assertEqual(
- attributes_to_string({"class": "foo", "style": "color: red;"}),
- 'class="foo" style="color: red;"',
- )
+ assert format_attributes({"class": "foo", "style": "color: red;"}) == 'class="foo" style="color: red;"'
def test_escapes_special_characters(self):
- self.assertEqual(
- attributes_to_string({"x-on:click": "bar", "@click": "'baz'"}),
- 'x-on:click="bar" @click="'baz'"',
- )
+ assert format_attributes({"x-on:click": "bar", "@click": "'baz'"}) == 'x-on:click="bar" @click="'baz'"' # noqa: E501
def test_does_not_escape_special_characters_if_safe_string(self):
- self.assertEqual(
- attributes_to_string({"foo": mark_safe("'bar'")}),
- "foo=\"'bar'\"",
- )
+ assert format_attributes({"foo": mark_safe("'bar'")}) == "foo=\"'bar'\""
def test_result_is_safe_string(self):
- result = attributes_to_string({"foo": mark_safe("'bar'")})
- self.assertTrue(isinstance(result, SafeString))
+ result = format_attributes({"foo": mark_safe("'bar'")})
+ assert isinstance(result, SafeString)
def test_attribute_with_no_value(self):
- self.assertEqual(
- attributes_to_string({"required": None}),
- "",
- )
+ assert format_attributes({"required": None}) == ""
def test_attribute_with_false_value(self):
- self.assertEqual(
- attributes_to_string({"required": False}),
- "",
- )
+ assert format_attributes({"required": False}) == ""
def test_attribute_with_true_value(self):
- self.assertEqual(
- attributes_to_string({"required": True}),
- "required",
- )
+ assert format_attributes({"required": True}) == "required"
-class AppendAttributesTest(BaseTestCase):
+@djc_test
+class TestMergeAttributes:
def test_single_dict(self):
- self.assertEqual(
- append_attributes(("foo", "bar")),
- {"foo": "bar"},
- )
+ assert merge_attributes({"foo": "bar"}) == {"foo": "bar"}
def test_appends_dicts(self):
- self.assertEqual(
- append_attributes(("class", "foo"), ("id", "bar"), ("class", "baz")),
- {"class": "foo baz", "id": "bar"},
- )
+ assert merge_attributes({"class": "foo", "id": "bar"}, {"class": "baz"}) == {
+ "class": "foo baz",
+ "id": "bar",
+ } # noqa: E501
+
+ def test_merge_with_empty_dict(self):
+ assert merge_attributes({}, {"foo": "bar"}) == {"foo": "bar"}
+
+ def test_merge_with_overlapping_keys(self):
+ assert merge_attributes({"foo": "bar"}, {"foo": "baz"}) == {"foo": "bar baz"}
+
+ def test_merge_classes(self):
+ assert merge_attributes(
+ {"class": "foo"},
+ {
+ "class": [
+ "bar",
+ "tuna",
+ "tuna2",
+ "tuna3",
+ {"baz": True, "baz2": False, "tuna": False, "tuna2": True, "tuna3": None},
+ ["extra", {"extra2": False, "baz2": True, "tuna": True, "tuna2": False}],
+ ]
+ },
+ ) == {"class": "foo bar tuna baz baz2 extra"}
+
+ def test_merge_styles(self):
+ assert merge_attributes(
+ {"style": "color: red; width: 100px; height: 100px;"},
+ {
+ "style": [
+ "background-color: blue;",
+ {"background-color": "green", "color": None, "width": False},
+ ["position: absolute", {"height": "12px"}],
+ ]
+ },
+ ) == {"style": "color: red; height: 12px; background-color: green; position: absolute;"}
+
+ def test_merge_with_none_values(self):
+ # Normal attributes merge even `None` values
+ assert merge_attributes({"foo": None}, {"foo": "bar"}) == {"foo": "None bar"}
+ assert merge_attributes({"foo": "bar"}, {"foo": None}) == {"foo": "bar None"}
+
+ # Classes append the class only if the last value is truthy
+ assert merge_attributes({"class": {"bar": None}}, {"class": {"bar": True}}) == {"class": "bar"}
+ assert merge_attributes({"class": {"bar": True}}, {"class": {"bar": None}}) == {"class": ""}
+
+ # Styles remove values that are `False` and ignore `None`
+ assert merge_attributes(
+ {"style": {"color": None}},
+ {"style": {"color": "blue"}},
+ ) == {"style": "color: blue;"}
+ assert merge_attributes(
+ {"style": {"color": "blue"}},
+ {"style": {"color": None}},
+ ) == {"style": "color: blue;"}
+
+ def test_merge_with_false_values(self):
+ # Normal attributes merge even `False` values
+ assert merge_attributes({"foo": False}, {"foo": "bar"}) == {"foo": "False bar"}
+ assert merge_attributes({"foo": "bar"}, {"foo": False}) == {"foo": "bar False"}
+
+ # Classes append the class only if the last value is truthy
+ assert merge_attributes({"class": {"bar": False}}, {"class": {"bar": True}}) == {"class": "bar"}
+ assert merge_attributes({"class": {"bar": True}}, {"class": {"bar": False}}) == {"class": ""}
+
+ # Styles remove values that are `False` and ignore `None`
+ assert merge_attributes(
+ {"style": {"color": False}},
+ {"style": {"color": "blue"}},
+ ) == {"style": "color: blue;"}
+ assert merge_attributes(
+ {"style": {"color": "blue"}},
+ {"style": {"color": False}},
+ ) == {"style": ""}
-class HtmlAttrsTests(BaseTestCase):
+@djc_test
+class TestHtmlAttrs:
template_str: types.django_html = """
{% load component_tags %}
{% component "test" attrs:@click.stop="dispatch('click_event')" attrs:x-data="{hello: 'world'}" attrs:class=class_var %}
{% endcomponent %}
""" # noqa: E501
- @parametrize_context_behavior(["django", "isolated"])
- def test_tag_positional_args(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_tag_positional_args(self, components_settings):
@register("test")
class AttrsComponent(Component):
template: types.django_html = """
@@ -90,23 +144,23 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
"class": "123 457",
}
template = Template(self.template_str)
- with self.assertRaisesMessage(
- TemplateSyntaxError, "'html_attrs' received some positional argument(s) after some keyword"
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'html_attrs': takes 2 positional argument(s) but more were given"), # noqa: E501
):
template.render(Context({"class_var": "padding-top-8"}))
@@ -142,23 +197,23 @@ class HtmlAttrsTests(BaseTestCase):
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_raises_on_extra_positional_args(self):
@register("test")
@@ -118,17 +172,18 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_kwargs_2(self):
@register("test")
@@ -170,23 +225,23 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"props": {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
"class": "added_class",
"data-id": 123,
@@ -210,15 +265,15 @@ class HtmlAttrsTests(BaseTestCase):
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_spread(self):
@register("test")
@@ -198,10 +253,10 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
# NOTE: The attrs from self.template_str should be ignored because they are not used.
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_aggregate_args(self):
@register("test")
@@ -230,23 +285,29 @@ class HtmlAttrsTests(BaseTestCase):
+
`
+ #
+ # Which raises, because `attrs` is passed both as positional and as keyword argument.
def test_tag_raises_on_aggregate_and_positional_args_for_attrs(self):
@register("test")
class AttrsComponent(Component):
@@ -257,12 +318,15 @@ class HtmlAttrsTests(BaseTestCase):
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template = Template(self.template_str)
- with self.assertRaisesMessage(TemplateSyntaxError, "Received argument 'attrs' both as a regular input"):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'html_attrs': got multiple values for argument 'attrs'"),
+ ):
template.render(Context({"class_var": "padding-top-8"}))
def test_tag_raises_on_aggregate_and_positional_args_for_defaults(self):
@@ -270,19 +334,26 @@ class HtmlAttrsTests(BaseTestCase):
class AttrsComponent(Component):
template: types.django_html = """
{% load component_tags %}
-
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
+ # Note: Because there's both `attrs:class` and `defaults:class`, the `attrs`,
+ # it's as if the template tag call was (ignoring the `class` and `data-id` attrs):
+ #
+ # `{% html_attrs attrs={"class": ...} defaults={"class": ...} attrs %}>content
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template = Template(self.template_str)
- with self.assertRaisesMessage(
+ with pytest.raises(
TemplateSyntaxError,
- "Received argument 'defaults' both as a regular input",
+ match=re.escape("Received argument 'defaults' both as a regular input"),
):
template.render(Context({"class_var": "padding-top-8"}))
@@ -296,15 +367,15 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template_str: types.django_html = """
{% load component_tags %}
@@ -330,15 +401,15 @@ class HtmlAttrsTests(BaseTestCase):
""" # noqa: E501
template = Template(template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""",
@@ -320,8 +391,8 @@ class HtmlAttrsTests(BaseTestCase):
+
""" # noqa: E501
- def get_context_data(self, *args, attrs):
- return {"attrs": attrs}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"attrs": kwargs["attrs"]}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""", # noqa: E501
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_no_attrs_no_defaults(self):
@register("test")
@@ -350,20 +421,20 @@ class HtmlAttrsTests(BaseTestCase):
+
"""
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "attrs": attrs,
+ "attrs": kwargs["attrs"],
"defaults": {"class": "override-me"},
}
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""",
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_empty(self):
@register("test")
@@ -375,23 +446,23 @@ class HtmlAttrsTests(BaseTestCase):
+
"""
- def get_context_data(self, *args, attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"attrs": None,
"defaults": None,
@@ -411,12 +482,45 @@ class HtmlAttrsTests(BaseTestCase):
template = Template(self.template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
content
""",
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
def test_tag_null_attrs_and_defaults(self):
@register("test")
@@ -403,7 +474,7 @@ class HtmlAttrsTests(BaseTestCase):
+ DEMO
+
+ {{ slot_css }}
+
+
+ {{ slot_content }}
+
+ {# AlpineJS + Plugins #}
+
+
+
+
+
+ {# HTMX #}
+
+
+ {# Axios (AJAX) #}
+
+
+ {# Any extra scripts #}
+ {{ slot_js }}
+
+
+
+
+
+"""
+
+
+class BaseData(NamedTuple):
+ slot_css: Optional[str] = None
+ slot_js: Optional[str] = None
+ slot_content: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def base(context: Context, data: BaseData) -> str:
+ render_context: RenderContext = context["render_context"]
+
+ with context.push(
+ {
+ "csrf_token": render_context.csrf_token,
+ "theme": theme,
+ # Slots
+ "slot_css": data.slot_css,
+ "slot_js": data.slot_js,
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(base_template_str).render(context)
+
+
+#####################################
+# SIDEBAR
+#####################################
+
+
+class SidebarItem(NamedTuple):
+ name: str
+ icon: Optional[str] = None
+ icon_variant: Optional[str] = None
+ href: Optional[str] = None
+ children: Optional[List["SidebarItem"]] = None
+
+
+# Links in the sidebar.
+def gen_sidebar_menu_items(active_projects: List[Project]) -> List[Tuple[IconData, List[ButtonData]]]:
+ items: List[Tuple[IconData, List[ButtonData]]] = [
+ (
+ IconData(
+ name="home",
+ variant="outline",
+ href="/",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Homepage",
+ ),
+ [],
+ ),
+ (
+ IconData(
+ name="folder",
+ variant="outline",
+ href="/projects",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Projects",
+ ),
+ [
+ ButtonData(
+ variant="plain",
+ href=f"/projects/{project['id']}",
+ slot_content=project["name"],
+ attrs={
+ "class": "p-2 !w-full",
+ },
+ )
+ for project in active_projects
+ ],
+ ),
+ (
+ IconData(
+ name="folder",
+ variant="outline",
+ href="/page-3",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Page 3",
+ ),
+ [],
+ ),
+ (
+ IconData(
+ name="bars-arrow-down",
+ variant="outline",
+ href="/page-4",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Page 4",
+ ),
+ [],
+ ),
+ (
+ IconData(
+ name="forward",
+ variant="outline",
+ href="/page-5",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Page 5",
+ ),
+ [],
+ ),
+ (
+ IconData(
+ name="archive-box",
+ variant="outline",
+ href="/faq",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="FAQ",
+ ),
+ [],
+ ),
+ ]
+
+ return items
+
+
+sidebar_template_str: types.django_html = """
+
+ {% icon bookmarks_icon_data %}
+
+"""
+
+
+class BookmarksData(NamedTuple):
+ project_id: int
+ bookmarks: List[ProjectBookmark]
+ attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def bookmarks(context: Context, data: BookmarksData):
+ bookmark_entries: List[BookmarkData] = []
+ attachment_entries: List[BookmarkData] = []
+
+ for bookmark in data.bookmarks:
+ is_attachment = bookmark["attachment"] is not None
+
+ if is_attachment:
+ # Send user to the Output tab in Project page and open and scroll
+ # to the relevent output that has the correct attachment.
+ edit_url = (
+ f"/edit/{data.project_id}/bookmark/{bookmark['id']}"
+ f"?{ProjectPageTabsToQueryParams.OUTPUTS.value}"
+ f"&panel={bookmark['attachment']['output']['id']}" # type: ignore[index]
+ )
+ else:
+ edit_url = f"/edit/{data.project_id}/bookmark/{bookmark['id']}"
+
+ entry = BookmarkData(
+ bookmark=BookmarkItem(
+ text=bookmark["text"],
+ url=bookmark["url"],
+ id=bookmark["id"],
+ edit_url=edit_url,
+ ),
+ js={
+ "onMenuToggle": "onContextMenuToggle",
+ },
+ )
+
+ if is_attachment:
+ attachment_entries.append(entry)
+ else:
+ bookmark_entries.append(entry)
+
+ create_bookmark_url = f"/create/{data.project_id}/bookmark"
+
+ bookmarks_icon_data = IconData(
+ name="bookmark",
+ variant="outline",
+ text_attrs={
+ "class": "py-2 text-sm",
+ },
+ slot_content="Project Bookmarks",
+ )
+
+ add_new_bookmark_icon_data = IconData(
+ name="plus",
+ variant="outline",
+ size=18,
+ href=create_bookmark_url,
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "px-2 py-1 text-xs",
+ },
+ svg_attrs={
+ "class": "mt-0.5 ml-1",
+ },
+ slot_content="Add New Bookmark",
+ )
+
+ context_menu_data = MenuData(
+ items=menu_items, # type: ignore[arg-type]
+ model="contextMenuItem.value",
+ anchor="contextMenuRef.value",
+ anchor_dir="bottom",
+ list_attrs={
+ "class": "w-24 ml-8 z-40",
+ },
+ attrs={
+ "@click_outside": "onContextMenuClickOutside",
+ },
+ )
+
+ with context.push(
+ {
+ "bookmark_entries": bookmark_entries,
+ "attachment_entries": attachment_entries,
+ "create_bookmark_url": create_bookmark_url,
+ "menu_items": menu_items,
+ "attrs": data.attrs,
+ "theme": theme,
+ "bookmarks_icon_data": bookmarks_icon_data,
+ "add_new_bookmark_icon_data": add_new_bookmark_icon_data,
+ "context_menu_data": context_menu_data,
+ }
+ ):
+ return lazy_load_template(bookmarks_template_str).render(context)
+
+
+bookmarks_tag = bookmarks
+
+#####################################
+# BOOKMARK
+#####################################
+
+
+class BookmarkItem(NamedTuple):
+ id: int
+ text: str
+ url: str
+ edit_url: str
+
+
+bookmark_template_str: types.django_html = """
+
+
+"""
+
+
+class BookmarkData(NamedTuple):
+ bookmark: BookmarkItem
+ js: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def bookmark(context: Context, data: BookmarkData):
+ bookmark_icon_data = IconData(
+ name="ellipsis-vertical",
+ variant="outline",
+ color=theme.sidebar_link,
+ svg_attrs={
+ "class": "inline",
+ },
+ text_attrs={
+ "class": "p-0",
+ },
+ attrs={
+ "class": "self-center cursor-pointer",
+ "x-ref": "bookmark_menu",
+ "@click": "onMenuToggle",
+ },
+ )
+
+ with context.push(
+ {
+ "theme": theme,
+ "bookmark": data.bookmark._asdict(),
+ "js": data.js,
+ "bookmark_icon_data": bookmark_icon_data,
+ }
+ ):
+ return lazy_load_template(bookmark_template_str).render(context)
+
+
+#####################################
+# LIST
+#####################################
+
+
+@dataclass(frozen=True)
+class ListItem:
+ """
+ Single menu item used with the `menu` components.
+
+ Menu items can be divided by a horizontal line to indicate that the items
+ belong together. In code, we specify this by wrapping the item(s) as an array.
+ """
+
+ value: Any
+ """Value of the menu item to render."""
+
+ link: Optional[str] = None
+ """
+ If set, the list item will be wrapped in an `` tag pointing to this link.
+ """
+
+ attrs: Optional[dict] = None
+ """Any additional attributes to apply to the list item."""
+
+ meta: Optional[dict] = None
+ """Any additional data to pass along the list item."""
+
+
+list_template_str: types.django_html = """
+ DEMO
+ {% component_css_dependencies %}
+
+ {% slot "css" / %}
+
+
+ {% slot "content" default / %}
+
+ {# AlpineJS + Plugins #}
+
+
+
+
+
+ {# HTMX #}
+
+
+ {# Axios (AJAX) #}
+
+
+ {# JS scripts from our custom Django components #}
+ {% component_js_dependencies %}
+
+ {# Any extra scripts #}
+ {% slot "js" / %}
+
+
+
+
+ """
+
+ js: types.js = """
+ ////////////////////////////////////////////////////////////////
+ // base.js
+ ////////////////////////////////////////////////////////////////
+
+ /** Global JS state / methods */
+ const app = {
+ // NOTE: queryManager.js MUST be loaded before this script!
+ query: createQueryManager(),
+ };
+
+ app.query.load();
+
+ ////////////////////////////////////////////////////////////////
+ // queryManager.js
+ ////////////////////////////////////////////////////////////////
+
+ /**
+ * Callback when a URL's query param changes.
+ *
+ * @callback OnParamChangeCallback
+ * @param {string | null} newValue - New value of the query param.
+ * @param {string | null} oldValue - Old value of the query param.
+ */
+
+ /**
+ * Function that can be called once to remove the registered callback.
+ *
+ * @callback UnregisterFn
+ */
+
+ /**
+ * Callback for modifying URL.
+ *
+ * @callback OnUrlModifyCallback
+ * @param {URL} currUrl - Current URL.
+ * @returns {URL | string} New URL.
+ */
+
+ /**
+ * Singular interface for manipulating URL search/query parameters
+ * and reacting to changes.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Location/search
+ */
+ const createQueryManager = () => {
+ /**
+ * @type {Record}
+ */
+ const callbacks = {};
+
+ /**
+ * Store previous values of query params, so we can provide both new and old
+ * values to the callbacks.
+ *
+ * NOTE: Use `setParamValue` instead of setting values directly.
+ *
+ * @type {Record}
+ */
+ const previousParamValues = {};
+
+ /**
+ * @param {string} key
+ * @param {string | null} newValue
+ */
+ const setParamValue = (key, newValue) => {
+ const oldValue =
+ previousParamValues[key] === undefined ? null : previousParamValues[key];
+
+ previousParamValues[key] = newValue;
+
+ const paramCallbacks = callbacks[key] || [];
+
+ paramCallbacks.forEach((cb) => cb(newValue, oldValue));
+ };
+
+ /**
+ * Register a listener that will be triggered when a value changes for the query param
+ * of given name.
+ *
+ * Returns a function that can be called once to remove the registered callback.
+ *
+ * @param {string} paramName
+ * @param {OnParamChangeCallback} callback
+ * @returns {UnregisterFn}
+ */
+ const registerParam = (paramName, callback) => {
+ if (callbacks[paramName] == undefined) {
+ callbacks[paramName] = [];
+ }
+
+ callbacks[paramName].push(callback);
+
+ // Run the callback once if the query param already has some value
+ if (previousParamValues[paramName] != null) {
+ callback(previousParamValues[paramName], null);
+ }
+
+ // Return a function that can be called once to remove the registered callback
+ let unregisterCalled = false;
+ const unregister = () => {
+ if (unregisterCalled) return;
+ unregisterCalled = true;
+
+ unregisterParam(paramName, callback);
+ };
+
+ return unregister;
+ };
+
+ /**
+ * Unregister a callback that was previously registered with `registerParam`
+ * for the query param of given name.
+ *
+ * @param {string} paramName
+ * @param {OnParamChangeCallback} callback
+ */
+ const unregisterParam = (paramName, callback) => {
+ // Nothing to do
+ if (callbacks[paramName] == undefined) return;
+
+ // Remove one instance of callback from the array to simulate similar behavior
+ // as browser's addEventListener/removeEventListener.
+ // See https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+ const indexToRemove = callbacks[paramName].indexOf(callback);
+ if (indexToRemove !== -1) {
+ callbacks[paramName].splice(indexToRemove, 1);
+ }
+ };
+
+ /**
+ * Shared logic for modifying the page's URL in-place (without reload).
+ *
+ * @param {OnUrlModifyCallback} mapFn
+ */
+ const modifyUrl = (mapFn) => {
+ // Prepare current URL
+ const currUrl = new URL(globalThis.location.href);
+
+ // Let the user of this function decide how to transform the URL
+ let updatedUrl = mapFn(currUrl);
+
+ // Update browser URL without reloading the page
+ // See https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
+ // And https://stackoverflow.com/a/3354511/9788634
+ globalThis.history.replaceState(null, "", updatedUrl.toString());
+ };
+
+ /**
+ * Set query parameters to the URL.
+ *
+ * If the URL already contains query params of the same name, these will be overwritten.
+ *
+ * @param {Record} params
+ */
+ const setParams = (params) => {
+ modifyUrl((currUrl) => {
+ Object.entries(params).forEach(([key, val]) => {
+ currUrl.searchParams.set(key, val);
+ });
+ return currUrl.href;
+ });
+
+ // Trigger callbacks for all params that were set.
+ Object.entries(params).forEach(([key, val]) => setParamValue(key, val));
+ };
+
+ /** Clear all query parameters from the URL. */
+ const clearParams = () => {
+ modifyUrl((currUrl) => {
+ currUrl.search = "";
+ return currUrl.href;
+ });
+
+ // Trigger callbacks for all params that were unset.
+ Object.entries(previousParamValues)
+ .filter(([key, val]) => val !== null)
+ .forEach(([key, val]) => setParamValue(key, val));
+ };
+
+ /** Load query params from the current page URL, triggering any registered callbacks. */
+ const load = () => {
+ const currUrl = new URL(globalThis.location.href);
+ currUrl.searchParams.forEach((value, key) => setParamValue(key, value));
+ };
+
+ return {
+ setParams,
+ clearParams,
+ registerParam,
+ unregisterParam,
+ load,
+ };
+ };
+
+ ////////////////////////////////////////////////////////////////
+ // submitForm.js
+ ////////////////////////////////////////////////////////////////
+
+ /**
+ * @param {HTMLFormElement} formEl
+ */
+ const getFormData = (formEl) => {
+ return Object.fromEntries(new FormData(formEl));
+ };
+
+ /**
+ * @param {HTMLFormElement} formEl
+ * @param {object} formData
+ */
+ const submitForm = (formEl, data, { reload = false } = {}) => {
+ // Do not submit anything when the form doesn't specify the target URL
+ if (!formEl.hasAttribute('action')) Promise.resolve();
+
+ return axios.post(formEl.action, data, {
+ method: formEl.method,
+ })
+ .then((response) => {
+ if (reload) location.reload();
+ })
+ .catch((error) => {
+ console.error(error);
+ });
+ };
+ """
+
+#####################################
+# SIDEBAR
+#####################################
+
+class SidebarItem(NamedTuple):
+ name: str
+ icon: Optional[str] = None
+ icon_variant: Optional[str] = None
+ href: Optional[str] = None
+ children: Optional[List["SidebarItem"]] = None
+
+
+# Links in the sidebar.
+def gen_sidebar_menu_items(active_projects: List[Project]) -> List[SidebarItem]:
+ items: List[SidebarItem] = [
+ SidebarItem(
+ name="Homepage",
+ icon="home",
+ icon_variant="outline",
+ href="/",
+ ),
+ SidebarItem(
+ name="Projects",
+ icon="folder",
+ icon_variant="outline",
+ href="/projects",
+ children=[
+ SidebarItem(
+ name=project['name'],
+ icon=None,
+ href=f"/projects/{project['id']}",
+ )
+ for project in active_projects
+ ],
+ ),
+ SidebarItem(
+ name="Page 3",
+ icon="folder",
+ icon_variant="outline",
+ href="/page-3",
+ ),
+ SidebarItem(
+ name="Page 4",
+ icon="bars-arrow-down",
+ icon_variant="outline",
+ href="/page-4",
+ ),
+ SidebarItem(
+ name="page-5",
+ icon="forward",
+ icon_variant="outline",
+ href="/page-5",
+ ),
+ SidebarItem(
+ name="FAQ",
+ icon="archive-box",
+ icon_variant="outline",
+ href="/faq",
+ ),
+ ]
+
+ return items
+
+
+@register("Sidebar")
+class Sidebar(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ active_projects: List[Project],
+ attrs: Optional[dict] = None,
+ ):
+ context: RenderContext = self.inject("render_context").render_context
+ user = context.user
+ items = gen_sidebar_menu_items(active_projects)
+
+ faq_url = "/faq"
+
+ return {
+ "items": items,
+ "attrs": attrs,
+ "user": user,
+ "theme": theme,
+ "faq_url": faq_url,
+ }
+
+ template: types.django_html = """
+
+ {% component "Icon"
+ name="bookmark"
+ variant="outline"
+ text_attrs:class="py-2 text-sm"
+ %}
+ Project Bookmarks
+ {% endcomponent %}
+
+ """
+
+ js: types.js = """
+ const useContextMenu = (reactivity) => {
+ const { ref } = reactivity;
+
+ const contextMenuItem = ref(null);
+ const contextMenuRef = ref(null);
+
+ const contextMenuReset = () => {
+ contextMenuItem.value = null;
+ contextMenuRef.value = null;
+ };
+
+ const onContextMenuToggle = (data) => {
+ const { item, el } = data;
+
+ const willUntoggle = contextMenuItem.value && contextMenuItem.value.id === item.id;
+
+ // NOTE: We need to remove the component first before we can re-render it
+ // at a different place using `x-anchor`.
+ contextMenuItem.value = null;
+ contextMenuRef.value = null;
+
+ // If we are to untoggled currently-active menu, since we've already set values to null,
+ // there's nothing more to be done.
+ if (willUntoggle) {
+ return;
+ }
+
+ // Otherwise, we should open a new menu
+ setTimeout(() => {
+ contextMenuItem.value = item;
+ contextMenuRef.value = el;
+ });
+ };
+
+ const onContextMenuClickOutside = (event) => {
+ contextMenuReset();
+ };
+
+ return {
+ contextMenuItem,
+ contextMenuRef,
+ contextMenuReset,
+ onContextMenuToggle,
+ onContextMenuClickOutside,
+ };
+ };
+
+ // Define component similarly to defining Vue components
+ const Bookmarks = AlpineComposition.defineComponent({
+ name: "bookmarks",
+
+ props: {},
+ emits: {},
+
+ setup(props, vm, reactivity) {
+ const {
+ contextMenuItem,
+ contextMenuRef,
+ onContextMenuToggle,
+ onContextMenuClickOutside,
+ } = useContextMenu(reactivity);
+
+ return {
+ contextMenuItem,
+ contextMenuRef,
+ onContextMenuToggle,
+ onContextMenuClickOutside,
+ };
+ },
+ });
+
+ document.addEventListener('alpine:init', () => {
+ AlpineComposition.registerComponent(Alpine, Bookmarks);
+ });
+ """
+
+#####################################
+# BOOKMARK
+#####################################
+
+class BookmarkItem(NamedTuple):
+ id: int
+ text: str
+ url: str
+ edit_url: str
+
+
+@register("Bookmark")
+class Bookmark(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ bookmark: BookmarkItem,
+ js: Optional[dict] = None,
+ ):
+ return {
+ "theme": theme,
+ "bookmark": bookmark._asdict(),
+ "js": js,
+ }
+
+ template: types.django_html = """
+
+
+ """
+
+ js: types.js = """
+ // Define component similarly to defining Vue components
+ const Bookmark = AlpineComposition.defineComponent({
+ name: "bookmark",
+
+ props: {
+ bookmark: { type: Object, required: true },
+ },
+
+ emits: {
+ menuToggle: (obj) => true,
+ },
+
+ setup(props, vm) {
+ const onMenuToggle = () => {
+ vm.$emit('menuToggle', { item: props.bookmark, el: vm.$refs.bookmark_menu });
+ }
+
+ return {
+ bookmark: props.bookmark,
+ onMenuToggle,
+ };
+ },
+ });
+
+ document.addEventListener('alpine:init', () => {
+ AlpineComposition.registerComponent(Alpine, Bookmark);
+ });
+ """
+
+#####################################
+# LIST
+#####################################
+
+@dataclass(frozen=True)
+class ListItem:
+ """
+ Single menu item used with the `menu` components.
+
+ Menu items can be divided by a horizontal line to indicate that the items
+ belong together. In code, we specify this by wrapping the item(s) as an array.
+ """
+
+ value: Any
+ """Value of the menu item to render."""
+
+ link: Optional[str] = None
+ """
+ If set, the list item will be wrapped in an `` tag pointing to this link.
+ """
+
+ attrs: Optional[dict] = None
+ """Any additional attributes to apply to the list item."""
+
+ meta: Optional[dict] = None
+ """Any additional data to pass along the list item."""
+
+
+@register("List")
+class ListComponent(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ items: List[ListItem],
+ attrs: Optional[dict] = None,
+ item_attrs: Optional[dict] = None,
+ ):
+ return {
+ "items": items,
+ "attrs": attrs,
+ "item_attrs": item_attrs,
+ }
+
+ template: types.django_html = """
+ .TestComponent tests/test_command_list.py
+
+ # Check first line of output
+ assert re.compile(
+ # full_name path
+ r"full_name\s+path\s+"
+ ).search(output.strip().split("\n")[0])
+
+ # Check that the output contains the built-in component
+ assert re.compile(
+ # django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # or
+ # django_components.components.dynamic.DynamicComponent .tox/py311/lib/python3.11/site-packages/django_components/components/dynamic.py
+ r"django_components\.components\.dynamic\.DynamicComponent\s+[\w/\\.-]+django_components{SLASH}components{SLASH}dynamic\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
+
+ # Check that the output contains the test component
+ assert re.compile(
+ # tests.test_command_list.TestComponentListCommand.test_list_default..TestComponent tests/test_command_list.py
+ r"tests\.test_command_list\.TestComponentListCommand\.test_list_default\.\.TestComponent\s+tests{SLASH}test_command_list\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
+
+ def test_list_all(self):
+ class TestComponent(Component):
+ template = ""
+
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "list", "--all")
+ output = out.getvalue()
+
+ # NOTE: When we run all tests, the output is different, as other test files define components
+ # outside of the `@djc_test` decorator, and thus they leak into the output. Since this affects also
+ # the formatting (how much whitespace there is), regex is used to check for the headers and the expected
+ # components.
+ #
+ # The output should look like this:
+ #
+ # name full_name path
+ # ====================================================================================================================================================
+ # DynamicComponent django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # TestComponent tests.test_command_list.TestComponentListCommand.test_list_all..TestComponent tests/test_command_list.py
+
+ # Check first line of output
+ assert re.compile(
+ # name full_name path
+ r"name\s+full_name\s+path\s+"
+ ).search(output.strip().split("\n")[0])
+
+ # Check that the output contains the built-in component
+ assert re.compile(
+ # DynamicComponent django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # or
+ # DynamicComponent django_components.components.dynamic.DynamicComponent .tox/py311/lib/python3.11/site-packages/django_components/components/dynamic.py
+ r"DynamicComponent\s+django_components\.components\.dynamic\.DynamicComponent\s+[\w/\\.-]+django_components{SLASH}components{SLASH}dynamic\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
+
+ # Check that the output contains the test component
+ assert re.compile(
+ # TestComponent tests.test_command_list.TestComponentListCommand.test_list_all..TestComponent tests/test_command_list.py
+ r"TestComponent\s+tests\.test_command_list\.TestComponentListCommand\.test_list_all\.\.TestComponent\s+tests{SLASH}test_command_list\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
+
+ def test_list_specific_columns(self):
+ class TestComponent(Component):
+ template = ""
+
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "list", "--columns", "name,full_name")
+ output = out.getvalue()
+
+ # NOTE: When we run all tests, the output is different, as other test files define components
+ # outside of the `@djc_test` decorator, and thus they leak into the output. Since this affects also
+ # the formatting (how much whitespace there is), regex is used to check for the headers and the expected
+ # components.
+ #
+ # The output should look like this:
+ #
+ # name full_name
+ # ====================================================================================================================
+ # DynamicComponent django_components.components.dynamic.DynamicComponent
+ # TestComponent tests.test_command_list.TestComponentListCommand.test_list_specific_columns..TestComponent
+
+ # Check first line of output
+ assert re.compile(
+ # name full_name
+ r"name\s+full_name"
+ ).search(output.strip().split("\n")[0])
+
+ # Check that the output contains the built-in component
+ assert re.compile(
+ # DynamicComponent django_components.components.dynamic.DynamicComponent
+ r"DynamicComponent\s+django_components\.components\.dynamic\.DynamicComponent"
+ ).search(output)
+
+ # Check that the output contains the test component
+ assert re.compile(
+ # TestComponent tests.test_command_list.TestComponentListCommand.test_list_specific_columns..TestComponent
+ r"TestComponent\s+tests\.test_command_list\.TestComponentListCommand\.test_list_specific_columns\.\.TestComponent"
+ ).search(output)
+
+ def test_list_simple(self):
+ class TestComponent(Component):
+ template = ""
+
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "list", "--simple")
+ output = out.getvalue()
+
+ # NOTE: When we run all tests, the output is different, as other test files define components
+ # outside of the `@djc_test` decorator, and thus they leak into the output. Since this affects also
+ # the formatting (how much whitespace there is), regex is used to check for the headers and the expected
+ # components.
+ #
+ # The output should look like this:
+ #
+ # django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # tests.test_command_list.TestComponentListCommand.test_list_simple..TestComponent tests/test_command_list.py
+
+ # Check first line of output is omitted
+ assert re.compile(
+ # full_name path
+ r"full_name\s+path\s+"
+ ).search(output.strip().split("\n")[0]) is None
+
+ # Check that the output contains the built-in component
+ assert re.compile(
+ # django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # or
+ # django_components.components.dynamic.DynamicComponent .tox/py311/lib/python3.11/site-packages/django_components/components/dynamic.py
+ r"django_components\.components\.dynamic\.DynamicComponent\s+[\w/\\.-]+django_components{SLASH}components{SLASH}dynamic\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
+
+ # Check that the output contains the test component
+ assert re.compile(
+ # tests.test_command_list.TestComponentListCommand.test_list_simple..TestComponent tests/test_command_list.py
+ r"tests\.test_command_list\.TestComponentListCommand\.test_list_simple\.\.TestComponent\s+tests{SLASH}test_command_list\.py".format(
+ SLASH=SLASH
+ )
+ ).search(output)
diff --git a/tests/test_command_startcomponent.py b/tests/test_command_startcomponent.py
deleted file mode 100644
index 5e438c4f..00000000
--- a/tests/test_command_startcomponent.py
+++ /dev/null
@@ -1,113 +0,0 @@
-import os
-import tempfile
-from io import StringIO
-from shutil import rmtree
-
-from django.core.management import call_command
-from django.core.management.base import CommandError
-from django.test import TestCase
-
-from .django_test_setup import setup_test_config
-
-setup_test_config()
-
-
-class CreateComponentCommandTest(TestCase):
- def setUp(self):
- super().setUp()
- self.temp_dir = tempfile.mkdtemp()
-
- def tearDown(self):
- super().tearDown()
- rmtree(self.temp_dir)
-
- def test_default_file_names(self):
- component_name = "defaultcomponent"
- call_command("startcomponent", component_name, "--path", self.temp_dir)
-
- expected_files = [
- os.path.join(self.temp_dir, component_name, "script.js"),
- os.path.join(self.temp_dir, component_name, "style.css"),
- os.path.join(self.temp_dir, component_name, "template.html"),
- ]
- for file_path in expected_files:
- self.assertTrue(os.path.exists(file_path))
-
- def test_nondefault_creation(self):
- component_name = "testcomponent"
- call_command(
- "startcomponent",
- component_name,
- "--path",
- self.temp_dir,
- "--js",
- "test.js",
- "--css",
- "test.css",
- "--template",
- "test.html",
- )
-
- expected_files = [
- os.path.join(self.temp_dir, component_name, "test.js"),
- os.path.join(self.temp_dir, component_name, "test.css"),
- os.path.join(self.temp_dir, component_name, "test.html"),
- os.path.join(self.temp_dir, component_name, f"{component_name}.py"),
- ]
-
- for file_path in expected_files:
- self.assertTrue(os.path.exists(file_path), f"File {file_path} was not created")
-
- def test_dry_run(self):
- component_name = "dryruncomponent"
- call_command(
- "startcomponent",
- component_name,
- "--path",
- self.temp_dir,
- "--dry-run",
- )
-
- component_path = os.path.join(self.temp_dir, component_name)
- self.assertFalse(os.path.exists(component_path))
-
- def test_force_overwrite(self):
- component_name = "existingcomponent"
- component_path = os.path.join(self.temp_dir, component_name)
- os.makedirs(component_path)
-
- with open(os.path.join(component_path, f"{component_name}.py"), "w") as f:
- f.write("hello world")
-
- call_command(
- "startcomponent",
- component_name,
- "--path",
- self.temp_dir,
- "--force",
- )
-
- with open(os.path.join(component_path, f"{component_name}.py"), "r") as f:
- self.assertNotIn("hello world", f.read())
-
- def test_error_existing_component_no_force(self):
- component_name = "existingcomponent_2"
- component_path = os.path.join(self.temp_dir, component_name)
- os.makedirs(component_path)
-
- with self.assertRaises(CommandError):
- call_command("startcomponent", component_name, "--path", self.temp_dir)
-
- def test_verbose_output(self):
- component_name = "verbosecomponent"
- out = StringIO()
- call_command(
- "startcomponent",
- component_name,
- "--path",
- self.temp_dir,
- "--verbose",
- stdout=out,
- )
- output = out.getvalue()
- self.assertIn("component at", output)
diff --git a/tests/test_component.py b/tests/test_component.py
index 15617d41..28d2d71e 100644
--- a/tests/test_component.py
+++ b/tests/test_component.py
@@ -3,74 +3,89 @@ Tests focusing on the Component class.
For tests focusing on the `component` tag, see `test_templatetags_component.py`
"""
-from typing import Dict, Tuple, TypedDict, no_type_check
+import os
+import re
+from typing import Any, List, Literal, NamedTuple, Optional
-from django.core.exceptions import ImproperlyConfigured
+import pytest
+from django.conf import settings
from django.http import HttpRequest, HttpResponse
-from django.template import Context, RequestContext, Template, TemplateSyntaxError
+from django.template import Context, RequestContext, Template
+from django.template.base import TextNode
+from django.test import Client
+from django.urls import path
+from pytest_django.asserts import assertHTMLEqual, assertInHTML
-from django_components import Component, registry, types
-from django_components.slots import SlotRef
+from django_components import (
+ Component,
+ ComponentRegistry,
+ ComponentView,
+ Slot,
+ SlotInput,
+ all_components,
+ get_component_by_class_id,
+ register,
+ registry,
+ types,
+)
+from django_components.template import _get_component_template
+from django_components.urls import urlpatterns as dc_urlpatterns
-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})
-class ComponentTest(BaseTestCase):
- class ParentComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
- "
+
+ def test_metadata__component(self):
+ comp: Any = None
+
+ @register("test")
+ class TestComponent(Component):
+ template = "hello"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal comp
+ comp = self
+
+ class Outer(Component):
+ template = "{% component 'test' only / %}"
+
+ rendered = Outer.render()
+
+ assert rendered == 'hello'
+
+ assert isinstance(comp, TestComponent)
+
+ assert isinstance(comp.outer_context, Context)
+ assert comp.outer_context is not comp.context
+
+ assert isinstance(comp.registry, ComponentRegistry)
+ assert comp.registered_name == "test"
+
+ assert comp.node is not None
+ assert comp.node.template_component == Outer
+
+ if os.name == "nt":
+ assert comp.node.template_name.endswith("tests\\test_component.py::Outer") # type: ignore
+ else:
+ assert comp.node.template_name.endswith("tests/test_component.py::Outer") # type: ignore
+
+ def test_metadata__python(self):
+ comp: Any = None
+
+ @register("test")
+ class TestComponent(Component):
+ template = "hello"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal comp
+ comp = self
+
+ rendered = TestComponent.render(
+ context=Context(),
+ args=(),
+ kwargs={},
+ slots={},
+ deps_strategy="document",
+ render_dependencies=True,
+ request=None,
+ outer_context=Context(),
+ registry=ComponentRegistry(),
+ registered_name="test",
+ )
+
+ assert rendered == 'hello'
+
+ assert isinstance(comp, TestComponent)
+
+ assert isinstance(comp.outer_context, Context)
+ assert comp.outer_context == Context()
+
+ assert isinstance(comp.registry, ComponentRegistry)
+ assert comp.registered_name == "test"
+
+ assert comp.node is None
+
+
+@djc_test
+class TestComponentTemplateVars:
+ def test_args_kwargs_slots__simple_untyped(self):
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+
Default header
Default main
@@ -530,10 +1176,10 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- # See https://github.com/EmilStenstrom/django-components/issues/580
- # And https://github.com/EmilStenstrom/django-components/commit/fee26ec1d8b46b5ee065ca1ce6143889b0f96764
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_with_include_and_context(self):
+ # See https://github.com/django-components/django-components/issues/580
+ # And https://github.com/django-components/django-components/commit/fee26ec1d8b46b5ee065ca1ce6143889b0f96764
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_with_include_and_context(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -541,10 +1187,10 @@ class ComponentRenderTest(BaseTestCase):
"""
rendered = SimpleComponent.render(context=Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Default header
Default main
@@ -552,10 +1198,11 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- # See https://github.com/EmilStenstrom/django-components/issues/580
- # And https://github.com/EmilStenstrom/django-components/commit/fee26ec1d8b46b5ee065ca1ce6143889b0f96764
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_with_include_and_request_context(self):
+ # See https://github.com/django-components/django-components/issues/580
+ # And https://github.com/django-components/django-components/issues/634
+ # And https://github.com/django-components/django-components/commit/fee26ec1d8b46b5ee065ca1ce6143889b0f96764
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_with_include_and_request_context(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -563,10 +1210,10 @@ class ComponentRenderTest(BaseTestCase):
"""
rendered = SimpleComponent.render(context=RequestContext(HttpRequest()))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Default header
Default main
@@ -574,8 +1221,133 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_with_extends(self):
+ # See https://github.com/django-components/django-components/issues/580
+ # And https://github.com/django-components/django-components/issues/634
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_request_context_is_populated_from_context_processors(self, components_settings):
+ @register("thing")
+ class Thing(Component):
+ template: types.django_html = """
+ Rendered {{ how }}
+ [0-9a-zA-Z]{64})")
+
+ assert not token_re.findall(response.content)
+ assert "Existing context: foo" in response.content.decode()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_with_extends(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% extends 'block.html' %}
@@ -584,12 +1356,12 @@ class ComponentRenderTest(BaseTestCase):
{% endblock %}
"""
- rendered = SimpleComponent.render()
- self.assertHTMLEqual(
+ rendered = SimpleComponent.render(deps_strategy="ignore")
+ assertHTMLEqual(
rendered,
"""
-
+
content
""",
)
- self.assertNotIn("override-me", rendered)
+ assert "override-me" not in rendered
+
+
+@djc_test
+class TestParseStringStyle:
+ def test_single_style(self):
+ assert parse_string_style("color: red;") == {"color": "red"}
+
+ def test_multiple_styles(self):
+ assert parse_string_style("color: red; background-color: blue;") == {
+ "color": "red",
+ "background-color": "blue",
+ }
+
+ def test_with_comments(self):
+ assert parse_string_style("color: red /* comment */; background-color: blue;") == {
+ "color": "red",
+ "background-color": "blue",
+ }
+
+ def test_with_whitespace(self):
+ assert parse_string_style(" color: red; background-color: blue; ") == {
+ "color": "red",
+ "background-color": "blue",
+ }
+
+ def test_empty_string(self):
+ assert parse_string_style("") == {}
+
+ def test_no_delimiters(self):
+ assert parse_string_style("color: red background-color: blue") == {"color": "red background-color: blue"}
+
+ def test_incomplete_style(self):
+ assert parse_string_style("color: red; background-color") == {"color": "red"}
diff --git a/tests/test_autodiscover.py b/tests/test_autodiscover.py
index 62f655b1..03aee405 100644
--- a/tests/test_autodiscover.py
+++ b/tests/test_autodiscover.py
@@ -1,65 +1,58 @@
-import os
import sys
-from unittest import TestCase, mock
-from django.conf import settings
+import pytest
from django_components import AlreadyRegistered, registry
-from django_components.autodiscover import _filepath_to_python_module, autodiscover, import_libraries
+from django_components.autodiscovery import autodiscover, import_libraries
+from django_components.testing import djc_test
-from .django_test_setup import setup_test_config
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
-# NOTE: This is different from BaseTestCase in testutils.py, because here we need
-# TestCase instead of SimpleTestCase.
-class _TestCase(TestCase):
- def tearDown(self) -> None:
- super().tearDown()
- registry.clear()
-
-
-class TestAutodiscover(_TestCase):
+@djc_test
+class TestAutodiscover:
def test_autodiscover(self):
- setup_test_config({"autodiscover": False})
-
all_components = registry.all().copy()
- self.assertNotIn("single_file_component", all_components)
- self.assertNotIn("multi_file_component", all_components)
- self.assertNotIn("relative_file_component", all_components)
- self.assertNotIn("relative_file_pathobj_component", all_components)
+ assert "single_file_component" not in all_components
+ assert "multi_file_component" not in all_components
+ assert "relative_file_component" not in all_components
+ assert "relative_file_pathobj_component" not in all_components
try:
- modules = autodiscover(map_module=lambda p: "tests." + p)
+ modules = autodiscover(map_module=lambda p: "tests." + p if p.startswith("components") else p)
except AlreadyRegistered:
- self.fail("Autodiscover should not raise AlreadyRegistered exception")
+ pytest.fail("Autodiscover should not raise AlreadyRegistered exception")
- self.assertIn("tests.components.single_file", modules)
- self.assertIn("tests.components.multi_file.multi_file", modules)
- self.assertIn("tests.components.relative_file_pathobj.relative_file_pathobj", modules)
- self.assertIn("tests.components.relative_file.relative_file", modules)
+ assert "tests.components" in modules
+ assert "tests.components.single_file" in modules
+ assert "tests.components.staticfiles.staticfiles" in modules
+ assert "tests.components.multi_file.multi_file" in modules
+ assert "tests.components.relative_file_pathobj.relative_file_pathobj" in modules
+ assert "tests.components.relative_file.relative_file" in modules
+ assert "tests.test_app.components.app_lvl_comp.app_lvl_comp" in modules
+ assert "django_components.components" in modules
+ assert "django_components.components.dynamic" in modules
all_components = registry.all().copy()
- self.assertIn("single_file_component", all_components)
- self.assertIn("multi_file_component", all_components)
- self.assertIn("relative_file_component", all_components)
- self.assertIn("relative_file_pathobj_component", all_components)
+ assert "single_file_component" in all_components
+ assert "multi_file_component" in all_components
+ assert "relative_file_component" in all_components
+ assert "relative_file_pathobj_component" in all_components
-class TestImportLibraries(_TestCase):
+@djc_test
+class TestImportLibraries:
+ @djc_test(
+ components_settings={
+ "libraries": ["tests.components.single_file", "tests.components.multi_file.multi_file"]
+ }
+ )
def test_import_libraries(self):
- # Prepare settings
- setup_test_config(
- {
- "autodiscover": False,
- }
- )
- settings.COMPONENTS["libraries"] = ["tests.components.single_file", "tests.components.multi_file.multi_file"]
-
- # Ensure we start with a clean state
- registry.clear()
all_components = registry.all().copy()
- self.assertNotIn("single_file_component", all_components)
- self.assertNotIn("multi_file_component", all_components)
+ assert "single_file_component" not in all_components
+ assert "multi_file_component" not in all_components
# Ensure that the modules are executed again after import
if "tests.components.single_file" in sys.modules:
@@ -70,31 +63,24 @@ class TestImportLibraries(_TestCase):
try:
modules = import_libraries()
except AlreadyRegistered:
- self.fail("Autodiscover should not raise AlreadyRegistered exception")
+ pytest.fail("Autodiscover should not raise AlreadyRegistered exception")
- self.assertIn("tests.components.single_file", modules)
- self.assertIn("tests.components.multi_file.multi_file", modules)
+ assert "tests.components.single_file" in modules
+ assert "tests.components.multi_file.multi_file" in modules
all_components = registry.all().copy()
- self.assertIn("single_file_component", all_components)
- self.assertIn("multi_file_component", all_components)
-
- settings.COMPONENTS["libraries"] = []
+ assert "single_file_component" in all_components
+ assert "multi_file_component" in all_components
+ @djc_test(
+ components_settings={
+ "libraries": ["components.single_file", "components.multi_file.multi_file"]
+ }
+ )
def test_import_libraries_map_modules(self):
- # Prepare settings
- setup_test_config(
- {
- "autodiscover": False,
- }
- )
- settings.COMPONENTS["libraries"] = ["components.single_file", "components.multi_file.multi_file"]
-
- # Ensure we start with a clean state
- registry.clear()
all_components = registry.all().copy()
- self.assertNotIn("single_file_component", all_components)
- self.assertNotIn("multi_file_component", all_components)
+ assert "single_file_component" not in all_components
+ assert "multi_file_component" not in all_components
# Ensure that the modules are executed again after import
if "tests.components.single_file" in sys.modules:
@@ -103,62 +89,13 @@ class TestImportLibraries(_TestCase):
del sys.modules["tests.components.multi_file.multi_file"]
try:
- modules = import_libraries(map_module=lambda p: "tests." + p)
+ modules = import_libraries(map_module=lambda p: "tests." + p if p.startswith("components") else p)
except AlreadyRegistered:
- self.fail("Autodiscover should not raise AlreadyRegistered exception")
+ pytest.fail("Autodiscover should not raise AlreadyRegistered exception")
- self.assertIn("tests.components.single_file", modules)
- self.assertIn("tests.components.multi_file.multi_file", modules)
+ assert "tests.components.single_file" in modules
+ assert "tests.components.multi_file.multi_file" in modules
all_components = registry.all().copy()
- self.assertIn("single_file_component", all_components)
- self.assertIn("multi_file_component", all_components)
-
- settings.COMPONENTS["libraries"] = []
-
-
-class TestFilepathToPythonModule(_TestCase):
- def test_prepares_path(self):
- base_path = str(settings.BASE_DIR)
-
- the_path = os.path.join(base_path, "tests.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests",
- )
-
- the_path = os.path.join(base_path, "tests/components/relative_file/relative_file.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests.components.relative_file.relative_file",
- )
-
- def test_handles_nonlinux_paths(self):
- base_path = str(settings.BASE_DIR).replace("/", "//")
-
- with mock.patch("os.path.sep", new="//"):
- the_path = os.path.join(base_path, "tests.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests",
- )
-
- the_path = os.path.join(base_path, "tests//components//relative_file//relative_file.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests.components.relative_file.relative_file",
- )
-
- base_path = str(settings.BASE_DIR).replace("//", "\\")
- with mock.patch("os.path.sep", new="\\"):
- the_path = os.path.join(base_path, "tests.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests",
- )
-
- the_path = os.path.join(base_path, "tests\\components\\relative_file\\relative_file.py")
- self.assertEqual(
- _filepath_to_python_module(the_path),
- "tests.components.relative_file.relative_file",
- )
+ assert "single_file_component" in all_components
+ assert "multi_file_component" in all_components
diff --git a/tests/test_benchmark_django.py b/tests/test_benchmark_django.py
new file mode 100644
index 00000000..8d1ea2e0
--- /dev/null
+++ b/tests/test_benchmark_django.py
@@ -0,0 +1,6439 @@
+# NOTE: This file is used for benchmarking. Before editing this file,
+# please read through these:
+# - `benchmarks/README`
+# - https://github.com/django-components/django-components/pull/999
+
+import difflib
+import json
+from datetime import date, datetime, timedelta
+from dataclasses import dataclass, field, MISSING
+from enum import Enum
+from inspect import signature
+from pathlib import Path
+from types import MappingProxyType
+from typing import (
+ Any,
+ Callable,
+ Dict,
+ Iterable,
+ List,
+ Literal,
+ NamedTuple,
+ Optional,
+ Tuple,
+ Type,
+ TypedDict,
+ TypeVar,
+ Union,
+)
+
+import django
+from django import forms
+from django.conf import settings
+from django.http import HttpRequest
+from django.middleware import csrf
+from django.template import Context, Template
+from django.template.defaultfilters import title
+from django.utils.safestring import mark_safe
+from django.utils.timezone import now
+from django.contrib.humanize.templatetags.humanize import naturaltime
+from django.template.defaulttags import register as default_library
+
+from django_components import types, registry
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- IMPORTS END ------------ #
+
+# This variable is overridden by the benchmark runner
+CONTEXT_MODE: Literal["django", "isolated"] = "isolated"
+
+if not settings.configured:
+ settings.configure(
+ BASE_DIR=Path(__file__).resolve().parent,
+ INSTALLED_APPS=["django_components"],
+ TEMPLATES=[
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [
+ "tests/templates/",
+ "tests/components/", # Required for template relative imports in tests
+ ],
+ "OPTIONS": {
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ]
+ },
+ }
+ ],
+ COMPONENTS={
+ "autodiscover": False,
+ "context_behavior": CONTEXT_MODE,
+ },
+ MIDDLEWARE=[],
+ DATABASES={
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": ":memory:",
+ }
+ },
+ SECRET_KEY="secret",
+ ROOT_URLCONF="django_components.urls",
+ )
+ django.setup()
+else:
+ settings.COMPONENTS["context_behavior"] = CONTEXT_MODE
+
+#####################################
+#
+# IMPLEMENTATION START
+#
+#####################################
+
+templates_cache: Dict[int, Template] = {}
+
+def lazy_load_template(template: str) -> Template:
+ template_hash = hash(template)
+ if template_hash in templates_cache:
+ return templates_cache[template_hash]
+ else:
+ template_instance = Template(template)
+ templates_cache[template_hash] = template_instance
+ return template_instance
+
+#####################################
+# RENDER ENTRYPOINT
+#####################################
+
+def gen_render_data():
+ data = load_project_data_from_json(data_json)
+
+ # Generate Request and User
+ users = data.pop("users")
+ user = users[0]
+
+ bookmarks: List[ProjectBookmark] = [
+ {
+ "id": 82,
+ "project": data["project"],
+ "text": "Test bookmark",
+ "url": "http://localhost:8000/bookmarks/9/create",
+ "attachment": None,
+ }
+ ]
+
+ request = HttpRequest()
+ request.user = user
+ request.method = "GET"
+ request.path = "/projects/1"
+
+ data["layout_data"] = ProjectLayoutData(
+ bookmarks=bookmarks,
+ project=data["project"],
+ active_projects=[data["project"]],
+ request=request,
+ )
+
+ return data
+
+
+def render(data):
+ # Render
+ result = project_page(
+ Context(),
+ ProjectPageData(**data)
+ )
+
+ return result
+
+
+#####################################
+# DATA
+#####################################
+
+data_json = """
+{
+ "project": {
+ "pk": 1,
+ "fields": {
+ "name": "Project Name",
+ "organization": 1,
+ "status": "INPROGRESS",
+ "start_date": "2022-02-06",
+ "end_date": "2024-02-07"
+ }
+ },
+ "project_tags": [],
+ "phases": [
+ {
+ "pk": 8,
+ "fields": {
+ "project": 1,
+ "phase_template": 3
+ }
+ },
+ {
+ "pk": 7,
+ "fields": {
+ "project": 1,
+ "phase_template": 4
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "project": 1,
+ "phase_template": 5
+ }
+ },
+ {
+ "pk": 5,
+ "fields": {
+ "project": 1,
+ "phase_template": 6
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "project": 1,
+ "phase_template": 2
+ }
+ }
+ ],
+ "notes_1": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2025-02-07T08:59:58.689Z",
+ "modified": "2025-02-07T08:59:58.689Z",
+ "project": 1,
+ "text": "Test note 1"
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2025-02-07T08:59:58.689Z",
+ "modified": "2025-02-07T08:59:58.689Z",
+ "project": 1,
+ "text": "Test note 2"
+ }
+ }
+ ],
+ "comments_by_notes_1": {
+ "1": [
+ {
+ "pk": 3,
+ "fields": {
+ "parent": 1,
+ "notes": "Test note one two three",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "parent": 1,
+ "notes": "Test note 2",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "notes_2": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2024-02-07T11:20:49.085Z",
+ "modified": "2024-02-07T11:20:55.003Z",
+ "project": 1,
+ "text": "Test note x"
+ }
+ }
+ ],
+ "comments_by_notes_2": {
+ "1": [
+ {
+ "pk": 1,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 6",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 5",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 4",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 3",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "notes_3": [
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2024-02-07T11:20:49.085Z",
+ "modified": "2024-02-07T11:20:55.003Z",
+ "project": 1,
+ "text": "Test note 2"
+ }
+ }
+ ],
+ "comments_by_notes_3": {
+ "2": [
+ {
+ "pk": 1,
+ "fields": {
+ "parent": 2,
+ "text": "Test note 1",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 3,
+ "fields": {
+ "parent": 2,
+ "text": "Test note 0",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "roles_with_users": [
+ {
+ "pk": 6,
+ "fields": {
+ "user": 2,
+ "project": 1,
+ "name": "Assistant"
+ }
+ },
+ {
+ "pk": 7,
+ "fields": {
+ "user": 2,
+ "project": 1,
+ "name": "Owner"
+ }
+ }
+ ],
+ "contacts": [],
+ "outputs": [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 16",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 15,
+ "fields": {
+ "name": "Lorem ipsum 15",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 16,
+ "fields": {
+ "name": "Lorem ipsum 14",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 17,
+ "fields": {
+ "name": "Lorem ipsum 13",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 18,
+ "fields": {
+ "name": "Lorem ipsum 12",
+ "description": "",
+ "completed": true,
+ "phase": 4,
+ "dependency": null
+ }
+ },
+ [
+ [
+ {
+ "pk": 19,
+ "fields": {
+ "text": "Test bookmark",
+ "url": "http://localhost:8000/create/bookmmarks/9/",
+ "created_by": 1,
+ "output": 18
+ }
+ },
+ []
+ ]
+ ],
+ []
+ ],
+ [
+ {
+ "pk": 20,
+ "fields": {
+ "name": "Lorem ipsum 11",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": 14
+ }
+ },
+ [],
+ [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 10",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ []
+ ]
+ ]
+ ],
+ [
+ {
+ "pk": 21,
+ "fields": {
+ "name": "Lorem ipsum 9",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 22,
+ "fields": {
+ "name": "Lorem ipsum 8",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 23,
+ "fields": {
+ "name": "Lorem ipsum 7",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 24,
+ "fields": {
+ "name": "Lorem ipsum 6",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 25,
+ "fields": {
+ "name": "Lorem ipsum 5",
+ "description": "",
+ "completed": false,
+ "phase": 6,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 26,
+ "fields": {
+ "name": "Lorem ipsum 4",
+ "description": "",
+ "completed": false,
+ "phase": 6,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 27,
+ "fields": {
+ "name": "Lorem ipsum 3",
+ "description": "",
+ "completed": false,
+ "phase": 5,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 28,
+ "fields": {
+ "name": "Lorem ipsum 2",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": 14
+ }
+ },
+ [],
+ [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 1",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ []
+ ]
+ ]
+ ]
+ ],
+ "status_updates": [],
+ "user_is_project_member": true,
+ "user_is_project_owner": true,
+ "phase_titles": {
+ "PHASE_0": "Phase 0",
+ "PHASE_1": "Phase 1",
+ "PHASE_2": "Phase 2",
+ "PHASE_3": "Phase 3",
+ "PHASE_4": "Phase 4",
+ "PHASE_5": "Phase 5",
+ "LEGACY": "Legacy"
+ },
+ "users": [
+ {
+ "pk": 2,
+ "fields": {
+ "name": "UserName",
+ "is_staff": true
+ }
+ }
+ ],
+ "organizations": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Org Name"
+ }
+ }
+ ],
+ "phase_templates": [
+ {
+ "pk": 3,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 3",
+ "description": "## Phase 3",
+ "type": "PHASE_3"
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 2",
+ "description": "## Phase 2",
+ "type": "PHASE_2"
+ }
+ },
+ {
+ "pk": 5,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 4",
+ "description": "## Phase 4",
+ "type": "PHASE_4"
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 5",
+ "description": "## Phase 5",
+ "type": "PHASE_5"
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 1",
+ "description": "## Phase 1",
+ "type": "PHASE_1"
+ }
+ }
+ ]
+}
+"""
+
+#####################################
+# DATA LOADER
+#####################################
+
+
+def load_project_data_from_json(contents: str) -> dict:
+ """
+ Loads project data from JSON and resolves references between objects.
+ Returns the data with all resolvable references replaced with actual object references.
+ """
+ data = json.loads(contents)
+
+ # First create lookup tables for objects that will be referenced
+ users_by_id = {user["pk"]: {"id": user["pk"], **user["fields"]} for user in data.get("users", [])}
+
+ def _get_user(user_id: int):
+ return users_by_id[user_id] if user_id in users_by_id else data.get("users", [])[0]
+
+ organizations_by_id = {org["pk"]: {"id": org["pk"], **org["fields"]} for org in data.get("organizations", [])}
+
+ phase_templates_by_id = {pt["pk"]: {"id": pt["pk"], **pt["fields"]} for pt in data.get("phase_templates", [])}
+
+ # 1. Resolve project's organization reference
+ project = {"id": data["project"]["pk"], **data["project"]["fields"]}
+ if "organization" in project:
+ org_id = project.pop("organization") # Remove the ID field
+ project["organization"] = organizations_by_id[org_id] # Add the reference
+
+ # 2. Project tags - no changes needed
+ project_tags = data["project_tags"]
+
+ # 3. Resolve phases' references
+ phases = []
+ phases_by_id = {} # We'll need this for resolving output references later
+ for phase_data in data["phases"]:
+ phase = {"id": phase_data["pk"], **phase_data["fields"]}
+ if "project" in phase:
+ phase["project"] = project
+ if "phase_template" in phase:
+ template_id = phase.pop("phase_template")
+ phase["phase_template"] = phase_templates_by_id[template_id]
+ phases.append(phase)
+ phases_by_id[phase["id"]] = phase
+
+ # 4. Resolve notes_1 references
+ notes_1 = []
+ notes_1_by_id = {} # We'll need this for resolving notes references
+ for note_data in data["notes_1"]:
+ note = {"id": note_data["pk"], **note_data["fields"]}
+ if "project" in note:
+ note["project"] = project
+ notes_1.append(note)
+ notes_1_by_id[note["id"]] = note
+
+ # 5. Resolve comments_by_notes_1 references
+ comments_by_notes_1 = {}
+ for note_id, comments_list in data["comments_by_notes_1"].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {"id": comment_data["pk"], **comment_data["fields"]}
+ if "modified_by" in comment:
+ comment["modified_by"] = _get_user(comment["modified_by"])
+ if "parent" in comment:
+ comment["parent"] = notes_1_by_id[comment["parent"]]
+ resolved_comments.append(comment)
+ comments_by_notes_1[note_id] = resolved_comments
+
+ # 6. Resolve notes_2' references
+ notes_2 = []
+ notes_2_by_id = {} # We'll need this for resolving notes references
+ for note_data in data["notes_2"]:
+ note = {"id": note_data["pk"], **note_data["fields"]}
+ if "project" in note:
+ note["project"] = project
+ notes_2.append(note)
+ notes_2_by_id[note["id"]] = note
+
+ # 7. Resolve comments_by_notes_2 references
+ comments_by_notes_2 = {}
+ for note_id, comments_list in data["comments_by_notes_2"].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {"id": comment_data["pk"], **comment_data["fields"]}
+ if "modified_by" in comment:
+ comment["modified_by"] = _get_user(comment["modified_by"])
+ if "parent" in comment:
+ comment["parent"] = notes_2_by_id[comment["parent"]]
+ resolved_comments.append(comment)
+ comments_by_notes_2[note_id] = resolved_comments
+
+ # 8. Resolve notes_3 references
+ notes_3 = []
+ notes_3_by_id = {} # We'll need this for resolving notes references
+ for note_data in data["notes_3"]:
+ note = {"id": note_data["pk"], **note_data["fields"]}
+ if "project" in note:
+ note["project"] = project
+ notes_3.append(note)
+ notes_3_by_id[note["id"]] = note
+
+ # 9. Resolve comments_by_notes_3 references
+ comments_by_notes_3 = {}
+ for note_id, comments_list in data["comments_by_notes_3"].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {"id": comment_data["pk"], **comment_data["fields"]}
+ if "modified_by" in comment:
+ comment["modified_by"] = _get_user(comment["modified_by"])
+ if "parent" in comment:
+ comment["parent"] = notes_3_by_id[comment["parent"]]
+ resolved_comments.append(comment)
+ comments_by_notes_3[note_id] = resolved_comments
+
+ # 10. Resolve roles_with_users references
+ roles = []
+ for role_data in data["roles_with_users"]:
+ role = {"id": role_data["pk"], **role_data["fields"]}
+ if "project" in role:
+ role["project"] = project
+ if "user" in role:
+ role["user"] = _get_user(role["user"])
+ roles.append(role)
+
+ # 11. Contacts - EMPTY, so no changes needed
+ contacts = data["contacts"]
+
+ # 12. Resolve outputs references
+ resolved_outputs = []
+ outputs_by_id = {} # For resolving dependencies
+
+ # First pass: Create all output objects and build lookup
+ for output_tuple in data["outputs"]:
+ output_data = output_tuple[0]
+ output = {"id": output_data["pk"], **output_data["fields"]}
+ if "phase" in output:
+ output["phase"] = phases_by_id[output["phase"]]
+ outputs_by_id[output["id"]] = output
+
+ # Second pass: Process each output with its attachments and dependencies
+ for output_tuple in data["outputs"]:
+ output_data, attachments_data, dependencies_data = output_tuple
+ output = outputs_by_id[output_data["pk"]]
+
+ # Process attachments
+ resolved_attachments = []
+ for attachment_tuple in attachments_data:
+ attachment_data = attachment_tuple[0]
+ attachment = {"id": attachment_data["pk"], **attachment_data["fields"]}
+ if "created_by" in attachment:
+ attachment["created_by"] = _get_user(attachment["created_by"])
+ if "output" in attachment:
+ attachment["output"] = outputs_by_id[attachment["output"]]
+ # Keep tags as is
+ resolved_attachments.append((attachment, attachment_tuple[1]))
+
+ # Process dependencies
+ resolved_dependencies = []
+ for dep_tuple in dependencies_data:
+ dep_data = dep_tuple[0]
+ dep_output = outputs_by_id[dep_data["pk"]]
+ # Keep the tuple structure but with resolved references
+ resolved_dependencies.append((dep_output, dep_tuple[1]))
+
+ resolved_outputs.append((output, resolved_attachments, resolved_dependencies))
+
+ return {
+ "project": project,
+ "project_tags": project_tags,
+ "phases": phases,
+ "notes_1": notes_1,
+ "comments_by_notes_1": comments_by_notes_1,
+ "notes_2": notes_2,
+ "comments_by_notes_2": comments_by_notes_2,
+ "notes_3": notes_3,
+ "comments_by_notes_3": comments_by_notes_3,
+ "roles_with_users": roles,
+ "contacts": contacts,
+ "outputs": resolved_outputs,
+ "status_updates": data["status_updates"],
+ "user_is_project_member": data["user_is_project_member"],
+ "user_is_project_owner": data["user_is_project_owner"],
+ "phase_titles": data["phase_titles"],
+ "users": data["users"],
+ }
+
+
+#####################################
+# TYPES
+#####################################
+
+
+class User(TypedDict):
+ id: int
+ name: str
+
+
+class Organization(TypedDict):
+ id: int
+ name: str
+
+
+class Project(TypedDict):
+ id: int
+ name: str
+ organization: Organization
+ status: str
+ start_date: date
+ end_date: date
+
+
+class ProjectRole(TypedDict):
+ id: int
+ user: User
+ project: Project
+ name: str
+
+
+class ProjectBookmark(TypedDict):
+ id: int
+ project: Project
+ text: str
+ url: str
+ attachment: Optional["ProjectOutputAttachment"]
+
+
+class ProjectStatusUpdate(TypedDict):
+ id: int
+ project: Project
+ text: str
+ modified_by: User
+ modified: str
+
+
+class ProjectContact(TypedDict):
+ id: int
+ project: Project
+ link_id: str
+ name: str
+ job: str
+
+
+class PhaseTemplate(TypedDict):
+ id: int
+ name: str
+ description: str
+ type: str
+
+
+class ProjectPhase(TypedDict):
+ id: int
+ project: Project
+ phase_template: PhaseTemplate
+
+
+class ProjectOutput(TypedDict):
+ id: int
+ name: str
+ description: str
+ completed: bool
+ phase: ProjectPhase
+ dependency: Optional["ProjectOutput"]
+
+
+class ProjectOutputAttachment(TypedDict):
+ id: int
+ text: str
+ url: str
+ created_by: User
+ output: ProjectOutput
+
+
+class ProjectNote(TypedDict):
+ id: int
+ project: Project
+ text: str
+ created: str
+
+
+class ProjectNoteComment(TypedDict):
+ id: int
+ parent: ProjectNote
+ text: str
+ modified_by: User
+ modified: str
+
+
+#####################################
+# CONSTANTS
+#####################################
+
+FORM_SHORT_TEXT_MAX_LEN = 255
+
+
+# This allows us to compare Enum values against strings
+class StrEnum(str, Enum):
+ pass
+
+
+class TagResourceType(StrEnum):
+ PROJECT = "PROJECT"
+ PROJECT_BOOKMARK = "PROJECT_BOOKMARK"
+ PROJECT_OUTPUT = "PROJECT_OUTPUT"
+ PROJECT_OUTPUT_ATTACHMENT = "PROJECT_OUTPUT_ATTACHMENT"
+ PROJECT_TEMPLATE = "PROJECT_TEMPLATE"
+
+
+class ProjectPhaseType(StrEnum):
+ PHASE_1 = "PHASE_1"
+ PHASE_2 = "PHASE_2"
+ PHASE_3 = "PHASE_3"
+ PHASE_4 = "PHASE_4"
+ PHASE_5 = "PHASE_5"
+
+
+class TagTypeMeta(NamedTuple):
+ allowed_values: Tuple[str, ...]
+
+
+# Additional metadata for Tags
+#
+# NOTE: We use MappingProxyType as an immutable dict.
+# See https://stackoverflow.com/questions/2703599
+TAG_TYPE_META = MappingProxyType(
+ {
+ TagResourceType.PROJECT: TagTypeMeta(
+ allowed_values=(
+ "Tag 1",
+ "Tag 2",
+ "Tag 3",
+ "Tag 4",
+ ),
+ ),
+ TagResourceType.PROJECT_BOOKMARK: TagTypeMeta(
+ allowed_values=(
+ "Tag 5",
+ "Tag 6",
+ "Tag 7",
+ "Tag 8",
+ ),
+ ),
+ TagResourceType.PROJECT_OUTPUT: TagTypeMeta(
+ allowed_values=tuple(),
+ ),
+ TagResourceType.PROJECT_OUTPUT_ATTACHMENT: TagTypeMeta(
+ allowed_values=(
+ "Tag 9",
+ "Tag 10",
+ "Tag 11",
+ "Tag 12",
+ "Tag 13",
+ "Tag 14",
+ "Tag 15",
+ "Tag 16",
+ "Tag 17",
+ "Tag 18",
+ "Tag 19",
+ "Tag 20",
+ ),
+ ),
+ TagResourceType.PROJECT_TEMPLATE: TagTypeMeta(
+ allowed_values=("Tag 21",),
+ ),
+ }
+)
+
+
+class ProjectOutputDef(NamedTuple):
+ title: str
+ description: Optional[str] = None
+ dependency: Optional[str] = None
+
+
+class ProjectPhaseMeta(NamedTuple):
+ type: ProjectPhaseType
+ outputs: List[ProjectOutputDef]
+
+
+# This constant decides in which order the project phases are shown,
+# as well as what kind of name of description they have.
+#
+# NOTE: We use MappingProxyType as an immutable dict.
+# See https://stackoverflow.com/questions/2703599
+PROJECT_PHASES_META = MappingProxyType(
+ {
+ ProjectPhaseType.PHASE_1: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_1,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 0"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_2: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_2,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 1"),
+ ProjectOutputDef(title="Lorem ipsum 2"),
+ ProjectOutputDef(title="Lorem ipsum 3"),
+ ProjectOutputDef(title="Lorem ipsum 4"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_3: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_3,
+ outputs=[
+ ProjectOutputDef(
+ title="Lorem ipsum 6",
+ dependency="Lorem ipsum 1",
+ ),
+ ProjectOutputDef(
+ title="Lorem ipsum 7",
+ dependency="Lorem ipsum 1",
+ ),
+ ProjectOutputDef(title="Lorem ipsum 8"),
+ ProjectOutputDef(title="Lorem ipsum 9"),
+ ProjectOutputDef(title="Lorem ipsum 10"),
+ ProjectOutputDef(title="Lorem ipsum 11"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_4: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_4,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 12"),
+ ProjectOutputDef(title="Lorem ipsum 13"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_5: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_5,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 14"),
+ ],
+ ),
+ }
+)
+
+#####################################
+# THEME
+#####################################
+
+ThemeColor = Literal["default", "error", "success", "alert", "info"]
+ThemeVariant = Literal["primary", "secondary"]
+
+VARIANTS = ["primary", "secondary"]
+
+
+class ThemeStylingUnit(NamedTuple):
+ """
+ Smallest unit of info, this class defines a specific styling of a specific
+ component in a specific state.
+
+ E.g. styling of a disabled "Error" button.
+ """
+
+ color: str
+ """CSS class(es) specifying color"""
+ css: str = ""
+ """Other CSS classes not specific to color"""
+
+
+class ThemeStylingVariant(NamedTuple):
+ """
+ Collection of styling combinations that are meaningful as a group.
+
+ E.g. all "error" variants - primary, disabled, secondary, ...
+ """
+
+ primary: ThemeStylingUnit
+ primary_disabled: ThemeStylingUnit
+ secondary: ThemeStylingUnit
+ secondary_disabled: ThemeStylingUnit
+
+
+class Theme(NamedTuple):
+ """Class for defining a styling and color theme for the app."""
+
+ default: ThemeStylingVariant
+ error: ThemeStylingVariant
+ alert: ThemeStylingVariant
+ success: ThemeStylingVariant
+ info: ThemeStylingVariant
+
+ sidebar: str
+ sidebar_link: str
+ background: str
+ tab_active: str
+ tab_text_active: str
+ tab_text_inactive: str
+ check_interactive: str
+ check_static: str
+ check_outline: str
+
+
+_secondary_btn_styling = "ring-1 ring-inset"
+
+theme = Theme(
+ default=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-blue-600 text-white hover:bg-blue-500 focus-visible:outline-blue-600 transition"
+ ),
+ primary_disabled=ThemeStylingUnit(color="bg-blue-300 text-blue-50 focus-visible:outline-blue-600 transition"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-gray-800 ring-gray-300 hover:bg-gray-100 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-gray-300 ring-gray-300 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ error=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-red-600 text-white hover:bg-red-500 focus-visible:outline-red-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-red-300 text-white focus-visible:outline-red-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-red-600 ring-red-300 hover:bg-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-red-200 ring-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ alert=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-amber-500 text-white hover:bg-amber-400 focus-visible:outline-amber-500"),
+ primary_disabled=ThemeStylingUnit(color="bg-amber-100 text-orange-300 focus-visible:outline-amber-500"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-amber-500 ring-amber-300 hover:bg-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-orange-200 ring-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ success=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-green-600 text-white hover:bg-green-500 focus-visible:outline-green-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-green-300 text-white focus-visible:outline-green-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-green-600 ring-green-300 hover:bg-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-green-200 ring-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ info=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-sky-600 text-white hover:bg-sky-500 focus-visible:outline-sky-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-sky-300 text-white focus-visible:outline-sky-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-sky-600 ring-sky-300 hover:bg-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-sky-200 ring-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ sidebar="bg-neutral-900 text-neutral-200",
+ sidebar_link="hover:bg-neutral-700 hover:text-white transition",
+ background="bg-neutral-200",
+ tab_active="border-blue-700",
+ tab_text_active="text-blue-700",
+ tab_text_inactive="text-gray-500 hover:text-blue-700",
+ check_interactive="bg-blue-600 group-hover:bg-blue-500 transition",
+ check_static="bg-blue-600",
+ check_outline="border-2 border-blue-600 bg-white",
+)
+
+
+def get_styling_css(
+ variant: Optional["ThemeVariant"] = None,
+ color: Optional["ThemeColor"] = None,
+ disabled: Optional[bool] = None,
+):
+ """
+ Dynamically access CSS styling classes for a specific variant and state.
+
+ E.g. following two calls get styling classes for:
+ 1. Secondary error state
+ 1. Secondary alert disabled state
+ 2. Primary default disabled state
+ ```py
+ get_styling_css('secondary', 'error')
+ get_styling_css('secondary', 'alert', disabled=True)
+ get_styling_css(disabled=True)
+ ```
+ """
+ variant = variant or "primary"
+ color = color or "default"
+ disabled = disabled if disabled is not None else False
+
+ color_variants: ThemeStylingVariant = getattr(theme, color)
+
+ if variant not in VARIANTS:
+ raise ValueError(f'Unknown theme variant "{variant}", must be one of {VARIANTS}')
+
+ variant_name = variant if not disabled else f"{variant}_disabled"
+ styling: ThemeStylingUnit = getattr(color_variants, variant_name)
+
+ css = f"{styling.color} {styling.css}".strip()
+ return css
+
+
+#####################################
+# HELPERS
+#####################################
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+def format_timestamp(timestamp: datetime):
+ """
+ If the timestamp is more than 7 days ago, format it as "Jan 1, 2025".
+ Otherwise, format it as a natural time string (e.g. "3 days ago").
+ """
+ if now() - timestamp > timedelta(days=7):
+ return timestamp.strftime("%b %-d, %Y")
+ else:
+ return naturaltime(timestamp)
+
+
+def group_by(
+ lst: Iterable[T],
+ keyfn: Callable[[T, int], Any],
+ mapper: Optional[Callable[[T, int], U]] = None,
+):
+ """
+ Given a list, generates a key for each item in the list using the `keyfn`.
+
+ Returns a dictionary of generated keys, where each value is a list of corresponding
+ items.
+
+ Similar to Lodash's `groupby`.
+
+ Optionally map the values in the lists with `mapper`.
+ """
+ grouped: Dict[Any, List[Union[U, T]]] = {}
+ for index, item in enumerate(lst):
+ key = dynamic_apply(keyfn, item, index)
+ if key not in grouped:
+ grouped[key] = []
+
+ mapped_item = dynamic_apply(mapper, item, index) if mapper else item
+ grouped[key].append(mapped_item)
+ return grouped
+
+
+def dynamic_apply(fn: Callable, *args):
+ """
+ Given a function and positional arguments that should be applied to given function,
+ this helper will apply only as many arguments as the function defines, or only
+ as much as the number of arguments that we can apply.
+ """
+ mapper_args_count = len(signature(fn).parameters)
+ num_args_to_apply = min(mapper_args_count, len(args))
+ first_n_args = args[:num_args_to_apply]
+
+ return fn(*first_n_args)
+
+
+#####################################
+# SHARED FORMS
+#####################################
+
+
+class ConditionalEditForm(forms.Form):
+ """
+ Subclass of Django's Form that sets all fields as NON-editable based
+ on the `editable` field.
+ """
+
+ editable: bool = True
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ if self.editable is not None and not self.editable:
+ self._disable_all_form_fields()
+
+ def _disable_all_form_fields(self):
+ fields: Dict[str, forms.Field] = self.fields # type: ignore[assignment]
+ for form_field in fields.values():
+ form_field.widget.attrs["readonly"] = True
+
+
+#####################################
+# TEMPLATE TAG FILTERS
+#####################################
+
+
+@default_library.filter("alpine")
+def to_alpine_json(value: dict):
+ """
+ Serialize Python object such that it can be passed to Alpine callbacks
+ in Django templates.
+ """
+ # Avoid using double quotes since this value is passed to an HTML element
+ # attribute.
+ # NOTE: Maybe we could use HTML escaping to avoid the issue with double quotes?
+ data = json.dumps(value).replace('"', "'")
+ return data
+
+
+@default_library.filter("json")
+def to_json(value: dict):
+ """Serialize Python object to JSON."""
+ data = json.dumps(value)
+ return data
+
+
+@default_library.simple_tag
+def define(val=None):
+ return val
+
+
+@default_library.filter
+def get_item(dictionary: dict, key: str):
+ return dictionary.get(key)
+
+
+@default_library.filter("js")
+def serialize_to_js(obj):
+ """
+ Serialize a Python object to a JS-like expression.
+ Works recursively with nested dictionaries and lists.
+
+ So given a dict
+ `{"a": 123, "b": "console.log('abc')", "c": "'mystring'"}`
+
+ The filter exports:
+ `"{ a: 123, b: console.log('abc'), c: 'mystring' }"`
+ """
+ if isinstance(obj, dict):
+ # If the object is a dictionary, iterate through key-value pairs
+ items = []
+ for key, value in obj.items():
+ serialized_value = serialize_to_js(value) # Recursively serialize the value
+ items.append(f"{key}: {serialized_value}")
+ return f"{{ {', '.join(items)} }}"
+
+ elif isinstance(obj, (list, tuple)):
+ # If the object is a list, recursively serialize each item
+ serialized_items = [serialize_to_js(item) for item in obj]
+ return f"[{', '.join(serialized_items)}]"
+
+ elif isinstance(obj, str):
+ return obj
+
+ else:
+ # For other types (int, float, etc.), just return the string representation
+ return str(obj)
+
+
+#####################################
+# BUTTON
+#####################################
+
+button_template_str: types.django_html = """
+ {# Based on buttons from https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% if is_link %}
+
+ {% else %}
+
+ {% else %}
+
+ {% endif %}
+"""
+
+
+class ButtonData(NamedTuple):
+ href: Optional[str] = None
+ link: Optional[bool] = None
+ disabled: Optional[bool] = False
+ variant: Union["ThemeVariant", Literal["plain"]] = "primary"
+ color: Union["ThemeColor", str] = "default"
+ type: Optional[str] = "button"
+ attrs: Optional[dict] = None
+ slot_content: Optional[str] = ""
+
+
+@registry.library.simple_tag(takes_context=True)
+def button(context: Context, data: ButtonData):
+ common_css = (
+ "inline-flex w-full text-sm font-semibold"
+ " sm:mt-0 sm:w-auto focus-visible:outline-2 focus-visible:outline-offset-2"
+ )
+ if data.variant == "plain":
+ all_css_class = common_css
+ else:
+ button_classes = get_styling_css(data.variant, data.color, data.disabled) # type: ignore[arg-type]
+ all_css_class = f"{button_classes} {common_css} px-3 py-2 justify-center rounded-md shadow-sm"
+
+ is_link = not data.disabled and (data.href or data.link)
+
+ all_attrs = {**(data.attrs or {})}
+ if data.disabled:
+ all_attrs["aria-disabled"] = "true"
+
+ with context.push(
+ {
+ "href": data.href,
+ "disabled": data.disabled,
+ "type": data.type,
+ "btn_class": all_css_class,
+ "attrs": all_attrs,
+ "is_link": is_link,
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(button_template_str).render(context)
+
+
+#####################################
+# MENU
+#####################################
+
+MaybeNestedList = List[Union[T, List[T]]]
+MenuItemGroup = List["MenuItem"]
+
+
+@dataclass(frozen=True)
+class MenuItem:
+ """
+ Single menu item used with the `menu` components.
+
+ Menu items can be divided by a horizontal line to indicate that the items
+ belong together. In code, we specify this by wrapping the item(s) as an array.
+
+ ```py
+ menu_items = [
+ # Group 1
+ [
+ MenuItem(value="Edit", link="#"),
+ MenuItem(value="Duplicate"),
+ ],
+ # Group 2
+ MenuItem(value="Add step before"),
+ MenuItem(value="Add step after"),
+ MenuItem(value="Add child step"),
+ # Group 3
+ [
+ MenuItem(value="Delete"),
+ ],
+ ]
+ ```
+ """
+
+ value: Any
+ """Value of the menu item to render."""
+
+ link: Optional[str] = None
+ """
+ If set, the menu item will be wrapped in an `` tag pointing to this
+ link.
+ """
+
+ item_attrs: Optional[dict] = None
+ """HTML attributes specific to this menu item."""
+
+
+menu_template_str: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/elements/dropdowns #}
+
+ {% comment %}
+ NOTE: {{ model }} is the Alpine variable used for opening/closing. The variable name
+ is set dynamically, hence we use Django's double curly braces to refer to it.
+ {% endcomment %}
+
+ {# This is what opens the modal #}
+ {% if slot_activator %}
+
+"""
+
+
+class MenuData(NamedTuple):
+ items: MaybeNestedList[Union[MenuItem, str]]
+ model: Optional[str] = None
+ # CSS and HTML attributes
+ attrs: Optional[dict] = None
+ activator_attrs: Optional[dict] = None
+ list_attrs: Optional[dict] = None
+ # UX
+ close_on_esc: Optional[bool] = True
+ close_on_click_outside: Optional[bool] = True
+ anchor: Optional[str] = None
+ anchor_dir: Optional[str] = "bottom"
+ # Slots
+ slot_activator: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def menu(context: Context, data: MenuData):
+ is_model_overriden = bool(data.model)
+ model = data.model or "open"
+
+ all_list_attrs: dict = {}
+ if data.list_attrs:
+ all_list_attrs.update(data.list_attrs)
+ if data.anchor:
+ all_list_attrs[f"x-anchor.{data.anchor_dir}"] = data.anchor
+ all_list_attrs.update(
+ {
+ "x-show": model,
+ "x-cloak": "",
+ }
+ )
+
+ menu_list_data = MenuListData(
+ items=data.items,
+ attrs=all_list_attrs,
+ )
+
+ with context.push(
+ {
+ "model": model,
+ "is_model_overriden": is_model_overriden,
+ "close_on_click_outside": data.close_on_click_outside,
+ "close_on_esc": data.close_on_esc,
+ "activator_attrs": data.activator_attrs,
+ "attrs": data.attrs,
+ "menu_list_data": menu_list_data,
+ "slot_activator": data.slot_activator,
+ }
+ ):
+ return lazy_load_template(menu_template_str).render(context)
+
+
+#####################################
+# MENU LIST
+#####################################
+
+
+def _normalize_item(item: Union[MenuItem, str]):
+ # Wrap plain value in MenuItem
+ if not isinstance(item, MenuItem):
+ return MenuItem(value=item)
+ return item
+
+
+# Normalize a list of MenuItems such that they are all in groups. We achieve
+# this by collecting consecutive ungrouped items into a single group.
+def _normalize_items_to_groups(items: MaybeNestedList[Union[MenuItem, str]]):
+ def is_group(item):
+ return isinstance(item, Iterable) and not isinstance(item, str)
+
+ groups: List[List[Union[MenuItem, str]]] = []
+
+ curr_group: Optional[List[Union[MenuItem, str]]] = None
+ for index, item_or_grp in enumerate(items):
+ group: List[Union[MenuItem, str]] = []
+ if isinstance(item_or_grp, Iterable) and not isinstance(item_or_grp, str):
+ group = item_or_grp
+ else:
+ if curr_group is not None:
+ group = curr_group
+ else:
+ group = curr_group = []
+ group.append(item_or_grp)
+
+ is_not_last = index < len(items) - 1
+ if is_not_last and not is_group(items[index + 1]):
+ continue
+ groups.append(group)
+ curr_group = None
+
+ return groups
+
+
+def prepare_menu_items(items: MaybeNestedList[Union[MenuItem, str]]):
+ groups = _normalize_items_to_groups(items)
+ normalized_groups: List[MenuItemGroup] = []
+
+ for group in groups:
+ norm_group = list(map(_normalize_item, group))
+ normalized_groups.append(norm_group)
+
+ return normalized_groups
+
+
+menu_list_template_str: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/elements/dropdowns #}
+
+ {{ slot_activator }}
+
+ {% endif %}
+
+ {% menu_list menu_list_data %}
+
+ {% for group in item_groups %}
+
+""" # noqa: E501
+
+
+class MenuListData(NamedTuple):
+ items: MaybeNestedList[Union[MenuItem, str]]
+ attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def menu_list(context: Context, data: MenuListData):
+ item_groups = prepare_menu_items(data.items)
+
+ with context.push(
+ {
+ "item_groups": item_groups,
+ "attrs": data.attrs,
+ }
+ ):
+ return lazy_load_template(menu_list_template_str).render(context)
+
+
+#####################################
+# TABLE
+#####################################
+
+
+class TableHeader(NamedTuple):
+ """Table header data structure used with the `table` components."""
+
+ name: str
+ """Header name, as displayed to the users."""
+
+ key: str
+ """Dictionary key on `TableRow.cols` that holds data for this header."""
+
+ hidden: Optional[bool] = None
+ """
+ Whether to hide the header. The column will still be rendered,
+ only the column title will be hidden.
+ """
+
+ cell_attrs: Optional[dict] = None
+ """HTML attributes specific to this table header cell."""
+
+
+@dataclass(frozen=True)
+class TableCell:
+ """Single table cell (row + col) used with the `table` components."""
+
+ value: Any
+ """Value of the cell to render."""
+
+ colspan: int = 1
+ """
+ How many columns should this cell occupy.
+
+ See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#colspan
+ """
+
+ link: Optional[str] = None
+ """
+ If set, the cell value will be wrapped in an `` tag pointing to this
+ link.
+ """
+
+ link_attrs: Optional[dict] = None
+ """
+ HTML attributes for the `` tag wrapping the link, if `link` is set.
+ """
+
+ cell_attrs: Optional[dict] = None
+ """HTML attributes specific to this table cell."""
+
+ linebreaks: Optional[bool] = None
+ """Whether to apply the `linebreaks` filter to this table cell."""
+
+ def __post_init__(self):
+ if not isinstance(self.colspan, int) or self.colspan < 1:
+ raise ValueError("TableCell.colspan must be a non-negative integer." f" Instead got {self.colspan}")
+
+
+NULL_CELL = TableCell("")
+"""Definition of an empty cell"""
+
+
+@dataclass(frozen=True)
+class TableRow:
+ """
+ Table row data structure used with the `table` components.
+
+ TableRow holds columnar data in the `cols` dict, e.g.:
+ ```py
+ rows = [
+ TableRow(
+ cols={
+ 'name': TableCell(
+ value='My Name',
+ link='https://www.example.com',
+ link_attrs={
+ "class": 'font-weight-bold',
+ },
+ ),
+ 'desc': 'Lorem Ipsum'
+ }
+ ),
+ ]
+ ```
+ """
+
+ cols: Dict[str, TableCell] = field(default_factory=dict)
+ """Data within this row."""
+
+ row_attrs: Optional[dict] = None
+ """HTML attributes for this row."""
+
+ col_attrs: Optional[dict] = None
+ """
+ HTML attributes for each column in this row.
+
+ NOTE: This may be overriden by `TableCell.cell_attrs`.
+ """
+
+
+def create_table_row(
+ cols: Optional[Dict[str, Union[TableCell, Any]]] = None,
+ row_attrs: Optional[dict] = None,
+ col_attrs: Optional[dict] = None,
+):
+ # Normalize the values of `cols` to `TableCell` instances. This
+ # way we allow to set values of `self.cols` dict as plain values, e.g.:
+ #
+ # ```py
+ # create_table_row(
+ # cols={
+ # "my_value": 12
+ # }
+ # )
+ # ```
+ #
+ # Instead of having to wrap it in `TableCell` instance, like so:
+ #
+ # ```py
+ # TableRow(
+ # cols={
+ # "my_value": TableCell(value=12)
+ # }
+ # )
+ # ```
+ resolved_cols: Dict[str, TableCell] = {}
+ if cols:
+ for key, val in cols.items():
+ resolved_cols[key] = TableCell(value=val) if not isinstance(val, TableCell) else val
+
+ return TableRow(
+ cols=resolved_cols,
+ row_attrs=row_attrs,
+ col_attrs=col_attrs,
+ )
+
+
+def prepare_row_headers(row: TableRow, headers: List[TableHeader]):
+ # Skip headers when cells have colspan > 1, thus merging those cells
+ final_row_headers = []
+ headers_to_skip = 0
+ for header in headers:
+ if headers_to_skip > 0:
+ headers_to_skip -= 1
+ continue
+
+ final_row_headers.append(header)
+ cell = row.cols.get(header.key, None)
+ if cell is not None:
+ headers_to_skip = cell.colspan - 1
+
+ return final_row_headers
+
+
+table_template_str: types.django_html = """
+
+ {% for item in group %}
+ {% if item.link %}
+
+ {{ item.value }}
+
+ {% else %}
+
+ {% endfor %}
+
+ {{ item.value }}
+
+ {% endif %}
+ {% endfor %}
+
+
+"""
+
+
+class TableData(NamedTuple):
+ headers: List[TableHeader]
+ rows: List[TableRow]
+ attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def table(context: Context, data: TableData):
+ rows_to_render = [tuple([row, prepare_row_headers(row, data.headers)]) for row in data.rows]
+
+ with context.push(
+ {
+ "headers": data.headers,
+ "rows_to_render": rows_to_render,
+ "NULL_CELL": NULL_CELL,
+ "attrs": data.attrs,
+ }
+ ):
+ return lazy_load_template(table_template_str).render(context)
+
+
+#####################################
+# ICON
+#####################################
+
+icon_template_str: types.django_html = """
+
+
+
+
+
+
+
+ | + + {% if header.hidden %} + {{ header.name }} + {% else %} + {{ header.name }} + {% endif %} + + | + {% endfor %} +
|---|
| + + {% if cell.link %} + + {% if cell.linebreaks %} + {{ cell.value | linebreaksbr }} + {% else %} + {{ cell.value }} + {% endif %} + + {% else %} + {% if cell.linebreaks %} + {{ cell.value | linebreaksbr }} + {% else %} + {{ cell.value }} + {% endif %} + {% endif %} + + | + {% endfor %} +
+ {% if href %}
+
+ {% else %}
+
+ {% endif %}
+ {% heroicon heroicon_data %}
+ {{ slot_content }}
+
+ {% if href %}
+
+ {% else %}
+
+ {% endif %}
+
+"""
+
+
+class IconData(NamedTuple):
+ name: str
+ variant: Optional[str] = None
+ size: Optional[int] = None
+ stroke_width: Optional[float] = None
+ viewbox: Optional[str] = None
+ svg_attrs: Optional[dict] = None
+ # Note: Unlike the underlying icon component, this component uses color CSS classes
+ color: Optional[str] = ""
+ icon_color: Optional[str] = ""
+ text_color: Optional[str] = ""
+ href: Optional[str] = None
+ text_attrs: Optional[dict] = None
+ link_attrs: Optional[dict] = None
+ attrs: Optional[dict] = None
+ # Slots
+ slot_content: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def icon(context: Context, data: IconData):
+ # Allow to set icon and text independently, or both at same time via `color` prop
+ icon_color = data.color if not data.icon_color else data.icon_color
+ text_color = data.color if not data.text_color else data.text_color
+
+ svg_attrs = data.svg_attrs.copy() if data.svg_attrs else {}
+ if not svg_attrs.get("class"):
+ svg_attrs["class"] = ""
+ svg_attrs["class"] += f" {icon_color or ''} h-6 w-6 shrink-0"
+
+ heroicon_data = HeroIconData(
+ name=data.name,
+ variant=data.variant,
+ size=data.size,
+ viewbox=data.viewbox,
+ stroke_width=data.stroke_width,
+ attrs=svg_attrs,
+ )
+
+ with context.push(
+ {
+ "name": data.name,
+ "variant": data.variant,
+ "size": data.size,
+ "viewbox": data.viewbox,
+ "stroke_width": data.stroke_width,
+ "svg_attrs": svg_attrs,
+ "text_color": text_color,
+ "text_attrs": data.text_attrs,
+ "link_attrs": data.link_attrs,
+ "href": data.href,
+ "attrs": data.attrs,
+ "heroicon_data": heroicon_data,
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(icon_template_str).render(context)
+
+
+#####################################
+# HEROICONS
+#####################################
+
+# Single hard-coded icon
+ICONS = {
+ "outline": {
+ "academic-cap": [
+ {
+ "stroke-linecap": "round",
+ "stroke-linejoin": "round",
+ "d": "M4.26 10.147a60.438 60.438 0 0 0-.491 6.347A48.62 48.62 0 0 1 12 20.904a48.62 48.62 0 0 1 8.232-4.41 60.46 60.46 0 0 0-.491-6.347m-15.482 0a50.636 50.636 0 0 0-2.658-.813A59.906 59.906 0 0 1 12 3.493a59.903 59.903 0 0 1 10.399 5.84c-.896.248-1.783.52-2.658.814m-15.482 0A50.717 50.717 0 0 1 12 13.489a50.702 50.702 0 0 1 7.74-3.342M6.75 15a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm0 0v-3.675A55.378 55.378 0 0 1 12 8.443m-7.007 11.55A5.981 5.981 0 0 0 6.75 15.75v-1.5", # noqa: E501
+ }
+ ]
+ }
+}
+
+
+class ComponentDefaultsMeta(type):
+ def __new__(mcs, name: str, bases: Tuple, namespace: Dict) -> Type:
+ # Apply dataclass decorator to the class
+ return dataclass(super().__new__(mcs, name, bases, namespace))
+
+
+class ComponentDefaults(metaclass=ComponentDefaultsMeta):
+ def __post_init__(self) -> None:
+ fields = self.__class__.__dataclass_fields__ # type: ignore[attr-defined]
+ for field_name, dataclass_field in fields.items():
+ if dataclass_field.default is not MISSING:
+ if getattr(self, field_name) is None:
+ setattr(self, field_name, dataclass_field.default)
+
+
+class IconDefaults(ComponentDefaults):
+ name: str
+ variant: str = "outline"
+ size: int = 24
+ color: str = "currentColor"
+ stroke_width: float = 1.5
+ viewbox: str = "0 0 24 24"
+ attrs: Optional[Dict] = None
+
+
+heroicon_template_str: types.django_html = """
+ {% load component_tags %}
+
+"""
+
+
+class HeroIconData(NamedTuple):
+ name: str
+ variant: Optional[str] = None
+ size: Optional[int] = None
+ color: Optional[str] = None
+ stroke_width: Optional[float] = None
+ viewbox: Optional[str] = None
+ attrs: Optional[Dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def heroicon(context: Context, data: HeroIconData):
+ kwargs = IconDefaults(**data._asdict())
+
+ if kwargs.variant not in ["outline", "solid"]:
+ raise ValueError(f"Invalid variant: {kwargs.variant}. Must be either 'outline' or 'solid'")
+
+ # variant_icons = ICONS[kwargs.variant]
+ variant_icons = ICONS["outline"]
+ icon_name = "academic-cap"
+
+ if icon_name not in variant_icons:
+ # Give users a helpful message by fuzzy-search the closest key
+ msg = ""
+ icon_names = list(variant_icons.keys())
+ if icon_names:
+ fuzzy_matches = difflib.get_close_matches(icon_name, icon_names, n=3, cutoff=0.7)
+ if fuzzy_matches:
+ suggestions = ", ".join([f"'{match}'" for match in fuzzy_matches])
+ msg += f". Did you mean any of {suggestions}?"
+
+ raise ValueError(f"Invalid icon name: {icon_name}{msg}")
+
+ icon_paths = variant_icons[icon_name]
+
+ # These are set as "default" attributes, so users can override them
+ # by passing them in the `attrs` argument.
+ default_attrs: Dict[str, Any] = {
+ "viewBox": kwargs.viewbox,
+ "style": f"width: {kwargs.size}px; height: {kwargs.size}px",
+ "aria-hidden": "true",
+ }
+
+ # The SVG applies the color differently in "outline" and "solid" versions
+ if kwargs.variant == "outline":
+ default_attrs["fill"] = "none"
+ default_attrs["stroke"] = kwargs.color
+ default_attrs["stroke-width"] = kwargs.stroke_width
+ else:
+ default_attrs["fill"] = kwargs.color
+ default_attrs["stroke"] = "none"
+
+ with context.push(
+ {
+ "icon_paths": icon_paths,
+ "default_attrs": default_attrs,
+ "attrs": kwargs.attrs,
+ }
+ ):
+ return lazy_load_template(heroicon_template_str).render(context)
+
+
+#####################################
+# EXPANSION PANEL
+#####################################
+
+expansion_panel_template_str: types.django_html = """
+
+
+
+
+"""
+
+
+class ExpansionPanelData(NamedTuple):
+ open: Optional[bool] = False
+ panel_id: Optional[str] = None
+ attrs: Optional[dict] = None
+ header_attrs: Optional[dict] = None
+ content_attrs: Optional[dict] = None
+ icon_position: Literal["left", "right"] = "left"
+ slot_header: Optional[str] = None
+ slot_content: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def expansion_panel(context: Context, data: ExpansionPanelData):
+ init_data = {"open": data.open}
+
+ expand_icon_data = IconData(
+ name="chevron-down",
+ variant="outline",
+ attrs={
+ "style": "width: fit-content;",
+ "class": "{ 'rotate-180': isOpen }",
+ },
+ )
+
+ with context.push(
+ {
+ "attrs": data.attrs,
+ "header_attrs": data.header_attrs,
+ "content_attrs": data.content_attrs,
+ "icon_position": data.icon_position,
+ "init_data": init_data,
+ "panel_id": data.panel_id if data.panel_id else False,
+ "expand_icon_data": expand_icon_data,
+ "slot_header": data.slot_header,
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(expansion_panel_template_str).render(context)
+
+#####################################
+# PROJECT_PAGE
+#####################################
+
+
+# Tabs on this page and the query params to open specific tabs on page load.
+class ProjectPageTabsToQueryParams(Enum):
+ PROJECT_INFO = {"tabs-proj-right": "1"}
+ OUTPUTS = {"tabs-proj-right": "5"}
+
+
+project_page_header_template_str: types.django_html = """
+
+ {% if icon_position == "left" %}
+ {% icon expand_icon_data %}
+ {% endif %}
+
+ {{ slot_header }}
+
+ {% if icon_position == "right" %}
+ {% icon expand_icon_data %}
+ {% endif %}
+
+
+ {{ slot_content }}
+
+
+
+"""
+
+project_page_tabs_template_str: types.django_html = """
+ {% for tab in project_page_tabs %}
+ {% tab_item tab %}
+ {% endfor %}
+"""
+
+
+class ProjectPageData(NamedTuple):
+ phases: List[ProjectPhase]
+ project_tags: List[str]
+ notes_1: List[ProjectNote]
+ comments_by_notes_1: Dict[str, List[ProjectNoteComment]]
+ notes_2: List[ProjectNote]
+ comments_by_notes_2: Dict[str, List[ProjectNoteComment]]
+ notes_3: List[ProjectNote]
+ comments_by_notes_3: Dict[str, List[ProjectNoteComment]]
+ status_updates: List[ProjectStatusUpdate]
+ roles_with_users: List[ProjectRole]
+ contacts: List[ProjectContact]
+ outputs: List["OutputWithAttachmentsAndDeps"]
+ user_is_project_member: bool
+ user_is_project_owner: bool
+ phase_titles: Dict[ProjectPhaseType, str]
+ # Used by project layout
+ layout_data: "ProjectLayoutData"
+ project: Project
+ breadcrumbs: Optional[List["Breadcrumb"]] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_page(context: Context, data: ProjectPageData):
+ rendered_phases: List[ListItem] = []
+ phases_by_type = {p["phase_template"]["type"]: p for p in data.phases}
+ for phase_meta in PROJECT_PHASES_META.values():
+ phase = phases_by_type[phase_meta.type]
+ title = data.phase_titles[phase_meta.type]
+ rendered_phases.append(
+ ListItem(
+ value=title,
+ link=f"/projects/{data.project['id']}/phases/{phase['phase_template']['type']}",
+ )
+ )
+
+ project_page_tabs = [
+ TabItemData(
+ header="Project Info",
+ slot_content=project_info(
+ context,
+ ProjectInfoData(
+ project=data.project,
+ project_tags=data.project_tags,
+ roles_with_users=data.roles_with_users,
+ contacts=data.contacts,
+ status_updates=data.status_updates,
+ editable=data.user_is_project_owner,
+ )
+ ),
+ ),
+ TabItemData(
+ header="Notes 1",
+ slot_content=project_notes(
+ context,
+ ProjectNotesData(
+ project_id=data.project["id"],
+ notes=data.notes_1,
+ comments_by_notes=data.comments_by_notes_1, # type: ignore[arg-type]
+ editable=data.user_is_project_member,
+ )
+ ),
+ ),
+ TabItemData(
+ header="Notes 2",
+ slot_content=project_notes(
+ context,
+ ProjectNotesData(
+ project_id=data.project["id"],
+ notes=data.notes_2,
+ comments_by_notes=data.comments_by_notes_2, # type: ignore[arg-type]
+ editable=data.user_is_project_member,
+ )
+ ),
+ ),
+ TabItemData(
+ header="Notes 3",
+ slot_content=project_notes(
+ context,
+ ProjectNotesData(
+ project_id=data.project["id"],
+ notes=data.notes_3,
+ comments_by_notes=data.comments_by_notes_3, # type: ignore[arg-type]
+ editable=data.user_is_project_member,
+ )
+ ),
+ ),
+ TabItemData(
+ header="Outputs",
+ slot_content=project_outputs_summary(
+ context,
+ ProjectOutputsSummaryData(
+ project_id=data.project["id"],
+ outputs=data.outputs,
+ editable=data.user_is_project_member,
+ phase_titles=data.phase_titles,
+ )
+ ),
+ ),
+ ]
+
+ def render_tabs(tabs_context: Context):
+ with tabs_context.push(
+ {
+ "project_page_tabs": project_page_tabs,
+ }
+ ):
+ return lazy_load_template(project_page_tabs_template_str).render(tabs_context)
+
+ phases_content = list_tag(
+ context,
+ ListData(
+ items=rendered_phases,
+ item_attrs={"class": "py-5"},
+ )
+ )
+ with context.push(
+ {
+ "project": data.project,
+ }
+ ):
+ header_content = lazy_load_template(project_page_header_template_str).render(context)
+
+ layout_tabbed_data = ProjectLayoutTabbedData(
+ layout_data=data.layout_data,
+ breadcrumbs=data.breadcrumbs,
+ top_level_tab_index=1,
+ slot_left_panel=phases_content,
+ slot_header=header_content,
+ slot_tabs=CallableSlot(render_tabs),
+ )
+
+ return project_layout_tabbed(context, layout_tabbed_data)
+
+#####################################
+# PROJECT_LAYOUT_TABBED
+#####################################
+
+
+class ProjectLayoutData(NamedTuple):
+ request: HttpRequest
+ active_projects: List[Project]
+ project: Project
+ bookmarks: List[ProjectBookmark]
+
+
+def gen_tabs(project_id: int):
+ return [
+ TabStaticEntry(
+ header="Tab 2",
+ href=f"/projects/{project_id}/tab-2",
+ content=None,
+ ),
+ TabStaticEntry(
+ header="Tab 1",
+ href=f"/projects/{project_id}/tab-1",
+ content=None,
+ ),
+ ]
+
+
+project_layout_tabbed_content_template_str: types.django_html = """
+ {{ slot_header }}
+
+ {% if top_level_tab_index is not None %}
+ {% tabs_static content_tabs_static_data %}
+ {% endif %}
+
+
+
+
+
+ {{ project.name }}
+
+ {{ project.start_date }} - {{ project.end_date }}
+
+
+
+ {# Split the content to 2 columns, based on whether `left_panel` slot is filled #}
+ {% if slot_left_panel %}
+
+"""
+
+
+class ProjectLayoutTabbedData(NamedTuple):
+ layout_data: ProjectLayoutData
+ breadcrumbs: Optional[List["Breadcrumb"]] = None
+ top_level_tab_index: Optional[int] = None
+ variant: Literal["thirds", "halves"] = "thirds"
+ # Slots
+ slot_left_panel: Optional[str] = None
+ slot_js: Optional[str] = None
+ slot_css: Optional[str] = None
+ slot_header: Optional[str] = None
+ slot_tabs: Optional["CallableSlot"] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_layout_tabbed(context: Context, data: ProjectLayoutTabbedData):
+ projects_url = "/projects"
+ curr_project_url = f"/projects/{data.layout_data.project['id']}"
+
+ prefixed_breadcrumbs = [
+ Breadcrumb(
+ link=projects_url,
+ value=icon(
+ context,
+ IconData(
+ name="home",
+ variant="outline",
+ size=20,
+ stroke_width=2,
+ color="text-gray-400 hover:text-gray-500",
+ ),
+ ),
+ ),
+ Breadcrumb(value=data.layout_data.project["name"], link=curr_project_url),
+ *(data.breadcrumbs or []),
+ ]
+
+ top_level_tabs = gen_tabs(data.layout_data.project["id"])
+
+ left_pannel_attrs = {
+ "class": "w-1/3" if data.variant == "thirds" else "w-1/2",
+ }
+ right_pannel_attrs = {
+ "class": "w-2/3" if data.variant == "thirds" else "w-1/2",
+ }
+
+ breadcrumbs_content = breadcrumbs_tag(context, BreadcrumbsData(items=prefixed_breadcrumbs))
+ bookmarks_content = bookmarks_tag(
+ context,
+ BookmarksData(bookmarks=data.layout_data.bookmarks, project_id=data.layout_data.project["id"])
+ )
+
+ content_tabs_static_data = TabsStaticData(
+ tabs=top_level_tabs,
+ tab_index=data.top_level_tab_index or 0,
+ )
+
+ content_tabs_data = TabsData(
+ name="proj-right",
+ attrs={"class": "p-6 h-full"},
+ content_attrs={"class": "flex flex-col"},
+ slot_content=data.slot_tabs,
+ )
+
+ with context.push(
+ {
+ "layout_data": data.layout_data,
+ "breadcrumbs": prefixed_breadcrumbs,
+ "bookmarks": data.layout_data.bookmarks,
+ "project": data.layout_data.project,
+ "top_level_tabs": top_level_tabs,
+ "top_level_tab_index": data.top_level_tab_index,
+ "theme": theme,
+ "left_pannel_attrs": left_pannel_attrs,
+ "right_pannel_attrs": right_pannel_attrs,
+ "content_tabs_static_data": content_tabs_static_data,
+ "content_tabs_data": content_tabs_data,
+ "slot_left_panel": data.slot_left_panel,
+ "slot_header": data.slot_header,
+ "slot_tabs": data.slot_tabs,
+ }
+ ):
+ layout_content = lazy_load_template(project_layout_tabbed_content_template_str).render(context)
+
+ layout_data = LayoutData(
+ data=data.layout_data,
+ attrs=None,
+ slot_js=data.slot_js,
+ slot_css=data.slot_css,
+ slot_header=breadcrumbs_content,
+ slot_sidebar=bookmarks_content,
+ slot_content=layout_content,
+ )
+
+ return layout(context, layout_data)
+
+
+#####################################
+# LAYOUT
+#####################################
+
+# inputs:
+# - attrs
+# - sidebar_data
+# - navbar_data
+# - slot_header
+# - slot_content
+layout_base_content_template_str: types.django_html = """
+
+
+
+ {{ slot_left_panel }}
+
+
+ {% endif %}
+
+
+ {% endif %}
+
+ {% tabs content_tabs_data %}
+
+
+ {% if slot_left_panel %}
+
+
+
+"""
+
+
+layout_template_str: types.django_html = """
+ {% render_context_provider render_context_provider_data %}
+"""
+
+
+class LayoutData(NamedTuple):
+ data: ProjectLayoutData
+ attrs: Optional[dict] = None
+ # Slots
+ slot_js: Optional[str] = None
+ slot_css: Optional[str] = None
+ slot_header: Optional[str] = None
+ slot_content: Optional[str] = None
+ slot_sidebar: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def layout(context: Context, data: LayoutData):
+ def render_context_provider_slot(provided_context: Context):
+ navbar_data = NavbarData(
+ attrs={
+ "@sidebar_toggle": "toggleSidebar",
+ },
+ )
+
+ sidebar_data = SidebarData(
+ active_projects=data.data.active_projects,
+ slot_content=data.slot_sidebar,
+ )
+
+ with provided_context.push(
+ {
+ "attrs": data.attrs,
+ "navbar_data": navbar_data,
+ "sidebar_data": sidebar_data,
+ "slot_header": data.slot_header,
+ "slot_content": data.slot_content,
+ }
+ ):
+ layout_base_content = lazy_load_template(layout_base_content_template_str).render(provided_context)
+
+ base_data = BaseData(
+ slot_content=layout_base_content,
+ slot_css=data.slot_css,
+ slot_js=(data.slot_js or "")
+ + """
+
+ """,
+ )
+
+ with provided_context.push(
+ {
+ "base_data": base_data,
+ }
+ ):
+ return lazy_load_template("{% base base_data %}").render(provided_context)
+
+ render_context_provider_data = RenderContextProviderData(
+ request=data.data.request,
+ slot_content=CallableSlot(render=render_context_provider_slot),
+ )
+
+ with context.push(
+ {
+ "render_context_provider_data": render_context_provider_data,
+ }
+ ):
+ return lazy_load_template(layout_template_str).render(context)
+
+
+#####################################
+# RENDER_CONTEXT_PROVIDER
+#####################################
+
+
+class RenderContext(NamedTuple):
+ """
+ Data that's commonly available in all template rendering.
+
+ In templates, we can assume that the data defined here is ALWAYS defined.
+ """
+
+ request: HttpRequest
+ user: User
+ csrf_token: str
+
+
+class CallableSlot(NamedTuple):
+ render: Callable[[Context], str]
+
+
+class RenderContextProviderData(NamedTuple):
+ request: HttpRequest
+ slot_content: Optional[CallableSlot] = None
+
+
+# This component "provides" data. This is similar to ContextProviders
+# in React, or the "provide" part of Vue's provide/inject feature.
+#
+# Components nested inside `RenderContextProvider` can access the
+# data with `self.inject("render_context")`.
+@registry.library.simple_tag(takes_context=True)
+def render_context_provider(context: Context, data: RenderContextProviderData) -> str:
+ if not data.slot_content:
+ return ""
+
+ csrf_token = csrf.get_token(data.request)
+ render_context = RenderContext(
+ request=data.request,
+ user=data.request.user,
+ csrf_token=csrf_token,
+ )
+
+ with context.push({"render_context": render_context}):
+ return data.slot_content.render(context)
+
+
+#####################################
+# BASE
+#####################################
+
+base_template_str: types.django_html = """
+ {% load static %}
+
+
+
+
+
+
+
+
+ {% sidebar sidebar_data %}
+
+
+
+ {% navbar navbar_data %}
+
+
+ {{ slot_header }}
+
+
+
+ {{ slot_content }}
+
+
+
+"""
+
+
+class SidebarData(NamedTuple):
+ active_projects: List[Project]
+ attrs: Optional[dict] = None
+ slot_content: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def sidebar(context: Context, data: SidebarData):
+ render_context: RenderContext = context["render_context"]
+ user = render_context.user
+ items = gen_sidebar_menu_items(data.active_projects)
+
+ faq_url = "/faq"
+
+ download_icon_data = IconData(
+ name="document-arrow-down",
+ variant="outline",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="Download",
+ )
+
+ feedback_icon_data = IconData(
+ name="megaphone",
+ variant="outline",
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ link_attrs={
+ "target": "_blank",
+ },
+ slot_content="Feedback",
+ )
+
+ faq_icon_data = IconData(
+ name="user-group",
+ variant="outline",
+ href=faq_url,
+ color=theme.sidebar_link,
+ text_attrs={
+ "class": "p-2",
+ },
+ slot_content="FAQ",
+ )
+
+ with context.push(
+ {
+ "items": items,
+ "attrs": data.attrs,
+ "user": user,
+ "theme": theme,
+ "faq_url": faq_url,
+ "download_icon_data": download_icon_data,
+ "feedback_icon_data": feedback_icon_data,
+ "faq_icon_data": faq_icon_data,
+ # Slots
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(sidebar_template_str).render(context)
+
+
+#####################################
+# NAVBAR
+#####################################
+
+navbar_template_str: types.django_html = """
+
+ DEMO
+
+
+
+
+
+
+
+
+
+""" # noqa: E501
+
+
+class NavbarData(NamedTuple):
+ attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def navbar(context: Context, data: NavbarData):
+ sidebar_toggle_icon_data = IconData(
+ name="bars-3",
+ variant="outline",
+ )
+
+ with context.push(
+ {
+ "sidebar_toggle_icon_data": sidebar_toggle_icon_data,
+ "attrs": data.attrs,
+ }
+ ):
+ return lazy_load_template(navbar_template_str).render(context)
+
+
+#####################################
+# DIALOG
+#####################################
+
+
+def construct_btn_onclick(model: str, btn_on_click: Optional[str]):
+ """
+ We want to allow the component users to define Alpine.js `@click` actions.
+ However, we also need to use `@click` to close the dialog after clicking
+ one of the buttons.
+
+ Hence, this function constructs the '@click' attribute, such that we can do both.
+
+ NOTE: `model` is the name of the Alpine variable used by the dialog.
+ """
+ on_click_cb = f"{model} = false;"
+ if btn_on_click:
+ on_click_cb = f"{btn_on_click}; {on_click_cb}"
+ return mark_safe(on_click_cb)
+
+
+dialog_template_str: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% comment %}
+ NOTE: {{ model }} is the Alpine variable used for opening/closing. The variable name
+ is set dynamically, hence we use Django's double curly braces to refer to it.
+ {% endcomment %}
+
+ {# Search not implemented #}
+
+
+
+
+
+
+
+
+
+ {% if slot_activator %}
+ {# This is what opens the modal #}
+
+""" # noqa: E501
+
+
+class DialogData(NamedTuple):
+ model: Optional[str] = None
+ # Classes and HTML attributes
+ attrs: Optional[dict] = None
+ activator_attrs: Optional[dict] = None
+ title_attrs: Optional[dict] = None
+ content_attrs: Optional[dict] = None
+ # Confirm button
+ confirm_hide: Optional[bool] = None
+ confirm_text: Optional[str] = "Confirm"
+ confirm_href: Optional[str] = None
+ confirm_disabled: Optional[bool] = None
+ confirm_variant: Optional["ThemeVariant"] = "primary"
+ confirm_color: Optional["ThemeColor"] = None
+ confirm_type: Optional[str] = None
+ confirm_on_click: Optional[str] = ""
+ confirm_attrs: Optional[dict] = None
+ # Cancel button
+ cancel_hide: Optional[bool] = None
+ cancel_text: Optional[str] = "Cancel"
+ cancel_href: Optional[str] = None
+ cancel_disabled: Optional[bool] = None
+ cancel_variant: Optional["ThemeVariant"] = "secondary"
+ cancel_color: Optional["ThemeColor"] = None
+ cancel_type: Optional[str] = None
+ cancel_on_click: Optional[str] = ""
+ cancel_attrs: Optional[dict] = None
+ # UX
+ close_on_esc: Optional[bool] = True
+ close_on_click_outside: Optional[bool] = True
+ # Slots
+ slot_activator: Optional[str] = None
+ slot_prepend: Optional[str] = None
+ slot_title: Optional[str] = None
+ slot_content: Optional[str] = None
+ slot_append: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def dialog(context: Context, data: DialogData):
+ is_model_overriden = bool(data.model)
+ model = data.model or "open"
+
+ # Modify "attrs" passed to buttons, so we close the dialog when clicking the buttons
+ cancel_attrs = {
+ **(data.cancel_attrs or {}),
+ "@click": construct_btn_onclick(model, data.cancel_on_click),
+ }
+ confirm_attrs = {
+ **(data.confirm_attrs or {}),
+ "@click": construct_btn_onclick(model, data.confirm_on_click),
+ }
+
+ confirm_button_data = ButtonData(
+ variant=data.confirm_variant, # type: ignore[arg-type]
+ color=data.confirm_color, # type: ignore[arg-type]
+ disabled=data.confirm_disabled,
+ href=data.confirm_href,
+ type=data.confirm_type,
+ attrs=confirm_attrs,
+ slot_content=data.confirm_text,
+ )
+
+ cancel_button_data = ButtonData(
+ variant=data.cancel_variant, # type: ignore[arg-type]
+ color=data.cancel_color, # type: ignore[arg-type]
+ disabled=data.cancel_disabled,
+ href=data.cancel_href,
+ type=data.cancel_type,
+ attrs=cancel_attrs,
+ slot_content=data.cancel_text,
+ )
+
+ with context.push(
+ {
+ "model": model,
+ "is_model_overriden": is_model_overriden,
+ # Classes and HTML attributes
+ "attrs": data.attrs,
+ "activator_attrs": data.activator_attrs,
+ "content_attrs": data.content_attrs,
+ "title_attrs": data.title_attrs,
+ # UX
+ "close_on_esc": data.close_on_esc,
+ "close_on_click_outside": data.close_on_click_outside,
+ # Confirm button
+ "confirm_hide": data.confirm_hide,
+ "confirm_text": data.confirm_text,
+ "confirm_href": data.confirm_href,
+ "confirm_disabled": data.confirm_disabled,
+ "confirm_variant": data.confirm_variant,
+ "confirm_color": data.confirm_color,
+ "confirm_type": data.confirm_type,
+ "confirm_attrs": confirm_attrs,
+ "confirm_button_data": confirm_button_data,
+ # Cancel button
+ "cancel_hide": data.cancel_hide,
+ "cancel_text": data.cancel_text,
+ "cancel_href": data.cancel_href,
+ "cancel_disabled": data.cancel_disabled,
+ "cancel_variant": data.cancel_variant,
+ "cancel_color": data.cancel_color,
+ "cancel_type": data.cancel_type,
+ "cancel_attrs": cancel_attrs,
+ "cancel_button_data": cancel_button_data,
+ # Slots
+ "slot_activator": data.slot_activator,
+ "slot_prepend": data.slot_prepend,
+ "slot_title": data.slot_title,
+ "slot_content": data.slot_content,
+ "slot_append": data.slot_append,
+ }
+ ):
+ return lazy_load_template(dialog_template_str).render(context)
+
+
+#####################################
+# TAGS
+#####################################
+
+
+class TagEntry(NamedTuple):
+ tag: str
+ selected: bool = False
+
+
+# JS props that can be passed to the Alpine component via python
+class TagsJsProps(TypedDict):
+ initTags: str
+
+
+tags_template_str: types.django_html = """
+
+ {{ slot_activator }}
+
+ {% endif %}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {{ slot_prepend }}
+
+
+
+ {% if slot_title %}
+
+
+ {{ slot_append }}
+ + {{ slot_title }} +
+ {% endif %} + + {{ slot_content }} +
+ {% if not confirm_hide %}
+ {% button confirm_button_data %}
+ {% endif %}
+
+ {% if not cancel_hide %}
+ {% button cancel_button_data %}
+ {% endif %}
+
+
+
+
+ {{ slot_title }}
+
+
+
+
+"""
+
+
+class TagsData(NamedTuple):
+ tag_type: str
+ js_props: dict
+ editable: bool = True
+ max_width: Union[int, str] = "300px"
+ attrs: Optional[dict] = None
+ slot_title: Optional[str] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def tags(context: Context, data: TagsData):
+ all_tags = TAG_TYPE_META[data.tag_type.upper()].allowed_values # type: ignore[index]
+
+ remove_button_data = ButtonData(
+ color="error",
+ attrs={
+ "class": "!py-1",
+ "@click": "removeTag(index)",
+ },
+ slot_content="Remove",
+ )
+
+ add_tag_button_data = ButtonData(
+ attrs={
+ "class": "!py-1",
+ "@click": "addTag",
+ },
+ slot_content="Add tag",
+ )
+
+ slot_title = (
+ data.slot_title
+ or """
+
+
+
+
+ {% if editable %}
+
+
+
+ {% if editable %}
+
+
+ {% button remove_button_data %}
+
+ {% endif %}
+
+ {% button add_tag_button_data %}
+
+ {% endif %}
+ + Tags: +
+ """ + ) + + with context.push( + { + "editable": data.editable, + "all_tags": all_tags, + "max_width": data.max_width, + "attrs": data.attrs, + "js_props": data.js_props, + "remove_button_data": remove_button_data, + "add_tag_button_data": add_tag_button_data, + "slot_title": slot_title, + } + ): + return lazy_load_template(tags_template_str).render(context) + + +##################################### +# FORM +##################################### + +form_template_str: types.django_html = """ + + +""" + + +class FormData(NamedTuple): + type: Literal["table", "paragraph", "ul", None] = None + editable: bool = True + method: str = "post" + # Submit btn + submit_hide: Optional[bool] = None + submit_text: Optional[str] = "Submit" + submit_href: Optional[str] = None + submit_disabled: Optional[bool] = None + submit_variant: Optional["ThemeVariant"] = "primary" + submit_color: Optional["ThemeColor"] = None + submit_type: Optional[str] = "submit" + submit_attrs: Optional[dict] = None + # Cancel btn + cancel_hide: Optional[bool] = None + cancel_text: Optional[str] = "Cancel" + cancel_href: Optional[str] = None + cancel_disabled: Optional[bool] = None + cancel_variant: Optional["ThemeVariant"] = "secondary" + cancel_color: Optional["ThemeColor"] = None + cancel_type: Optional[str] = "button" + cancel_attrs: Optional[dict] = None + # Actions + actions_hide: Optional[bool] = None + actions_attrs: Optional[dict] = None + # Other + form_content_attrs: Optional[dict] = None + attrs: Optional[dict] = None + # Slots + slot_actions_prepend: Optional[str] = None + slot_actions_append: Optional[str] = None + slot_form: Optional[str] = None + slot_below_form: Optional[str] = None + + +@registry.library.simple_tag(takes_context=True) +def form(context: Context, data: FormData): + if data.type == "table": + form_content_tag = "table" + elif data.type == "paragraph": + form_content_tag = "div" + elif data.type == "ul": + form_content_tag = "ul" + else: + form_content_tag = "div" + + # Add AlpineJS bindings to submit button + submit_attrs = { + **(data.submit_attrs or {}), + ":disabled": "isSubmitting", + } + + submit_button_data = ButtonData( + variant=data.submit_variant, # type: ignore[arg-type] + color=data.submit_color, # type: ignore[arg-type] + disabled=data.submit_disabled, + type=data.submit_type, + attrs=submit_attrs, + slot_content=data.submit_text, + ) + + cancel_button_data = ButtonData( + variant=data.cancel_variant, # type: ignore[arg-type] + color=data.cancel_color, # type: ignore[arg-type] + disabled=data.cancel_disabled, + href=data.cancel_href, + type=data.cancel_type, + attrs=data.cancel_attrs, + slot_content=data.cancel_text, + ) + + with context.push( + { + "form_content_tag": form_content_tag, + "form_content_attrs": data.form_content_attrs, + "method": data.method, + "editable": data.editable, + "submit_hide": data.submit_hide, + "submit_text": data.submit_text, + "submit_href": data.submit_href, + "submit_disabled": data.submit_disabled or not data.editable, + "submit_variant": data.submit_variant, + "submit_color": data.submit_color, + "submit_type": data.submit_type, + "submit_attrs": submit_attrs, + "cancel_hide": data.cancel_hide, + "cancel_text": data.cancel_text, + "cancel_href": data.cancel_href, + "cancel_disabled": data.cancel_disabled, + "cancel_variant": data.cancel_variant, + "cancel_color": data.cancel_color, + "cancel_type": data.cancel_type, + "cancel_attrs": data.cancel_attrs, + "actions_hide": data.actions_hide, + "actions_attrs": data.actions_attrs, + "attrs": data.attrs, + "cancel_button_data": cancel_button_data, + "submit_button_data": submit_button_data, + "slot_actions_prepend": data.slot_actions_prepend, + "slot_actions_append": data.slot_actions_append, + "slot_form": data.slot_form, + "slot_below_form": data.slot_below_form, + } + ): + return lazy_load_template(form_template_str).render(context) + + +##################################### +# BREADCRUMBS +##################################### + + +@dataclass(frozen=True) +class Breadcrumb: + """ + Single breadcrumb item used with the `breadcrumb` components. + """ + + value: Any + """Value of the menu item to render.""" + + link: Optional[str] = None + """ + If set, the item will be wrapped in an `` tag pointing to this + link. + """ + + item_attrs: Optional[dict] = None + """HTML attributes specific to this item.""" + + +breadcrumbs_template_str: types.django_html = """ + +""" + + +class BreadcrumbsData(NamedTuple): + items: List[Breadcrumb] + attrs: Optional[dict] = None + + +@registry.library.simple_tag(takes_context=True) +def breadcrumbs(context: Context, data: BreadcrumbsData): + with context.push( + { + "items": data.items, + "attrs": data.attrs, + } + ): + return lazy_load_template(breadcrumbs_template_str).render(context) + + +breadcrumbs_tag = breadcrumbs + +##################################### +# BOOKMARKS +##################################### + +item_class = "px-4 py-1 text-sm text-gray-900 hover:bg-gray-100 cursor-pointer" +menu_items = [ + [ + MenuItem( + value="Edit", + link="#", + item_attrs={ + "class": item_class, + ":href": "contextMenuItem.value.edit_url", + }, + ), + ], +] + +bookmarks_template_str: types.django_html = """ +-
+ {% for bookmark in bookmark_entries %}
+ {% bookmark bookmark %}
+ {% endfor %}
+
+
- + {% icon add_new_bookmark_icon_data %} + + +
+ Attachments:
+
+
+ {% for bookmark in attachment_entries %}
+ {% bookmark bookmark %}
+ {% endfor %}
+
+ {% menu context_menu_data %}
+
+
+
+
+
+ {{ bookmark.text }}
+
+
+ {% icon bookmark_icon_data %}
+
+
+ -
+ {% for item in items %}
+
-
+ +++ {% if item.link %} + + {% endif %} + ++
+ {{ item.value }} +
+ + {% if item.link %} + + {% endif %} +
+ {% empty %}
+ {{ slot_empty }}
+ {% endfor %}
+
+
+""" # noqa: E501
+
+
+class TabsImplData(NamedTuple):
+ tabs: List[TabEntry]
+ # Unique name to identify this tabs instance, so we can open/close the tabs
+ # based on the query params.
+ name: Optional[str] = None
+ attrs: Optional[dict] = None
+ header_attrs: Optional[dict] = None
+ content_attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def tabs_impl(context: Context, data: TabsImplData):
+ with context.push(
+ {
+ "attrs": data.attrs,
+ "tabs": data.tabs,
+ "header_attrs": data.header_attrs,
+ "content_attrs": data.content_attrs,
+ "tabs_data": {"name": data.name},
+ "theme": theme,
+ }
+ ):
+ return lazy_load_template(tabs_impl_template_str).render(context)
+
+
+class TabsData(NamedTuple):
+ # Unique name to identify this tabs instance, so we can open/close the tabs
+ # based on the query params.
+ name: Optional[str] = None
+ attrs: Optional[dict] = None
+ header_attrs: Optional[dict] = None
+ content_attrs: Optional[dict] = None
+ slot_content: Optional[CallableSlot] = None
+
+
+# This is an "API" component, meaning that it's designed to process
+# user input provided as nested components. But after the input is
+# processed, it delegates to an internal "implementation" component
+# that actually renders the content.
+@registry.library.simple_tag(takes_context=True)
+def tabs(context: Context, data: TabsData):
+ if not data.slot_content:
+ return ""
+
+ ProvidedData = NamedTuple("ProvidedData", [("tabs", List[TabEntry]), ("enabled", bool)])
+ collected_tabs: List[TabEntry] = []
+ provided_data = ProvidedData(tabs=collected_tabs, enabled=True)
+
+ with context.push({"_tabs": provided_data}):
+ data.slot_content.render(context)
+
+ # By the time we get here, all child TabItem components should have been
+ # rendered, and they should've populated the tabs list.
+ return tabs_impl(
+ context,
+ TabsImplData(
+ tabs=collected_tabs,
+ name=data.name,
+ attrs=data.attrs,
+ header_attrs=data.header_attrs,
+ content_attrs=data.content_attrs,
+ ),
+ )
+
+
+class TabItemData(NamedTuple):
+ header: str
+ disabled: bool = False
+ slot_content: Optional[str] = None
+
+
+# Use this component to define individual tabs inside the default slot
+# inside the `tab` component.
+@registry.library.simple_tag(takes_context=True)
+def tab_item(context, data: TabItemData):
+ # Access the list of tabs registered for parent Tabs component
+ # This raises if we're not nested inside the Tabs component.
+ tab_ctx = context["_tabs"]
+
+ # We accessed the _tabs context, but we're inside ANOTHER TabItem
+ if not tab_ctx.enabled:
+ raise RuntimeError(
+ "Component 'tab_item' was called with no parent Tabs component. "
+ "Either wrap 'tab_item' in Tabs component, or check if the component "
+ "is not a descendant of another instance of 'tab_item'"
+ )
+ parent_tabs = tab_ctx.tabs
+
+ parent_tabs.append(
+ {
+ "header": data.header,
+ "disabled": data.disabled,
+ "content": mark_safe(data.slot_content or "").strip(),
+ }
+ )
+ return ""
+
+
+tabs_static_template_str: types.django_html = """
+ -
+ {% for tab in tabs %}
+ {% if not tab.disabled %}
+
- + + {{ tab.header }} + + + {% else %} +
-
+
+ {{ tab.header }} +
+
+ {% endif %}
+ {% endfor %}
+
+
+ {% for tab in tabs %}
+
+
+
+
+ {{ tab.content|safe }}
+
+ {% endfor %}
+
+
+"""
+
+
+class TabsStaticData(NamedTuple):
+ tabs: List[TabStaticEntry]
+ tab_index: int = 0
+ hide_body: bool = False
+ attrs: Optional[dict] = None
+ header_attrs: Optional[dict] = None
+ content_attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def tabs_static(context: Context, data: TabsStaticData):
+ selected_content = data.tabs[data.tab_index].content
+
+ tabs_data = []
+ for tab_index, tab in enumerate(data.tabs):
+ is_selectd = tab_index == data.tab_index
+ styling = {
+ "tab": "border-b-2 " + theme.tab_active if is_selectd else "",
+ "text": theme.tab_text_active if is_selectd else theme.tab_text_inactive,
+ }
+ tabs_data.append((tab, styling))
+
+ with context.push(
+ {
+ "attrs": data.attrs,
+ "tabs_data": tabs_data,
+ "header_attrs": data.header_attrs,
+ "content_attrs": data.content_attrs,
+ "hide_body": data.hide_body,
+ "selected_content": selected_content,
+ "theme": theme,
+ }
+ ):
+ return lazy_load_template(tabs_static_template_str).render(context)
+
+
+#####################################
+# PROJECT_INFO
+#####################################
+
+
+class ProjectInfoEntry(NamedTuple):
+ title: str
+ value: str
+
+
+project_info_template_str: types.django_html = """
+ -
+ {% for tab, styling in tabs_data %}
+ {% if not tab.disabled %}
+
- + + {{ tab.header }} + + + {% else %} +
-
+
+ {{ tab.header }} +
+
+ {% endif %}
+ {% endfor %}
+
+
+
+
+ {% endif %}
+
+ {{ selected_content }}
+
+
+ {# Info section #}
+
+"""
+
+
+class ProjectInfoData(NamedTuple):
+ project: Project
+ project_tags: List[str]
+ contacts: List[ProjectContact]
+ status_updates: List[ProjectStatusUpdate]
+ roles_with_users: List[ProjectRole]
+ editable: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_info(context: Context, data: ProjectInfoData) -> str:
+ project_edit_url = f"/edit/{data.project['id']}/"
+ edit_project_roles_url = f"/edit/{data.project['id']}/roles/"
+ edit_contacts_url = f"/edit/{data.project['id']}/contacts/"
+ create_status_update_url = f"/create/{data.project['id']}/status_update/"
+
+ contacts_data = [
+ {
+ "contact": contact,
+ "link_icon_data": IconData(
+ href=f"/contacts/{contact['link_id']}",
+ name="arrow-top-right-on-square",
+ variant="outline",
+ color="text-gray-400 hover:text-gray-500",
+ ),
+ }
+ for contact in data.contacts
+ ]
+
+ project_info = [
+ ProjectInfoEntry("Org", data.project["organization"]["name"]),
+ ProjectInfoEntry("Duration", f"{data.project['start_date']} - {data.project['end_date']}"),
+ ProjectInfoEntry("Status", data.project["status"]),
+ ProjectInfoEntry("Tags", ", ".join(data.project_tags) or "-"),
+ ]
+
+ edit_project_button_data = ButtonData(
+ href=project_edit_url,
+ attrs={"class": "not-prose"},
+ slot_content="Edit Project",
+ )
+
+ edit_team_button_data = ButtonData(
+ href=edit_project_roles_url,
+ attrs={"class": "not-prose"},
+ slot_content="Edit Team",
+ )
+
+ edit_contacts_button_data = ButtonData(
+ href=edit_contacts_url,
+ attrs={"class": "not-prose"},
+ slot_content="Edit Contacts",
+ )
+
+ status_updates_data = ProjectStatusUpdatesData(
+ project_id=data.project["id"],
+ status_updates=data.status_updates,
+ editable=data.editable,
+ )
+
+ project_users_data = ProjectUsersData(
+ project_id=data.project["id"],
+ roles_with_users=data.roles_with_users,
+ available_roles=None,
+ available_users=None,
+ editable=False,
+ )
+
+ with context.push(
+ {
+ "project_edit_url": project_edit_url,
+ "edit_contacts_url": edit_contacts_url,
+ "edit_project_roles_url": edit_project_roles_url,
+ "create_status_update_url": create_status_update_url,
+ "contacts_data": contacts_data,
+ "project": data.project,
+ "roles_with_users": data.roles_with_users,
+ "project_info": project_info,
+ "status_updates": data.status_updates,
+ "editable": data.editable,
+ "status_updates_data": status_updates_data,
+ "project_users_data": project_users_data,
+ "edit_project_button_data": edit_project_button_data,
+ "edit_team_button_data": edit_team_button_data,
+ "edit_contacts_button_data": edit_contacts_button_data,
+ }
+ ):
+ return lazy_load_template(project_info_template_str).render(context)
+
+
+#####################################
+# PROJECT_NOTES
+#####################################
+
+project_notes_template_str: types.django_html = """
+
+
+ {% for key, value in project_info %}
+
+
+
+ {# Status Updates section #}
+ {% project_status_updates status_updates_data %}
+
+
+
+ Project Info
+ + {% if editable %} + {% button edit_project_button_data %} + {% endif %} +| + {{ key }}: + | ++ {{ value }} + | +
+ {# Team section #}
+
+
+
+
+ {# Contacts section #}
+
+
+
+ {% project_users project_users_data %}
+ Team
+ + {% if editable %} + {% button edit_team_button_data %} + {% endif %} +
+
+
+ {% else %}
+
+
+
+
+ {% if contacts_data %}
+ Contacts
+ + {% if editable %} + {% button edit_contacts_button_data %} + {% endif %} +| Name | +Job | +Link | +
|---|---|---|
| {{ row.contact.name }} | +{{ row.contact.job }} | ++ {% icon link_icon_data %} + | +
No entries
+ {% endif %} +
+
+"""
+
+
+def _make_comments_data(note: ProjectNote, comment: ProjectNoteComment):
+ modified_time_str = format_timestamp(datetime.fromisoformat(comment["modified"]))
+ formatted_modified_by = (
+ modified_time_str
+ + " "
+ + comment['modified_by']['name']
+ )
+
+ edit_comment_icon_data = IconData(
+ name="pencil-square",
+ variant="outline",
+ href=f"/update/{note['project']['id']}/note/{note['id']}/comment/{comment['id']}/",
+ color="text-gray-400 hover:text-gray-500",
+ )
+
+ return {
+ "timestamp": formatted_modified_by,
+ "notes": comment["text"],
+ "edit_comment_icon_data": edit_comment_icon_data,
+ }
+
+
+def _make_notes_data(
+ notes: List[ProjectNote],
+ comments_by_notes: Dict[int, List[ProjectNoteComment]],
+):
+ notes_data: List[dict] = []
+ for note in notes:
+ comments = comments_by_notes.get(note["id"], [])
+ comments_data = [_make_comments_data(note, comment) for comment in comments]
+
+ edit_note_icon_data = IconData(
+ name="pencil-square",
+ variant="outline",
+ href=f"/edit/{note['project']['id']}/note/{note['id']}/",
+ color="text-gray-400 hover:text-gray-500",
+ )
+
+ create_comment_button_data = ButtonData(
+ href=f"/create/{note['project']['id']}/note/{note['id']}/",
+ slot_content="Add comment",
+ )
+
+ notes_data.append(
+ {
+ "text": note["text"],
+ "timestamp": note["created"],
+ "edit_note_icon_data": edit_note_icon_data,
+ "comments": comments_data,
+ "create_comment_button_data": create_comment_button_data,
+ }
+ )
+
+ return notes_data
+
+
+class ProjectNotesData(NamedTuple):
+ project_id: int
+ notes: List[ProjectNote]
+ comments_by_notes: Dict[int, List[ProjectNoteComment]]
+ editable: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_notes(context: Context, data: ProjectNotesData) -> str:
+ notes_data = _make_notes_data(data.notes, data.comments_by_notes)
+
+ create_note_button_data = ButtonData(
+ href=f"/create/{data.project_id}/note/",
+ slot_content="Add Note",
+ )
+
+ with context.push(
+ {
+ "create_note_button_data": create_note_button_data,
+ "notes_data": notes_data,
+ "editable": data.editable,
+ }
+ ):
+ return lazy_load_template(project_notes_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUTS_SUMMARY
+#####################################
+
+
+class AttachmentWithTags(NamedTuple):
+ attachment: ProjectOutputAttachment
+ tags: List[str]
+
+
+class OutputWithAttachments(NamedTuple):
+ output: ProjectOutput
+ attachments: List[AttachmentWithTags]
+
+
+class OutputWithAttachmentsAndDeps(NamedTuple):
+ output: ProjectOutput
+ attachments: List[AttachmentWithTags]
+ dependencies: List[OutputWithAttachments]
+
+
+outputs_summary_expansion_content_template_str: types.django_html = """
+ {% if outputs %}
+ {% project_outputs outputs_data %}
+ {% else %}
+ No outputs
+ {% endif %}
+"""
+
+project_outputs_summary_template_str: types.django_html = """
+ Notes
+ {% if notes_data %} +
+ {% for note in notes_data %}
+
+ {% endif %}
+
+ {% if editable %}
+ {% button create_note_button_data %}
+ {% endif %}
+
+
+ {% endfor %}
+
+
+ {{ note.timestamp }}
+
+ {% if editable %}
+ {% icon note.edit_note_icon_data %}
+ {% endif %}
+
+ + {{ note.text }} +
+ +
+
+ + Comments +
+ + {% for comment in note.comments %} +
+
+ {% endfor %}
+
+
+
+ {{ comment.timestamp }}
+
+ {% if editable %}
+ {% icon comment.edit_comment_icon_data %}
+ {% endif %}
+
+
+
+ + {{ comment.text }} +
+
+ {% if editable %}
+ {% button note.create_comment_button_data %}
+ {% endif %}
+
+
+ {% for group in groups %}
+ {% expansion_panel group %}
+ {% endfor %}
+
+"""
+
+
+class ProjectOutputsSummaryData(NamedTuple):
+ project_id: int
+ outputs: List["OutputWithAttachmentsAndDeps"]
+ editable: bool
+ phase_titles: Dict[ProjectPhaseType, str]
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_outputs_summary(context: Context, data: ProjectOutputsSummaryData) -> str:
+ outputs_by_phase = group_by(data.outputs, lambda output, _: output[0]["phase"]["phase_template"]["type"])
+
+ groups: List[ExpansionPanelData] = []
+ for phase_meta in PROJECT_PHASES_META.values():
+ phase_outputs = outputs_by_phase.get(phase_meta.type, [])
+ title = data.phase_titles[phase_meta.type]
+ has_outputs = bool(phase_outputs)
+
+ outputs_data = ProjectOutputsData(
+ outputs=phase_outputs,
+ project_id=data.project_id,
+ editable=data.editable,
+ )
+
+ with context.push(
+ {
+ "outputs_data": outputs_data,
+ "outputs": data.outputs,
+ }
+ ):
+ expansion_panel_content = lazy_load_template(outputs_summary_expansion_content_template_str).render(context) # noqa: E501
+
+ expansion_panel_data = ExpansionPanelData(
+ open=has_outputs,
+ header_attrs={"class": "flex gap-x-2 prose"},
+ slot_header=f"""
+ + {title} +
+ """, + slot_content=expansion_panel_content, + ) + + groups.append(expansion_panel_data) + + with context.push( + { + "groups": groups, + } + ): + return lazy_load_template(project_outputs_summary_template_str).render(context) + + +##################################### +# PROJECT_STATUS_UPDATES +##################################### + +project_status_updates_template_str: types.django_html = """ +
+
+"""
+
+
+def _make_status_update_data(status_update: ProjectStatusUpdate):
+ modified_time_str = format_timestamp(datetime.fromisoformat(status_update["modified"]))
+ formatted_modified_by = (
+ modified_time_str
+ + " "
+ + status_update['modified_by']['name']
+ )
+
+ return {
+ "timestamp": formatted_modified_by,
+ "text": status_update["text"],
+ "edit_href": f"/edit/{status_update['project']['id']}/status_update/{status_update['id']}",
+ }
+
+
+class ProjectStatusUpdatesData(NamedTuple):
+ project_id: int
+ status_updates: List[ProjectStatusUpdate]
+ editable: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_status_updates(context: Context, data: ProjectStatusUpdatesData) -> str:
+ create_status_update_url = f"/create/{data.project_id}/status_update"
+
+ updates_data = [_make_status_update_data(status_update) for status_update in data.status_updates]
+ updates_data = [
+ (
+ entry,
+ IconData(
+ name="pencil-square",
+ variant="outline",
+ href=entry["edit_href"],
+ color="text-gray-400 hover:text-gray-500",
+ ),
+ )
+ for entry in updates_data
+ ]
+
+ add_status_button_data = ButtonData(
+ href=create_status_update_url,
+ slot_content="Add status update",
+ )
+
+ with context.push(
+ {
+ "create_status_update_url": create_status_update_url,
+ "updates_data": updates_data,
+ "editable": data.editable,
+ "add_status_button_data": add_status_button_data,
+ }
+ ):
+ return lazy_load_template(project_status_updates_template_str).render(context)
+
+
+#####################################
+# PROJECT USERS
+#####################################
+
+roles_table_headers = [
+ TableHeader(key="name", name="Name"),
+ TableHeader(key="role", name="Role"),
+ TableHeader(key="delete", name="", hidden=True),
+]
+
+
+class ProjectAddUserForm(ConditionalEditForm):
+ user_id = forms.ChoiceField(required=True, choices=[], label="User")
+ role = forms.ChoiceField(required=True, choices=[])
+
+ def __init__(
+ self,
+ editable: bool,
+ available_role_choices: List[Tuple[str, str]],
+ available_user_choices: List[Tuple[str, str]],
+ *args,
+ **kwargs,
+ ):
+ self.editable = editable
+
+ super().__init__(*args, **kwargs)
+
+ user_field: forms.ChoiceField = self.fields["user_id"] # type: ignore[assignment]
+ user_field.choices = available_user_choices
+
+ role_field: forms.ChoiceField = self.fields["role"] # type: ignore[assignment]
+ role_field.choices = available_role_choices
+
+
+user_dialog_title_template_str: types.django_html = """
+
+
+ {% if updates_data %}
+ Status Updates
+ {% if editable %} + {% button add_status_button_data %} + {% endif %} +
+ {% for update, update_icon_data in updates_data %}
+
+ {% endif %}
+
+
+ {% endfor %}
+
+
+ {{ update.timestamp }}
+
+ {% if editable %}
+ {% icon update_icon_data %}
+ {% endif %}
+
+ + {{ update.text }} +
+
+
+ Remove
+
+ from this project?
+
+ {% icon delete_icon_data %}
+
+"""
+
+project_users_template_str: types.django_html = """
+
+ {% if table_rows %}
+ {% table table_data %}
+ {% endif %}
+
+ {% if editable %}
+
+"""
+
+
+class ProjectUsersData(NamedTuple):
+ project_id: int
+ roles_with_users: List[ProjectRole]
+ available_roles: Optional[List[str]]
+ available_users: Optional[List[User]]
+ editable: bool = False
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_users(context: Context, data: ProjectUsersData) -> str:
+ roles_table_rows = []
+ for role in data.roles_with_users:
+ user = role["user"]
+
+ if data.editable:
+ delete_action = project_user_action(
+ context,
+ ProjectUserActionData(
+ project_id=data.project_id,
+ role_id=role["id"],
+ user_name=user["name"],
+ ),
+ )
+ else:
+ delete_action = ""
+
+ roles_table_rows.append(
+ create_table_row(
+ cols={
+ "name": TableCell(user["name"]),
+ "role": TableCell(role["name"]),
+ "delete": delete_action,
+ }
+ )
+ )
+
+ submit_url = f"/submit/{data.project_id}/role/create"
+ project_url = f"/project/{data.project_id}"
+
+ if data.available_roles:
+ available_role_choices = [(role, role) for role in data.available_roles]
+ else:
+ available_role_choices = []
+
+ if data.available_users:
+ available_user_choices = [(str(user["id"]), user["name"]) for user in data.available_users]
+ else:
+ available_user_choices = []
+
+ table_data = TableData(
+ headers=roles_table_headers,
+ rows=roles_table_rows,
+ attrs={"@user_delete": "onUserDelete"},
+ )
+
+ set_role_button_data = ButtonData(
+ type="submit",
+ slot_content="Set role",
+ )
+
+ cancel_button_data = ButtonData(
+ href=project_url,
+ variant="secondary",
+ slot_content="Go back",
+ )
+
+ delete_icon_data = IconData(
+ name="trash",
+ variant="outline",
+ size=18,
+ attrs={"class": "p-2 self-center"},
+ )
+
+ with context.push(
+ {
+ "delete_icon_data": delete_icon_data,
+ }
+ ):
+ user_dialog_title = lazy_load_template(user_dialog_title_template_str).render(context)
+
+ dialog_data = DialogData(
+ model="isDeleteDialogOpen",
+ confirm_text="Delete",
+ confirm_href="#",
+ confirm_color="error",
+ confirm_attrs={":href": "role.delete_url"},
+ content_attrs={"class": "w-full"},
+ slot_content="Set project roles
+ + + + + {% dialog dialog_data %} + + {% endif %} + +This action cannot be undone.
",
+ slot_title=user_dialog_title,
+ )
+
+ with context.push(
+ {
+ "editable": data.editable,
+ "table_headers": roles_table_headers,
+ "table_rows": roles_table_rows,
+ "add_user_form": ProjectAddUserForm(
+ data.editable,
+ available_role_choices,
+ available_user_choices,
+ ),
+ "submit_url": submit_url,
+ "project_url": project_url,
+ "table_data": table_data,
+ "set_role_button_data": set_role_button_data,
+ "cancel_button_data": cancel_button_data,
+ "dialog_data": dialog_data,
+ }
+ ):
+ return lazy_load_template(project_users_template_str).render(context)
+
+
+#####################################
+# PROJECT_USER_ACTION
+#####################################
+
+project_user_action_template_str: types.django_html = """
+
+ {% icon delete_icon_data %}
+
+"""
+
+
+class ProjectUserActionData(NamedTuple):
+ project_id: int
+ role_id: int
+ user_name: str
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_user_action(context: Context, data: ProjectUserActionData) -> str:
+ delete_url = f"/delete/{data.project_id}/{data.role_id}"
+
+ role_data = {
+ "delete_url": delete_url,
+ "role_id": data.role_id,
+ "user_name": data.user_name,
+ }
+
+ delete_icon_data = IconData(
+ name="trash",
+ variant="outline",
+ size=18,
+ href="#",
+ color="text-gray-500 hover:text-gray-400",
+ svg_attrs={"class": "inline mb-1"},
+ attrs={
+ "class": "p-2",
+ "@click.stop": "$dispatch('user_delete', { role })",
+ },
+ )
+
+ with context.push(
+ {
+ "role": role_data,
+ "delete_icon_data": delete_icon_data,
+ }
+ ):
+ return lazy_load_template(project_user_action_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUTS
+#####################################
+
+output_expansion_panel_content_template_str: types.django_html = """
+
+ {# Dependencies #}
+ {% for dep_data in dependencies_data %}
+ {% project_output_dependency dep_data %}
+ {% endfor %}
+
+ {# Own data + attachments #}
+ {% project_output_form output_form_data %}
+
+"""
+
+project_outputs_template_str: types.django_html = """
+
+ {% for data, output_badge_data, expansion_panel_data in outputs_data %}
+
+"""
+
+
+class ProjectOutputsData(NamedTuple):
+ project_id: int
+ outputs: List[OutputWithAttachmentsAndDeps]
+ editable: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_outputs(context: Context, data: ProjectOutputsData) -> str:
+ outputs_data: List[Tuple[RenderedProjectOutput, ProjectOutputBadgeData, ExpansionPanelData]] = []
+ for output_tuple in data.outputs:
+ output, attachments, dependencies = output_tuple
+
+ attach_data: List[RenderedAttachment] = []
+ for attachment in attachments:
+ attach_data.append(
+ RenderedAttachment(
+ url=attachment[0]["url"],
+ text=attachment[0]["text"],
+ tags=attachment[1],
+ )
+ )
+
+ update_output_url = "/update"
+
+ deps: List[RenderedOutputDep] = []
+ for dep in dependencies:
+ output, attachments = dep
+ phase_url = f"/phase/{data.project_id}/{output['phase']['phase_template']['type']}"
+ deps.append(
+ RenderedOutputDep(
+ dependency=dep,
+ phase_url=phase_url,
+ attachments=[
+ {
+ "url": d.attachment["url"],
+ "text": d.attachment["text"],
+ "tags": d.tags,
+ }
+ for d in attachments
+ ],
+ )
+ )
+
+ has_missing_deps = any([not output["completed"] for output, _ in dependencies])
+
+ output_badge_data = ProjectOutputBadgeData(
+ completed=output["completed"],
+ missing_deps=has_missing_deps,
+ )
+
+ output_data = RenderedProjectOutput(
+ output=output,
+ dependencies=deps,
+ has_missing_deps=has_missing_deps,
+ output_data={
+ "editable": data.editable,
+ },
+ attachments=attach_data,
+ update_output_url=update_output_url,
+ )
+ output_form_data = ProjectOutputFormData(
+ data=output_data,
+ editable=data.editable,
+ )
+ with context.push(
+ {
+ "dependencies_data": [ProjectOutputDependencyData(dependency=dep) for dep in deps],
+ "output_form_data": output_form_data,
+ }
+ ):
+ output_expansion_panel_content = lazy_load_template(output_expansion_panel_content_template_str).render(context) # noqa: E501
+
+ expansion_panel_data = ExpansionPanelData(
+ panel_id=output["id"], # type: ignore[arg-type]
+ icon_position="right",
+ attrs={"class": "border-b border-solid border-gray-300 pb-2 mb-3"},
+ header_attrs={"class": "flex align-center justify-between"},
+ slot_header=f"""
+
+
+ {% endfor %}
+
+ {% project_output_badge output_badge_data %}
+
+
+ {% expansion_panel expansion_panel_data %}
+
+
+ {output['name']}
+
+ """,
+ slot_content=output_expansion_panel_content,
+ )
+
+ outputs_data.append(
+ (
+ output_data,
+ output_badge_data,
+ expansion_panel_data,
+ )
+ )
+
+ with context.push(
+ {
+ "outputs_data": outputs_data,
+ }
+ ):
+ return lazy_load_template(project_outputs_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUT_BADGE
+#####################################
+
+project_output_badge_template_str: types.django_html = """
+
+ {# Missing dependencies #}
+ {% if missing_deps %}
+ {% icon missing_icon_data %}
+
+ {# Completed #}
+ {% elif completed %}
+
+ {% icon completed_icon_data %}
+
+
+ {# NOT completed #}
+ {% else %}
+
+ {% endif %}
+
+""" # noqa: E501
+
+
+class ProjectOutputBadgeData(NamedTuple):
+ completed: bool
+ missing_deps: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_output_badge(context: Context, data: ProjectOutputBadgeData):
+ missing_icon_data = IconData(
+ name="exclamation-triangle",
+ variant="outline",
+ color="text-black",
+ size=32,
+ stroke_width=2,
+ attrs={"title": "A dependent dependency has not been met!"},
+ )
+
+ completed_icon_data = IconData(
+ name="check",
+ variant="outline",
+ color="text-white",
+ size=20,
+ stroke_width=2,
+ attrs={"class": "p-2"},
+ )
+
+ with context.push(
+ {
+ "completed": data.completed,
+ "missing_deps": data.missing_deps,
+ "theme": theme,
+ "missing_icon_data": missing_icon_data,
+ "completed_icon_data": completed_icon_data,
+ }
+ ):
+ return lazy_load_template(project_output_badge_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUT_DEPENDENCY
+#####################################
+
+project_output_dependency_template_str: types.django_html = """
+
+
+"""
+
+
+class ProjectOutputDependencyData(NamedTuple):
+ dependency: "RenderedOutputDep"
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_output_dependency(context: Context, data: ProjectOutputDependencyData):
+ warning_icon_data = IconData(
+ name="exclamation-triangle",
+ variant="outline",
+ size=24,
+ stroke_width=2,
+ color="text-gray-500",
+ attrs={"class": "float-left pr-1"},
+ )
+
+ missing_button_data = ButtonData(
+ variant="plain",
+ href=data.dependency.phase_url,
+ attrs={
+ "target": "_blank",
+ "class": "hover:text-gray-600 !underline",
+ },
+ slot_content=title(data.dependency.dependency[0]["phase"]["phase_template"]["type"]),
+ )
+
+ parent_attachments_data = ProjectOutputAttachmentsData(
+ editable=False,
+ has_attachments=bool(data.dependency.attachments),
+ js_props={"attachments": "attachments.value"},
+ )
+
+ with context.push(
+ {
+ "attachments": data.dependency.attachments,
+ "dependency": data.dependency.dependency,
+ "phase_url": data.dependency.phase_url,
+ "OUTPUT_DESCRIPTION_PLACEHOLDER": OUTPUT_DESCRIPTION_PLACEHOLDER,
+ "warning_icon_data": warning_icon_data,
+ "missing_button_data": missing_button_data,
+ "parent_attachments_data": parent_attachments_data,
+ }
+ ):
+ return lazy_load_template(project_output_dependency_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUT_ATTACHMENTS
+#####################################
+
+
+class ProjectOutputAttachmentsJsProps(TypedDict):
+ attachments: str
+
+
+project_output_attachments_template_str: types.django_html = """
+
+ {% if dependency.output.completed %}
+ {% if dependency.output.description %}
+ {{ dependency.output.description }}
+ {% else %}
+
+ {{ OUTPUT_DESCRIPTION_PLACEHOLDER }}
+
+ {% endif %}
+ {% else %}
+
+ {% icon warning_icon_data %}
+
+ Missing '{{ dependency.output.name }}' from
+
+ {% button missing_button_data %}
+
+ {% endif %}
+
+
+ {# Attachments of parent dependencies #}
+ {% project_output_attachments parent_attachments_data %}
+
+
+
+
+"""
+
+
+class ProjectOutputAttachmentsData(NamedTuple):
+ has_attachments: bool
+ js_props: ProjectOutputAttachmentsJsProps
+ editable: bool
+ attrs: Optional[dict] = None
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_output_attachments(context: Context, data: ProjectOutputAttachmentsData):
+ attachment_preview_button_data = ButtonData(
+ variant="plain",
+ link=True,
+ attrs={
+ "x-bind:href": "attachment.url",
+ "x-text": "attachment.text",
+ "target": "_blank",
+ "class": "hover:text-gray-600 !underline",
+ "style": "color: cornflowerblue;",
+ },
+ )
+
+ edit_button_data = ButtonData(
+ attrs={
+ "class": "!py-1",
+ "x-text": "attachment.isPreview ? 'Edit' : 'Preview'",
+ "@click": "() => $emit('toggleAttachment', index)",
+ },
+ slot_content="Edit",
+ )
+
+ remove_button_data = ButtonData(
+ color="error",
+ attrs={
+ "class": "!py-1",
+ "@click": "() => $emit('removeAttachment', index)",
+ },
+ slot_content="Remove",
+ )
+
+ tags_data = TagsData(
+ tag_type="project_output_attachment",
+ editable=data.editable,
+ js_props={
+ "initTags": "attachment.tags",
+ "onChange": "(tags) => $emit('setAttachmentTags', index, tags)",
+ },
+ attrs={
+ "class": "pb-8",
+ },
+ )
+
+ with context.push(
+ {
+ "has_attachments": data.has_attachments,
+ "editable": data.editable,
+ "attrs": data.attrs,
+ "js_props": data.js_props,
+ "text_max_len": FORM_SHORT_TEXT_MAX_LEN,
+ "attachment_preview_button_data": attachment_preview_button_data,
+ "edit_button_data": edit_button_data,
+ "remove_button_data": remove_button_data,
+ "tags_data": tags_data,
+ }
+ ):
+ return lazy_load_template(project_output_attachments_template_str).render(context)
+
+
+#####################################
+# PROJECT_OUTPUT_FORM
+#####################################
+
+OUTPUT_DESCRIPTION_PLACEHOLDER = "Placeholder text"
+
+
+class RenderedAttachment(NamedTuple):
+ url: str
+ text: str
+ tags: List[str]
+
+
+class RenderedOutputDep(NamedTuple):
+ dependency: OutputWithAttachments
+ phase_url: str
+ attachments: List[dict]
+
+
+class RenderedProjectOutput(NamedTuple):
+ output: ProjectOutput
+ dependencies: List[RenderedOutputDep]
+ has_missing_deps: bool
+ output_data: dict
+ attachments: List[RenderedAttachment]
+ update_output_url: str
+
+
+form_content_template_str: types.django_html = """
+ {# Output description - editable #}
+ {% if editable %}
+
+ {% else %}
+ {# Output description - readonly #}
+
+ {% if not has_attachments and editable %}
+ This output does not have any attachments, create one below:
+ {% elif not has_attachments and not editable %}
+ This output does not have any attachments.
+ {% elif has_attachments and not editable %}
+ Attachments:
+ {% else %} {# NOTE: Else branch required by django-shouty #}
+ {% endif %}
+
+
+
+
+
+
+ {% if data.output.description %}
+ {{ data.output.description }}
+ {% else %}
+ {{ OUTPUT_DESCRIPTION_PLACEHOLDER }}
+ {% endif %}
+
+ {% endif %}
+
+
+
+
+ {% project_output_attachments project_output_attachments_data %}
+"""
+
+project_output_form_template_str: types.django_html = """
+
+ Completed:
+
+ {# NOTE: See https://stackoverflow.com/a/1992745/9788634 #}
+
+
+
+
+ {% if editable %}
+ {% button add_attachment_button_data %}
+
+ {% button save_button_data %}
+ {% endif %}
+
+
+ {% form form_data %}
+
+
+"""
+
+
+class ProjectOutputFormData(NamedTuple):
+ data: RenderedProjectOutput
+ editable: bool
+
+
+@registry.library.simple_tag(takes_context=True)
+def project_output_form(context: Context, data: ProjectOutputFormData):
+ project_output_attachments_data = ProjectOutputAttachmentsData(
+ has_attachments=bool(data.data.attachments),
+ editable=data.editable,
+ js_props={
+ "attachments": "attachments.value",
+ "onToggleAttachment": "(index) => toggleAttachmentPreview(index)",
+ "onSetAttachmentTags": "(index, tags) => setAttachmentTags(index, tags)",
+ "onUpdateAttachmentData": "(index, data) => updateAttachmentData(index, data)",
+ "onRemoveAttachment": "(index) => removeAttachment(index)",
+ }, # type: ignore[typeddict-unknown-key]
+ )
+
+ save_button_data = ButtonData(
+ attrs={
+ "@click": "onOutputSubmit({ reload: true })",
+ },
+ slot_content="Save",
+ )
+
+ add_attachment_button_data = ButtonData(
+ variant="secondary",
+ attrs={"@click": "addAttachment"},
+ slot_content="Add attachment",
+ )
+
+ with context.push(
+ {
+ "data": data.data,
+ "editable": data.editable,
+ "OUTPUT_DESCRIPTION_PLACEHOLDER": OUTPUT_DESCRIPTION_PLACEHOLDER,
+ "project_output_attachments_data": project_output_attachments_data,
+ "save_button_data": save_button_data,
+ "add_attachment_button_data": add_attachment_button_data,
+ }
+ ):
+ form_content = lazy_load_template(form_content_template_str).render(context)
+
+ form_data = FormData(
+ submit_href=data.data.update_output_url,
+ actions_hide=True,
+ slot_form=form_content,
+ )
+
+ with context.push(
+ {
+ "form_data": form_data,
+ "alpine_attachments": [d._asdict() for d in data.data.attachments],
+ }
+ ):
+ return lazy_load_template(project_output_form_template_str).render(context)
+
+#####################################
+#
+# IMPLEMENTATION END
+#
+#####################################
+
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- TESTS START ------------ #
+# The code above is used also used when benchmarking.
+# The section below is NOT included.
+
+from django_components.testing import djc_test # noqa: E402
+
+@djc_test
+def test_render(snapshot):
+ data = gen_render_data()
+ rendered = render(data)
+ assert rendered == snapshot
diff --git a/tests/test_benchmark_django_small.py b/tests/test_benchmark_django_small.py
new file mode 100644
index 00000000..7ac92eda
--- /dev/null
+++ b/tests/test_benchmark_django_small.py
@@ -0,0 +1,340 @@
+# NOTE: This file is used for benchmarking. Before editing this file,
+# please read through these:
+# - `benchmarks/README`
+# - https://github.com/django-components/django-components/pull/999
+
+from pathlib import Path
+from typing import Dict, Literal, NamedTuple, Optional, Union
+
+import django
+from django.conf import settings
+from django.template import Context, Template
+
+from django_components import types
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- IMPORTS END ------------ #
+
+# This variable is overridden by the benchmark runner
+CONTEXT_MODE: Literal["django", "isolated"] = "isolated"
+
+if not settings.configured:
+ settings.configure(
+ BASE_DIR=Path(__file__).resolve().parent,
+ INSTALLED_APPS=["django_components"],
+ TEMPLATES=[
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [
+ "tests/templates/",
+ "tests/components/", # Required for template relative imports in tests
+ ],
+ "OPTIONS": {
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ]
+ },
+ }
+ ],
+ COMPONENTS={
+ "autodiscover": False,
+ "context_behavior": CONTEXT_MODE,
+ },
+ MIDDLEWARE=[],
+ DATABASES={
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": ":memory:",
+ }
+ },
+ SECRET_KEY="secret",
+ ROOT_URLCONF="django_components.urls",
+ )
+ django.setup()
+else:
+ settings.COMPONENTS["context_behavior"] = CONTEXT_MODE
+
+#####################################
+#
+# IMPLEMENTATION START
+#
+#####################################
+
+templates_cache: Dict[int, Template] = {}
+
+
+def lazy_load_template(template: str) -> Template:
+ template_hash = hash(template)
+ if template_hash in templates_cache:
+ return templates_cache[template_hash]
+ else:
+ template_instance = Template(template)
+ templates_cache[template_hash] = template_instance
+ return template_instance
+
+
+#####################################
+# RENDER ENTRYPOINT
+#####################################
+
+
+def gen_render_data():
+ data = ButtonData(
+ href="https://example.com",
+ disabled=False,
+ variant="primary",
+ type="button",
+ attrs={
+ "class": "py-2 px-4",
+ },
+ slot_content="Click me!",
+ )
+ return data
+
+
+def render(data: "ButtonData"):
+ # Render
+ result = button(Context(), data)
+ return result
+
+
+#####################################
+# THEME
+#####################################
+
+ThemeColor = Literal["default", "error", "success", "alert", "info"]
+ThemeVariant = Literal["primary", "secondary"]
+
+VARIANTS = ["primary", "secondary"]
+
+
+class ThemeStylingUnit(NamedTuple):
+ """
+ Smallest unit of info, this class defines a specific styling of a specific
+ component in a specific state.
+
+ E.g. styling of a disabled "Error" button.
+ """
+
+ color: str
+ """CSS class(es) specifying color"""
+ css: str = ""
+ """Other CSS classes not specific to color"""
+
+
+class ThemeStylingVariant(NamedTuple):
+ """
+ Collection of styling combinations that are meaningful as a group.
+
+ E.g. all "error" variants - primary, disabled, secondary, ...
+ """
+
+ primary: ThemeStylingUnit
+ primary_disabled: ThemeStylingUnit
+ secondary: ThemeStylingUnit
+ secondary_disabled: ThemeStylingUnit
+
+
+class Theme(NamedTuple):
+ """Class for defining a styling and color theme for the app."""
+
+ default: ThemeStylingVariant
+ error: ThemeStylingVariant
+ alert: ThemeStylingVariant
+ success: ThemeStylingVariant
+ info: ThemeStylingVariant
+
+
+_secondary_btn_styling = "ring-1 ring-inset"
+
+theme = Theme(
+ default=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-blue-600 text-white hover:bg-blue-500 focus-visible:outline-blue-600 transition"
+ ),
+ primary_disabled=ThemeStylingUnit(color="bg-blue-300 text-blue-50 focus-visible:outline-blue-600 transition"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-gray-800 ring-gray-300 hover:bg-gray-100 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-gray-300 ring-gray-300 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ error=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-red-600 text-white hover:bg-red-500 focus-visible:outline-red-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-red-300 text-white focus-visible:outline-red-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-red-600 ring-red-300 hover:bg-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-red-200 ring-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ alert=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-amber-500 text-white hover:bg-amber-400 focus-visible:outline-amber-500"),
+ primary_disabled=ThemeStylingUnit(color="bg-amber-100 text-orange-300 focus-visible:outline-amber-500"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-amber-500 ring-amber-300 hover:bg-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-orange-200 ring-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ success=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-green-600 text-white hover:bg-green-500 focus-visible:outline-green-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-green-300 text-white focus-visible:outline-green-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-green-600 ring-green-300 hover:bg-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-green-200 ring-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ info=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-sky-600 text-white hover:bg-sky-500 focus-visible:outline-sky-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-sky-300 text-white focus-visible:outline-sky-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-sky-600 ring-sky-300 hover:bg-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-sky-200 ring-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+)
+
+
+def get_styling_css(
+ variant: Optional["ThemeVariant"] = None,
+ color: Optional["ThemeColor"] = None,
+ disabled: Optional[bool] = None,
+):
+ """
+ Dynamically access CSS styling classes for a specific variant and state.
+
+ E.g. following two calls get styling classes for:
+ 1. Secondary error state
+ 1. Secondary alert disabled state
+ 2. Primary default disabled state
+ ```py
+ get_styling_css('secondary', 'error')
+ get_styling_css('secondary', 'alert', disabled=True)
+ get_styling_css(disabled=True)
+ ```
+ """
+ variant = variant or "primary"
+ color = color or "default"
+ disabled = disabled if disabled is not None else False
+
+ color_variants: ThemeStylingVariant = getattr(theme, color)
+
+ if variant not in VARIANTS:
+ raise ValueError(f'Unknown theme variant "{variant}", must be one of {VARIANTS}')
+
+ variant_name = variant if not disabled else f"{variant}_disabled"
+ styling: ThemeStylingUnit = getattr(color_variants, variant_name)
+
+ css = f"{styling.color} {styling.css}".strip()
+ return css
+
+
+#####################################
+# BUTTON
+#####################################
+
+button_template_str: types.django_html = """
+ {# Based on buttons from https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% if is_link %}
+
+ {% else %}
+
+ {% else %}
+
+ {% endif %}
+"""
+
+
+class ButtonData(NamedTuple):
+ href: Optional[str] = None
+ link: Optional[bool] = None
+ disabled: Optional[bool] = False
+ variant: Union["ThemeVariant", Literal["plain"]] = "primary"
+ color: Union["ThemeColor", str] = "default"
+ type: Optional[str] = "button"
+ attrs: Optional[dict] = None
+ slot_content: Optional[str] = ""
+
+
+def button(context: Context, data: ButtonData):
+ common_css = (
+ "inline-flex w-full text-sm font-semibold"
+ " sm:mt-0 sm:w-auto focus-visible:outline-2 focus-visible:outline-offset-2"
+ )
+ if data.variant == "plain":
+ all_css_class = common_css
+ else:
+ button_classes = get_styling_css(data.variant, data.color, data.disabled) # type: ignore[arg-type]
+ all_css_class = f"{button_classes} {common_css} px-3 py-2 justify-center rounded-md shadow-sm"
+
+ is_link = not data.disabled and (data.href or data.link)
+
+ all_attrs = {**(data.attrs or {})}
+ if data.disabled:
+ all_attrs["aria-disabled"] = "true"
+
+ with context.push(
+ {
+ "href": data.href,
+ "disabled": data.disabled,
+ "type": data.type,
+ "btn_class": all_css_class,
+ "attrs": all_attrs,
+ "is_link": is_link,
+ "slot_content": data.slot_content,
+ }
+ ):
+ return lazy_load_template(button_template_str).render(context)
+
+
+#####################################
+#
+# IMPLEMENTATION END
+#
+#####################################
+
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- TESTS START ------------ #
+# The code above is used also used when benchmarking.
+# The section below is NOT included.
+
+from django_components.testing import djc_test # noqa: E402
+
+@djc_test
+def test_render(snapshot):
+ data = gen_render_data()
+ rendered = render(data)
+ assert rendered == snapshot
diff --git a/tests/test_benchmark_djc.py b/tests/test_benchmark_djc.py
new file mode 100644
index 00000000..0757ce1b
--- /dev/null
+++ b/tests/test_benchmark_djc.py
@@ -0,0 +1,6052 @@
+# NOTE: This file is used for benchmarking. Before editing this file,
+# please read through these:
+# - `benchmarks/README`
+# - https://github.com/django-components/django-components/pull/999
+
+import difflib
+import json
+from datetime import date, datetime, timedelta
+from dataclasses import dataclass, field, MISSING
+from enum import Enum
+from inspect import signature
+from itertools import chain
+from pathlib import Path
+from types import MappingProxyType
+from typing import (
+ Any,
+ Callable,
+ Dict,
+ Iterable,
+ List,
+ Literal,
+ NamedTuple,
+ Optional,
+ Tuple,
+ Type,
+ TypedDict,
+ TypeVar,
+ Union,
+)
+
+import django
+from django import forms
+from django.conf import settings
+from django.http import HttpRequest
+from django.middleware import csrf
+from django.utils.safestring import mark_safe
+from django.utils.timezone import now
+from django.contrib.humanize.templatetags.humanize import naturaltime
+from django.template.defaulttags import register as default_library
+
+from django_components import Component, registry, register, types
+
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- IMPORTS END ------------ #
+
+# This variable is overridden by the benchmark runner
+CONTEXT_MODE: Literal["django", "isolated"] = "isolated"
+
+if not settings.configured:
+ settings.configure(
+ BASE_DIR=Path(__file__).resolve().parent,
+ INSTALLED_APPS=["django_components"],
+ TEMPLATES=[
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [
+ "tests/templates/",
+ "tests/components/", # Required for template relative imports in tests
+ ],
+ "OPTIONS": {
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ]
+ },
+ }
+ ],
+ COMPONENTS={
+ "autodiscover": False,
+ "context_behavior": CONTEXT_MODE,
+ },
+ MIDDLEWARE=[],
+ DATABASES={
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": ":memory:",
+ }
+ },
+ SECRET_KEY="secret",
+ ROOT_URLCONF="django_components.urls",
+ )
+ django.setup()
+else:
+ settings.COMPONENTS["context_behavior"] = CONTEXT_MODE
+
+#####################################
+# RENDER ENTRYPOINT
+#####################################
+
+def gen_render_data():
+ data = load_project_data_from_json(data_json)
+
+ # Generate Request and User
+ users = data.pop("users")
+ user = users[0]
+
+ bookmarks: List[ProjectBookmark] = [
+ {
+ "id": 82,
+ "project": data["project"],
+ "text": "Test bookmark",
+ "url": "http://localhost:8000/bookmarks/9/create",
+ "attachment": None,
+ }
+ ]
+
+ request = HttpRequest()
+ request.user = user
+ request.method = "GET"
+ request.path = "/projects/1"
+
+ data["layout_data"] = ProjectLayoutData(
+ bookmarks=bookmarks,
+ project=data["project"],
+ active_projects=[data["project"]],
+ request=request,
+ )
+
+ return data
+
+
+def render(data):
+ result = ProjectPage.render(kwargs=data)
+ return result
+
+
+#####################################
+# DATA
+#####################################
+
+data_json = """
+{
+ "project": {
+ "pk": 1,
+ "fields": {
+ "name": "Project Name",
+ "organization": 1,
+ "status": "INPROGRESS",
+ "start_date": "2022-02-06",
+ "end_date": "2024-02-07"
+ }
+ },
+ "project_tags": [],
+ "phases": [
+ {
+ "pk": 8,
+ "fields": {
+ "project": 1,
+ "phase_template": 3
+ }
+ },
+ {
+ "pk": 7,
+ "fields": {
+ "project": 1,
+ "phase_template": 4
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "project": 1,
+ "phase_template": 5
+ }
+ },
+ {
+ "pk": 5,
+ "fields": {
+ "project": 1,
+ "phase_template": 6
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "project": 1,
+ "phase_template": 2
+ }
+ }
+ ],
+ "notes_1": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2025-02-07T08:59:58.689Z",
+ "modified": "2025-02-07T08:59:58.689Z",
+ "project": 1,
+ "text": "Test note 1"
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2025-02-07T08:59:58.689Z",
+ "modified": "2025-02-07T08:59:58.689Z",
+ "project": 1,
+ "text": "Test note 2"
+ }
+ }
+ ],
+ "comments_by_notes_1": {
+ "1": [
+ {
+ "pk": 3,
+ "fields": {
+ "parent": 1,
+ "notes": "Test note one two three",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "parent": 1,
+ "notes": "Test note 2",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "notes_2": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2024-02-07T11:20:49.085Z",
+ "modified": "2024-02-07T11:20:55.003Z",
+ "project": 1,
+ "text": "Test note x"
+ }
+ }
+ ],
+ "comments_by_notes_2": {
+ "1": [
+ {
+ "pk": 1,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 6",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 5",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 4",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "parent": 1,
+ "text": "Test note 3",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "notes_3": [
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2024-02-07T11:20:49.085Z",
+ "modified": "2024-02-07T11:20:55.003Z",
+ "project": 1,
+ "text": "Test note 2"
+ }
+ }
+ ],
+ "comments_by_notes_3": {
+ "2": [
+ {
+ "pk": 1,
+ "fields": {
+ "parent": 2,
+ "text": "Test note 1",
+ "modified_by": 1
+ }
+ },
+ {
+ "pk": 3,
+ "fields": {
+ "parent": 2,
+ "text": "Test note 0",
+ "modified_by": 1
+ }
+ }
+ ]
+ },
+ "roles_with_users": [
+ {
+ "pk": 6,
+ "fields": {
+ "user": 2,
+ "project": 1,
+ "name": "Assistant"
+ }
+ },
+ {
+ "pk": 7,
+ "fields": {
+ "user": 2,
+ "project": 1,
+ "name": "Owner"
+ }
+ }
+ ],
+ "contacts": [],
+ "outputs": [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 16",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 15,
+ "fields": {
+ "name": "Lorem ipsum 15",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 16,
+ "fields": {
+ "name": "Lorem ipsum 14",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 17,
+ "fields": {
+ "name": "Lorem ipsum 13",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 18,
+ "fields": {
+ "name": "Lorem ipsum 12",
+ "description": "",
+ "completed": true,
+ "phase": 4,
+ "dependency": null
+ }
+ },
+ [
+ [
+ {
+ "pk": 19,
+ "fields": {
+ "text": "Test bookmark",
+ "url": "http://localhost:8000/create/bookmmarks/9/",
+ "created_by": 1,
+ "output": 18
+ }
+ },
+ []
+ ]
+ ],
+ []
+ ],
+ [
+ {
+ "pk": 20,
+ "fields": {
+ "name": "Lorem ipsum 11",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": 14
+ }
+ },
+ [],
+ [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 10",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ []
+ ]
+ ]
+ ],
+ [
+ {
+ "pk": 21,
+ "fields": {
+ "name": "Lorem ipsum 9",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 22,
+ "fields": {
+ "name": "Lorem ipsum 8",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 23,
+ "fields": {
+ "name": "Lorem ipsum 7",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 24,
+ "fields": {
+ "name": "Lorem ipsum 6",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 25,
+ "fields": {
+ "name": "Lorem ipsum 5",
+ "description": "",
+ "completed": false,
+ "phase": 6,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 26,
+ "fields": {
+ "name": "Lorem ipsum 4",
+ "description": "",
+ "completed": false,
+ "phase": 6,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 27,
+ "fields": {
+ "name": "Lorem ipsum 3",
+ "description": "",
+ "completed": false,
+ "phase": 5,
+ "dependency": null
+ }
+ },
+ [],
+ []
+ ],
+ [
+ {
+ "pk": 28,
+ "fields": {
+ "name": "Lorem ipsum 2",
+ "description": "",
+ "completed": false,
+ "phase": 7,
+ "dependency": 14
+ }
+ },
+ [],
+ [
+ [
+ {
+ "pk": 14,
+ "fields": {
+ "name": "Lorem ipsum 1",
+ "description": "",
+ "completed": false,
+ "phase": 8,
+ "dependency": null
+ }
+ },
+ []
+ ]
+ ]
+ ]
+ ],
+ "status_updates": [],
+ "user_is_project_member": true,
+ "user_is_project_owner": true,
+ "phase_titles": {
+ "PHASE_0": "Phase 0",
+ "PHASE_1": "Phase 1",
+ "PHASE_2": "Phase 2",
+ "PHASE_3": "Phase 3",
+ "PHASE_4": "Phase 4",
+ "PHASE_5": "Phase 5",
+ "LEGACY": "Legacy"
+ },
+ "users": [
+ {
+ "pk": 2,
+ "fields": {
+ "name": "UserName",
+ "is_staff": true
+ }
+ }
+ ],
+ "organizations": [
+ {
+ "pk": 1,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Org Name"
+ }
+ }
+ ],
+ "phase_templates": [
+ {
+ "pk": 3,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 3",
+ "description": "## Phase 3",
+ "type": "PHASE_3"
+ }
+ },
+ {
+ "pk": 4,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 2",
+ "description": "## Phase 2",
+ "type": "PHASE_2"
+ }
+ },
+ {
+ "pk": 5,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 4",
+ "description": "## Phase 4",
+ "type": "PHASE_4"
+ }
+ },
+ {
+ "pk": 6,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 5",
+ "description": "## Phase 5",
+ "type": "PHASE_5"
+ }
+ },
+ {
+ "pk": 2,
+ "fields": {
+ "created": "2025-02-07T16:27:49.837Z",
+ "modified": "2025-02-07T16:27:49.837Z",
+ "name": "Phase 1",
+ "description": "## Phase 1",
+ "type": "PHASE_1"
+ }
+ }
+ ]
+}
+"""
+
+#####################################
+# DATA LOADER
+#####################################
+
+def load_project_data_from_json(contents: str) -> dict:
+ """
+ Loads project data from JSON and resolves references between objects.
+ Returns the data with all resolvable references replaced with actual object references.
+ """
+ data = json.loads(contents)
+
+ # First create lookup tables for objects that will be referenced
+ users_by_id = {
+ user['pk']: {'id': user['pk'], **user['fields']}
+ for user in data.get('users', [])
+ }
+
+ def _get_user(user_id: int):
+ return users_by_id[user_id] if user_id in users_by_id else data.get('users', [])[0]
+
+ organizations_by_id = {
+ org['pk']: {'id': org['pk'], **org['fields']}
+ for org in data.get('organizations', [])
+ }
+
+ phase_templates_by_id = {
+ pt['pk']: {'id': pt['pk'], **pt['fields']}
+ for pt in data.get('phase_templates', [])
+ }
+
+ # 1. Resolve project's organization reference
+ project = {'id': data['project']['pk'], **data['project']['fields']}
+ if 'organization' in project:
+ org_id = project.pop('organization') # Remove the ID field
+ project['organization'] = organizations_by_id[org_id] # Add the reference
+
+ # 2. Project tags - no changes needed
+ project_tags = data['project_tags']
+
+ # 3. Resolve phases' references
+ phases = []
+ phases_by_id = {} # We'll need this for resolving output references later
+ for phase_data in data['phases']:
+ phase = {'id': phase_data['pk'], **phase_data['fields']}
+ if 'project' in phase:
+ phase['project'] = project
+ if 'phase_template' in phase:
+ template_id = phase.pop('phase_template')
+ phase['phase_template'] = phase_templates_by_id[template_id]
+ phases.append(phase)
+ phases_by_id[phase['id']] = phase
+
+ # 4. Resolve notes_1 references
+ notes_1 = []
+ notes_1_by_id = {} # We'll need this for resolving notes references
+ for note_data in data['notes_1']:
+ note = {'id': note_data['pk'], **note_data['fields']}
+ if 'project' in note:
+ note['project'] = project
+ notes_1.append(note)
+ notes_1_by_id[note['id']] = note
+
+ # 5. Resolve comments_by_notes_1 references
+ comments_by_notes_1 = {}
+ for note_id, comments_list in data['comments_by_notes_1'].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {'id': comment_data['pk'], **comment_data['fields']}
+ if 'modified_by' in comment:
+ comment['modified_by'] = _get_user(comment['modified_by'])
+ if 'parent' in comment:
+ comment['parent'] = notes_1_by_id[comment['parent']]
+ resolved_comments.append(comment)
+ comments_by_notes_1[note_id] = resolved_comments
+
+ # 6. Resolve notes_2' references
+ notes_2 = []
+ notes_2_by_id = {} # We'll need this for resolving notes references
+ for note_data in data['notes_2']:
+ note = {'id': note_data['pk'], **note_data['fields']}
+ if 'project' in note:
+ note['project'] = project
+ notes_2.append(note)
+ notes_2_by_id[note['id']] = note
+
+ # 7. Resolve comments_by_notes_2 references
+ comments_by_notes_2 = {}
+ for note_id, comments_list in data['comments_by_notes_2'].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {'id': comment_data['pk'], **comment_data['fields']}
+ if 'modified_by' in comment:
+ comment['modified_by'] = _get_user(comment['modified_by'])
+ if 'parent' in comment:
+ comment['parent'] = notes_2_by_id[comment['parent']]
+ resolved_comments.append(comment)
+ comments_by_notes_2[note_id] = resolved_comments
+
+ # 8. Resolve notes_3 references
+ notes_3 = []
+ notes_3_by_id = {} # We'll need this for resolving notes references
+ for note_data in data['notes_3']:
+ note = {'id': note_data['pk'], **note_data['fields']}
+ if 'project' in note:
+ note['project'] = project
+ notes_3.append(note)
+ notes_3_by_id[note['id']] = note
+
+ # 9. Resolve comments_by_notes_3 references
+ comments_by_notes_3 = {}
+ for note_id, comments_list in data['comments_by_notes_3'].items():
+ resolved_comments = []
+ for comment_data in comments_list:
+ comment = {'id': comment_data['pk'], **comment_data['fields']}
+ if 'modified_by' in comment:
+ comment['modified_by'] = _get_user(comment['modified_by'])
+ if 'parent' in comment:
+ comment['parent'] = notes_3_by_id[comment['parent']]
+ resolved_comments.append(comment)
+ comments_by_notes_3[note_id] = resolved_comments
+
+ # 10. Resolve roles_with_users references
+ roles = []
+ for role_data in data['roles_with_users']:
+ role = {'id': role_data['pk'], **role_data['fields']}
+ if 'project' in role:
+ role['project'] = project
+ if 'user' in role:
+ role['user'] = _get_user(role['user'])
+ roles.append(role)
+
+ # 11. Contacts - EMPTY, so no changes needed
+ contacts = data['contacts']
+
+ # 12. Resolve outputs references
+ resolved_outputs = []
+ outputs_by_id = {} # For resolving dependencies
+
+ # First pass: Create all output objects and build lookup
+ for output_tuple in data['outputs']:
+ output_data = output_tuple[0]
+ output = {'id': output_data['pk'], **output_data['fields']}
+ if 'phase' in output:
+ output['phase'] = phases_by_id[output['phase']]
+ outputs_by_id[output['id']] = output
+
+ # Second pass: Process each output with its attachments and dependencies
+ for output_tuple in data['outputs']:
+ output_data, attachments_data, dependencies_data = output_tuple
+ output = outputs_by_id[output_data['pk']]
+
+ # Process attachments
+ resolved_attachments = []
+ for attachment_tuple in attachments_data:
+ attachment_data = attachment_tuple[0]
+ attachment = {'id': attachment_data['pk'], **attachment_data['fields']}
+ if 'created_by' in attachment:
+ attachment['created_by'] = _get_user(attachment['created_by'])
+ if 'output' in attachment:
+ attachment['output'] = outputs_by_id[attachment['output']]
+ # Keep tags as is
+ resolved_attachments.append((attachment, attachment_tuple[1]))
+
+ # Process dependencies
+ resolved_dependencies = []
+ for dep_tuple in dependencies_data:
+ dep_data = dep_tuple[0]
+ dep_output = outputs_by_id[dep_data['pk']]
+ # Keep the tuple structure but with resolved references
+ resolved_dependencies.append((dep_output, dep_tuple[1]))
+
+ resolved_outputs.append((output, resolved_attachments, resolved_dependencies))
+
+ return {
+ 'project': project,
+ 'project_tags': project_tags,
+ 'phases': phases,
+ 'notes_1': notes_1,
+ 'comments_by_notes_1': comments_by_notes_1,
+ 'notes_2': notes_2,
+ 'comments_by_notes_2': comments_by_notes_2,
+ 'notes_3': notes_3,
+ 'comments_by_notes_3': comments_by_notes_3,
+ 'roles_with_users': roles,
+ 'contacts': contacts,
+ 'outputs': resolved_outputs,
+ 'status_updates': data['status_updates'],
+ 'user_is_project_member': data['user_is_project_member'],
+ 'user_is_project_owner': data['user_is_project_owner'],
+ 'phase_titles': data['phase_titles'],
+ 'users': data['users'],
+ }
+
+#####################################
+# TYPES
+#####################################
+
+class User(TypedDict):
+ id: int
+ name: str
+
+
+class Organization(TypedDict):
+ id: int
+ name: str
+
+
+class Project(TypedDict):
+ id: int
+ name: str
+ organization: Organization
+ status: str
+ start_date: date
+ end_date: date
+
+
+class ProjectRole(TypedDict):
+ id: int
+ user: User
+ project: Project
+ name: str
+
+
+class ProjectBookmark(TypedDict):
+ id: int
+ project: Project
+ text: str
+ url: str
+ attachment: Optional["ProjectOutputAttachment"]
+
+
+class ProjectStatusUpdate(TypedDict):
+ id: int
+ project: Project
+ text: str
+ modified_by: User
+ modified: str
+
+
+class ProjectContact(TypedDict):
+ id: int
+ project: Project
+ link_id: str
+ name: str
+ job: str
+
+
+class PhaseTemplate(TypedDict):
+ id: int
+ name: str
+ description: str
+ type: str
+
+
+class ProjectPhase(TypedDict):
+ id: int
+ project: Project
+ phase_template: PhaseTemplate
+
+
+class ProjectOutput(TypedDict):
+ id: int
+ name: str
+ description: str
+ completed: bool
+ phase: ProjectPhase
+ dependency: Optional["ProjectOutput"]
+
+
+class ProjectOutputAttachment(TypedDict):
+ id: int
+ text: str
+ url: str
+ created_by: User
+ output: ProjectOutput
+
+
+class ProjectNote(TypedDict):
+ id: int
+ project: Project
+ text: str
+ created: str
+
+
+class ProjectNoteComment(TypedDict):
+ id: int
+ parent: ProjectNote
+ text: str
+ modified_by: User
+ modified: str
+
+
+#####################################
+# CONSTANTS
+#####################################
+
+FORM_SHORT_TEXT_MAX_LEN = 255
+
+# This allows us to compare Enum values against strings
+class StrEnum(str, Enum):
+ pass
+
+
+class TagResourceType(StrEnum):
+ PROJECT = "PROJECT"
+ PROJECT_BOOKMARK = "PROJECT_BOOKMARK"
+ PROJECT_OUTPUT = "PROJECT_OUTPUT"
+ PROJECT_OUTPUT_ATTACHMENT = "PROJECT_OUTPUT_ATTACHMENT"
+ PROJECT_TEMPLATE = "PROJECT_TEMPLATE"
+
+class ProjectPhaseType(StrEnum):
+ PHASE_1 = "PHASE_1"
+ PHASE_2 = "PHASE_2"
+ PHASE_3 = "PHASE_3"
+ PHASE_4 = "PHASE_4"
+ PHASE_5 = "PHASE_5"
+
+class TagTypeMeta(NamedTuple):
+ allowed_values: Tuple[str, ...]
+
+
+# Additional metadata for Tags
+#
+# NOTE: We use MappingProxyType as an immutable dict.
+# See https://stackoverflow.com/questions/2703599
+TAG_TYPE_META = MappingProxyType(
+ {
+ TagResourceType.PROJECT: TagTypeMeta(
+ allowed_values=(
+ "Tag 1",
+ "Tag 2",
+ "Tag 3",
+ "Tag 4",
+ ),
+ ),
+ TagResourceType.PROJECT_BOOKMARK: TagTypeMeta(
+ allowed_values=(
+ "Tag 5",
+ "Tag 6",
+ "Tag 7",
+ "Tag 8",
+ ),
+ ),
+ TagResourceType.PROJECT_OUTPUT: TagTypeMeta(
+ allowed_values=tuple(),
+ ),
+ TagResourceType.PROJECT_OUTPUT_ATTACHMENT: TagTypeMeta(
+ allowed_values=(
+ "Tag 9",
+ "Tag 10",
+ "Tag 11",
+ "Tag 12",
+ "Tag 13",
+ "Tag 14",
+ "Tag 15",
+ "Tag 16",
+ "Tag 17",
+ "Tag 18",
+ "Tag 19",
+ "Tag 20",
+ ),
+ ),
+ TagResourceType.PROJECT_TEMPLATE: TagTypeMeta(
+ allowed_values=("Tag 21",),
+ ),
+ }
+)
+
+class ProjectOutputDef(NamedTuple):
+ title: str
+ description: Optional[str] = None
+ dependency: Optional[str] = None
+
+
+class ProjectPhaseMeta(NamedTuple):
+ type: ProjectPhaseType
+ outputs: List[ProjectOutputDef]
+
+
+# This constant decides in which order the project phases are shown,
+# as well as what kind of name of description they have.
+#
+# NOTE: We use MappingProxyType as an immutable dict.
+# See https://stackoverflow.com/questions/2703599
+PROJECT_PHASES_META = MappingProxyType(
+ {
+ ProjectPhaseType.PHASE_1: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_1,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 0"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_2: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_2,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 1"),
+ ProjectOutputDef(title="Lorem ipsum 2"),
+ ProjectOutputDef(title="Lorem ipsum 3"),
+ ProjectOutputDef(title="Lorem ipsum 4"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_3: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_3,
+ outputs=[
+ ProjectOutputDef(
+ title="Lorem ipsum 6",
+ dependency="Lorem ipsum 1",
+ ),
+ ProjectOutputDef(
+ title="Lorem ipsum 7",
+ dependency="Lorem ipsum 1",
+ ),
+ ProjectOutputDef(title="Lorem ipsum 8"),
+ ProjectOutputDef(title="Lorem ipsum 9"),
+ ProjectOutputDef(title="Lorem ipsum 10"),
+ ProjectOutputDef(title="Lorem ipsum 11"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_4: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_4,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 12"),
+ ProjectOutputDef(title="Lorem ipsum 13"),
+ ],
+ ),
+ ProjectPhaseType.PHASE_5: ProjectPhaseMeta(
+ type=ProjectPhaseType.PHASE_5,
+ outputs=[
+ ProjectOutputDef(title="Lorem ipsum 14"),
+ ],
+ ),
+ }
+)
+
+#####################################
+# THEME
+#####################################
+
+ThemeColor = Literal["default", "error", "success", "alert", "info"]
+ThemeVariant = Literal["primary", "secondary"]
+
+VARIANTS = ["primary", "secondary"]
+
+class ThemeStylingUnit(NamedTuple):
+ """
+ Smallest unit of info, this class defines a specific styling of a specific
+ component in a specific state.
+
+ E.g. styling of a disabled "Error" button.
+ """
+
+ color: str
+ """CSS class(es) specifying color"""
+ css: str = ""
+ """Other CSS classes not specific to color"""
+
+
+class ThemeStylingVariant(NamedTuple):
+ """
+ Collection of styling combinations that are meaningful as a group.
+
+ E.g. all "error" variants - primary, disabled, secondary, ...
+ """
+
+ primary: ThemeStylingUnit
+ primary_disabled: ThemeStylingUnit
+ secondary: ThemeStylingUnit
+ secondary_disabled: ThemeStylingUnit
+
+
+class Theme(NamedTuple):
+ """Class for defining a styling and color theme for the app."""
+
+ default: ThemeStylingVariant
+ error: ThemeStylingVariant
+ alert: ThemeStylingVariant
+ success: ThemeStylingVariant
+ info: ThemeStylingVariant
+
+ sidebar: str
+ sidebar_link: str
+ background: str
+ tab_active: str
+ tab_text_active: str
+ tab_text_inactive: str
+ check_interactive: str
+ check_static: str
+ check_outline: str
+
+
+_secondary_btn_styling = "ring-1 ring-inset"
+
+theme = Theme(
+ default=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-blue-600 text-white hover:bg-blue-500 focus-visible:outline-blue-600 transition"
+ ),
+ primary_disabled=ThemeStylingUnit(
+ color="bg-blue-300 text-blue-50 focus-visible:outline-blue-600 transition"
+ ),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-gray-800 ring-gray-300 hover:bg-gray-100 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-gray-300 ring-gray-300 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ error=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-red-600 text-white hover:bg-red-500 focus-visible:outline-red-600"
+ ),
+ primary_disabled=ThemeStylingUnit(
+ color="bg-red-300 text-white focus-visible:outline-red-600"
+ ),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-red-600 ring-red-300 hover:bg-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-red-200 ring-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ alert=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-amber-500 text-white hover:bg-amber-400 focus-visible:outline-amber-500"
+ ),
+ primary_disabled=ThemeStylingUnit(
+ color="bg-amber-100 text-orange-300 focus-visible:outline-amber-500"
+ ),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-amber-500 ring-amber-300 hover:bg-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-orange-200 ring-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ success=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-green-600 text-white hover:bg-green-500 focus-visible:outline-green-600"
+ ),
+ primary_disabled=ThemeStylingUnit(
+ color="bg-green-300 text-white focus-visible:outline-green-600"
+ ),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-green-600 ring-green-300 hover:bg-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-green-200 ring-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ info=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-sky-600 text-white hover:bg-sky-500 focus-visible:outline-sky-600"
+ ),
+ primary_disabled=ThemeStylingUnit(
+ color="bg-sky-300 text-white focus-visible:outline-sky-600"
+ ),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-sky-600 ring-sky-300 hover:bg-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-sky-200 ring-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ sidebar="bg-neutral-900 text-neutral-200",
+ sidebar_link="hover:bg-neutral-700 hover:text-white transition",
+ background="bg-neutral-200",
+ tab_active="border-blue-700",
+ tab_text_active="text-blue-700",
+ tab_text_inactive="text-gray-500 hover:text-blue-700",
+ check_interactive="bg-blue-600 group-hover:bg-blue-500 transition",
+ check_static="bg-blue-600",
+ check_outline="border-2 border-blue-600 bg-white",
+)
+
+
+def get_styling_css(
+ variant: Optional["ThemeVariant"] = None,
+ color: Optional["ThemeColor"] = None,
+ disabled: Optional[bool] = None,
+):
+ """
+ Dynamically access CSS styling classes for a specific variant and state.
+
+ E.g. following two calls get styling classes for:
+ 1. Secondary error state
+ 1. Secondary alert disabled state
+ 2. Primary default disabled state
+ ```py
+ get_styling_css('secondary', 'error')
+ get_styling_css('secondary', 'alert', disabled=True)
+ get_styling_css(disabled=True)
+ ```
+ """
+ variant = variant or "primary"
+ color = color or "default"
+ disabled = disabled if disabled is not None else False
+
+ color_variants: ThemeStylingVariant = getattr(theme, color)
+
+ if variant not in VARIANTS:
+ raise ValueError(
+ f'Unknown theme variant "{variant}", must be one of {VARIANTS}'
+ )
+
+ variant_name = variant if not disabled else f"{variant}_disabled"
+ styling: ThemeStylingUnit = getattr(color_variants, variant_name)
+
+ css = f"{styling.color} {styling.css}".strip()
+ return css
+
+
+#####################################
+# HELPERS
+#####################################
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+def format_timestamp(timestamp: datetime):
+ """
+ If the timestamp is more than 7 days ago, format it as "Jan 1, 2025".
+ Otherwise, format it as a natural time string (e.g. "3 days ago").
+ """
+ if now() - timestamp > timedelta(days=7):
+ return timestamp.strftime("%b %-d, %Y")
+ else:
+ return naturaltime(timestamp)
+
+def group_by(
+ lst: Iterable[T],
+ keyfn: Callable[[T, int], Any],
+ mapper: Optional[Callable[[T, int], U]] = None,
+):
+ """
+ Given a list, generates a key for each item in the list using the `keyfn`.
+
+ Returns a dictionary of generated keys, where each value is a list of corresponding
+ items.
+
+ Similar to Lodash's `groupby`.
+
+ Optionally map the values in the lists with `mapper`.
+ """
+ grouped: Dict[Any, List[Union[U, T]]] = {}
+ for index, item in enumerate(lst):
+ key = dynamic_apply(keyfn, item, index)
+ if key not in grouped:
+ grouped[key] = []
+
+ mapped_item = dynamic_apply(mapper, item, index) if mapper else item
+ grouped[key].append(mapped_item)
+ return grouped
+
+def dynamic_apply(fn: Callable, *args):
+ """
+ Given a function and positional arguments that should be applied to given function,
+ this helper will apply only as many arguments as the function defines, or only
+ as much as the number of arguments that we can apply.
+ """
+ mapper_args_count = len(signature(fn).parameters)
+ num_args_to_apply = min(mapper_args_count, len(args))
+ first_n_args = args[:num_args_to_apply]
+
+ return fn(*first_n_args)
+
+#####################################
+# SHARED FORMS
+#####################################
+
+class ConditionalEditForm(forms.Form):
+ """
+ Subclass of Django's Form that sets all fields as NON-editable based
+ on the `editable` field.
+ """
+
+ editable: bool = True
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+ if self.editable is not None and not self.editable:
+ self._disable_all_form_fields()
+
+ def _disable_all_form_fields(self):
+ fields: Dict[str, forms.Field] = self.fields # type: ignore[assignment]
+ for form_field in fields.values():
+ form_field.widget.attrs["readonly"] = True
+
+#####################################
+# TEMPLATE TAG FILTERS
+#####################################
+
+@default_library.filter("alpine")
+def to_alpine_json(value: dict):
+ """
+ Serialize Python object such that it can be passed to Alpine callbacks
+ in Django templates.
+ """
+ # Avoid using double quotes since this value is passed to an HTML element
+ # attribute.
+ # NOTE: Maybe we could use HTML escaping to avoid the issue with double quotes?
+ data = json.dumps(value).replace('"', "'")
+ return data
+
+@default_library.filter("json")
+def to_json(value: dict):
+ """Serialize Python object to JSON."""
+ data = json.dumps(value)
+ return data
+
+@default_library.simple_tag
+def define(val=None):
+ return val
+
+@default_library.filter
+def get_item(dictionary: dict, key: str):
+ return dictionary.get(key)
+
+@default_library.filter("js")
+def serialize_to_js(obj):
+ """
+ Serialize a Python object to a JS-like expression.
+ Works recursively with nested dictionaries and lists.
+
+ So given a dict
+ `{"a": 123, "b": "console.log('abc')", "c": "'mystring'"}`
+
+ The filter exports:
+ `"{ a: 123, b: console.log('abc'), c: 'mystring' }"`
+ """
+ if isinstance(obj, dict):
+ # If the object is a dictionary, iterate through key-value pairs
+ items = []
+ for key, value in obj.items():
+ serialized_value = serialize_to_js(value) # Recursively serialize the value
+ items.append(f"{key}: {serialized_value}")
+ return f"{{ {', '.join(items)} }}"
+
+ elif isinstance(obj, (list, tuple)):
+ # If the object is a list, recursively serialize each item
+ serialized_items = [serialize_to_js(item) for item in obj]
+ return f"[{', '.join(serialized_items)}]"
+
+ elif isinstance(obj, str):
+ return obj
+
+ else:
+ # For other types (int, float, etc.), just return the string representation
+ return str(obj)
+
+#####################################
+# BUTTON
+#####################################
+
+@register("Button")
+class Button(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ href: Optional[str] = None,
+ link: Optional[bool] = None,
+ disabled: Optional[bool] = False,
+ variant: Union["ThemeVariant", Literal["plain"]] = "primary",
+ color: Union["ThemeColor", str] = "default",
+ type: Optional[str] = "button",
+ attrs: Optional[dict] = None,
+ ):
+ common_css = (
+ "inline-flex w-full text-sm font-semibold"
+ " sm:mt-0 sm:w-auto focus-visible:outline-2 focus-visible:outline-offset-2"
+ )
+ if variant == "plain":
+ all_css_class = common_css
+ else:
+ button_classes = get_styling_css(variant, color, disabled) # type: ignore[arg-type]
+ all_css_class = (
+ f"{button_classes} {common_css} px-3 py-2 justify-center rounded-md shadow-sm"
+ )
+
+ is_link = not disabled and (href or link)
+
+ all_attrs = {
+ **(attrs or {})
+ }
+ if disabled:
+ all_attrs["aria-disabled"] = "true"
+
+ return {
+ "href": href,
+ "disabled": disabled,
+ "type": type,
+ "btn_class": all_css_class,
+ "attrs": all_attrs,
+ "is_link": is_link,
+ }
+
+ template: types.django_html = """
+ {# Based on buttons from https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% if is_link %}
+
+ {% else %}
+
+ {% else %}
+
+ {% endif %}
+ """
+
+
+#####################################
+# MENU
+#####################################
+
+MaybeNestedList = List[Union[T, List[T]]]
+MenuItemGroup = List["MenuItem"]
+
+
+@dataclass(frozen=True)
+class MenuItem:
+ """
+ Single menu item used with the `menu` components.
+
+ Menu items can be divided by a horizontal line to indicate that the items
+ belong together. In code, we specify this by wrapping the item(s) as an array.
+
+ ```py
+ menu_items = [
+ # Group 1
+ [
+ MenuItem(value="Edit", link="#"),
+ MenuItem(value="Duplicate"),
+ ],
+ # Group 2
+ MenuItem(value="Add step before"),
+ MenuItem(value="Add step after"),
+ MenuItem(value="Add child step"),
+ # Group 3
+ [
+ MenuItem(value="Delete"),
+ ],
+ ]
+ ```
+ """
+
+ value: Any
+ """Value of the menu item to render."""
+
+ link: Optional[str] = None
+ """
+ If set, the menu item will be wrapped in an `` tag pointing to this
+ link.
+ """
+
+ item_attrs: Optional[dict] = None
+ """HTML attributes specific to this menu item."""
+
+
+@register("Menu")
+class Menu(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ items: MaybeNestedList[Union[MenuItem, str]],
+ model: Optional[str] = None,
+ # CSS and HTML attributes
+ attrs: Optional[dict] = None,
+ activator_attrs: Optional[dict] = None,
+ list_attrs: Optional[dict] = None,
+ # UX
+ close_on_esc: Optional[bool] = True,
+ close_on_click_outside: Optional[bool] = True,
+ anchor: Optional[str] = None,
+ anchor_dir: Optional[str] = "bottom",
+ ):
+ is_model_overriden = bool(model)
+ model = model or "open"
+
+ all_list_attrs: dict = {}
+ if list_attrs:
+ all_list_attrs.update(list_attrs)
+ if anchor:
+ all_list_attrs[f"x-anchor.{anchor_dir}"] = anchor
+ all_list_attrs.update({
+ "x-show": model,
+ "x-cloak": "",
+ })
+
+ return {
+ "model": model,
+ "items": items,
+ "is_model_overriden": is_model_overriden,
+ "close_on_click_outside": close_on_click_outside,
+ "close_on_esc": close_on_esc,
+ "activator_attrs": activator_attrs,
+ "list_attrs": all_list_attrs,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/elements/dropdowns #}
+
+ {% comment %}
+ NOTE: {{ model }} is the Alpine variable used for opening/closing. The variable name
+ is set dynamically, hence we use Django's double curly braces to refer to it.
+ {% endcomment %}
+
+ {# This is what opens the modal #}
+ {% if component_vars.is_filled.activator or component_vars.is_filled.default %}
+
+ """
+
+#####################################
+# MENU LIST
+#####################################
+
+def _normalize_item(item: Union[MenuItem, str]):
+ # Wrap plain value in MenuItem
+ if not isinstance(item, MenuItem):
+ return MenuItem(value=item)
+ return item
+
+
+# Normalize a list of MenuItems such that they are all in groups. We achieve
+# this by collecting consecutive ungrouped items into a single group.
+def _normalize_items_to_groups(items: MaybeNestedList[Union[MenuItem, str]]):
+ def is_group(item):
+ return isinstance(item, Iterable) and not isinstance(item, str)
+
+ groups: List[List[Union[MenuItem, str]]] = []
+
+ curr_group: Optional[List[Union[MenuItem, str]]] = None
+ for index, item_or_grp in enumerate(items):
+ group: List[Union[MenuItem, str]] = []
+ if isinstance(item_or_grp, Iterable) and not isinstance(item_or_grp, str):
+ group = item_or_grp
+ else:
+ if curr_group is not None:
+ group = curr_group
+ else:
+ group = curr_group = []
+ group.append(item_or_grp)
+
+ is_not_last = index < len(items) - 1
+ if is_not_last and not is_group(items[index + 1]):
+ continue
+ groups.append(group)
+ curr_group = None
+
+ return groups
+
+
+def prepare_menu_items(items: MaybeNestedList[Union[MenuItem, str]]):
+ groups = _normalize_items_to_groups(items)
+ normalized_groups: List[MenuItemGroup] = []
+
+ for group in groups:
+ norm_group = list(map(_normalize_item, group))
+ normalized_groups.append(norm_group)
+
+ return normalized_groups
+
+
+@register("MenuList")
+class MenuList(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ items: MaybeNestedList[Union[MenuItem, str]],
+ attrs: Optional[dict] = None,
+ ):
+ item_groups = prepare_menu_items(items)
+
+ return {
+ "item_groups": item_groups,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/elements/dropdowns #}
+
+ {% slot "activator" default / %}
+
+ {% endif %}
+
+ {% component "MenuList" items=items attrs=list_attrs / %}
+
+ {% for group in item_groups %}
+
+ """ # noqa: E501
+
+#####################################
+# TABLE
+#####################################
+
+class TableHeader(NamedTuple):
+ """Table header data structure used with the `table` components."""
+
+ name: str
+ """Header name, as displayed to the users."""
+
+ key: str
+ """Dictionary key on `TableRow.cols` that holds data for this header."""
+
+ hidden: Optional[bool] = None
+ """
+ Whether to hide the header. The column will still be rendered,
+ only the column title will be hidden.
+ """
+
+ cell_attrs: Optional[dict] = None
+ """HTML attributes specific to this table header cell."""
+
+
+@dataclass(frozen=True)
+class TableCell:
+ """Single table cell (row + col) used with the `table` components."""
+
+ value: Any
+ """Value of the cell to render."""
+
+ colspan: int = 1
+ """
+ How many columns should this cell occupy.
+
+ See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#colspan
+ """
+
+ link: Optional[str] = None
+ """
+ If set, the cell value will be wrapped in an `` tag pointing to this
+ link.
+ """
+
+ link_attrs: Optional[dict] = None
+ """
+ HTML attributes for the `` tag wrapping the link, if `link` is set.
+ """
+
+ cell_attrs: Optional[dict] = None
+ """HTML attributes specific to this table cell."""
+
+ linebreaks: Optional[bool] = None
+ """Whether to apply the `linebreaks` filter to this table cell."""
+
+ def __post_init__(self):
+ if not isinstance(self.colspan, int) or self.colspan < 1:
+ raise ValueError(
+ "TableCell.colspan must be a non-negative integer."
+ f" Instead got {self.colspan}"
+ )
+
+
+NULL_CELL = TableCell("")
+"""Definition of an empty cell"""
+
+
+@dataclass(frozen=True)
+class TableRow:
+ """
+ Table row data structure used with the `table` components.
+
+ TableRow holds columnar data in the `cols` dict, e.g.:
+ ```py
+ rows = [
+ TableRow(
+ cols={
+ 'name': TableCell(
+ value='My Name',
+ link='https://www.example.com',
+ link_attrs={
+ "class": 'font-weight-bold',
+ },
+ ),
+ 'desc': 'Lorem Ipsum'
+ }
+ ),
+ ]
+ ```
+ """
+
+ cols: Dict[str, TableCell] = field(default_factory=dict)
+ """Data within this row."""
+
+ row_attrs: Optional[dict] = None
+ """HTML attributes for this row."""
+
+ col_attrs: Optional[dict] = None
+ """
+ HTML attributes for each column in this row.
+
+ NOTE: This may be overriden by `TableCell.cell_attrs`.
+ """
+
+
+def create_table_row(
+ cols: Optional[Dict[str, Union[TableCell, Any]]] = None,
+ row_attrs: Optional[dict] = None,
+ col_attrs: Optional[dict] = None,
+):
+ # Normalize the values of `cols` to `TableCell` instances. This
+ # way we allow to set values of `self.cols` dict as plain values, e.g.:
+ #
+ # ```py
+ # create_table_row(
+ # cols={
+ # "my_value": 12
+ # }
+ # )
+ # ```
+ #
+ # Instead of having to wrap it in `TableCell` instance, like so:
+ #
+ # ```py
+ # TableRow(
+ # cols={
+ # "my_value": TableCell(value=12)
+ # }
+ # )
+ # ```
+ resolved_cols: Dict[str, TableCell] = {}
+ if cols:
+ for key, val in cols.items():
+ resolved_cols[key] = TableCell(value=val) if not isinstance(val, TableCell) else val
+
+ return TableRow(
+ cols=resolved_cols,
+ row_attrs=row_attrs,
+ col_attrs=col_attrs,
+ )
+
+
+def prepare_row_headers(row: TableRow, headers: List[TableHeader]):
+ # Skip headers when cells have colspan > 1, thus merging those cells
+ final_row_headers = []
+ headers_to_skip = 0
+ for header in headers:
+ if headers_to_skip > 0:
+ headers_to_skip -= 1
+ continue
+
+ final_row_headers.append(header)
+ cell = row.cols.get(header.key, None)
+ if cell is not None:
+ headers_to_skip = cell.colspan - 1
+
+ return final_row_headers
+
+
+@register("Table")
+class Table(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ headers: List[TableHeader],
+ rows: List[TableRow],
+ attrs: Optional[dict] = None,
+ ):
+ rows_to_render = [
+ tuple([row, prepare_row_headers(row, headers)]) for row in rows
+ ]
+
+ return {
+ "headers": headers,
+ "rows_to_render": rows_to_render,
+ "NULL_CELL": NULL_CELL,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+
+ {% for item in group %}
+ {% if item.link %}
+
+ {{ item.value }}
+
+ {% else %}
+
+ {% endfor %}
+
+ {{ item.value }}
+
+ {% endif %}
+ {% endfor %}
+
+
+ """ # noqa: E501
+
+#####################################
+# ICON
+#####################################
+
+@register("Icon")
+class Icon(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ name: str,
+ variant: Optional[str] = None,
+ size: Optional[int] = None,
+ stroke_width: Optional[float] = None,
+ viewbox: Optional[str] = None,
+ svg_attrs: Optional[dict] = None,
+ # Note: Unlike the underlying icon component, this component uses color CSS classes
+ color: Optional[str] = "",
+ icon_color: Optional[str] = "",
+ text_color: Optional[str] = "",
+ href: Optional[str] = None,
+ text_attrs: Optional[dict] = None,
+ link_attrs: Optional[dict] = None,
+ attrs: Optional[dict] = None,
+ ):
+ # Allow to set icon and text independently, or both at same time via `color` prop
+ if not icon_color:
+ icon_color = color
+ if not text_color:
+ text_color = color
+
+ svg_attrs = svg_attrs.copy() if svg_attrs else {}
+ if not svg_attrs.get("class"):
+ svg_attrs["class"] = ""
+ svg_attrs["class"] += f" {icon_color or ''} h-6 w-6 shrink-0"
+
+ return {
+ "name": name,
+ "variant": variant,
+ "size": size,
+ "viewbox": viewbox,
+ "stroke_width": stroke_width,
+ "svg_attrs": svg_attrs,
+ "text_color": text_color,
+ "text_attrs": text_attrs,
+ "link_attrs": link_attrs,
+ "href": href,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+
+
+
+
+
+
+
+ | + + {% if header.hidden %} + {{ header.name }} + {% else %} + {{ header.name }} + {% endif %} + + | + {% endfor %} +
|---|
| + + {% if cell.link %} + + {% if cell.linebreaks %} + {{ cell.value | linebreaksbr }} + {% else %} + {{ cell.value }} + {% endif %} + + {% else %} + {% if cell.linebreaks %} + {{ cell.value | linebreaksbr }} + {% else %} + {{ cell.value }} + {% endif %} + {% endif %} + + | + {% endfor %} +
+ {% if href %}
+
+ {% else %}
+
+ {% endif %}
+ {% component "heroicons"
+ name=name
+ variant=variant
+ size=size
+ viewbox=viewbox
+ stroke_width=stroke_width
+ attrs=svg_attrs
+ / %}
+ {% slot "content" default / %}
+
+ {% if href %}
+
+ {% else %}
+
+ {% endif %}
+
+ """
+
+
+#####################################
+# HEROICONS
+#####################################
+
+# Single hard-coded icon
+ICONS = {
+ "outline": {
+ "academic-cap": [
+ {'stroke-linecap': 'round', 'stroke-linejoin': 'round', 'd': 'M4.26 10.147a60.438 60.438 0 0 0-.491 6.347A48.62 48.62 0 0 1 12 20.904a48.62 48.62 0 0 1 8.232-4.41 60.46 60.46 0 0 0-.491-6.347m-15.482 0a50.636 50.636 0 0 0-2.658-.813A59.906 59.906 0 0 1 12 3.493a59.903 59.903 0 0 1 10.399 5.84c-.896.248-1.783.52-2.658.814m-15.482 0A50.717 50.717 0 0 1 12 13.489a50.702 50.702 0 0 1 7.74-3.342M6.75 15a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm0 0v-3.675A55.378 55.378 0 0 1 12 8.443m-7.007 11.55A5.981 5.981 0 0 0 6.75 15.75v-1.5'} # noqa: E501
+ ]
+ }
+}
+
+
+class ComponentDefaultsMeta(type):
+ def __new__(mcs, name: str, bases: Tuple, namespace: Dict) -> Type:
+ # Apply dataclass decorator to the class
+ return dataclass(super().__new__(mcs, name, bases, namespace))
+
+
+class ComponentDefaults(metaclass=ComponentDefaultsMeta):
+ def __post_init__(self) -> None:
+ fields = self.__class__.__dataclass_fields__ # type: ignore[attr-defined]
+ for field_name, dataclass_field in fields.items():
+ if dataclass_field.default is not MISSING:
+ if getattr(self, field_name) is None:
+ setattr(self, field_name, dataclass_field.default)
+
+
+class IconDefaults(ComponentDefaults):
+ name: str
+ variant: str = "outline"
+ size: int = 24
+ color: str = "currentColor"
+ stroke_width: float = 1.5
+ viewbox: str = "0 0 24 24"
+ attrs: Optional[Dict] = None
+
+
+@register("heroicons")
+class HeroIcon(Component):
+ """The icon component"""
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ """
+
+ def get_context_data(
+ self,
+ /,
+ *,
+ name: str,
+ variant: Optional[str] = None,
+ size: Optional[int] = None,
+ color: Optional[str] = None,
+ stroke_width: Optional[float] = None,
+ viewbox: Optional[str] = None,
+ attrs: Optional[Dict] = None,
+ ) -> Dict:
+ kwargs = IconDefaults(**self.kwargs)
+
+ if kwargs.variant not in ["outline", "solid"]:
+ raise ValueError(f"Invalid variant: {kwargs.variant}. Must be either 'outline' or 'solid'")
+
+ # variant_icons = ICONS[kwargs.variant]
+ variant_icons = ICONS["outline"]
+ icon_name = "academic-cap"
+
+ if icon_name not in variant_icons:
+ # Give users a helpful message by fuzzy-search the closest key
+ msg = ""
+ icon_names = list(variant_icons.keys())
+ if icon_names:
+ fuzzy_matches = difflib.get_close_matches(icon_name, icon_names, n=3, cutoff=0.7)
+ if fuzzy_matches:
+ suggestions = ", ".join([f"'{match}'" for match in fuzzy_matches])
+ msg += f". Did you mean any of {suggestions}?"
+
+ raise ValueError(f"Invalid icon name: {icon_name}{msg}")
+
+ icon_paths = variant_icons[icon_name]
+
+ # These are set as "default" attributes, so users can override them
+ # by passing them in the `attrs` argument.
+ default_attrs: Dict[str, Any] = {
+ "viewBox": kwargs.viewbox,
+ "style": f"width: {kwargs.size}px; height: {kwargs.size}px",
+ "aria-hidden": "true",
+ }
+
+ # The SVG applies the color differently in "outline" and "solid" versions
+ if kwargs.variant == "outline":
+ default_attrs["fill"] = "none"
+ default_attrs["stroke"] = kwargs.color
+ default_attrs["stroke-width"] = kwargs.stroke_width
+ else:
+ default_attrs["fill"] = kwargs.color
+ default_attrs["stroke"] = "none"
+
+ return {
+ "icon_paths": icon_paths,
+ "default_attrs": default_attrs,
+ "attrs": kwargs.attrs,
+ }
+
+#####################################
+# EXPANSION PANEL
+#####################################
+
+@register("ExpansionPanel")
+class ExpansionPanel(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ open: Optional[bool] = False,
+ panel_id: Optional[str] = None,
+ attrs: Optional[dict] = None,
+ header_attrs: Optional[dict] = None,
+ content_attrs: Optional[dict] = None,
+ icon_position: Literal["left", "right"] = "left",
+ ):
+ init_data = {"open": open}
+ return {
+ "attrs": attrs,
+ "header_attrs": header_attrs,
+ "content_attrs": content_attrs,
+ "icon_position": icon_position,
+ "init_data": init_data,
+ "panel_id": panel_id if panel_id else False,
+ }
+
+ template: types.django_html = """
+
+
+ """
+
+ js: types.js = """
+ document.addEventListener("alpine:init", () => {
+ Alpine.data("expansion_panel", () => ({
+ // Variables
+ isOpen: false,
+
+ // Methods
+ init() {
+ const initDataStr = this.$el.dataset.init;
+ const initData = JSON.parse(initDataStr);
+
+ this.isOpen = initData.open;
+
+ const panelId = this.$el.dataset.panelid;
+ const panel = new URL(location.href).searchParams.get("panel");
+
+ if (panel && panel == panelId) {
+ this.isOpen = true;
+ this.$el.scrollIntoView();
+ }
+ },
+
+ togglePanel(event) {
+ this.isOpen = !this.isOpen;
+ },
+ }));
+ });
+ """
+
+#####################################
+# PROJECT_PAGE
+#####################################
+
+# Tabs on this page and the query params to open specific tabs on page load.
+class ProjectPageTabsToQueryParams(Enum):
+ PROJECT_INFO = {"tabs-proj-right": "1"}
+ OUTPUTS = {"tabs-proj-right": "5"}
+
+
+@register("ProjectPage")
+class ProjectPage(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ phases: List[ProjectPhase],
+ project_tags: List[str],
+ notes_1: List[ProjectNote],
+ comments_by_notes_1: Dict[str, List[ProjectNoteComment]],
+ notes_2: List[ProjectNote],
+ comments_by_notes_2: Dict[str, List[ProjectNoteComment]],
+ notes_3: List[ProjectNote],
+ comments_by_notes_3: Dict[str, List[ProjectNoteComment]],
+ status_updates: List[ProjectStatusUpdate],
+ roles_with_users: List[ProjectRole],
+ contacts: List[ProjectContact],
+ outputs: List["OutputWithAttachmentsAndDeps"],
+ user_is_project_member: bool,
+ user_is_project_owner: bool,
+ phase_titles: Dict[ProjectPhaseType, str],
+ # Used by project layout
+ layout_data: "ProjectLayoutData",
+ project: Project,
+ breadcrumbs: Optional[List["Breadcrumb"]] = None,
+ ):
+ rendered_phases: List[ListItem] = []
+ phases_by_type = {p['phase_template']['type']: p for p in phases}
+ for phase_meta in PROJECT_PHASES_META.values():
+ phase = phases_by_type[phase_meta.type]
+ title = phase_titles[phase_meta.type]
+ rendered_phases.append(
+ ListItem(
+ value=title,
+ link=f"/projects/{project['id']}/phases/{phase['phase_template']['type']}",
+ )
+ )
+
+ redirect_url = f"/projects/{project['id']}"
+
+ return {
+ "layout_data": layout_data,
+ "project": project,
+ "breadcrumbs": breadcrumbs or [],
+ "project_tags": project_tags,
+ "rendered_phases": rendered_phases,
+ "contacts": contacts,
+ "notes_1": notes_1,
+ "comments_by_notes_1": comments_by_notes_1,
+ "notes_2": notes_2,
+ "comments_by_notes_2": comments_by_notes_2,
+ "notes_3": notes_3,
+ "comments_by_notes_3": comments_by_notes_3,
+ "status_updates": status_updates,
+ "roles_with_users": roles_with_users,
+ "outputs": outputs,
+ "user_is_project_member": user_is_project_member,
+ "user_is_project_owner": user_is_project_owner,
+ "project_page_url": redirect_url,
+ "phase_titles": phase_titles,
+ }
+
+ template: types.django_html = """
+ {% component "ProjectLayoutTabbed"
+ data=layout_data
+ breadcrumbs=breadcrumbs
+ top_level_tab_index=1
+ %}
+ {% fill "header" %}
+
+ {% if icon_position == "left" %}
+ {% component "Icon"
+ name="chevron-down"
+ variant="outline"
+ attrs:style="width: fit-content;"
+ attrs::class="{ 'rotate-180': isOpen }"
+ / %}
+ {% endif %}
+
+ {% slot "header" / %}
+
+ {% if icon_position == "right" %}
+ {% component "Icon"
+ name="chevron-down"
+ variant="outline"
+ attrs:style="width: fit-content;"
+ attrs::class="{ 'rotate-180': isOpen }"
+ / %}
+ {% endif %}
+
+
+ {% slot "content" default / %}
+
+
+
+ {% endfill %}
+
+ {% fill "left_panel" %}
+ {% component "List"
+ items=rendered_phases
+ item_attrs:class="py-5"
+ / %}
+ {% endfill %}
+
+ {% fill "tabs" %}
+ {% component "TabItem" header="Project Info" %}
+ {% component "ProjectInfo"
+ project=project
+ project_tags=project_tags
+ roles_with_users=roles_with_users
+ contacts=contacts
+ status_updates=status_updates
+ editable=user_is_project_owner
+ / %}
+ {% endcomponent %}
+
+ {% component "TabItem" header="Notes 1" %}
+ {% component "ProjectNotes"
+ project_id=project.id
+ notes=notes_1
+ comments_by_notes=comments_by_notes_1
+ editable=user_is_project_member
+ / %}
+ {% endcomponent %}
+
+ {% component "TabItem" header="Notes 2" %}
+ {% component "ProjectNotes"
+ project_id=project.id
+ notes=notes_2
+ comments_by_notes=comments_by_notes_2
+ editable=user_is_project_member
+ / %}
+ {% endcomponent %}
+
+ {% component "TabItem" header="Notes 3" %}
+ {% component "ProjectNotes"
+ project_id=project.id
+ notes=notes_3
+ comments_by_notes=comments_by_notes_3
+ editable=user_is_project_member
+ / %}
+ {% endcomponent %}
+
+ {% component "TabItem" header="Outputs" %}
+ {% component "ProjectOutputsSummary"
+ project_id=project.id
+ outputs=outputs
+ editable=user_is_project_member
+ phase_titles=phase_titles
+ / %}
+ {% endcomponent %}
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+#####################################
+# PROJECT_LAYOUT_TABBED
+#####################################
+
+class ProjectLayoutData(NamedTuple):
+ request: HttpRequest
+ active_projects: List[Project]
+ project: Project
+ bookmarks: List[ProjectBookmark]
+
+
+def gen_tabs(project_id: int):
+ return [
+ TabStaticEntry(
+ header="Tab 2",
+ href=f"/projects/{project_id}/tab-2",
+ content=None,
+ ),
+ TabStaticEntry(
+ header="Tab 1",
+ href=f"/projects/{project_id}/tab-1",
+ content=None,
+ ),
+ ]
+
+
+@register("ProjectLayoutTabbed")
+class ProjectLayoutTabbed(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ data: ProjectLayoutData,
+ breadcrumbs: Optional[List["Breadcrumb"]] = None,
+ top_level_tab_index: Optional[int] = None,
+ variant: Literal["thirds", "halves"] = "thirds",
+ ):
+ projects_url = "/projects"
+ curr_project_url = f"/projects/{data.project['id']}"
+
+ prefixed_breadcrumbs = chain(
+ [
+ Breadcrumb(
+ link=projects_url,
+ value=Icon.render(
+ kwargs={
+ "name": "home",
+ "variant": "outline",
+ "size": 20,
+ "stroke_width": 2,
+ "color": "text-gray-400 hover:text-gray-500",
+ },
+ deps_strategy="ignore",
+ ),
+ ),
+ Breadcrumb(value=data.project["name"], link=curr_project_url),
+ ],
+ breadcrumbs or [],
+ )
+
+ top_level_tabs = gen_tabs(data.project["id"])
+
+ left_pannel_attrs = {
+ "class": "w-1/3" if variant == "thirds" else "w-1/2",
+ }
+ right_pannel_attrs = {
+ "class": "w-2/3" if variant == "thirds" else "w-1/2",
+ }
+
+ return {
+ "layout_data": data,
+ "breadcrumbs": prefixed_breadcrumbs,
+ "bookmarks": data.bookmarks,
+ "project": data.project,
+ "top_level_tabs": top_level_tabs,
+ "top_level_tab_index": top_level_tab_index,
+ "theme": theme,
+ "left_pannel_attrs": left_pannel_attrs,
+ "right_pannel_attrs": right_pannel_attrs,
+ }
+
+ template: types.django_html = """
+ {% component "Layout" data=layout_data %}
+ {% fill "js" %}
+ {% slot "js" / %}
+ {% endfill %}
+
+ {% fill "css" %}
+ {% slot "css" / %}
+ {% endfill %}
+
+ {% fill "header" %}
+ {% component "Breadcrumbs" items=breadcrumbs / %}
+ {% endfill %}
+
+ {% fill "sidebar" %}
+ {% component "Bookmarks" bookmarks=bookmarks project_id=project.id / %}
+ {% endfill %}
+
+ {% fill "content" %}
+ {% slot "header" / %}
+
+ {% if top_level_tab_index is not None %}
+ {% component "TabsStatic" tabs=top_level_tabs index=top_level_tab_index / %}
+ {% endif %}
+
+
+
+
+
+ {{ project.name }}
+
+ {{ project.start_date }} - {{ project.end_date }}
+
+
+
+ {# Split the content to 2 columns, based on whether `left_panel` slot is filled #}
+ {% if component_vars.is_filled.left_panel %}
+
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+#####################################
+# LAYOUT
+#####################################
+
+class LayoutData(NamedTuple):
+ request: HttpRequest
+ active_projects: List[Project]
+
+
+@register("Layout")
+class Layout(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ data: LayoutData,
+ attrs: Optional[dict] = None,
+ ):
+ return {
+ "request": data.request,
+ "active_projects": data.active_projects,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+ {% component "RenderContextProvider" request=request %}
+ {% component "Base" %}
+ {% fill "js" %}
+ {% slot "js" / %}
+ {% endfill %}
+
+ {% fill "css" %}
+ {% slot "css" / %}
+ {% endfill %}
+
+ {% fill "content" %}
+
+
+
+ {% slot "left_panel" / %}
+
+
+ {% endif %}
+
+ {% slot "content" default %}
+
+ {% endif %}
+
+ {% component "Tabs"
+ name="proj-right"
+ attrs:class="p-6 h-full"
+ content_attrs:class="flex flex-col"
+ %}
+ {% slot "tabs" / %}
+ {% endcomponent %}
+
+ {% endslot %}
+
+ {% if component_vars.is_filled.left_panel %}
+
+
+
+ {% endfill %}
+ {% endcomponent %}
+ {% endcomponent %}
+ """
+
+ js: types.js = """
+ document.addEventListener('alpine:init', () => {
+ // NOTE: Defined as standalone function so we can call it variable initialization
+ const computeSidebarState = (prevState) => {
+ const width = (window.innerWidth > 0) ? window.innerWidth : screen.width;
+ // We automatically hide the sidebar when window is smaller than 1024px
+ const sidebarBreakpoint = 1024;
+ if (!prevState && width >= sidebarBreakpoint) {
+ return true;
+ } else if (prevState && width < sidebarBreakpoint) {
+ return false;
+ } else {
+ return prevState;
+ }
+ };
+
+ Alpine.data('layout', () => ({
+ // Variables
+ sidebarOpen: computeSidebarState(false),
+
+ init() {
+ this.onWindowResize();
+ },
+
+ // Handlers
+ toggleSidebar() {
+ this.sidebarOpen = !this.sidebarOpen;
+ },
+
+ onWindowResize() {
+ this.sidebarOpen = computeSidebarState(this.sidebarOpen);
+ },
+ }));
+ });
+ """
+
+
+#####################################
+# RENDER_CONTEXT_PROVIDER
+#####################################
+
+class RenderContext(NamedTuple):
+ """
+ Data that's commonly available in all template rendering.
+
+ In templates, we can assume that the data defined here is ALWAYS defined.
+ """
+ request: HttpRequest
+ user: User
+ csrf_token: str
+
+
+# This component "provides" data. This is similar to ContextProviders
+# in React, or the "provide" part of Vue's provide/inject feature.
+#
+# Components nested inside `RenderContextProvider` can access the
+# data with `self.inject("render_context")`.
+@register("RenderContextProvider")
+class RenderContextProvider(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ request: HttpRequest,
+ ):
+ csrf_token = csrf.get_token(request)
+ context = RenderContext(
+ request=request,
+ user=request.user,
+ csrf_token=csrf_token,
+ )
+
+ return {
+ "context": context,
+ }
+
+ template: types.django_html = """
+ {% provide "render_context" render_context=context %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+#####################################
+# BASE
+#####################################
+
+@register("Base")
+class Base(Component):
+ def get_context_data(self) -> dict:
+ context: RenderContext = self.inject("render_context").render_context
+
+ return {
+ "csrf_token": context.csrf_token,
+ "theme": theme,
+ }
+
+ template: types.django_html = """
+ {% load static %}
+
+
+
+
+
+
+
+
+ {% component "Sidebar" active_projects=active_projects %}
+ {% fill "content" %}
+ {% slot "sidebar" / %}
+ {% endfill %}
+ {% endcomponent %}
+
+
+
+ {% component "Navbar" attrs:@sidebar_toggle="toggleSidebar" / %}
+
+
+ {% slot "header" / %}
+
+
+
+ {% slot "content" default / %}
+
+
+
+ """
+
+#####################################
+# NAVBAR
+#####################################
+
+@register("Navbar")
+class Navbar(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ attrs: Optional[dict] = None,
+ ):
+ return {
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+
+ DEMO
+
+
+
+
+
+
+
+
+
+ """ # noqa: E501
+
+#####################################
+# DIALOG
+#####################################
+
+def construct_btn_onclick(model: str, btn_on_click: Optional[str]):
+ """
+ We want to allow the component users to define Alpine.js `@click` actions.
+ However, we also need to use `@click` to close the dialog after clicking
+ one of the buttons.
+
+ Hence, this function constructs the '@click' attribute, such that we can do both.
+
+ NOTE: `model` is the name of the Alpine variable used by the dialog.
+ """
+ on_click_cb = f"{model} = false;"
+ if btn_on_click:
+ on_click_cb = f"{btn_on_click}; {on_click_cb}"
+ return mark_safe(on_click_cb)
+
+
+@register("Dialog")
+class Dialog(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ model: Optional[str] = None,
+ # Classes and HTML attributes
+ attrs: Optional[dict] = None,
+ activator_attrs: Optional[dict] = None,
+ title_attrs: Optional[dict] = None,
+ content_attrs: Optional[dict] = None,
+ # Confirm button
+ confirm_hide: Optional[bool] = None,
+ confirm_text: Optional[str] = "Confirm",
+ confirm_href: Optional[str] = None,
+ confirm_disabled: Optional[bool] = None,
+ confirm_variant: Optional["ThemeVariant"] = "primary",
+ confirm_color: Optional["ThemeColor"] = None,
+ confirm_type: Optional[str] = None,
+ confirm_on_click: Optional[str] = "",
+ confirm_attrs: Optional[dict] = None,
+ # Cancel button
+ cancel_hide: Optional[bool] = None,
+ cancel_text: Optional[str] = "Cancel",
+ cancel_href: Optional[str] = None,
+ cancel_disabled: Optional[bool] = None,
+ cancel_variant: Optional["ThemeVariant"] = "secondary",
+ cancel_color: Optional["ThemeColor"] = None,
+ cancel_type: Optional[str] = None,
+ cancel_on_click: Optional[str] = "",
+ cancel_attrs: Optional[dict] = None,
+ # UX
+ close_on_esc: Optional[bool] = True,
+ close_on_click_outside: Optional[bool] = True,
+ ):
+ is_model_overriden = bool(model)
+ model = model or "open"
+
+ # Modify "attrs" passed to buttons, so we close the dialog when clicking the buttons
+ cancel_attrs = {
+ **(cancel_attrs or {}),
+ "@click": construct_btn_onclick(model, cancel_on_click),
+ }
+ confirm_attrs = {
+ **(confirm_attrs or {}),
+ "@click": construct_btn_onclick(model, confirm_on_click),
+ }
+
+ return {
+ "model": model,
+ "is_model_overriden": is_model_overriden,
+ # Classes and HTML attributes
+ "attrs": attrs,
+ "activator_attrs": activator_attrs,
+ "content_attrs": content_attrs,
+ "title_attrs": title_attrs,
+ # UX
+ "close_on_esc": close_on_esc,
+ "close_on_click_outside": close_on_click_outside,
+ # Confirm button
+ "confirm_hide": confirm_hide,
+ "confirm_text": confirm_text,
+ "confirm_href": confirm_href,
+ "confirm_disabled": confirm_disabled,
+ "confirm_variant": confirm_variant,
+ "confirm_color": confirm_color,
+ "confirm_type": confirm_type,
+ "confirm_attrs": confirm_attrs,
+ # Cancel button
+ "cancel_hide": cancel_hide,
+ "cancel_text": cancel_text,
+ "cancel_href": cancel_href,
+ "cancel_disabled": cancel_disabled,
+ "cancel_variant": cancel_variant,
+ "cancel_color": cancel_color,
+ "cancel_type": cancel_type,
+ "cancel_attrs": cancel_attrs,
+ }
+
+ template: types.django_html = """
+ {# Based on https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% comment %}
+ NOTE: {{ model }} is the Alpine variable used for opening/closing. The variable name
+ is set dynamically, hence we use Django's double curly braces to refer to it.
+ {% endcomment %}
+
+ {# Search not implemented #}
+
+
+
+
+
+
+
+
+
+ {% if component_vars.is_filled.activator or component_vars.is_filled.default %}
+ {# This is what opens the modal #}
+
+ """ # noqa: E501
+
+#####################################
+# TAGS
+#####################################
+
+class TagEntry(NamedTuple):
+ tag: str
+ selected: bool = False
+
+
+# JS props that can be passed to the Alpine component via python
+class TagsJsProps(TypedDict):
+ initTags: str
+
+
+@register("Tags")
+class Tags(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ tag_type: str,
+ js_props: dict,
+ editable: bool = True,
+ max_width: Union[int, str] = '300px',
+ attrs: Optional[dict] = None,
+ ):
+ all_tags = TAG_TYPE_META[tag_type.upper()].allowed_values # type: ignore[index]
+
+ return {
+ "editable": editable,
+ "all_tags": all_tags,
+ "max_width": max_width,
+ "attrs": attrs,
+ "js_props": js_props,
+ }
+
+ template: types.django_html = """
+
+ {% slot "activator" default / %}
+
+ {% endif %}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {% slot "prepend" / %}
+
+
+
+ {% if component_vars.is_filled.title %}
+
+
+ {% slot "append" / %}
+ + {% slot "title" / %} +
+ {% endif %} + + {% slot "content" / %} +
+ {% if not confirm_hide %}
+ {% component "Button"
+ variant=confirm_variant
+ color=confirm_color
+ disabled=confirm_disabled
+ href=confirm_href
+ type=confirm_type
+ attrs=confirm_attrs
+ %}
+ {{ confirm_text }}
+ {% endcomponent %}
+ {% endif %}
+
+ {% if not cancel_hide %}
+ {% component "Button"
+ variant=cancel_variant
+ color=cancel_color
+ disabled=cancel_disabled
+ href=cancel_href
+ type=cancel_type
+ attrs=cancel_attrs
+ %}
+ {{ cancel_text }}
+ {% endcomponent %}
+ {% endif %}
+
+
+
+
+ {% slot "title" %}
+
+ """
+
+ js: types.js = """
+ // Define component similarly to defining Vue components
+ const Tags = AlpineComposition.defineComponent({
+ name: "tags",
+
+ props: {
+ initAllTags: { type: String, required: true },
+ initTags: { type: Array, required: true },
+ },
+
+ emits: {
+ change: () => true,
+ },
+
+ // Instead of Alpine's init(), use setup()
+ // Props are passed down as reactive props, same as in Vue
+ // Second argument is the Alpine component instance.
+ setup(props, vm) {
+ const { ref, watch } = AlpineComposition.createReactivityAPI(vm);
+
+ const allTags = ref([]);
+ const tags = ref([]);
+
+ // Set the initial state from HTML
+ if (props.initAllTags) {
+ allTags.value = JSON.parse(props.initAllTags);
+ }
+
+ if (props.initTags) {
+ tags.value = props.initTags.map((t) => ({
+ value: t,
+ options: [],
+ }));
+
+ const availableTags = getAvailableTags();
+ tags.value = tags.value.map((t) => ({
+ value: t.value,
+ options: [t.value, ...availableTags],
+ }));
+ }
+
+ watch(tags, () => {
+ onTagsChange();
+ });
+
+ onTagsChange();
+
+ // Methods
+ const addTag = () => {
+ const availableTags = getAvailableTags();
+ if (!availableTags.length) return;
+
+ // Add tag by removing it from available tags
+ const nextValue = availableTags.shift();
+ const newSelectedTags = [
+ ...tags.value.map((t) => t.value),
+ nextValue,
+ ];
+
+ // And add it to the selected tags
+ tags.value = newSelectedTags.map((t) => ({
+ value: t,
+ options: [t, ...availableTags],
+ }));
+ }
+
+ const removeTag = (index) => {
+ // Remove the removed tag from selected items
+ tags.value = tags.value.filter((_, i) => i !== index);
+
+ // And add it to the available tags
+ const availableTags = getAvailableTags();
+ tags.value = tags.value.map((t) => ({
+ value: t.value,
+ options: [t.value, ...availableTags],
+ }));
+ }
+
+ const setTag = (index, value) => {
+ // Update the value
+ const oldValue = tags.value[index].value;
+ tags.value = tags.value.map((t) => ({
+ value: t.value === oldValue ? value : t.value,
+ options: t.options,
+ }));
+
+ // Then update the available tags
+ const availableTags = getAvailableTags();
+ tags.value = tags.value.map((t) => ({
+ value: t.value,
+ options: [t.value, ...availableTags],
+ }));
+ }
+
+ // When tags are added or removed, we add/remove HTML by AlpineJS,
+ // so user doesn't have to refresh the page.
+ function onTagsChange() {
+ if (vm.$refs.tagsInput) {
+ vm.$refs.tagsInput.value = tags.value.map((t) => t.value).join(',');
+ }
+
+ // Emit the final list of selected tags
+ const payload = tags.value.map((t) => t.value);
+ vm.$emit("change", payload);
+ }
+
+ function getAvailableTags() {
+ const selectedTagsSet = new Set(tags.value.map((t) => t.value));
+ return allTags.value.filter((t) => !selectedTagsSet.has(t));
+ }
+
+ return {
+ tags,
+ allTags,
+ addTag,
+ removeTag,
+ setTag,
+ };
+ },
+ });
+
+ document.addEventListener('alpine:init', () => {
+ AlpineComposition.registerComponent(Alpine, Tags);
+ });
+ """
+
+#####################################
+# FORM
+#####################################
+
+@register("Form")
+class Form(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ type: Literal["table", "paragraph", "ul", None] = None,
+ editable: bool = True,
+ method: str = "post",
+ # Submit btn
+ submit_hide: Optional[bool] = None,
+ submit_text: Optional[str] = "Submit",
+ submit_href: Optional[str] = None,
+ submit_disabled: Optional[bool] = None,
+ submit_variant: Optional["ThemeVariant"] = "primary",
+ submit_color: Optional["ThemeColor"] = None,
+ submit_type: Optional[str] = "submit",
+ submit_attrs: Optional[dict] = None,
+ # Cancel btn
+ cancel_hide: Optional[bool] = None,
+ cancel_text: Optional[str] = "Cancel",
+ cancel_href: Optional[str] = None,
+ cancel_disabled: Optional[bool] = None,
+ cancel_variant: Optional["ThemeVariant"] = "secondary",
+ cancel_color: Optional["ThemeColor"] = None,
+ cancel_type: Optional[str] = "button",
+ cancel_attrs: Optional[dict] = None,
+ # Actions
+ actions_hide: Optional[bool] = None,
+ actions_attrs: Optional[dict] = None,
+ # Other
+ form_content_attrs: Optional[dict] = None,
+ attrs: Optional[dict] = None,
+ ):
+ if type == "table":
+ form_content_tag = "table"
+ elif type == "paragraph":
+ form_content_tag = "div"
+ elif type == "ul":
+ form_content_tag = "ul"
+ else:
+ form_content_tag = "div"
+
+ # Add AlpineJS bindings to submit button
+ submit_attrs = {
+ **(submit_attrs or {}),
+ ":disabled": "isSubmitting",
+ }
+
+ return {
+ "form_content_tag": form_content_tag,
+ "form_content_attrs": form_content_attrs,
+ "method": method,
+ "editable": editable,
+ "submit_hide": submit_hide,
+ "submit_text": submit_text,
+ "submit_href": submit_href,
+ "submit_disabled": submit_disabled or not editable,
+ "submit_variant": submit_variant,
+ "submit_color": submit_color,
+ "submit_type": submit_type,
+ "submit_attrs": submit_attrs,
+ "cancel_hide": cancel_hide,
+ "cancel_text": cancel_text,
+ "cancel_href": cancel_href,
+ "cancel_disabled": cancel_disabled,
+ "cancel_variant": cancel_variant,
+ "cancel_color": cancel_color,
+ "cancel_type": cancel_type,
+ "cancel_attrs": cancel_attrs,
+ "actions_hide": actions_hide,
+ "actions_attrs": actions_attrs,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+
+ """
+
+ js: types.js = """
+ document.addEventListener('alpine:init', () => {
+ Alpine.data('form', () => {
+ const data = Alpine.reactive({
+ // Variables
+ formData: {},
+ isSubmitting: false,
+
+ // Methods
+ updateFormModel(event) {
+ const form = this.$el.closest("form");
+ if (!form) {
+ this.formData = null;
+ return;
+ };
+
+ const formDataObj = new FormData(form)
+ this.formData = [...formDataObj.entries()].reduce((agg, [key, val]) => {
+ agg[key] = val;
+ return agg;
+ }, {});
+ },
+
+ onSubmit(event) {
+ if (this.isSubmitting) return;
+
+ this.isSubmitting = true;
+ event.target.submit();
+ },
+ });
+
+ // Detect when Alpine's form state has changed and emit event when that happens
+ // NOTE: Alpine's reactivity is based on @vue/reactivity
+ Alpine.watch(() => data.formData, (newVal, oldVal) => {
+ const hasDataChanged = JSON.stringify(newVal || null) !== JSON.stringify(oldVal || null);
+ if (!hasDataChanged) return;
+
+ data.$dispatch('change', newVal);
+ });
+
+ return data;
+ });
+ });
+ """
+
+#####################################
+# BREADCRUMBS
+#####################################
+
+@dataclass(frozen=True)
+class Breadcrumb:
+ """
+ Single breadcrumb item used with the `breadcrumb` components.
+ """
+
+ value: Any
+ """Value of the menu item to render."""
+
+ link: Optional[str] = None
+ """
+ If set, the item will be wrapped in an `` tag pointing to this
+ link.
+ """
+
+ item_attrs: Optional[dict] = None
+ """HTML attributes specific to this item."""
+
+
+@register("Breadcrumbs")
+class Breadcrumbs(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ items: List[Breadcrumb],
+ attrs: Optional[dict] = None,
+ ):
+ return {
+ "items": items,
+ "attrs": attrs,
+ }
+
+ template: types.django_html = """
+
+ """
+
+
+#####################################
+# BOOKMARKS
+#####################################
+
+item_class = "px-4 py-1 text-sm text-gray-900 hover:bg-gray-100 cursor-pointer"
+menu_items = [
+ [
+ MenuItem(
+ value="Edit",
+ link="#",
+ item_attrs={
+ "class": item_class,
+ ":href": "contextMenuItem.value.edit_url",
+ },
+ ),
+ ],
+]
+
+
+@register("Bookmarks")
+class Bookmarks(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ bookmarks: List[ProjectBookmark],
+ attrs: Optional[dict] = None,
+ ):
+ bookmark_data: List[BookmarkItem] = []
+ attachment_data: List[BookmarkItem] = []
+
+ for bookmark in bookmarks:
+ is_attachment = bookmark['attachment'] is not None
+
+ if is_attachment:
+ # Send user to the Output tab in Project page and open and scroll
+ # to the relevent output that has the correct attachment.
+ edit_url = (
+ f"/edit/{project_id}/bookmark/{bookmark['id']}"
+ f"?{ProjectPageTabsToQueryParams.OUTPUTS.value}"
+ f"&panel={bookmark['attachment']['output']['id']}" # type: ignore[index]
+ ) # type: ignore[index]
+ else:
+ edit_url = f"/edit/{project_id}/bookmark/{bookmark['id']}"
+
+ entry = BookmarkItem(
+ text=bookmark['text'],
+ url=bookmark['url'],
+ id=bookmark['id'],
+ edit_url=edit_url,
+ )
+
+ if is_attachment:
+ attachment_data.append(entry)
+ else:
+ bookmark_data.append(entry)
+
+ create_bookmark_url = f"/create/{project_id}/bookmark"
+
+ return {
+ "bookmark_data": bookmark_data,
+ "attachment_data": attachment_data,
+ "create_bookmark_url": create_bookmark_url,
+ "menu_items": menu_items,
+ "attrs": attrs,
+ "theme": theme,
+ }
+
+ template: types.django_html = """
+ + Tags: +
+ {% endslot %} + + +
+
+
+
+ {% if editable %}
+
+
+
+ {% if editable %}
+
+
+ {% component "Button"
+ color="error"
+ attrs:class="!py-1"
+ attrs:@click="removeTag(index)"
+ %}
+ Remove
+ {% endcomponent %}
+
+ {% endif %}
+
+ {% component "Button"
+ attrs:class="!py-1"
+ attrs:@click="addTag"
+ %}
+ Add tag
+ {% endcomponent %}
+
+ {% endif %}
+ -
+ {% for bookmark in bookmark_data %}
+ {% component "Bookmark"
+ bookmark=bookmark
+ js:onMenuToggle="onContextMenuToggle"
+ / %}
+ {% endfor %}
+
+
- + {% component "Icon" + name="plus" + variant="outline" + size=18 + href=create_bookmark_url + color=theme.sidebar_link + text_attrs:class="px-2 py-1 text-xs" + svg_attrs:class="mt-0.5 ml-1" + %} + Add New Bookmark + {% endcomponent %} + + +
+ Attachments:
+
+
+ {% for bookmark in attachment_data %}
+ {% component "Bookmark"
+ bookmark=bookmark
+ js:onMenuToggle="onContextMenuToggle"
+ / %}
+ {% endfor %}
+
+ {% component "Menu"
+ items=menu_items
+ model="contextMenuItem.value"
+ anchor="contextMenuRef.value"
+ anchor_dir="bottom"
+ list_attrs:class="w-24 ml-8 z-40"
+ attrs:@click_outside="onContextMenuClickOutside"
+ / %}
+
+
+
+
+ {{ bookmark.text }}
+
+
+ {% component "Icon"
+ name='ellipsis-vertical'
+ variant='outline'
+ color=theme.sidebar_link
+ svg_attrs:class="inline"
+ text_attrs:class="p-0"
+ attrs:class="self-center cursor-pointer"
+ attrs:x-ref="bookmark_menu"
+ attrs:@click="onMenuToggle"
+ / %}
+
+ -
+ {% for item in items %}
+
-
+ +++ {% if item.link %} + + {% endif %} + ++
+ {{ item.value }} +
+ + {% if item.link %} + + {% endif %} +
+ {% empty %}
+ {% slot "empty" default / %}
+ {% endfor %}
+
+
+ """ # noqa: E501
+
+ js: types.js = """
+ document.addEventListener("alpine:init", () => {
+ Alpine.data("tabs", () => ({
+ // Variables
+ openTab: 1,
+ name: null,
+
+ // Computed
+ get tabQueryName() {
+ return `tabs-${this.name}`;
+ },
+
+ // Methods
+ init() {
+ // If we provided the `name` argument to the "tabs" component, then
+ // we register a listener for the query param `tabs-{name}`.
+ // The value of this query param is the current active tab (index).
+ //
+ // When user changes the currently-open tab, we push that info to the URL
+ // by updating the `tabs-{name}` query param.
+ //
+ // And when we navigate to a URL that already had `tabs-{name}` query param
+ // set, we load that tab.
+ if (this.$el.dataset['init']) {
+ const { name } = JSON.parse(this.$el.dataset['init']);
+
+ if (name) {
+ this.name = name
+ app.query.registerParam(
+ this.tabQueryName,
+ (newVal, oldVal) => this.onTabQueryParamChange(newVal, oldVal),
+ );
+ }
+ }
+
+ // Sometimes, the scrollable tab content area is scrolled to the bottom
+ // when the page loads. So we ensure here that the we scroll to the top if not already
+ // Also see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop
+ const containerEl = this.$refs.container;
+ if (containerEl.scrollTop) {
+ this.$refs.container.scrollTop = 0;
+ }
+ },
+
+ /**
+ * Set the current open tab and push the info to query params.
+ *
+ * @param {number} tabIndex
+ */
+ setOpenTab(tabIndex) {
+ this.openTab = tabIndex;
+
+ if (this.name) {
+ app.query.setParams({ [this.tabQueryName]: tabIndex });
+ }
+ },
+
+ /**
+ * Handle tab change from URL
+ *
+ * @param {*} newValue
+ * @param {*} oldValue
+ */
+ onTabQueryParamChange(newValue, oldValue) {
+ if (newValue == null) return;
+
+ const newValNum = typeof newValue === "number" ? newValue : Number.parseInt(newValue);
+ if (newValNum === this.openTab) return;
+
+ this.setOpenTab(newValNum);
+ },
+ }));
+ });
+ """
+
+
+# This is an "API" component, meaning that it's designed to process
+# user input provided as nested components. But after the input is
+# processed, it delegates to an internal "implementation" component
+# that actually renders the content.
+@register("Tabs")
+class Tabs(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ # Unique name to identify this tabs instance, so we can open/close the tabs
+ # based on the query params.
+ name: Optional[str] = None,
+ attrs: Optional[dict] = None,
+ header_attrs: Optional[dict] = None,
+ content_attrs: Optional[dict] = None,
+ ):
+ return {
+ "tabs": [],
+ "name": name,
+ "attrs": attrs,
+ "header_attrs": header_attrs,
+ "content_attrs": content_attrs,
+ "tabs_data": {"name": name},
+ }
+
+ def on_render_after(self, context, template, rendered, error=None) -> str:
+ # By the time we get here, all child TabItem components should have been
+ # rendered, and they should've populated the tabs list.
+ tabs: List[TabEntry] = context["tabs"]
+ return _TabsImpl.render(
+ kwargs={
+ "tabs": tabs,
+ "name": context["name"],
+ "attrs": context["attrs"],
+ "header_attrs": context["header_attrs"],
+ "content_attrs": context["content_attrs"],
+ },
+ deps_strategy="ignore",
+ )
+
+ template: types.django_html = """
+ {% provide "_tab" tabs=tabs enabled=True %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+
+# Use this component to define individual tabs inside the default slot
+# inside the `tab` component.
+@register("TabItem")
+class TabItem(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ header: str,
+ disabled: bool = False,
+ ):
+ # Access the list of tabs registered for parent Tabs component
+ # This raises if we're not nested inside the Tabs component.
+ tab_ctx = self.inject("_tab")
+
+ # We accessed the _tab context, but we're inside ANOTHER TabItem
+ if not tab_ctx.enabled:
+ raise RuntimeError(
+ f"Component '{self.name}' was called with no parent Tabs component. "
+ f"Either wrap '{self.name}' in Tabs component, or check if the component "
+ f"is not a descendant of another instance of '{self.name}'"
+ )
+ parent_tabs = tab_ctx.tabs
+
+ return {
+ "empty_tabs": [],
+ "parent_tabs": parent_tabs,
+ "header": header,
+ "disabled": disabled,
+ }
+
+ def on_render_after(self, context, template, content, error=None) -> None:
+ parent_tabs: List[dict] = context["parent_tabs"]
+ parent_tabs.append({
+ "header": context["header"],
+ "disabled": context["disabled"],
+ "content": mark_safe(content.strip()),
+ })
+
+ template: types.django_html = """
+ {% provide "_tab" tabs=empty_tabs enabled=False %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+
+@register("TabsStatic")
+class TabsStatic(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ tabs: List[TabStaticEntry],
+ index: int = 0,
+ hide_body: bool = False,
+ attrs: Optional[dict] = None,
+ header_attrs: Optional[dict] = None,
+ content_attrs: Optional[dict] = None,
+ ):
+ selected_content = tabs[index].content
+
+ tabs_data = []
+ for tab_index, tab in enumerate(tabs):
+ is_selectd = tab_index == index
+ styling = {
+ "tab": "border-b-2 " + theme.tab_active if is_selectd else "",
+ "text": theme.tab_text_active if is_selectd else theme.tab_text_inactive,
+ }
+ tabs_data.append((tab, styling))
+
+ return {
+ "attrs": attrs,
+ "tabs_data": tabs_data,
+ "header_attrs": header_attrs,
+ "content_attrs": content_attrs,
+ "hide_body": hide_body,
+ "selected_content": selected_content,
+ "theme": theme,
+ }
+
+ template: types.django_html = """
+ -
+ {% for tab in tabs %}
+ {% if not tab.disabled %}
+
- + + {{ tab.header }} + + + {% else %} +
-
+
+ {{ tab.header }} +
+
+ {% endif %}
+ {% endfor %}
+
+
+ {% for tab in tabs %}
+
+
+
+ {{ tab.content }}
+
+ {% endfor %}
+
+
+ """
+
+
+#####################################
+# PROJECT_INFO
+#####################################
+
+class ProjectInfoEntry(NamedTuple):
+ title: str
+ value: str
+
+
+@register("ProjectInfo")
+class ProjectInfo(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ project: Project,
+ project_tags: List[str],
+ contacts: List[ProjectContact],
+ status_updates: List[ProjectStatusUpdate],
+ roles_with_users: List[ProjectRole],
+ editable: bool,
+ ):
+ project_edit_url = f"/edit/{project['id']}/"
+ edit_project_roles_url = f"/edit/{project['id']}/roles/"
+ edit_contacts_url = f"/edit/{project['id']}/contacts/"
+ create_status_update_url = f"/create/{project['id']}/status_update/"
+
+ contacts_data = [
+ {
+ "contact": contact,
+ "link_url": f"/contacts/{contact['link_id']}",
+ }
+ for contact in contacts
+ ]
+
+ project_info = [
+ ProjectInfoEntry("Org", project['organization']['name']),
+ ProjectInfoEntry("Duration", f"{project['start_date']} - {project['end_date']}"),
+ ProjectInfoEntry("Status", project['status']),
+ ProjectInfoEntry("Tags", ", ".join(project_tags) or "-"),
+ ]
+
+ return {
+ "project_edit_url": project_edit_url,
+ "edit_contacts_url": edit_contacts_url,
+ "edit_project_roles_url": edit_project_roles_url,
+ "create_status_update_url": create_status_update_url,
+ "contacts_data": contacts_data,
+ "project": project,
+ "roles_with_users": roles_with_users,
+ "project_info": project_info,
+ "status_updates": status_updates,
+ "editable": editable,
+ }
+
+ template: types.django_html = """
+ -
+ {% for tab, styling in tabs_data %}
+ {% if not tab.disabled %}
+
- + + {{ tab.header }} + + + {% else %} +
-
+
+ {{ tab.header }} +
+
+ {% endif %}
+ {% endfor %}
+
+
+
+
+ {% endif %}
+
+ {{ selected_content }}
+
+
+ {# Info section #}
+
+ """
+
+#####################################
+# PROJECT_NOTES
+#####################################
+
+def _make_comments_data(note: ProjectNote, comment: ProjectNoteComment):
+ modified_time_str = format_timestamp(datetime.fromisoformat(comment['modified']))
+ formatted_modified_by = (
+ modified_time_str
+ + " "
+ + comment['modified_by']['name']
+ )
+
+ return {
+ "timestamp": formatted_modified_by,
+ "notes": comment['text'],
+ "edit_href": f"/update/{note['project']['id']}/note/{note['id']}/comment/{comment['id']}/",
+ }
+
+
+def _make_notes_data(
+ notes: List[ProjectNote],
+ comments_by_notes: Dict[int, List[ProjectNoteComment]],
+):
+ notes_data: List[dict] = []
+ for note in notes:
+ comments = comments_by_notes.get(note['id'], [])
+ comments_data = [_make_comments_data(note, comment) for comment in comments]
+
+ notes_data.append(
+ {
+ "text": note['text'],
+ "timestamp": note['created'],
+ "edit_href": f"/edit/{note['project']['id']}/note/{note['id']}/",
+ "comments": comments_data,
+ "create_comment_url": f"/create/{note['project']['id']}/note/{note['id']}/",
+ }
+ )
+
+ return notes_data
+
+
+@register("ProjectNotes")
+class ProjectNotes(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ notes: List[ProjectNote],
+ comments_by_notes: Dict[int, List[ProjectNoteComment]],
+ editable: bool,
+ ):
+ create_note_url = f"/create/{project_id}/note/"
+ notes_data = _make_notes_data(notes, comments_by_notes)
+
+ return {
+ "create_note_url": create_note_url,
+ "notes_data": notes_data,
+ "editable": editable,
+ }
+
+ template: types.django_html = """
+
+
+ {% for key, value in project_info %}
+
+
+
+ {# Status Updates section #}
+ {% component "ProjectStatusUpdates"
+ project_id=project.id
+ status_updates=status_updates
+ editable=editable
+ / %}
+
+
+
+ Project Info
+ + {% if editable %} + {% component "Button" + href=project_edit_url + attrs:class="not-prose" + %} + Edit Project + {% endcomponent %} + {% endif %} +| + {{ key }}: + | ++ {{ value }} + | +
+ {# Team section #}
+
+
+
+
+ {# Contacts section #}
+
+
+
+ {% component "ProjectUsers"
+ project_id=project.id
+ roles_with_users=roles_with_users
+ available_roles=None
+ available_users=None
+ editable=False
+ / %}
+ Team
+ + {% if editable %} + {% component "Button" + href=edit_project_roles_url + attrs:class="not-prose" + %} + Edit Team + {% endcomponent %} + {% endif %} +
+
+
+ {% else %}
+
+
+
+
+ {% if contacts_data %}
+ Contacts
+ + {% if editable %} + {% component "Button" + href=edit_contacts_url + attrs:class="not-prose" + %} + Edit Contacts + {% endcomponent %} + {% endif %} +| Name | +Job | +Link | +
|---|---|---|
| {{ row.contact.name }} | +{{ row.contact.job }} | ++ {% component "Icon" + href=row.link_url + name="arrow-top-right-on-square" + variant="outline" + color="text-gray-400 hover:text-gray-500" + / %} + | +
No entries
+ {% endif %} +
+
+ """
+
+
+#####################################
+# PROJECT_OUTPUTS_SUMMARY
+#####################################
+
+class AttachmentWithTags(NamedTuple):
+ attachment: ProjectOutputAttachment
+ tags: List[str]
+
+
+class OutputWithAttachments(NamedTuple):
+ output: ProjectOutput
+ attachments: List[AttachmentWithTags]
+
+
+class OutputWithAttachmentsAndDeps(NamedTuple):
+ output: ProjectOutput
+ attachments: List[AttachmentWithTags]
+ dependencies: List[OutputWithAttachments]
+
+
+@register("ProjectOutputsSummary")
+class ProjectOutputsSummary(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ outputs: List["OutputWithAttachmentsAndDeps"],
+ editable: bool,
+ phase_titles: Dict[ProjectPhaseType, str],
+ ):
+ outputs_by_phase = group_by(outputs, lambda output, _: output[0]['phase']['phase_template']['type'])
+
+ groups: List[dict] = []
+ for phase_meta in PROJECT_PHASES_META.values():
+ phase_outputs = outputs_by_phase.get(phase_meta.type, [])
+ title = phase_titles[phase_meta.type]
+ groups.append(
+ {
+ "phase_title": title,
+ "phase_type": phase_meta.type,
+ "outputs": phase_outputs,
+ "has_outputs": bool(phase_outputs),
+ }
+ )
+
+ return {
+ "project_id": project_id,
+ "editable": editable,
+ "groups": groups,
+ }
+
+ template: types.django_html = """
+ Notes
+ {% if notes_data %} +
+ {% for note in notes_data %}
+
+ {% endif %}
+
+ {% if editable %}
+ {% component "Button" href=create_note_url %}
+ Add Note
+ {% endcomponent %}
+ {% endif %}
+
+
+ {% endfor %}
+
+
+ {{ note.timestamp }}
+
+ {% if editable %}
+ {% component "Icon"
+ name="pencil-square"
+ variant="outline"
+ href=note.edit_href
+ color="text-gray-400 hover:text-gray-500"
+ / %}
+ {% endif %}
+
+ + {{ note.text }} +
+ +
+
+ + Comments +
+ + {% for comment in note.comments %} +
+
+ {% endfor %}
+
+
+
+ {{ comment.timestamp }}
+
+ {% if editable %}
+ {% component "Icon"
+ name="pencil-square"
+ variant="outline"
+ href=comment.edit_href
+ color="text-gray-400 hover:text-gray-500"
+ / %}
+ {% endif %}
+
+
+
+ + {{ comment.text }} +
+
+ {% if editable %}
+ {% component "Button" href=note.create_comment_url %}
+ Add comment
+ {% endcomponent %}
+ {% endif %}
+
+
+ {% for group in groups %}
+ {% component "ExpansionPanel"
+ open=group.has_outputs
+ header_attrs:class="flex gap-x-2 prose"
+ %}
+ {% fill "header" %}
+
+ """
+
+
+#####################################
+# PROJECT_STATUS_UPDATES
+#####################################
+
+def _make_status_update_data(status_update: ProjectStatusUpdate):
+ modified_time_str = format_timestamp(datetime.fromisoformat(status_update['modified']))
+ formatted_modified_by = (
+ modified_time_str
+ + " "
+ + status_update['modified_by']['name']
+ )
+
+ return {
+ "timestamp": formatted_modified_by,
+ "text": status_update['text'],
+ "edit_href": f"/edit/{status_update['project']['id']}/status_update/{status_update['id']}",
+ }
+
+
+@register("ProjectStatusUpdates")
+class ProjectStatusUpdates(Component):
+
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ status_updates: List[ProjectStatusUpdate],
+ editable: bool,
+ ):
+ create_status_update_url = f"/create/{project_id}/status_update"
+
+ updates_data = [_make_status_update_data(status_update) for status_update in status_updates]
+
+ return {
+ "create_status_update_url": create_status_update_url,
+ "updates_data": updates_data,
+ "editable": editable,
+ }
+
+ template: types.django_html = """
+ + {{ group.phase_title }} +
+ {% endfill %} + + {% fill "content" %} + {% if group.outputs %} + {% component "ProjectOutputs" + outputs=group.outputs + project_id=project_id + phase_type=group.phase_type + editable=editable + / %} + {% else %} + No outputs + {% endif %} + {% endfill %} + {% endcomponent %} + {% endfor %} +
+
+ """
+
+
+#####################################
+# PROJECT USERS
+#####################################
+
+roles_table_headers = [
+ TableHeader(key="name", name="Name"),
+ TableHeader(key="role", name="Role"),
+ TableHeader(key="delete", name="", hidden=True),
+]
+
+
+class ProjectAddUserForm(ConditionalEditForm):
+ user_id = forms.ChoiceField(required=True, choices=[], label="User")
+ role = forms.ChoiceField(required=True, choices=[])
+
+ def __init__(
+ self,
+ editable: bool,
+ available_role_choices: List[Tuple[str, str]],
+ available_user_choices: List[Tuple[str, str]],
+ *args,
+ **kwargs,
+ ):
+ self.editable = editable
+
+ super().__init__(*args, **kwargs)
+
+ user_field: forms.ChoiceField = self.fields["user_id"] # type: ignore[assignment]
+ user_field.choices = available_user_choices
+
+ role_field: forms.ChoiceField = self.fields["role"] # type: ignore[assignment]
+ role_field.choices = available_role_choices
+
+
+@register("ProjectUsers")
+class ProjectUsers(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ roles_with_users: List[ProjectRole],
+ available_roles: Optional[List[str]],
+ available_users: Optional[List[User]],
+ editable: bool = False,
+ ):
+ roles_table_rows = []
+ for role in roles_with_users:
+ user = role['user']
+
+ if editable:
+ delete_action = ProjectUserAction.render(
+ kwargs={
+ "user_name": user['name'],
+ "project_id": project_id,
+ "role_id": role['id'],
+ },
+ deps_strategy="ignore",
+ )
+ else:
+ delete_action = ""
+
+ roles_table_rows.append(
+ create_table_row(
+ cols={
+ "name": TableCell(user['name']),
+ "role": TableCell(role['name']),
+ "delete": delete_action,
+ }
+ )
+ )
+
+ submit_url = f"/submit/{project_id}/role/create"
+ project_url = f"/project/{project_id}"
+
+ if available_roles:
+ available_role_choices = [
+ (role, role) for role in available_roles
+ ]
+ else:
+ available_role_choices = []
+
+ if available_users:
+ available_user_choices = [
+ (str(user['id']), user['name']) for user in available_users
+ ]
+ else:
+ available_user_choices = []
+
+ return {
+ "editable": editable,
+ "table_headers": roles_table_headers,
+ "table_rows": roles_table_rows,
+ "add_user_form": ProjectAddUserForm(
+ editable,
+ available_role_choices,
+ available_user_choices,
+ ),
+ "submit_url": submit_url,
+ "project_url": project_url,
+ }
+
+ template: types.django_html = """
+
+
+ {% if updates_data %}
+ Status Updates
+ {% if editable %} + {% component "Button" href=create_status_update_url %} + Add status update + {% endcomponent %} + {% endif %} +
+ {% for update in updates_data %}
+
+ {% endif %}
+
+
+ {% endfor %}
+
+
+ {{ update.timestamp }}
+
+ {% if editable %}
+ {% component "Icon"
+ name="pencil-square"
+ variant="outline"
+ href=update.edit_href
+ color="text-gray-400 hover:text-gray-500"
+ / %}
+ {% endif %}
+
+ + {{ update.text }} +
+
+ {% if table_rows %}
+ {% component "Table"
+ headers=table_headers
+ rows=table_rows
+ attrs:@user_delete="onUserDelete"
+ / %}
+ {% endif %}
+
+ {% if editable %}
+
+ """
+
+ js: types.js = """
+ document.addEventListener('alpine:init', () => {
+ Alpine.data('project_users', () => ({
+ // Variables
+ isDeleteDialogOpen: false,
+ role: null,
+
+ // Methods
+ onUserDelete(event) {
+ const { role } = event.detail;
+
+ this.role = role;
+ this.isDeleteDialogOpen = !!role;
+ },
+ }));
+ });
+ """
+
+#####################################
+# PROJECT_USER_ACTION
+#####################################
+
+@register("ProjectUserAction")
+class ProjectUserAction(Component):
+
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ role_id: int,
+ user_name: str,
+ ):
+ delete_url = f"/delete/{project_id}/{role_id}"
+
+ role_data = {
+ "delete_url": delete_url,
+ "role_id": role_id,
+ "user_name": user_name,
+ }
+
+ return {
+ "role": role_data,
+ }
+
+ template: types.django_html = """
+ Set project roles
+ + + + + {% component "Dialog" + model="isDeleteDialogOpen" + confirm_text="Delete" + confirm_href='#' + confirm_color="error" + confirm_attrs::href="role.delete_url" + content_attrs:class="w-full" + %} + {% fill "title" %} +
+
+ Remove
+
+ from this project?
+
+ {% component "Icon"
+ name="trash"
+ variant="outline"
+ size=18
+ attrs:class="p-2 self-center"
+ / %}
+
+ {% endfill %}
+
+ {% fill "content" %}
+
+ This action cannot be undone.
+
+ {% endfill %}
+
+ {% endcomponent %}
+
+ {% endif %}
+
+ {% component "Icon"
+ name="trash"
+ variant="outline"
+ size=18
+ href="#"
+ color="text-gray-500 hover:text-gray-400"
+ svg_attrs:class="inline mb-1"
+ attrs:class="p-2"
+ attrs:@click.stop="$dispatch('user_delete', { role })"
+ / %}
+
+ """
+
+#####################################
+# PROJECT_OUTPUTS
+#####################################
+
+
+@register("ProjectOutputs")
+class ProjectOutputs(Component):
+
+ def get_context_data(
+ self,
+ /,
+ *,
+ project_id: int,
+ phase_type: str,
+ outputs: List[OutputWithAttachmentsAndDeps],
+ editable: bool,
+ ) -> Any:
+ outputs_data: List[RenderedProjectOutput] = []
+ for output_tuple in outputs:
+ output, attachments, dependencies = output_tuple
+
+ attach_data: List[RenderedAttachment] = []
+ for attachment in attachments:
+ attach_data.append(RenderedAttachment(
+ url=attachment[0]['url'],
+ text=attachment[0]['text'],
+ tags=attachment[1],
+ ))
+
+ update_output_url = "/update"
+
+ deps: List[RenderedOutputDep] = []
+ for dep in dependencies:
+ output, attachments = dep
+ phase_url = f"/phase/{project_id}/{output['phase']['phase_template']['type']}"
+ deps.append(
+ RenderedOutputDep(
+ dependency=dep,
+ phase_url=phase_url,
+ attachments=[
+ {
+ "url": d.attachment['url'],
+ "text": d.attachment['text'],
+ "tags": d.tags,
+ }
+ for d in attachments
+ ],
+ )
+ )
+
+ has_missing_deps = any(
+ [not output['completed'] for output, _ in dependencies]
+ )
+
+ outputs_data.append(
+ RenderedProjectOutput(
+ output=output,
+ dependencies=deps,
+ has_missing_deps=has_missing_deps,
+ output_data={
+ "editable": editable,
+ },
+ attachments=attach_data,
+ update_output_url=update_output_url,
+ )
+ )
+
+ return {
+ "outputs_data": outputs_data,
+ "editable": editable,
+ }
+
+ template: types.django_html = """
+
+ {% for data in outputs_data %}
+
+ """
+
+#####################################
+# PROJECT_OUTPUT_BADGE
+#####################################
+
+@register("ProjectOutputBadge")
+class ProjectOutputBadge(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ completed: bool,
+ missing_deps: bool,
+ ):
+ return {
+ "completed": completed,
+ "missing_deps": missing_deps,
+ "theme": theme,
+ }
+
+ template: types.django_html = """
+
+ {# Missing dependencies #}
+ {% if missing_deps %}
+ {% component "Icon"
+ name="exclamation-triangle"
+ variant="outline"
+ color="text-black"
+ size=32
+ stroke_width=2
+ attrs:title="A dependent dependency has not been met!"
+ / %}
+
+ {# Completed #}
+ {% elif completed %}
+
+ {% component "Icon"
+ name="check"
+ variant="outline"
+ color="text-white"
+ size=20
+ stroke_width=2
+ attrs:class="p-2"
+ / %}
+
+
+ {# NOT completed #}
+ {% else %}
+
+ {% endif %}
+
+ """ # noqa: E501
+
+#####################################
+# PROJECT_OUTPUT_DEPENDENCY
+#####################################
+
+@register("ProjectOutputDependency")
+class ProjectOutputDependency(Component):
+ def get_context_data(self, /, *, dependency: "RenderedOutputDep"):
+ return {
+ "attachments": dependency.attachments,
+ "dependency": dependency.dependency,
+ "phase_url": dependency.phase_url,
+ "OUTPUT_DESCRIPTION_PLACEHOLDER": OUTPUT_DESCRIPTION_PLACEHOLDER,
+ }
+
+ template: types.django_html = """
+
+
+ {% endfor %}
+
+ {% component "ProjectOutputBadge"
+ completed=data.output.completed
+ missing_deps=data.has_missing_deps
+ / %}
+
+
+ {% component "ExpansionPanel"
+ panel_id=data.output.id
+ icon_position="right"
+ attrs:class="border-b border-solid border-gray-300 pb-2 mb-3"
+ header_attrs:class="flex align-center justify-between"
+ %}
+ {% fill "header" %}
+
+
+ {{ data.output.name }}
+
+ {% endfill %}
+
+ {% fill "content" %}
+
+ {# Dependencies #}
+ {% for dep in data.dependencies %}
+ {% component "ProjectOutputDependency" dependency=dep / %}
+ {% endfor %}
+
+ {# Own data + attachments #}
+ {% component "ProjectOutputForm" data=data editable=editable / %}
+
+ {% endfill %}
+ {% endcomponent %}
+
+
+ """
+
+ js: types.js = """
+ // Define component similarly to defining Vue components
+ const ProjectOutputDependency = AlpineComposition.defineComponent({
+ name: 'project_output_dependency',
+
+ props: {
+ initAttachments: { type: String, required: true },
+ },
+
+ // Instead of Alpine's init(), use setup()
+ // Props are passed down as reactive props, same as in Vue
+ // Second argument is the Alpine component instance.
+ setup(props, vm, { ref }) {
+ const attachments = ref([]);
+
+ // Set the initial state from HTML
+ if (props.initAttachments) {
+ attachments.value = JSON.parse(props.initAttachments).map(({ url, text, tags }) => ({
+ url,
+ text,
+ tags,
+ isPreview: true,
+ }));
+ }
+
+ // Only those variables exposed by returning can be accessed from within HTML
+ return {
+ attachments,
+ };
+ },
+ });
+
+ document.addEventListener('alpine:init', () => {
+ AlpineComposition.registerComponent(Alpine, ProjectOutputDependency);
+ });
+ """
+
+#####################################
+# PROJECT_OUTPUT_ATTACHMENTS
+#####################################
+
+class ProjectOutputAttachmentsJsProps(TypedDict):
+ attachments: str
+
+
+@register("ProjectOutputAttachments")
+class ProjectOutputAttachments(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ has_attachments: bool,
+ js_props: ProjectOutputAttachmentsJsProps,
+ editable: bool,
+ attrs: Optional[dict] = None,
+ ):
+ return {
+ "has_attachments": has_attachments,
+ "editable": editable,
+ "attrs": attrs,
+ "js_props": js_props,
+ "text_max_len": FORM_SHORT_TEXT_MAX_LEN,
+ "tag_type": "project_output_attachment",
+ }
+
+ template: types.django_html = """
+
+ {% if dependency.output.completed %}
+ {% if dependency.output.description %}
+ {{ dependency.output.description }}
+ {% else %}
+
+ {{ OUTPUT_DESCRIPTION_PLACEHOLDER }}
+
+ {% endif %}
+ {% else %}
+
+ {% component "Icon"
+ name="exclamation-triangle"
+ variant="outline"
+ size=24
+ stroke_width=2
+ color="text-gray-500"
+ attrs:class="float-left pr-1"
+ / %}
+
+ Missing '{{ dependency.output.name }}' from
+
+ {% component "Button"
+ variant="plain"
+ href=phase_url
+ attrs:target="_blank"
+ attrs:class="hover:text-gray-600 !underline"
+ %}
+ {{ dependency.output.phase.phase_template.type|title }}
+ {% endcomponent %}
+
+ {% endif %}
+
+
+ {# Attachments of parent dependencies #}
+ {% component "ProjectOutputAttachments"
+ editable=False
+ has_attachments=dependency.attachments
+ js_props:attachments="attachments.value"
+ / %}
+
+
+ """
+
+ js: types.js = """
+ const ProjectOutputAttachments = AlpineComposition.defineComponent({
+ name: "project_output_attachments",
+
+ props: {
+ attachments: { type: Object, required: true },
+ },
+
+ emits: {
+ updateAttachmentData: (index, data) => true,
+ setAttachmentTags: (index, tags) => true,
+ removeAttachment: (index) => true,
+ toggleAttachment: (index) => true,
+ },
+
+ setup(props, vm, { toRefs, watch }) {
+ const { attachments } = toRefs(props);
+
+ return {
+ attachments,
+ };
+ },
+ });
+
+ document.addEventListener("alpine:init", () => {
+ AlpineComposition.registerComponent(Alpine, ProjectOutputAttachments);
+ });
+ """
+
+
+#####################################
+# PROJECT_OUTPUT_FORM
+#####################################
+
+OUTPUT_DESCRIPTION_PLACEHOLDER = "Placeholder text"
+
+
+class RenderedAttachment(NamedTuple):
+ url: str
+ text: str
+ tags: List[str]
+
+
+class RenderedOutputDep(NamedTuple):
+ dependency: OutputWithAttachments
+ phase_url: str
+ attachments: List[dict]
+
+
+class RenderedProjectOutput(NamedTuple):
+ output: ProjectOutput
+ dependencies: List[RenderedOutputDep]
+ has_missing_deps: bool
+ output_data: dict
+ attachments: List[RenderedAttachment]
+ update_output_url: str
+
+
+@register("ProjectOutputForm")
+class ProjectOutputForm(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ data: RenderedProjectOutput,
+ editable: bool,
+ ):
+ return {
+ "data": data,
+ "editable": editable,
+ "alpine_attachments": [d._asdict() for d in data.attachments],
+ "OUTPUT_DESCRIPTION_PLACEHOLDER": OUTPUT_DESCRIPTION_PLACEHOLDER,
+ }
+
+ template: types.django_html = """
+
+ {% if not has_attachments and editable %}
+ This output does not have any attachments, create one below:
+ {% elif not has_attachments and not editable %}
+ This output does not have any attachments.
+ {% elif has_attachments and not editable %}
+ Attachments:
+ {% else %} {# NOTE: Else branch required by django-shouty #}
+ {% endif %}
+
+
+
+
+
+
+ {% component "Form"
+ submit_href=data.update_output_url
+ actions_hide=True
+ %}
+ {# Output description - editable #}
+ {% if editable %}
+
+ {% else %}
+ {# Output description - readonly #}
+
+ """ # noqa: E501
+
+ js: types.js = """
+ // Define component similarly to defining Vue components
+ const ProjectOutputForm = AlpineComposition.defineComponent({
+ name: 'project_output_form',
+
+ props: {
+ initAttachments: { type: String, required: true },
+ },
+
+ // Instead of Alpine's init(), use setup()
+ // Props are passed down as reactive props, same as in Vue
+ // Second argument is the Alpine component instance.
+ setup(props, vm, { ref, nextTick, watch }) {
+ const attachments = ref([]);
+
+ // Set the initial state
+ if (props.initAttachments) {
+ attachments.value = JSON.parse(props.initAttachments).map(({ url, text, tags }) => ({
+ url,
+ text,
+ isPreview: true,
+ tags,
+ }));
+ }
+
+ watch(attachments, () => {
+ onAttachmentsChange();
+ }, { immediate: true });
+
+ // Methods
+ const addAttachment = () => {
+ attachments.value = [...attachments.value, { url: "", text: "", tags: [], isPreview: false }];
+ };
+
+ const removeAttachment = (index) => {
+ attachments.value = attachments.value.filter((_, i) => i !== index);
+
+ // NOTE: For unknown reason, AlpineJS removes the attachment from for-loop
+ // only on second click. So we do so ourselves
+ const attachmentEls = [...vm.$el.querySelectorAll('.project-output-form-attachment')];
+ if (attachmentEls.length > attachments.value.length) {
+ attachmentEls[index].remove();
+ }
+
+ // Send the request to remove the attachment in the server too, but
+ // don't yet reload the page in case user is editing other attachments.
+ onOutputSubmit({ reload: false });
+ };
+
+ const setAttachmentTags = (index, tags) => {
+ attachments.value = attachments.value.map((attach, currIndex) => {
+ if (index !== currIndex) return attach;
+
+ return { ...attach, tags };
+ });
+ };
+
+ const updateAttachmentData = (index, data) => {
+ attachments.value = attachments.value.map((attach, currIndex) => {
+ if (index !== currIndex) return attach;
+
+ return { ...attach, ...data };
+ });
+ };
+
+ const toggleAttachmentPreview = (index) => {
+ let didCloseEditing = false;
+
+ attachments.value = attachments.value.map((attach, i) => {
+ if (index === i) {
+ attach.isPreview = !attach.isPreview;
+
+ if (attach.isPreview) didCloseEditing = true;
+ }
+ return attach;
+ });
+
+ if (didCloseEditing) onOutputSubmit({ reload: false });
+ };
+
+ // When attachments are added or removed, we add/remove HTML by AlpineJS,
+ // so user doesn't have to refresh the page.
+ function onAttachmentsChange() {
+ // We wait until the HTML is updated...
+ nextTick(() => {
+ // ...Then populate the generated HTML
+ const attachmentEls = [...vm.$el.querySelectorAll('.project-output-form-attachment')];
+ attachmentEls.forEach((attachEl, index) => {
+ if (index >= attachments.value.length) return;
+
+ const attachment = attachments.value[index];
+ attachEl.querySelector('input[name="url"]').value = attachment.url;
+ attachEl.querySelector('input[name="text"]').value = attachment.text;
+ });
+ });
+ }
+
+ const onOutputSubmit = ({ reload }) => {
+ /** @type {HTMLFormElement} */
+ const formEl = vm.$el.querySelector('form');
+ const formData = Object.fromEntries(new FormData(formEl));
+ const data = {
+ description: formData.description,
+ completed: formData.completed.toLowerCase() === "on",
+ attachments: attachments.value.map(({ text, url, tags }) => ({ text, url, tags })),
+ };
+
+ axios.post(formEl.action, data, {
+ method: formEl.method,
+ })
+ .then((response) => {
+ if (reload) location.reload();
+ })
+ .catch((error) => {
+ console.error(error);
+ });
+ };
+
+ return {
+ attachments,
+ addAttachment,
+ removeAttachment,
+ setAttachmentTags,
+ updateAttachmentData,
+ toggleAttachmentPreview,
+ onOutputSubmit,
+ };
+ },
+ });
+
+ document.addEventListener('alpine:init', () => {
+ AlpineComposition.registerComponent(Alpine, ProjectOutputForm);
+ });
+ """
+
+
+#####################################
+#
+# IMPLEMENTATION END
+#
+#####################################
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- TESTS START ------------ #
+# The code above is used also used when benchmarking.
+# The section below is NOT included.
+
+from django_components.testing import djc_test # noqa: E402
+
+@djc_test
+def test_render(snapshot):
+ registry.register("Button", Button)
+ registry.register("Menu", Menu)
+ registry.register("MenuList", MenuList)
+ registry.register("Table", Table)
+ registry.register("Icon", Icon)
+ registry.register("heroicons", HeroIcon)
+ registry.register("ExpansionPanel", ExpansionPanel)
+ registry.register("ProjectPage", ProjectPage)
+ registry.register("ProjectLayoutTabbed", ProjectLayoutTabbed)
+ registry.register("Layout", Layout)
+ registry.register("RenderContextProvider", RenderContextProvider)
+ registry.register("Base", Base)
+ registry.register("Sidebar", Sidebar)
+ registry.register("Navbar", Navbar)
+ registry.register("Dialog", Dialog)
+ registry.register("Tags", Tags)
+ registry.register("Form", Form)
+ registry.register("Breadcrumbs", Breadcrumbs)
+ registry.register("Bookmarks", Bookmarks)
+ registry.register("Bookmark", Bookmark)
+ registry.register("List", ListComponent)
+ registry.register("_tabs", _TabsImpl)
+ registry.register("Tabs", Tabs)
+ registry.register("TabItem", TabItem)
+ registry.register("TabsStatic", TabsStatic)
+ registry.register("ProjectInfo", ProjectInfo)
+ registry.register("ProjectNotes", ProjectNotes)
+ registry.register("ProjectOutputsSummary", ProjectOutputsSummary)
+ registry.register("ProjectStatusUpdates", ProjectStatusUpdates)
+ registry.register("ProjectUsers", ProjectUsers)
+ registry.register("ProjectUserAction", ProjectUserAction)
+ registry.register("ProjectOutputs", ProjectOutputs)
+ registry.register("ProjectOutputBadge", ProjectOutputBadge)
+ registry.register("ProjectOutputDependency", ProjectOutputDependency)
+ registry.register("ProjectOutputAttachments", ProjectOutputAttachments)
+ registry.register("ProjectOutputForm", ProjectOutputForm)
+
+ data = gen_render_data()
+ rendered = render(data)
+ assert rendered == snapshot
diff --git a/tests/test_benchmark_djc_small.py b/tests/test_benchmark_djc_small.py
new file mode 100644
index 00000000..5c96b3bc
--- /dev/null
+++ b/tests/test_benchmark_djc_small.py
@@ -0,0 +1,343 @@
+# NOTE: This file is used for benchmarking. Before editing this file,
+# please read through these:
+# - `benchmarks/README`
+# - https://github.com/django-components/django-components/pull/999
+
+from pathlib import Path
+from typing import Dict, Literal, NamedTuple, Optional, Union
+
+import django
+from django.conf import settings
+from django.template import Context, Template
+
+from django_components import Component, types
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- IMPORTS END ------------ #
+
+# This variable is overridden by the benchmark runner
+CONTEXT_MODE: Literal["django", "isolated"] = "isolated"
+
+if not settings.configured:
+ settings.configure(
+ BASE_DIR=Path(__file__).resolve().parent,
+ INSTALLED_APPS=["django_components"],
+ TEMPLATES=[
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [
+ "tests/templates/",
+ "tests/components/", # Required for template relative imports in tests
+ ],
+ "OPTIONS": {
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ]
+ },
+ }
+ ],
+ COMPONENTS={
+ "autodiscover": False,
+ "context_behavior": CONTEXT_MODE,
+ },
+ MIDDLEWARE=[],
+ DATABASES={
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": ":memory:",
+ }
+ },
+ SECRET_KEY="secret",
+ ROOT_URLCONF="django_components.urls",
+ )
+
+ django.setup()
+else:
+ settings.COMPONENTS["context_behavior"] = CONTEXT_MODE
+
+#####################################
+#
+# IMPLEMENTATION START
+#
+#####################################
+
+templates_cache: Dict[int, Template] = {}
+
+
+def lazy_load_template(template: str) -> Template:
+ template_hash = hash(template)
+ if template_hash in templates_cache:
+ return templates_cache[template_hash]
+ else:
+ template_instance = Template(template)
+ templates_cache[template_hash] = template_instance
+ return template_instance
+
+
+#####################################
+# RENDER ENTRYPOINT
+#####################################
+
+
+def gen_render_data():
+ data = {
+ "href": "https://example.com",
+ "disabled": False,
+ "variant": "primary",
+ "type": "button",
+ "attrs": {
+ "class": "py-2 px-4",
+ },
+ }
+ return data
+
+
+def render(data: Dict):
+ # Render
+ result = Button.render(
+ context=Context(),
+ kwargs=data,
+ slots={
+ "content": "Click me!",
+ },
+ )
+ return result
+
+
+#####################################
+# THEME
+#####################################
+
+ThemeColor = Literal["default", "error", "success", "alert", "info"]
+ThemeVariant = Literal["primary", "secondary"]
+
+VARIANTS = ["primary", "secondary"]
+
+
+class ThemeStylingUnit(NamedTuple):
+ """
+ Smallest unit of info, this class defines a specific styling of a specific
+ component in a specific state.
+
+ E.g. styling of a disabled "Error" button.
+ """
+
+ color: str
+ """CSS class(es) specifying color"""
+ css: str = ""
+ """Other CSS classes not specific to color"""
+
+
+class ThemeStylingVariant(NamedTuple):
+ """
+ Collection of styling combinations that are meaningful as a group.
+
+ E.g. all "error" variants - primary, disabled, secondary, ...
+ """
+
+ primary: ThemeStylingUnit
+ primary_disabled: ThemeStylingUnit
+ secondary: ThemeStylingUnit
+ secondary_disabled: ThemeStylingUnit
+
+
+class Theme(NamedTuple):
+ """Class for defining a styling and color theme for the app."""
+
+ default: ThemeStylingVariant
+ error: ThemeStylingVariant
+ alert: ThemeStylingVariant
+ success: ThemeStylingVariant
+ info: ThemeStylingVariant
+
+
+_secondary_btn_styling = "ring-1 ring-inset"
+
+theme = Theme(
+ default=ThemeStylingVariant(
+ primary=ThemeStylingUnit(
+ color="bg-blue-600 text-white hover:bg-blue-500 focus-visible:outline-blue-600 transition"
+ ),
+ primary_disabled=ThemeStylingUnit(color="bg-blue-300 text-blue-50 focus-visible:outline-blue-600 transition"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-gray-800 ring-gray-300 hover:bg-gray-100 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-gray-300 ring-gray-300 focus-visible:outline-gray-600 transition",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ error=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-red-600 text-white hover:bg-red-500 focus-visible:outline-red-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-red-300 text-white focus-visible:outline-red-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-red-600 ring-red-300 hover:bg-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-red-200 ring-red-100 focus-visible:outline-red-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ alert=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-amber-500 text-white hover:bg-amber-400 focus-visible:outline-amber-500"),
+ primary_disabled=ThemeStylingUnit(color="bg-amber-100 text-orange-300 focus-visible:outline-amber-500"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-amber-500 ring-amber-300 hover:bg-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-orange-200 ring-amber-100 focus-visible:outline-amber-500",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ success=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-green-600 text-white hover:bg-green-500 focus-visible:outline-green-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-green-300 text-white focus-visible:outline-green-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-green-600 ring-green-300 hover:bg-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-green-200 ring-green-100 focus-visible:outline-green-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+ info=ThemeStylingVariant(
+ primary=ThemeStylingUnit(color="bg-sky-600 text-white hover:bg-sky-500 focus-visible:outline-sky-600"),
+ primary_disabled=ThemeStylingUnit(color="bg-sky-300 text-white focus-visible:outline-sky-600"),
+ secondary=ThemeStylingUnit(
+ color="bg-white text-sky-600 ring-sky-300 hover:bg-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ secondary_disabled=ThemeStylingUnit(
+ color="bg-white text-sky-200 ring-sky-100 focus-visible:outline-sky-600",
+ css=_secondary_btn_styling,
+ ),
+ ),
+)
+
+
+def get_styling_css(
+ variant: Optional["ThemeVariant"] = None,
+ color: Optional["ThemeColor"] = None,
+ disabled: Optional[bool] = None,
+):
+ """
+ Dynamically access CSS styling classes for a specific variant and state.
+
+ E.g. following two calls get styling classes for:
+ 1. Secondary error state
+ 1. Secondary alert disabled state
+ 2. Primary default disabled state
+ ```py
+ get_styling_css('secondary', 'error')
+ get_styling_css('secondary', 'alert', disabled=True)
+ get_styling_css(disabled=True)
+ ```
+ """
+ variant = variant or "primary"
+ color = color or "default"
+ disabled = disabled if disabled is not None else False
+
+ color_variants: ThemeStylingVariant = getattr(theme, color)
+
+ if variant not in VARIANTS:
+ raise ValueError(f'Unknown theme variant "{variant}", must be one of {VARIANTS}')
+
+ variant_name = variant if not disabled else f"{variant}_disabled"
+ styling: ThemeStylingUnit = getattr(color_variants, variant_name)
+
+ css = f"{styling.color} {styling.css}".strip()
+ return css
+
+
+#####################################
+# BUTTON
+#####################################
+
+
+class Button(Component):
+ def get_context_data(
+ self,
+ /,
+ *,
+ href: Optional[str] = None,
+ link: Optional[bool] = None,
+ disabled: Optional[bool] = False,
+ variant: Union["ThemeVariant", Literal["plain"]] = "primary",
+ color: Union["ThemeColor", str] = "default",
+ type: Optional[str] = "button",
+ attrs: Optional[dict] = None,
+ ):
+ common_css = (
+ "inline-flex w-full text-sm font-semibold"
+ " sm:mt-0 sm:w-auto focus-visible:outline-2 focus-visible:outline-offset-2"
+ )
+ if variant == "plain":
+ all_css_class = common_css
+ else:
+ button_classes = get_styling_css(variant, color, disabled) # type: ignore[arg-type]
+ all_css_class = f"{button_classes} {common_css} px-3 py-2 justify-center rounded-md shadow-sm"
+
+ is_link = not disabled and (href or link)
+
+ all_attrs = {**(attrs or {})}
+ if disabled:
+ all_attrs["aria-disabled"] = "true"
+
+ return {
+ "href": href,
+ "disabled": disabled,
+ "type": type,
+ "btn_class": all_css_class,
+ "attrs": all_attrs,
+ "is_link": is_link,
+ }
+
+ template: types.django_html = """
+ {# Based on buttons from https://tailwindui.com/components/application-ui/overlays/modals #}
+
+ {% if is_link %}
+
+ {% else %}
+
+ {% else %}
+
+ {% endif %}
+ """
+
+
+#####################################
+#
+# IMPLEMENTATION END
+#
+#####################################
+
+
+# DO NOT REMOVE - See https://github.com/django-components/django-components/pull/999
+# ----------- TESTS START ------------ #
+# The code above is used also used when benchmarking.
+# The section below is NOT included.
+
+from django_components.testing import djc_test # noqa: E402
+
+@djc_test
+def test_render(snapshot):
+ data = gen_render_data()
+ rendered = render(data)
+ assert rendered == snapshot
diff --git a/tests/test_cache.py b/tests/test_cache.py
new file mode 100644
index 00000000..58630a93
--- /dev/null
+++ b/tests/test_cache.py
@@ -0,0 +1,141 @@
+from django_components import Component, register
+from django_components.testing import djc_test
+from django_components.util.cache import LRUCache
+
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestCache:
+ def test_cache(self):
+ cache = LRUCache[int](maxsize=3)
+
+ cache.set("a", 1)
+ cache.set("b", 2)
+ cache.set("c", 3)
+
+ assert cache.get("a") == 1
+ assert cache.get("b") == 2
+ assert cache.get("c") == 3
+
+ cache.set("d", 4)
+
+ assert cache.get("a") is None
+ assert cache.get("b") == 2
+ assert cache.get("c") == 3
+ assert cache.get("d") == 4
+
+ cache.set("e", 5)
+ cache.set("f", 6)
+
+ assert cache.get("b") is None
+ assert cache.get("c") is None
+ assert cache.get("d") == 4
+ assert cache.get("e") == 5
+ assert cache.get("f") == 6
+
+ cache.clear()
+
+ assert cache.get("d") is None
+ assert cache.get("e") is None
+ assert cache.get("f") is None
+
+ def test_cache_maxsize_zero(self):
+ cache = LRUCache[int](maxsize=0)
+
+ cache.set("a", 1)
+ assert cache.get("a") is None
+
+ cache.set("b", 2)
+ cache.set("c", 3)
+ assert cache.get("b") is None
+ assert cache.get("c") is None
+
+ # Same with negative numbers
+ cache = LRUCache[int](maxsize=-1)
+ cache.set("a", 1)
+ assert cache.get("a") is None
+
+ cache.set("b", 2)
+ cache.set("c", 3)
+ assert cache.get("b") is None
+ assert cache.get("c") is None
+
+
+@djc_test
+class TestComponentMediaCache:
+ @djc_test(
+ components_settings={"cache": "test-cache"},
+ django_settings={
+ "CACHES": {
+ # See https://docs.djangoproject.com/en/5.2/topics/cache/#local-memory-caching
+ "test-cache": {
+ "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+ "LOCATION": "test-cache",
+ "TIMEOUT": None, # No timeout
+ "OPTIONS": {
+ "MAX_ENTRIES": 10_000,
+ },
+ },
+ },
+ },
+ )
+ def test_component_media_caching(self):
+ from django.core.cache import caches
+
+ test_cache = caches["test-cache"]
+
+ @register("test_simple")
+ class TestSimpleComponent(Component):
+ template = """
+
+ {% if data.output.description %}
+ {{ data.output.description }}
+ {% else %}
+ {{ OUTPUT_DESCRIPTION_PLACEHOLDER }}
+ {% endif %}
+
+ {% endif %}
+
+
+
+
+ {% component "ProjectOutputAttachments"
+ has_attachments=data.attachments
+ editable=editable
+ js_props:attachments="attachments.value"
+ js_props:onToggleAttachment="(index) => toggleAttachmentPreview(index)"
+ js_props:onSetAttachmentTags="(index, tags) => setAttachmentTags(index, tags)"
+ js_props:onUpdateAttachmentData="(index, data) => updateAttachmentData(index, data)"
+ js_props:onRemoveAttachment="(index) => removeAttachment(index)"
+ / %}
+ {% endcomponent %}
+
+ Completed:
+
+ {# NOTE: See https://stackoverflow.com/a/1992745/9788634 #}
+
+
+
+
+ {% if editable %}
+ {% component "Button"
+ variant="secondary"
+ attrs:@click="addAttachment"
+ %}
+ Add attachment
+ {% endcomponent %}
+
+ {% component "Button"
+ attrs:@click="onOutputSubmit({ reload: true })"
+ %}
+ Save
+ {% endcomponent %}
+ {% endif %}
+
+ Template only component
+ """
+
+ @register("test_media_no_vars")
+ class TestMediaNoVarsComponent(Component):
+ template = """
+ Template and JS component
+ {% component "test_simple" / %}
+ """
+ js = "console.log('Hello from JS');"
+ css = ".novars-component { color: blue; }"
+
+ class TestMediaAndVarsComponent(Component):
+ template = """
+ Full component
+ {% component "test_media_no_vars" / %}
+ """
+ js = "console.log('Hello from full component');"
+ css = ".full-component { color: blue; }"
+
+ def get_js_data(self, args, kwargs, slots, context):
+ return {"message": "Hello"}
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return {"color": "blue"}
+
+ # Check that JS/CSS is cached for components that have them
+ assert test_cache.has_key(f"__components:{TestMediaAndVarsComponent.class_id}:js")
+ assert test_cache.has_key(f"__components:{TestMediaAndVarsComponent.class_id}:css")
+ assert test_cache.has_key(f"__components:{TestMediaNoVarsComponent.class_id}:js")
+ assert test_cache.has_key(f"__components:{TestMediaNoVarsComponent.class_id}:css")
+ assert not test_cache.has_key(f"__components:{TestSimpleComponent.class_id}:js")
+ assert not test_cache.has_key(f"__components:{TestSimpleComponent.class_id}:css")
+
+ # Check that we cache `Component.js` / `Component.css`
+ assert test_cache.get(f"__components:{TestMediaNoVarsComponent.class_id}:js").strip() == "console.log('Hello from JS');" # noqa: E501
+ assert test_cache.get(f"__components:{TestMediaNoVarsComponent.class_id}:css").strip() == ".novars-component { color: blue; }" # noqa: E501
+
+ # Render the components to trigger caching of JS/CSS variables from `get_js_data` / `get_css_data`
+ TestMediaAndVarsComponent.render()
+
+ # Check that we cache JS / CSS scripts generated from `get_js_data` / `get_css_data`
+ # NOTE: The hashes is generated from the data.
+ js_vars_hash = "216ecc"
+ css_vars_hash = "d039a3"
+
+ # TODO - Update once JS and CSS vars are enabled
+ assert test_cache.get(f"__components:{TestMediaAndVarsComponent.class_id}:js:{js_vars_hash}").strip() == ""
+ assert test_cache.get(f"__components:{TestMediaAndVarsComponent.class_id}:css:{css_vars_hash}").strip() == "" # noqa: E501
diff --git a/tests/test_command_components.py b/tests/test_command_components.py
new file mode 100644
index 00000000..b47bf7e8
--- /dev/null
+++ b/tests/test_command_components.py
@@ -0,0 +1,66 @@
+from io import StringIO
+from unittest.mock import patch
+
+from django.core.management import call_command
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestComponentCommand:
+ def test_root_command(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components")
+ output = out.getvalue()
+
+ # NOTE: The full output is different in CI and locally, because of different whitespace wrapping
+ # (probably due to different terminal widths). So we check only for parts of the output.
+ #
+ # The full expected output is:
+ # ```
+ # usage: components [-h] [--version] [-v {{0,1,2,3}}] [--settings SETTINGS] [--pythonpath PYTHONPATH]
+ # [--traceback] [--no-color] [--force-color] [--skip-checks]
+ # {{create,upgrade,ext}} ...
+ #
+ # The entrypoint for the 'components' commands.
+ #
+ # optional arguments:
+ # -h, --help show this help message and exit
+ # --version Show program's version number and exit.
+ # -v {{0,1,2,3}}, --verbosity {{0,1,2,3}}
+ # Verbosity level; 0=minimal output, 1=normal output, 2=verbose output,
+ # 3=very verbose output
+ # --settings SETTINGS The Python path to a settings module, e.g. "myproject.settings.main". If this
+ # isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
+ # --pythonpath PYTHONPATH
+ # A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
+ # --traceback Raise on CommandError exceptions.
+ # --no-color Don't colorize the command output.
+ # --force-color Force colorization of the command output.
+ # --skip-checks Skip system checks.
+ #
+ # subcommands:
+ # {{create,upgrade,ext}}
+ # create Create a new django component.
+ # upgrade Upgrade django components syntax from '{{% component_block ... %}}' to
+ # '{{% component ... %}}'.
+ # ext Run extension commands.
+ # ```
+
+ assert "usage: components" in output
+ assert "The entrypoint for the 'components' commands." in output
+ assert "-h, --help show this help message and exit" in output
+ assert "--version Show program's version number and exit." in output
+ assert "-v {0,1,2,3}" in output
+ assert "--settings SETTINGS The Python path to a settings module" in output
+ assert "--pythonpath PYTHONPATH" in output
+ assert "--traceback Raise on CommandError exceptions." in output
+ assert "--no-color Don't colorize the command output." in output
+ assert "--force-color Force colorization of the command output." in output
+ assert "--skip-checks Skip system checks." in output
+ assert "create Create a new django component." in output
+ assert "upgrade Upgrade django components syntax" in output
+ assert "ext Run extension commands." in output
diff --git a/tests/test_command_create.py b/tests/test_command_create.py
new file mode 100644
index 00000000..761861f1
--- /dev/null
+++ b/tests/test_command_create.py
@@ -0,0 +1,153 @@
+import os
+import tempfile
+from io import StringIO
+from shutil import rmtree
+from unittest.mock import patch
+
+import pytest
+from django.core.management import call_command
+from django.core.management.base import CommandError
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestCreateComponentCommand:
+ def test_default_file_names(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "defaultcomponent"
+ call_command("components", "create", component_name, "--path", temp_dir)
+
+ expected_files = [
+ os.path.join(temp_dir, component_name, "script.js"),
+ os.path.join(temp_dir, component_name, "style.css"),
+ os.path.join(temp_dir, component_name, "template.html"),
+ ]
+ for file_path in expected_files:
+ assert os.path.exists(file_path)
+
+ rmtree(temp_dir)
+
+ def test_nondefault_creation(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "testcomponent"
+ call_command(
+ "components",
+ "create",
+ component_name,
+ "--path",
+ temp_dir,
+ "--js",
+ "test.js",
+ "--css",
+ "test.css",
+ "--template",
+ "test.html",
+ )
+
+ expected_files = [
+ os.path.join(temp_dir, component_name, "test.js"),
+ os.path.join(temp_dir, component_name, "test.css"),
+ os.path.join(temp_dir, component_name, "test.html"),
+ os.path.join(temp_dir, component_name, f"{component_name}.py"),
+ ]
+
+ for file_path in expected_files:
+ assert os.path.exists(file_path), f"File {file_path} was not created"
+
+ rmtree(temp_dir)
+
+ def test_dry_run(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "dryruncomponent"
+ call_command(
+ "components",
+ "create",
+ component_name,
+ "--path",
+ temp_dir,
+ "--dry-run",
+ )
+
+ component_path = os.path.join(temp_dir, component_name)
+ assert not os.path.exists(component_path)
+
+ rmtree(temp_dir)
+
+ def test_force_overwrite(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "existingcomponent"
+ component_path = os.path.join(temp_dir, component_name)
+ os.makedirs(component_path)
+
+ with open(os.path.join(component_path, f"{component_name}.py"), "w") as f:
+ f.write("hello world")
+
+ call_command(
+ "components",
+ "create",
+ component_name,
+ "--path",
+ temp_dir,
+ "--force",
+ )
+
+ with open(os.path.join(component_path, f"{component_name}.py"), "r") as f:
+ assert "hello world" not in f.read()
+
+ rmtree(temp_dir)
+
+ def test_error_existing_component_no_force(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "existingcomponent_2"
+ component_path = os.path.join(temp_dir, component_name)
+ os.makedirs(component_path)
+
+ with pytest.raises(CommandError):
+ call_command("components", "create", component_name, "--path", temp_dir)
+
+ rmtree(temp_dir)
+
+ def test_verbose_output(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "verbosecomponent"
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command(
+ "components",
+ "create",
+ component_name,
+ "--path",
+ temp_dir,
+ "--verbose",
+ stdout=out,
+ )
+ output = out.getvalue()
+ assert "component at" in output
+
+ rmtree(temp_dir)
+
+ # TODO_V1 - REMOVE - deprecated
+ def test_startcomponent(self):
+ temp_dir = tempfile.mkdtemp()
+
+ component_name = "defaultcomponent"
+ call_command("startcomponent", component_name, "--path", temp_dir)
+
+ expected_files = [
+ os.path.join(temp_dir, component_name, "script.js"),
+ os.path.join(temp_dir, component_name, "style.css"),
+ os.path.join(temp_dir, component_name, "template.html"),
+ ]
+ for file_path in expected_files:
+ assert os.path.exists(file_path)
+
+ rmtree(temp_dir)
diff --git a/tests/test_command_ext.py b/tests/test_command_ext.py
new file mode 100644
index 00000000..c43dc54a
--- /dev/null
+++ b/tests/test_command_ext.py
@@ -0,0 +1,312 @@
+import re
+import sys
+from io import StringIO
+from textwrap import dedent
+from unittest.mock import patch
+
+from django.core.management import call_command
+from django_components import CommandArg, CommandArgGroup, ComponentCommand, ComponentExtension
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+# NOTE: Argparse changed how the optional args are displayed in Python 3.11+
+if sys.version_info >= (3, 10):
+ OPTIONS_TITLE = "options"
+else:
+ OPTIONS_TITLE = "optional arguments"
+
+
+class EmptyExtension(ComponentExtension):
+ name = "empty"
+
+
+class DummyCommand(ComponentCommand):
+ name = "dummy_cmd"
+ help = "Dummy command description."
+
+ arguments = [
+ CommandArg(
+ name_or_flags="--foo",
+ help="Foo description.",
+ ),
+ 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, *args, **kwargs):
+ kwargs.pop("_command")
+ kwargs.pop("_parser")
+ sorted_kwargs = dict(sorted(kwargs.items()))
+ print(f"DummyCommand.handle: args={args}, kwargs={sorted_kwargs}")
+
+
+class DummyExtension(ComponentExtension):
+ name = "dummy"
+
+ commands = [
+ DummyCommand,
+ ]
+
+
+@djc_test
+class TestExtensionsCommand:
+ def test_root_command(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext")
+ output = out.getvalue()
+
+ assert (
+ output
+ == dedent(
+ f"""
+ usage: components ext [-h] {{list,run}} ...
+
+ Run extension commands.
+
+ {OPTIONS_TITLE}:
+ -h, --help show this help message and exit
+
+ subcommands:
+ {{list,run}}
+ list List all extensions.
+ run Run a command added by an extension.
+ """
+ ).lstrip()
+ )
+
+
+@djc_test
+class TestExtensionsListCommand:
+ def test_list_default_extensions(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "list")
+ output = out.getvalue()
+
+ assert output.strip() == (
+ "name \n"
+ "===============\n"
+ "cache \n"
+ "defaults \n"
+ "dependencies \n"
+ "view \n"
+ "debug_highlight"
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_list_extra_extensions(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "list")
+ output = out.getvalue()
+
+ assert output.strip() == (
+ "name \n"
+ "===============\n"
+ "cache \n"
+ "defaults \n"
+ "dependencies \n"
+ "view \n"
+ "debug_highlight\n"
+ "empty \n"
+ "dummy"
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_list_all(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "list", "--all")
+ output = out.getvalue()
+
+ assert output.strip() == (
+ "name \n"
+ "===============\n"
+ "cache \n"
+ "defaults \n"
+ "dependencies \n"
+ "view \n"
+ "debug_highlight\n"
+ "empty \n"
+ "dummy"
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_list_specific_columns(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "list", "--columns", "name")
+ output = out.getvalue()
+
+ assert output.strip() == (
+ "name \n"
+ "===============\n"
+ "cache \n"
+ "defaults \n"
+ "dependencies \n"
+ "view \n"
+ "debug_highlight\n"
+ "empty \n"
+ "dummy"
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_list_simple(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "list", "--simple")
+ output = out.getvalue()
+
+ assert output.strip() == (
+ "cache \n"
+ "defaults \n"
+ "dependencies \n"
+ "view \n"
+ "debug_highlight\n"
+ "empty \n"
+ "dummy"
+ )
+
+
+@djc_test
+class TestExtensionsRunCommand:
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_run_command_root(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "run")
+ output = out.getvalue()
+
+ # Fix line breaking in CI on the first line between the `[-h]` and `{{cmd_name}}`
+ output = re.compile(r"\]\s+\{").sub("] {", output)
+ # Fix line breaking in CI on the first line between the `{{cmd_name}}` and `...`
+ output = re.compile(r"\}\s+\.\.\.").sub("} ...", output)
+
+ assert (
+ output
+ == dedent(
+ f"""
+ usage: components ext run [-h] {{dummy}} ...
+
+ Run a command added by an extension.
+
+ {OPTIONS_TITLE}:
+ -h, --help show this help message and exit
+
+ subcommands:
+ {{dummy}}
+ dummy Run commands added by the 'dummy' extension.
+ """
+ ).lstrip()
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_run_command_ext_empty(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "run", "dummy")
+ output = out.getvalue()
+
+ assert (
+ output
+ == dedent(
+ f"""
+ usage: components ext run dummy [-h] {{dummy_cmd}} ...
+
+ Run commands added by the 'dummy' extension.
+
+ {OPTIONS_TITLE}:
+ -h, --help show this help message and exit
+
+ subcommands:
+ {{dummy_cmd}}
+ dummy_cmd Dummy command description.
+ """
+ ).lstrip()
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_run_command_ext_with_commands(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "run", "dummy")
+ output = out.getvalue()
+
+ assert (
+ output
+ == dedent(
+ f"""
+ usage: components ext run dummy [-h] {{dummy_cmd}} ...
+
+ Run commands added by the 'dummy' extension.
+
+ {OPTIONS_TITLE}:
+ -h, --help show this help message and exit
+
+ subcommands:
+ {{dummy_cmd}}
+ dummy_cmd Dummy command description.
+ """
+ ).lstrip()
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_run_command_ext_command(self):
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "ext", "run", "dummy", "dummy_cmd")
+ output = out.getvalue()
+
+ # NOTE: The dummy command prints out the kwargs, which is what we check for here
+ assert (
+ output
+ == dedent(
+ """
+ DummyCommand.handle: args=(), kwargs={'bar': None, 'baz': None, 'foo': None, 'force_color': False, 'no_color': False, 'pythonpath': None, 'settings': None, 'skip_checks': True, 'traceback': False, 'verbosity': 1}
+ """ # noqa: E501
+ ).lstrip()
+ )
+
+ @djc_test(
+ components_settings={"extensions": [EmptyExtension, DummyExtension]},
+ )
+ def test_prints_error_if_command_not_found(self):
+ out = StringIO()
+ with patch("sys.stderr", new=out):
+ try:
+ call_command("components", "ext", "run", "dummy", "dummy_cmd_not_found")
+ except SystemExit:
+ output = out.getvalue()
+
+ assert "invalid choice: 'dummy_cmd_not_found'" in output
diff --git a/tests/test_command_list.py b/tests/test_command_list.py
new file mode 100644
index 00000000..2d3531bd
--- /dev/null
+++ b/tests/test_command_list.py
@@ -0,0 +1,190 @@
+import re
+from io import StringIO
+from unittest.mock import patch
+
+from django.core.management import call_command
+
+from django_components import Component
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# Either back or forward slash
+SLASH = r"[\\/]"
+
+
+@djc_test
+class TestComponentListCommand:
+ def test_list_default(self):
+ class TestComponent(Component):
+ template = ""
+
+ out = StringIO()
+ with patch("sys.stdout", new=out):
+ call_command("components", "list")
+ output = out.getvalue()
+
+ # NOTE: When we run all tests, the output is different, as other test files define components
+ # outside of the `@djc_test` decorator, and thus they leak into the output. Since this affects also
+ # the formatting (how much whitespace there is), regex is used to check for the headers and the expected
+ # components.
+ #
+ # The output should look like this:
+ #
+ # full_name path
+ # ======================================================================================================================================
+ # django_components.components.dynamic.DynamicComponent src/django_components/components/dynamic.py
+ # tests.test_command_list.TestComponentListCommand.test_list_default.
-
- Parent content
- {% component name="variable_display" shadowing_variable='override' new_variable='unique_val' %} - {% endcomponent %} -
- {% slot 'content' %}
-
- """ # noqa
+# Client for testing endpoints via requests
+class CustomClient(Client):
+ def __init__(self, urlpatterns=None, *args, **kwargs):
+ import types
- def get_context_data(self):
- return {"shadowing_variable": "NOT SHADOWED"}
+ if urlpatterns:
+ urls_module = types.ModuleType("urls")
+ urls_module.urlpatterns = urlpatterns + dc_urlpatterns # type: ignore
+ settings.ROOT_URLCONF = urls_module
+ else:
+ settings.ROOT_URLCONF = __name__
+ settings.SECRET_KEY = "secret" # noqa
+ super().__init__(*args, **kwargs)
- class VariableDisplay(Component):
- template: types.django_html = """
- {% load component_tags %}
- Slot content
- {% component name="variable_display" shadowing_variable='slot_default_override' new_variable='slot_default_unique' %} - {% endcomponent %} - {% endslot %} -Shadowing variable = {{ shadowing_variable }}
-Uniquely named variable = {{ unique_variable }}
- """ - def get_context_data(self, shadowing_variable=None, new_variable=None): - context = {} - if shadowing_variable is not None: - context["shadowing_variable"] = shadowing_variable - if new_variable is not None: - context["unique_variable"] = new_variable - return context - - def setUp(self): - super().setUp() - registry.register(name="parent_component", component=self.ParentComponent) - registry.register(name="variable_display", component=self.VariableDisplay) - - @parametrize_context_behavior(["django", "isolated"]) - def test_empty_component(self): - class EmptyComponent(Component): - pass - - with self.assertRaises(ImproperlyConfigured): - EmptyComponent("empty_component").get_template(Context({})) - - @parametrize_context_behavior(["django", "isolated"]) - def test_template_string_static_inlined(self): +@djc_test +class TestComponentLegacyApi: + # TODO_REMOVE_IN_V1 - Superseded by `self.get_template` in v1 + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_get_template_string(self, components_settings): class SimpleComponent(Component): - template: types.django_html = """ + def get_template_string(self, context): + content: types.django_html = """ + Variable: {{ variable }} + """ + return content + + def get_template_data(self, args, kwargs, slots, context): + return { + "variable": kwargs.get("variable", None), + } + + class Media: + css = "style.css" + js = "script.js" + + rendered = SimpleComponent.render(kwargs={"variable": "test"}) + assertHTMLEqual( + rendered, + """ + Variable: test + """, + ) + + # TODO_REMOVE_IN_V2 - `get_context_data()` was superseded by `self.get_template_data` + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_get_context_data(self, components_settings): + class SimpleComponent(Component): + template = """ Variable: {{ variable }} """ @@ -84,94 +99,124 @@ class ComponentTest(BaseTestCase): js = "script.js" rendered = SimpleComponent.render(kwargs={"variable": "test"}) - self.assertHTMLEqual( + assertHTMLEqual( rendered, """ - Variable: test + Variable: test """, ) - @parametrize_context_behavior(["django", "isolated"]) - def test_template_string_dynamic(self): + # TODO_REMOVE_IN_V1 - Registry and registered name should be passed to `Component.render()`, + # not to the constructor. + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_instantiation(self, components_settings): class SimpleComponent(Component): - def get_template_string(self, context): - content: types.django_html = """ - Variable: {{ variable }} - """ - return content + template = """ +
+ Name: {{ name }}
+
+ """
- def get_context_data(self, variable=None):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "variable": variable,
+ "name": self.name,
}
- class Media:
- css = "style.css"
- js = "script.js"
-
- rendered = SimpleComponent.render(kwargs={"variable": "test"})
- self.assertHTMLEqual(
+ # Old syntax
+ rendered = SimpleComponent("simple").render()
+ assertHTMLEqual(
rendered,
"""
- Variable: test
+
+ Name: simple
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_template_name_static(self):
- class SimpleComponent(Component):
- template_name = "simple_template.html"
-
- def get_context_data(self, variable=None):
- return {
- "variable": variable,
- }
-
- class Media:
- css = "style.css"
- js = "script.js"
-
- rendered = SimpleComponent.render(kwargs={"variable": "test"})
- self.assertHTMLEqual(
+ # New syntax
+ rendered = SimpleComponent.render(registered_name="simple")
+ assertHTMLEqual(
rendered,
"""
- Variable: test
+
+ Name: simple
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_template_name_dynamic(self):
+ # Sanity check
+ rendered = SimpleComponent.render()
+ assertHTMLEqual(
+ rendered,
+ """
+
+ Name: SimpleComponent
+
+ """,
+ )
+
+ # TODO_v1 - Remove
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_get_template_name(self, components_settings):
class SvgComponent(Component):
- def get_context_data(self, name, css_class="", title="", **attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "name": name,
- "css_class": css_class,
- "title": title,
- **attrs,
+ "name": kwargs.pop("name", None),
+ "css_class": kwargs.pop("css_class", None),
+ "title": kwargs.pop("title", None),
+ **kwargs,
}
def get_template_name(self, context):
return f"dynamic_{context['name']}.svg"
- self.assertHTMLEqual(
+ assertHTMLEqual(
SvgComponent.render(kwargs={"name": "svg1"}),
"""
-
+
""",
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
SvgComponent.render(kwargs={"name": "svg2"}),
"""
-
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_allows_to_override_get_template(self):
- class TestComponent(Component):
- def get_context_data(self, variable, **attrs):
+ # TODO_v1 - Remove
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_get_template__string(self, components_settings):
+ class SimpleComponent(Component):
+ def get_template(self, context):
+ content: types.django_html = """
+ Variable: {{ variable }}
+ """
+ return content
+
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "variable": variable,
+ "variable": kwargs.get("variable", None),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ rendered = SimpleComponent.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ # TODO_v1 - Remove
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_get_template__template(self, components_settings):
+ class TestComponent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.pop("variable", None),
}
def get_template(self, context):
@@ -179,39 +224,62 @@ class ComponentTest(BaseTestCase):
return Template(template_str)
rendered = TestComponent.render(kwargs={"variable": "test"})
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- Variable: test
+ Variable: test
""",
)
- def test_typed(self):
- TestCompArgs = Tuple[int, str]
+ # TODO_v1 - Remove
+ def test_get_template_is_cached(self):
+ class SimpleComponent(Component):
+ def get_template(self, context):
+ content: types.django_html = """
+ Variable: {{ variable }}
+ """
+ return content
- class TestCompKwargs(TypedDict):
- variable: str
- another: int
-
- class TestCompData(TypedDict):
- abc: int
-
- class TestCompSlots(TypedDict):
- my_slot: str
-
- class TestComponent(Component[TestCompArgs, TestCompKwargs, TestCompData, TestCompSlots]):
- def get_context_data(self, var1, var2, variable, another, **attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "variable": variable,
+ "variable": kwargs.get("variable", None),
}
- def get_template(self, context):
- template_str: types.django_html = """
- {% load component_tags %}
- Variable: {{ variable }}
- {% slot 'my_slot' / %}
- """
- return Template(template_str)
+ comp = SimpleComponent()
+ template_1 = _get_component_template(comp)
+ template_1._test_id = "123" # type: ignore[union-attr]
+
+ template_2 = _get_component_template(comp)
+ assert template_2._test_id == "123" # type: ignore[union-attr]
+
+ # TODO_v1 - Remove
+ def test_input(self):
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Variable: {{ variable }}
+ {% slot 'my_slot' / %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert self.input.args == [123, "str"]
+ assert self.input.kwargs == {"variable": "test", "another": 1}
+ assert isinstance(self.input.context, Context)
+ assert list(self.input.slots.keys()) == ["my_slot"]
+ my_slot = self.input.slots["my_slot"]
+ assert my_slot() == "MY_SLOT"
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ def on_render_before(self, context, template):
+ assert self.input.args == [123, "str"]
+ assert self.input.kwargs == {"variable": "test", "another": 1}
+ assert isinstance(self.input.context, Context)
+ assert list(self.input.slots.keys()) == ["my_slot"]
+ my_slot = self.input.slots["my_slot"]
+ assert my_slot() == "MY_SLOT"
rendered = TestComponent.render(
kwargs={"variable": "test", "another": 1},
@@ -219,59 +287,711 @@ class ComponentTest(BaseTestCase):
slots={"my_slot": "MY_SLOT"},
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- Variable: test MY_SLOT
+ Variable: test MY_SLOT
""",
)
- def test_input(self):
- tester = self
+@djc_test
+class TestComponent:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_empty_component(self, components_settings):
+ class EmptyComponent(Component):
+ pass
+
+ EmptyComponent.render(args=["123"])
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_template_string_static_inlined(self, components_settings):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ rendered = SimpleComponent.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_template_file_static(self, components_settings):
+ class SimpleComponent(Component):
+ template_file = "simple_template.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ rendered = SimpleComponent.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ # Test that even with cached template loaders, each Component has its own `Template`
+ # even when multiple components point to the same template file.
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ django_settings={
+ "TEMPLATES": [
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [
+ "tests/templates/",
+ "tests/components/",
+ ],
+ "OPTIONS": {
+ "builtins": [
+ "django_components.templatetags.component_tags",
+ ],
+ 'loaders': [
+ ('django.template.loaders.cached.Loader', [
+
+ # Default Django loader
+ 'django.template.loaders.filesystem.Loader',
+ # Including this is the same as APP_DIRS=True
+ 'django.template.loaders.app_directories.Loader',
+ # Components loader
+ 'django_components.template_loader.Loader',
+ ]),
+ ],
+ },
+ }
+ ],
+ },
+ )
+ def test_template_file_static__cached(self, components_settings):
+ class SimpleComponent1(Component):
+ template_file = "simple_template.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ class SimpleComponent2(Component):
+ template_file = "simple_template.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ SimpleComponent1.template # Triggers template loading
+ SimpleComponent2.template # Triggers template loading
+
+ # Both components have their own Template instance, but they point to the same template file.
+ assert isinstance(SimpleComponent1._template, Template)
+ assert isinstance(SimpleComponent2._template, Template)
+ assert SimpleComponent1._template is not SimpleComponent2._template
+ assert SimpleComponent1._template.source == SimpleComponent2._template.source
+
+ # The Template instances have different origins, but they point to the same template file.
+ assert SimpleComponent1._template.origin is not SimpleComponent2._template.origin
+ assert SimpleComponent1._template.origin.template_name == SimpleComponent2._template.origin.template_name
+ assert SimpleComponent1._template.origin.name == SimpleComponent2._template.origin.name
+ assert SimpleComponent1._template.origin.loader == SimpleComponent2._template.origin.loader
+
+ # The origins point to their respective Component classes.
+ assert SimpleComponent1._template.origin.component_cls == SimpleComponent1
+ assert SimpleComponent2._template.origin.component_cls == SimpleComponent2
+
+ rendered = SimpleComponent1.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ rendered = SimpleComponent2.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_template_file_static__compat(self, components_settings):
+ class SimpleComponent(Component):
+ template_name = "simple_template.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ # Access fields on Component class
+ assert SimpleComponent.template_name == "simple_template.html"
+ assert SimpleComponent.template_file == "simple_template.html"
+
+ SimpleComponent.template_name = "other_template.html"
+ assert SimpleComponent.template_name == "other_template.html"
+ assert SimpleComponent.template_file == "other_template.html"
+
+ SimpleComponent.template_name = "simple_template.html"
+ rendered = SimpleComponent.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ # Access fields on Component instance
+ comp = SimpleComponent()
+ assert comp.template_name == "simple_template.html"
+ assert comp.template_file == "simple_template.html"
+
+ # NOTE: Setting `template_file` on INSTANCE is not supported, as users should work
+ # with classes and not instances. This is tested for completeness.
+ comp.template_name = "other_template_2.html" # type: ignore[misc]
+ assert comp.template_name == "other_template_2.html"
+ assert comp.template_file == "other_template_2.html"
+ assert SimpleComponent.template_name == "other_template_2.html"
+ assert SimpleComponent.template_file == "other_template_2.html"
+
+ SimpleComponent.template_name = "simple_template.html"
+ rendered = comp.render(kwargs={"variable": "test"})
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test
+ """,
+ )
+
+ def test_get_component_by_id(self):
+ class SimpleComponent(Component):
+ pass
+
+ assert get_component_by_class_id(SimpleComponent.class_id) == SimpleComponent
+
+ def test_get_component_by_id_raises_on_missing_component(self):
+ with pytest.raises(KeyError):
+ get_component_by_class_id("nonexistent")
+
+ def test_get_context_data_returns_none(self):
+ class SimpleComponent(Component):
+ template = "Hello"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return None
+
+ assert SimpleComponent.render() == "Hello"
+
+
+@djc_test
+class TestComponentRenderAPI:
+ def test_component_render_id(self):
+ class SimpleComponent(Component):
+ template = "render_id: {{ render_id }}"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"render_id": self.id}
+
+ rendered = SimpleComponent.render()
+ assert rendered == "render_id: ca1bc3e"
+
+ def test_raw_input(self):
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Variable: {{ variable }}
+ {% slot 'my_slot' / %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert self.raw_args == [123, "str"]
+ assert self.raw_kwargs == {"variable": "test", "another": 1}
+ assert isinstance(self.context, Context)
+ assert list(self.raw_slots.keys()) == ["my_slot"]
+ my_slot = self.raw_slots["my_slot"]
+ assert my_slot() == "MY_SLOT"
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ def on_render_before(self, context, template):
+ assert self.raw_args == [123, "str"]
+ assert self.raw_kwargs == {"variable": "test", "another": 1}
+ assert isinstance(self.context, Context)
+ assert list(self.raw_slots.keys()) == ["my_slot"]
+ my_slot = self.raw_slots["my_slot"]
+ assert my_slot() == "MY_SLOT"
+
+ rendered = TestComponent.render(
+ kwargs={"variable": "test", "another": 1},
+ args=(123, "str"),
+ slots={"my_slot": "MY_SLOT"},
+ )
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: test MY_SLOT
+ """,
+ )
+
+ def test_args_kwargs_slots__simple(self):
+ called = False
class TestComponent(Component):
- @no_type_check
- def get_context_data(self, var1, var2, variable, another, **attrs):
- tester.assertEqual(self.input.args, (123, "str"))
- tester.assertEqual(self.input.kwargs, {"variable": "test", "another": 1})
- tester.assertIsInstance(self.input.context, Context)
- tester.assertEqual(self.input.slots, {"my_slot": "MY_SLOT"})
+ template = ""
- return {
- "variable": variable,
- }
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal called
+ called = True
- @no_type_check
- def get_template(self, context):
- tester.assertEqual(self.input.args, (123, "str"))
- tester.assertEqual(self.input.kwargs, {"variable": "test", "another": 1})
- tester.assertIsInstance(self.input.context, Context)
- tester.assertEqual(self.input.slots, {"my_slot": "MY_SLOT"})
+ assert self.args == [123, "str"]
+ assert self.kwargs == {"variable": "test", "another": 1}
+ assert list(self.slots.keys()) == ["my_slot"]
+ my_slot = self.slots["my_slot"]
+ assert my_slot() == "MY_SLOT"
- template_str: types.django_html = """
- {% load component_tags %}
- Variable: {{ variable }}
- {% slot 'my_slot' / %}
- """
- return Template(template_str)
-
- rendered = TestComponent.render(
+ TestComponent.render(
kwargs={"variable": "test", "another": 1},
args=(123, "str"),
slots={"my_slot": "MY_SLOT"},
)
- self.assertHTMLEqual(
- rendered,
+ assert called
+
+ def test_args_kwargs_slots__typed(self):
+ called = False
+
+ class TestComponent(Component):
+ template = ""
+
+ class Args(NamedTuple):
+ variable: int
+ another: str
+
+ class Kwargs(NamedTuple):
+ variable: str
+ another: int
+
+ class Slots(NamedTuple):
+ my_slot: SlotInput
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal called
+ called = True
+
+ assert self.args == TestComponent.Args(123, "str")
+ assert self.kwargs == TestComponent.Kwargs(variable="test", another=1)
+ assert isinstance(self.slots, TestComponent.Slots)
+ assert isinstance(self.slots.my_slot, Slot)
+ assert self.slots.my_slot() == "MY_SLOT"
+
+ # Check that the instances are reused across multiple uses
+ assert self.args is self.args
+ assert self.kwargs is self.kwargs
+ assert self.slots is self.slots
+
+ TestComponent.render(
+ kwargs={"variable": "test", "another": 1},
+ args=(123, "str"),
+ slots={"my_slot": "MY_SLOT"},
+ )
+
+ assert called
+
+ def test_args_kwargs_slots__available_outside_render(self):
+ comp: Any = None
+
+ class TestComponent(Component):
+ template = ""
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal comp
+ comp = self
+
+ assert comp is None
+
+ TestComponent.render()
+
+ assert comp.args == [] # type: ignore[attr-defined]
+ assert comp.kwargs == {} # type: ignore[attr-defined]
+ assert comp.slots == {} # type: ignore[attr-defined]
+ assert comp.context == Context() # type: ignore[attr-defined]
+
+ def test_metadata__template(self):
+ comp: Any = None
+
+ @register("test")
+ class TestComponent(Component):
+ template = "hello"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal comp
+ comp = self
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+ {% component "test" / %}
+
+ """
+ template = Template(template_str)
+ rendered = template.render(Context())
+
+ assertHTMLEqual(rendered, 'hello
')
+
+ assert isinstance(comp, TestComponent)
+
+ assert isinstance(comp.outer_context, Context)
+ assert comp.outer_context == Context()
+
+ assert isinstance(comp.registry, ComponentRegistry)
+ assert comp.registered_name == "test"
+
+ assert comp.node is not None
+ assert comp.node.template_component is None
+ assert comp.node.template_name == "
+ {# Test whole objects #}
+ args: {{ component_vars.args|safe }}
+ kwargs: {{ component_vars.kwargs|safe }}
+ slots: {{ component_vars.slots|safe }}
+
+ {# Test individual values #}
+ arg: {{ component_vars.args.0|safe }}
+ kwarg: {{ component_vars.kwargs.variable|safe }}
+ slot: {{ component_vars.slots.my_slot|safe }}
+
"""
- Variable: test MY_SLOT
+
+ html = TestComponent.render(
+ args=[123, "str"],
+ kwargs={"variable": "test", "another": 1},
+ slots={"my_slot": "MY_SLOT"},
+ )
+ assertHTMLEqual(
+ html,
+ """
+
+ args: [123, 'str']
+ kwargs: {'variable': 'test', 'another': 1}
+ slots: {'my_slot': }
+ arg: 123
+ kwarg: test
+ slot:
+
+ """,
+ )
+
+ def test_args_kwargs_slots__simple_typed(self):
+ class TestComponent(Component):
+ class Args(NamedTuple):
+ variable: int
+ another: str
+
+ class Kwargs(NamedTuple):
+ variable: str
+ another: int
+
+ class Slots(NamedTuple):
+ my_slot: SlotInput
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {# Test whole objects #}
+ args: {{ component_vars.args|safe }}
+ kwargs: {{ component_vars.kwargs|safe }}
+ slots: {{ component_vars.slots|safe }}
+
+ {# Test individual values #}
+ arg: {{ component_vars.args.variable|safe }}
+ kwarg: {{ component_vars.kwargs.variable|safe }}
+ slot: {{ component_vars.slots.my_slot|safe }}
+
+ """
+
+ html = TestComponent.render(
+ args=[123, "str"],
+ kwargs={"variable": "test", "another": 1},
+ slots={"my_slot": "MY_SLOT"},
+ )
+ assertHTMLEqual(
+ html,
+ """
+
+ args: Args(variable=123, another='str')
+ kwargs: Kwargs(variable='test', another=1)
+ slots: Slots(my_slot=)
+ arg: 123
+ kwarg: test
+ slot:
+
+ """,
+ )
+
+ def test_args_kwargs_slots__nested_untyped(self):
+ @register("wrapper")
+ class Wrapper(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "content" default %}
+
+ """
+
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ DEFAULT
+ {% endslot %}
+
+ {% component "wrapper" %}
+ {# Test whole objects #}
+ args: {{ component_vars.args|safe }}
+ kwargs: {{ component_vars.kwargs|safe }}
+ slots: {{ component_vars.slots|safe }}
+
+ {# Test individual values #}
+ arg: {{ component_vars.args.0|safe }}
+ kwarg: {{ component_vars.kwargs.variable|safe }}
+ slot: {{ component_vars.slots.my_slot|safe }}
+ {% endcomponent %}
+
+ """
+
+ html = TestComponent.render(
+ args=[123, "str"],
+ kwargs={"variable": "test", "another": 1},
+ slots={"my_slot": "MY_SLOT"},
+ )
+ assertHTMLEqual(
+ html,
+ """
+
+
+ """,
+ )
+
+ def test_args_kwargs_slots__nested_typed(self):
+ @register("wrapper")
+ class Wrapper(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ args: [123, 'str']
+ kwargs: {'variable': 'test', 'another': 1}
+ slots: {'my_slot': }
+ arg: 123
+ kwarg: test
+ slot:
+
+
+ {% slot "content" default %}
+
+ """
+
+ class TestComponent(Component):
+ class Args(NamedTuple):
+ variable: int
+ another: str
+
+ class Kwargs(NamedTuple):
+ variable: str
+ another: int
+
+ class Slots(NamedTuple):
+ my_slot: SlotInput
+
+ template: types.django_html = """
+ {% load component_tags %}
+ DEFAULT
+ {% endslot %}
+
+ {% component "wrapper" %}
+ {# Test whole objects #}
+ args: {{ component_vars.args|safe }}
+ kwargs: {{ component_vars.kwargs|safe }}
+ slots: {{ component_vars.slots|safe }}
+
+ {# Test individual values #}
+ arg: {{ component_vars.args.variable|safe }}
+ kwarg: {{ component_vars.kwargs.variable|safe }}
+ slot: {{ component_vars.slots.my_slot|safe }}
+ {% endcomponent %}
+
+ """
+
+ html = TestComponent.render(
+ args=[123, "str"],
+ kwargs={"variable": "test", "another": 1},
+ slots={"my_slot": "MY_SLOT"},
+ )
+ assertHTMLEqual(
+ html,
+ """
+
+
+ """,
+ )
+
+ def test_args_kwargs_slots__nested_conditional_slots(self):
+ @register("wrapper")
+ class Wrapper(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ args: Args(variable=123, another='str')
+ kwargs: Kwargs(variable='test', another=1)
+ slots: Slots(my_slot=)
+ arg: 123
+ kwarg: test
+ slot:
+
+
+ {% slot "content" default %}
+
+ """
+
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ DEFAULT
+ {% endslot %}
+
+ {% component "wrapper" %}
+ {% if component_vars.slots.subtitle %}
+
+ """
+
+ html = TestComponent.render(
+ slots={"subtitle": "SUBTITLE_FILLED"},
+ )
+ assertHTMLEqual(
+ html,
+ """
+
+ {% slot "subtitle" %}
+ Optional subtitle
+ {% endslot %}
+
+ {% endif %}
+ {% endcomponent %}
+
+
""",
)
-class ComponentRenderTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_minimal(self):
+@djc_test
+class TestComponentRender:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_minimal(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -287,20 +1007,20 @@ class ComponentRenderTest(BaseTestCase):
{% endslot %}
"""
- def get_context_data(self, the_arg2=None, *args, the_kwarg=None, **kwargs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "the_arg2": the_arg2,
- "the_kwarg": the_kwarg,
- "args": args,
+ "the_arg2": args[0] if args else None,
+ "the_kwarg": kwargs.pop("the_kwarg", None),
+ "args": args[1:],
"kwargs": kwargs,
}
rendered = SimpleComponent.render()
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
the_arg2: None
- args: ()
+ args: []
the_kwarg: None
kwargs: {}
---
@@ -310,8 +1030,8 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_full(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_full(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -331,12 +1051,12 @@ class ComponentRenderTest(BaseTestCase):
{% endslot %}
"""
- def get_context_data(self, the_arg, the_arg2=None, *args, the_kwarg, **kwargs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "the_arg": the_arg,
- "the_arg2": the_arg2,
- "the_kwarg": the_kwarg,
- "args": args,
+ "the_arg": args[0],
+ "the_arg2": args[1],
+ "the_kwarg": kwargs.pop("the_kwarg", None),
+ "args": args[2:],
"kwargs": kwargs,
}
@@ -346,12 +1066,12 @@ class ComponentRenderTest(BaseTestCase):
kwargs={"the_kwarg": "test", "kw2": "ooo"},
slots={"first": "FIRST_SLOT"},
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
the_arg: one
the_arg2: two
- args: ('three',)
+ args: ['three']
the_kwarg: test
kwargs: {'kw2': 'ooo'}
---
@@ -363,8 +1083,8 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_to_response_full(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_to_response_full(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -384,12 +1104,12 @@ class ComponentRenderTest(BaseTestCase):
{% endslot %}
"""
- def get_context_data(self, the_arg, the_arg2=None, *args, the_kwarg, **kwargs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "the_arg": the_arg,
- "the_arg2": the_arg2,
- "the_kwarg": the_kwarg,
- "args": args,
+ "the_arg": args[0],
+ "the_arg2": args[1],
+ "the_kwarg": kwargs.pop("the_kwarg"),
+ "args": args[2:],
"kwargs": kwargs,
}
@@ -399,14 +1119,14 @@ class ComponentRenderTest(BaseTestCase):
kwargs={"the_kwarg": "test", "kw2": "ooo"},
slots={"first": "FIRST_SLOT"},
)
- self.assertIsInstance(rendered, HttpResponse)
+ assert isinstance(rendered, HttpResponse)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered.content.decode(),
"""
the_arg: one
the_arg2: two
- args: ('three',)
+ args: ['three']
the_kwarg: test
kwargs: {'kw2': 'ooo'}
---
@@ -418,8 +1138,8 @@ class ComponentRenderTest(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_to_response_change_response_class(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_to_response_change_response_class(self, components_settings):
class MyResponse:
def __init__(self, content: str) -> None:
self.content = bytes(content, "utf-8")
@@ -429,89 +1149,15 @@ class ComponentRenderTest(BaseTestCase):
template: types.django_html = "HELLO"
rendered = SimpleComponent.render_to_response()
- self.assertIsInstance(rendered, MyResponse)
+ assert isinstance(rendered, MyResponse)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered.content.decode(),
"HELLO",
)
- @parametrize_context_behavior([("django", False), ("isolated", True)])
- def test_render_slot_as_func(self, context_behavior_data):
- is_isolated = context_behavior_data
-
- class SimpleComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
- {% slot "first" required data1="abc" data2:hello="world" data2:one=123 %}
- SLOT_DEFAULT
- {% endslot %}
- """
-
- def get_context_data(self, the_arg, the_kwarg=None, **kwargs):
- return {
- "the_arg": the_arg,
- "the_kwarg": the_kwarg,
- "kwargs": kwargs,
- }
-
- def first_slot(ctx: Context, slot_data: Dict, slot_ref: SlotRef):
- self.assertIsInstance(ctx, Context)
- # NOTE: Since the slot has access to the Context object, it should behave
- # the same way as it does in templates - when in "isolated" mode, then the
- # slot fill has access only to the "root" context, but not to the data of
- # get_context_data() of SimpleComponent.
- if is_isolated:
- self.assertEqual(ctx.get("the_arg"), None)
- self.assertEqual(ctx.get("the_kwarg"), None)
- self.assertEqual(ctx.get("kwargs"), None)
- self.assertEqual(ctx.get("abc"), None)
- else:
- self.assertEqual(ctx["the_arg"], "1")
- self.assertEqual(ctx["the_kwarg"], 3)
- self.assertEqual(ctx["kwargs"], {})
- self.assertEqual(ctx["abc"], "def")
-
- slot_data_expected = {
- "data1": "abc",
- "data2": {"hello": "world", "one": 123},
- }
- self.assertDictEqual(slot_data_expected, slot_data)
-
- self.assertIsInstance(slot_ref, SlotRef)
- self.assertEqual("SLOT_DEFAULT", str(slot_ref).strip())
-
- return f"FROM_INSIDE_FIRST_SLOT | {slot_ref}"
-
- rendered = SimpleComponent.render(
- context={"abc": "def"},
- args=["1"],
- kwargs={"the_kwarg": 3},
- slots={"first": first_slot},
- )
- self.assertHTMLEqual(
- rendered,
- "FROM_INSIDE_FIRST_SLOT | SLOT_DEFAULT",
- )
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_raises_on_missing_slot(self):
- class SimpleComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
- {% slot "first" required %}
- {% endslot %}
- """
-
- with self.assertRaises(TemplateSyntaxError):
- SimpleComponent.render()
-
- SimpleComponent.render(
- slots={"first": "FIRST_SLOT"},
- )
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_with_include(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_with_include(self, components_settings):
class SimpleComponent(Component):
template: types.django_html = """
{% load component_tags %}
@@ -519,10 +1165,10 @@ class ComponentRenderTest(BaseTestCase):
"""
rendered = SimpleComponent.render()
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
+ SUBTITLE_FILLED
+
+ CSRF token: {{ csrf_token|default:"No CSRF token" }}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"how": kwargs.pop("how")}
+
+ class View(ComponentView):
+ def get(self, request):
+ how = "via GET request"
+
+ return self.component.render_to_response(
+ context=RequestContext(self.request),
+ kwargs={"how": how},
+ )
+
+ client = CustomClient(urlpatterns=[path("test_thing/", Thing.as_view())])
+ response = client.get("/test_thing/")
+
+ assert response.status_code == 200
+
+ # Full response:
+ # """
+ #
+ # Rendered via GET request
+ #
+ #
+ # CSRF token:
+ #
+ # """
+ assertInHTML(
+ """
+
+ Rendered via GET request
+
+ """,
+ response.content.decode(),
+ )
+
+ token_re = re.compile(rb"CSRF token:\s+predictabletoken")
+ token = token_re.findall(response.content)[0]
+
+ assert token == b"CSRF token: predictabletoken"
+
+ def test_request_context_created_when_no_context(self):
+ @register("thing")
+ class Thing(Component):
+ template: types.django_html = """
+ CSRF token: {{ csrf_token|default:"No CSRF token" }}
+ """
+
+ class View:
+ def get(self, request):
+ return Thing.render_to_response(request=request)
+
+ client = CustomClient(urlpatterns=[path("test_thing/", Thing.as_view())])
+ response = client.get("/test_thing/")
+
+ assert response.status_code == 200
+
+ token_re = re.compile(rb"CSRF token:\s+predictabletoken")
+ token = token_re.findall(response.content)[0]
+
+ assert token == b"CSRF token: predictabletoken"
+
+ def test_request_context_created_when_already_a_context_dict(self):
+ @register("thing")
+ class Thing(Component):
+ template: types.django_html = """
+
+ # test_csrf_token
+ #
+ # CSRF token: {{ csrf_token|default:"No CSRF token" }}
+Existing context: {{ existing_context|default:"No existing context" }}
+ """ + + class View: + def get(self, request): + return Thing.render_to_response(request=request, context={"existing_context": "foo"}) + + client = CustomClient(urlpatterns=[path("test_thing/", Thing.as_view())]) + response = client.get("/test_thing/") + + assert response.status_code == 200 + + token_re = re.compile(rb"CSRF token:\s+predictabletoken") + token = token_re.findall(response.content)[0] + + assert token == b"CSRF token: predictabletoken" + assert "Existing context: foo" in response.content.decode() + + def request_context_ignores_context_when_already_a_context(self): + @register("thing") + class Thing(Component): + template: types.django_html = """ +CSRF token: {{ csrf_token|default:"No CSRF token" }}
+Existing context: {{ existing_context|default:"No existing context" }}
+ """ + + class View: + def get(self, request): + return Thing.render_to_response( + request=request, + context=Context({"existing_context": "foo"}), + ) + + client = CustomClient(urlpatterns=[path("test_thing/", Thing.as_view())]) + response = client.get("/test_thing/") + + assert response.status_code == 200 + + token_re = re.compile(rb"CSRF token:\s+(?P
@@ -598,38 +1370,678 @@ class ComponentRenderTest(BaseTestCase):
-
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_can_access_instance(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_can_access_instance(self, components_settings):
class TestComponent(Component):
template = "Variable: {{ id }}"
- def get_context_data(self, **attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "id": self.component_id,
+ "id": self.id,
}
- rendered = TestComponent(component_id="123").render()
- self.assertHTMLEqual(
+ rendered = TestComponent.render()
+ assertHTMLEqual(
rendered,
- "Variable: 123",
+ "Variable: ca1bc3e",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_render_to_response_can_access_instance(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_to_response_can_access_instance(self, components_settings):
class TestComponent(Component):
template = "Variable: {{ id }}"
- def get_context_data(self, **attrs):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "id": self.component_id,
+ "id": self.id,
}
- rendered_resp = TestComponent(component_id="123").render_to_response()
- self.assertHTMLEqual(
+ rendered_resp = TestComponent.render_to_response()
+ assertHTMLEqual(
rendered_resp.content.decode("utf-8"),
- "Variable: 123",
+ "Variable: ca1bc3e",
)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_prepends_exceptions_with_component_path(self, components_settings):
+ @register("broken")
+ class Broken(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "content" default / %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ data = self.inject("my_provide")
+ data["data1"] # This should raise TypeError
+ return {"data": data}
+
+ @register("provider")
+ class Provider(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" data=data %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+ @register("parent")
+ class Parent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "provider" data=data %}
+ {% component "broken" %}
+ {% slot "content" default / %}
+ {% endcomponent %}
+ {% endcomponent %}
+ """
+
+ @register("root")
+ class Root(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "parent" data=123 %}
+ {% fill "content" %}
+ 456
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ with pytest.raises(
+ TypeError,
+ match=re.escape(
+ "An error occured while rendering components Root > parent > provider > provider(slot:content) > broken:\n" # noqa: E501
+ "tuple indices must be integers or slices, not str"
+ ),
+ ):
+ Root.render()
+
+
+@djc_test
+class TestComponentHook:
+ def _gen_slotted_component(self, calls: List[str]):
+ class Slotted(Component):
+ template = "Hello from slotted"
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ calls.append("slotted__on_render_before")
+
+ def on_render(self, context: Context, template: Optional[Template]):
+ calls.append("slotted__on_render_pre")
+ html, error = yield template.render(context) # type: ignore[union-attr]
+
+ calls.append("slotted__on_render_post")
+
+ # Check that modifying the context or template does nothing
+ def on_render_after(
+ self,
+ context: Context,
+ template: Optional[Template],
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ calls.append("slotted__on_render_after")
+
+ return Slotted
+
+ def _gen_inner_component(self, calls: List[str]):
+ class Inner(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Inner start
+ {% slot "content" default / %}
+ Inner end
+ """
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ calls.append("inner__on_render_before")
+
+ def on_render(self, context: Context, template: Optional[Template]):
+ calls.append("inner__on_render_pre")
+ if template is None:
+ yield None
+ else:
+ html, error = yield template.render(context)
+
+ calls.append("inner__on_render_post")
+
+ # Check that modifying the context or template does nothing
+ def on_render_after(
+ self,
+ context: Context,
+ template: Optional[Template],
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ calls.append("inner__on_render_after")
+
+ return Inner
+
+ def _gen_middle_component(self, calls: List[str]):
+ class Middle(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Middle start
+ {% component "inner" %}
+ {% component "slotted" / %}
+ {% endcomponent %}
+ Middle text
+ {% component "inner" / %}
+ Middle end
+ """
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ calls.append("middle__on_render_before")
+
+ def on_render(self, context: Context, template: Optional[Template]):
+ calls.append("middle__on_render_pre")
+ html, error = yield template.render(context) # type: ignore[union-attr]
+
+ calls.append("middle__on_render_post")
+
+ # Check that modifying the context or template does nothing
+ def on_render_after(
+ self,
+ context: Context,
+ template: Optional[Template],
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ calls.append("middle__on_render_after")
+
+ return Middle
+
+ def _gen_outer_component(self, calls: List[str]):
+ class Outer(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Outer start
+ {% component "middle" / %}
+ Outer text
+ {% component "middle" / %}
+ Outer end
+ """
+
+ def on_render_before(self, context: Context, template: Optional[Template]) -> None:
+ calls.append("outer__on_render_before")
+
+ def on_render(self, context: Context, template: Optional[Template]):
+ calls.append("outer__on_render_pre")
+ html, error = yield template.render(context) # type: ignore[union-attr]
+
+ calls.append("outer__on_render_post")
+
+ # Check that modifying the context or template does nothing
+ def on_render_after(
+ self,
+ context: Context,
+ template: Optional[Template],
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ calls.append("outer__on_render_after")
+
+ return Outer
+
+ def _gen_broken_component(self):
+ class BrokenComponent(Component):
+ def on_render(self, context: Context, template: Template):
+ raise ValueError("BROKEN")
+
+ return BrokenComponent
+
+ def test_order(self):
+ calls: List[str] = []
+
+ registry.register("slotted", self._gen_slotted_component(calls))
+ registry.register("inner", self._gen_inner_component(calls))
+ registry.register("middle", self._gen_middle_component(calls))
+ Outer = self._gen_outer_component(calls)
+
+ result = Outer.render()
+
+ assertHTMLEqual(
+ result,
+ """
+ Outer start
+ Middle start
+ Inner start
+ Hello from slotted
+ Inner end
+ Middle text
+ Inner start
+ Inner end
+ Middle end
+ Outer text
+ Middle start
+ Inner start
+ Hello from slotted
+ Inner end
+ Middle text
+ Inner start
+ Inner end
+ Middle end
+ Outer end
+ """,
+ )
+
+ assert calls == [
+ "outer__on_render_before",
+ "outer__on_render_pre",
+ "middle__on_render_before",
+ "middle__on_render_pre",
+ "inner__on_render_before",
+ "inner__on_render_pre",
+ "slotted__on_render_before",
+ "slotted__on_render_pre",
+ "slotted__on_render_post",
+ "slotted__on_render_after",
+ "inner__on_render_post",
+ "inner__on_render_after",
+ "inner__on_render_before",
+ "inner__on_render_pre",
+ "inner__on_render_post",
+ "inner__on_render_after",
+ "middle__on_render_post",
+ "middle__on_render_after",
+ "middle__on_render_before",
+ "middle__on_render_pre",
+ "inner__on_render_before",
+ "inner__on_render_pre",
+ "slotted__on_render_before",
+ "slotted__on_render_pre",
+ "slotted__on_render_post",
+ "slotted__on_render_after",
+ "inner__on_render_post",
+ "inner__on_render_after",
+ "inner__on_render_before",
+ "inner__on_render_pre",
+ "inner__on_render_post",
+ "inner__on_render_after",
+ "middle__on_render_post",
+ "middle__on_render_after",
+ "outer__on_render_post",
+ "outer__on_render_after",
+ ]
+
+ def test_context(self):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ from_on_before: {{ from_on_before }}
+ from_on_before__edited1: {{ from_on_before__edited1 }}
+ from_on_before__edited2: {{ from_on_before__edited2 }}
+ from_on_render_pre: {{ from_on_render_pre }}
+ from_on_render_post: {{ from_on_render_post }}
+ from_on_render_pre__edited2: {{ from_on_render_pre__edited2 }}
+ from_on_render_post__edited2: {{ from_on_render_post__edited2 }}
+ from_on_after: {{ from_on_after }}
+ """
+
+ def on_render_before(self, context: Context, template: Template) -> None:
+ # Insert value into the Context
+ context["from_on_before"] = "1"
+
+ def on_render(self, context: Context, template: Template):
+ context["from_on_render_pre"] = "2"
+ # Check we can modify entries set by other methods
+ context["from_on_before__edited1"] = context["from_on_before"] + " (on_render)"
+
+ html, error = yield template.render(context)
+
+ context["from_on_render_post"] = "3"
+
+ # NOTE: Since this is called AFTER the render, the values set here should NOT
+ # make it to the rendered output.
+ def on_render_after(
+ self,
+ context: Context,
+ template: Template,
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ context["from_on_after"] = "4"
+ # Check we can modify entries set by other methods
+ # NOTE: These also check that the previous values are available
+ context["from_on_before__edited2"] = context["from_on_before"] + " (on_render_after)"
+ context["from_on_render_pre__edited2"] = context["from_on_render_pre"] + " (on_render_after)"
+ context["from_on_render_post__edited2"] = context["from_on_render_post"] + " (on_render_after)"
+
+ rendered = SimpleComponent.render()
+
+ assertHTMLEqual(
+ rendered,
+ """
+ from_on_before: 1
+ from_on_before__edited1: 1 (on_render)
+ from_on_before__edited2:
+ from_on_render_pre: 2
+ from_on_render_post:
+ from_on_render_pre__edited2:
+ from_on_render_post__edited2:
+ from_on_after:
+ """,
+ )
+
+ def test_template(self):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ text
+ """
+
+ def on_render_before(self, context: Context, template: Template) -> None:
+ # Insert text into the Template
+ #
+ # NOTE: Users should NOT do this, because this will insert the text every time
+ # the component is rendered.
+ template.nodelist.append(TextNode("\n---\nFROM_ON_BEFORE"))
+
+ def on_render(self, context: Context, template: Template):
+ template.nodelist.append(TextNode("\n---\nFROM_ON_RENDER_PRE"))
+
+ html, error = yield template.render(context)
+
+ template.nodelist.append(TextNode("\n---\nFROM_ON_RENDER_POST"))
+
+ # NOTE: Since this is called AFTER the render, the values set here should NOT
+ # make it to the rendered output.
+ def on_render_after(
+ self,
+ context: Context,
+ template: Template,
+ html: Optional[str],
+ error: Optional[Exception],
+ ) -> None:
+ template.nodelist.append(TextNode("\n---\nFROM_ON_AFTER"))
+
+ rendered = SimpleComponent.render()
+ assertHTMLEqual(
+ rendered,
+ """
+ text
+ ---
+ FROM_ON_BEFORE
+ ---
+ FROM_ON_RENDER_PRE
+ """,
+ )
+
+ def test_on_render_no_yield(self):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ text
+ """
+
+ def on_render(self, context: Context, template: Template):
+ return "OVERRIDDEN"
+
+ rendered = SimpleComponent.render()
+ assert rendered == "OVERRIDDEN"
+
+ def test_on_render_reraise_error(self):
+ registry.register("broken", self._gen_broken_component())
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% component "broken" / %}
+ """
+
+ def on_render(self, context: Context, template: Template):
+ html, error = yield template.render(context)
+
+ raise error from None # Re-raise original error
+
+ with pytest.raises(ValueError, match=re.escape("BROKEN")):
+ SimpleComponent.render()
+
+ @djc_test(
+ parametrize=(
+ ["template", "action", "method"],
+ [
+ ["simple", "return_none", "on_render"],
+ ["broken", "return_none", "on_render"],
+ [None, "return_none", "on_render"],
+
+ ["simple", "return_none", "on_render_after"],
+ ["broken", "return_none", "on_render_after"],
+ [None, "return_none", "on_render_after"],
+
+ ["simple", "no_return", "on_render"],
+ ["broken", "no_return", "on_render"],
+ [None, "no_return", "on_render"],
+
+ ["simple", "no_return", "on_render_after"],
+ ["broken", "no_return", "on_render_after"],
+ [None, "no_return", "on_render_after"],
+
+ ["simple", "raise_error", "on_render"],
+ ["broken", "raise_error", "on_render"],
+ [None, "raise_error", "on_render"],
+
+ ["simple", "raise_error", "on_render_after"],
+ ["broken", "raise_error", "on_render_after"],
+ [None, "raise_error", "on_render_after"],
+
+ ["simple", "return_html", "on_render"],
+ ["broken", "return_html", "on_render"],
+ [None, "return_html", "on_render"],
+
+ ["simple", "return_html", "on_render_after"],
+ ["broken", "return_html", "on_render_after"],
+ [None, "return_html", "on_render_after"],
+ ],
+ None
+ )
+ )
+ def test_result_interception(
+ self,
+ template: Literal["simple", "broken", None],
+ action: Literal["return_none", "no_return", "raise_error", "return_html"],
+ method: Literal["on_render", "on_render_after"],
+ ):
+ calls: List[str] = []
+
+ Broken = self._gen_broken_component()
+ Slotted = self._gen_slotted_component(calls)
+ Inner = self._gen_inner_component(calls)
+ Middle = self._gen_middle_component(calls)
+ Outer = self._gen_outer_component(calls)
+
+ # Make modifications to the components based on the parameters
+
+ # Set template
+ if template is None:
+ class Inner(Inner): # type: ignore
+ template = None
+
+ elif template == "broken":
+ class Inner(Inner): # type: ignore
+ template = "{% component 'broken' / %}"
+
+ elif template == "simple":
+ pass
+
+ # Set `on_render` behavior
+ if method == "on_render":
+ if action == "return_none":
+ class Inner(Inner): # type: ignore
+ def on_render(self, context: Context, template: Optional[Template]):
+ if template is None:
+ yield None
+ else:
+ html, error = yield template.render(context)
+ return None
+
+ elif action == "no_return":
+ class Inner(Inner): # type: ignore
+ def on_render(self, context: Context, template: Optional[Template]):
+ if template is None:
+ yield None
+ else:
+ html, error = yield template.render(context)
+
+ elif action == "raise_error":
+ class Inner(Inner): # type: ignore
+ def on_render(self, context: Context, template: Optional[Template]):
+ if template is None:
+ yield None
+ else:
+ html, error = yield template.render(context)
+ raise ValueError("ERROR_FROM_ON_RENDER")
+
+ elif action == "return_html":
+ class Inner(Inner): # type: ignore
+ def on_render(self, context: Context, template: Optional[Template]):
+ if template is None:
+ yield None
+ else:
+ html, error = yield template.render(context)
+ return "HTML_FROM_ON_RENDER"
+ else:
+ raise pytest.fail(f"Unknown action: {action}")
+
+ # Set `on_render_after` behavior
+ elif method == "on_render_after":
+ if action == "return_none":
+ class Inner(Inner): # type: ignore
+ def on_render_after(self, context: Context, template: Template, html: Optional[str], error: Optional[Exception]): # noqa: E501
+ return None
+
+ elif action == "no_return":
+ class Inner(Inner): # type: ignore
+ def on_render_after(self, context: Context, template: Template, html: Optional[str], error: Optional[Exception]): # noqa: E501
+ pass
+
+ elif action == "raise_error":
+ class Inner(Inner): # type: ignore
+ def on_render_after(self, context: Context, template: Template, html: Optional[str], error: Optional[Exception]): # noqa: E501
+ raise ValueError("ERROR_FROM_ON_RENDER")
+
+ elif action == "return_html":
+ class Inner(Inner): # type: ignore
+ def on_render_after(self, context: Context, template: Template, html: Optional[str], error: Optional[Exception]): # noqa: E501
+ return "HTML_FROM_ON_RENDER"
+ else:
+ raise pytest.fail(f"Unknown action: {action}")
+ else:
+ raise pytest.fail(f"Unknown method: {method}")
+
+ registry.register("broken", Broken)
+ registry.register("slotted", Slotted)
+ registry.register("inner", Inner)
+ registry.register("middle", Middle)
+ registry.register("outer", Outer)
+
+ def _gen_expected_output(inner1: str, inner2: str):
+ return f"""
+ Outer start
+ Middle start
+ {inner1}
+ Middle text
+ {inner2}
+ Middle end
+ Outer text
+ Middle start
+ {inner1}
+ Middle text
+ {inner2}
+ Middle end
+ Outer end
+ """
+
+ # Assert based on the behavior
+ if template is None:
+ # Overriden HTML
+ if action == "return_html":
+ expected = _gen_expected_output(inner1="HTML_FROM_ON_RENDER", inner2="HTML_FROM_ON_RENDER")
+ result = Outer.render()
+ assertHTMLEqual(result, expected)
+ # Overriden error
+ elif action == "raise_error":
+ with pytest.raises(ValueError, match="ERROR_FROM_ON_RENDER"):
+ Outer.render()
+ # Original output
+ elif action in ["return_none", "no_return"]:
+ expected = _gen_expected_output(inner1="", inner2="")
+ result = Outer.render()
+ assertHTMLEqual(result, expected)
+ else:
+ raise pytest.fail(f"Unknown action: {action}")
+
+ elif template == "simple":
+ # Overriden HTML
+ if action == "return_html":
+ expected = _gen_expected_output(inner1="HTML_FROM_ON_RENDER", inner2="HTML_FROM_ON_RENDER")
+ result = Outer.render()
+ assertHTMLEqual(result, expected)
+ # Overriden error
+ elif action == "raise_error":
+ with pytest.raises(ValueError, match="ERROR_FROM_ON_RENDER"):
+ Outer.render()
+ # Original output
+ elif action in ["return_none", "no_return"]:
+ expected = _gen_expected_output(
+ inner1="Inner start Hello from slotted Inner end",
+ inner2="Inner start Inner end",
+ )
+ result = Outer.render()
+ assertHTMLEqual(result, expected)
+ else:
+ raise pytest.fail(f"Unknown action: {action}")
+
+ elif template == "broken":
+ # Overriden HTML
+ if action == "return_html":
+ expected = _gen_expected_output(inner1="HTML_FROM_ON_RENDER", inner2="HTML_FROM_ON_RENDER")
+ result = Outer.render()
+ assertHTMLEqual(result, expected)
+ # Overriden error
+ elif action == "raise_error":
+ with pytest.raises(ValueError, match="ERROR_FROM_ON_RENDER"):
+ Outer.render()
+ # Original output
+ elif action in ["return_none", "no_return"]:
+ with pytest.raises(ValueError, match="broken"):
+ Outer.render()
+ else:
+ raise pytest.fail(f"Unknown action: {action}")
+
+ else:
+ raise pytest.fail(f"Unknown template: {template}")
+
+
+@djc_test
+class TestComponentHelpers:
+ def test_all_components(self):
+ # NOTE: When running all tests, this list may already have some components
+ # as some components in test files are defined on module level, outside of
+ # `djc_test` decorator.
+ all_comps_before = len(all_components())
+
+ # Components don't have to be registered to be included in the list
+ class TestComponent(Component):
+ template: types.django_html = """
+ Hello from test
+ """
+
+ assert len(all_components()) == all_comps_before + 1
+
+ @register("test2")
+ class Test2Component(Component):
+ template: types.django_html = """
+ Hello from test2
+ """
+
+ assert len(all_components()) == all_comps_before + 2
diff --git a/tests/test_component_cache.py b/tests/test_component_cache.py
new file mode 100644
index 00000000..b2ec2dc3
--- /dev/null
+++ b/tests/test_component_cache.py
@@ -0,0 +1,350 @@
+import re
+import time
+
+from django.core.cache import caches
+from django.template import Template
+from django.template.context import Context
+import pytest
+
+from django_components import Component, register
+from django_components.testing import djc_test
+
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# Common settings for all tests
+@djc_test(
+ django_settings={
+ "CACHES": {
+ "default": {
+ "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+ },
+ },
+ },
+)
+class TestComponentCache:
+ def test_cache_enabled(self):
+ did_call_get = False
+
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_get
+ did_call_get = True
+
+ # First render
+ component = TestComponent()
+ result = component.render()
+
+ assert did_call_get
+ assert result == "Hello"
+
+ # Check if the cache entry is set
+ cache_key = component.cache.get_cache_key([], {}, {})
+ assert cache_key == "components:cache:c98bf483e9a1937732d4542c714462ac"
+ assert component.cache.get_entry(cache_key) == "Hello"
+ assert caches["default"].get(cache_key) == "Hello"
+
+ # Second render
+ did_call_get = False
+ component.render()
+
+ # get_template_data not called because the cache entry was returned
+ assert not did_call_get
+ assert result == "Hello"
+
+ def test_cache_disabled(self):
+ did_call_get = False
+
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = False
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_get
+ did_call_get = True
+
+ # First render
+ component = TestComponent()
+ result = component.render()
+
+ assert did_call_get
+ assert result == "Hello"
+
+ # Check if the cache entry is not set
+ cache_instance = component.cache
+ cache_key = cache_instance.get_cache_key([], {}, {})
+ assert cache_instance.get_entry(cache_key) is None
+
+ # Second render
+ did_call_get = False
+ result = component.render()
+
+ # get_template_data IS called because the cache is NOT used
+ assert did_call_get
+ assert result == "Hello"
+
+ def test_cache_ttl(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+ ttl = 0.1 # .1 seconds TTL
+
+ component = TestComponent()
+ component.render()
+
+ cache_instance = component.cache
+ cache_key = cache_instance.get_cache_key([], {}, {})
+ assert cache_instance.get_entry(cache_key) == "Hello"
+
+ # Wait for TTL to expire
+ time.sleep(0.2)
+
+ assert cache_instance.get_entry(cache_key) is None
+
+ @djc_test(
+ django_settings={
+ "CACHES": {
+ "default": {
+ "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+ "LOCATION": "default",
+ },
+ "custom": {
+ "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+ "LOCATION": "custom",
+ },
+ },
+ },
+ )
+ def test_custom_cache_name(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+ cache_name = "custom"
+
+ component = TestComponent()
+ component.render()
+
+ assert component.cache.get_cache() is caches["custom"]
+ assert (
+ component.cache.get_entry("components:cache:bcb4b049d8556e06871b39e0e584e452")
+ == "Hello"
+ )
+
+ def test_cache_by_input(self):
+ class TestComponent(Component):
+ template = "Hello {{ input }}"
+
+ class Cache:
+ enabled = True
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"input": kwargs["input"]}
+
+ component = TestComponent()
+ component.render(
+ kwargs={"input": "world"},
+ )
+
+ component.render(
+ kwargs={"input": "cake"},
+ )
+
+ # Check if the cache entry is set
+ cache = caches["default"]
+
+ assert len(cache._cache) == 2
+ assert (
+ component.cache.get_entry("components:cache:3535e1d1e5f6fa5bc521e7fe203a68d0")
+ == "Hello world"
+ )
+ assert (
+ component.cache.get_entry("components:cache:a98a8bd5e72a544d7601798d5e777a77")
+ == "Hello cake"
+ )
+
+ def test_cache_input_hashing(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+
+ component = TestComponent()
+ component.render(args=(1, 2), kwargs={"key": "value"})
+
+ # The key consists of `component._class_hash`, hashed args, and hashed kwargs
+ expected_key = "1,2:key-value"
+ assert component.cache.hash([1, 2], {"key": "value"}) == expected_key
+
+ def test_override_hash_methods(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+
+ def hash(self, *args, **kwargs):
+ # Custom hash method for args and kwargs
+ return "custom-args-and-kwargs"
+
+ component = TestComponent()
+ component.render(args=(1, 2), kwargs={"key": "value"})
+
+ # The key should use the custom hash methods
+ expected_key = "components:cache:3d54974c467a578c509efec189b0d14b"
+ assert component.cache.get_cache_key([1, 2], {"key": "value"}, {}) == expected_key
+ assert component.cache.get_entry(expected_key) == "Hello"
+
+ def test_cached_component_inside_include(self):
+
+ @register("test_component")
+ class TestComponent(Component):
+ template = "Hello"
+
+ class Cache:
+ enabled = True
+
+ template = Template(
+ """
+ {% extends "component_inside_include_base.html" %}
+ {% block content %}
+ THIS_IS_IN_ACTUAL_TEMPLATE_SO_SHOULD_NOT_BE_OVERRIDDEN
+ {% endblock %}
+ """
+ )
+
+ result = template.render(Context({}))
+ assert "THIS_IS_IN_BASE_TEMPLATE_SO_SHOULD_BE_OVERRIDDEN" not in result
+ assert "THIS_IS_IN_ACTUAL_TEMPLATE_SO_SHOULD_NOT_BE_OVERRIDDEN" in result
+
+ result_cached = template.render(Context({}))
+ assert "THIS_IS_IN_BASE_TEMPLATE_SO_SHOULD_BE_OVERRIDDEN" not in result_cached
+ assert "THIS_IS_IN_ACTUAL_TEMPLATE_SO_SHOULD_NOT_BE_OVERRIDDEN" in result_cached
+
+ def test_cache_slots__fills(self):
+ @register("test_component")
+ class TestComponent(Component):
+ template = "Hello {{ input }} {{ variable }}
- """
-
- comp = SimpleComponent("simple_component")
-
- self.assertHTMLEqual(comp.render_dependencies(), "")
+ assert rendered.count("
-
-
- """,
- )
+ rendered = SimpleComponent.render()
+
+ assertInHTML('', rendered)
+ assertInHTML('', rendered)
+
+ assertInHTML('', rendered)
def test_css_js_as_string(self):
class SimpleComponent(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
class Media:
css = "path/to/style.css"
js = "path/to/script.js"
- comp = SimpleComponent("")
- self.assertHTMLEqual(
- comp.render_dependencies(),
- """
-
-
- """,
- )
+ rendered = SimpleComponent.render()
+
+ assertInHTML('', rendered)
+ assertInHTML('', rendered)
def test_css_as_dict(self):
class SimpleComponent(Component):
+ template = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+
class Media:
css = {
"all": "path/to/style.css",
@@ -275,16 +330,13 @@ class ComponentMediaTests(BaseTestCase):
}
js = ["path/to/script.js"]
- comp = SimpleComponent("")
- self.assertHTMLEqual(
- comp.render_dependencies(),
- """
-
-
-
-
- """,
- )
+ rendered = SimpleComponent.render()
+
+ assertInHTML('', rendered)
+ assertInHTML('', rendered)
+ assertInHTML('', rendered)
+
+ assertInHTML('', rendered)
def test_media_custom_render_js(self):
class MyMedia(Media):
@@ -292,23 +344,25 @@ class ComponentMediaTests(BaseTestCase):
tags: list[str] = []
for path in self._js: # type: ignore[attr-defined]
abs_path = self.absolute_path(path) # type: ignore[attr-defined]
- tags.append(f'', rendered, count=1)
+
+ assertInHTML("", rendered, count=1) # Inlined CSS
+ assertInHTML('', rendered, count=1) # Inlined JS
+
+ assertInHTML('', rendered, count=1) # Media.css
+
+ # Check that instead of `render_dependencies()`, we can simply call `Template.render()`
+ def test_template_render(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 = template.render(Context({}))
+
+ # Dependency manager script
+ assertInHTML('', rendered, count=1)
+
+ assertInHTML(
+ "",
+ rendered,
+ count=1,
+ ) # Inlined CSS
+ assertInHTML(
+ '', rendered, count=1
+ ) # Inlined JS
+
+ assertInHTML('', rendered, count=1) # Media.css
+ assert rendered.count("', rendered, count=0)
+
+ assertInHTML(
+ "",
+ rendered,
+ count=1,
+ ) # Inlined CSS
+ assertInHTML(
+ '', rendered, count=1
+ ) # Inlined JS
+
+ assertInHTML('', rendered, count=1) # Media.css
+ assert rendered.count("foo\n'
+ ' \n'
+ ' '
+ )
+
+ # Check that `Component.render()` renders dependencies
+ def test_component_render(self):
+ class SimpleComponentWithDeps(SimpleComponent):
+ template: types.django_html = (
+ """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+ + SimpleComponent.template
+ )
+
+ registry.register(name="test", component=SimpleComponentWithDeps)
+
+ rendered = SimpleComponentWithDeps.render(
+ kwargs={"variable": "foo"},
+ )
+
+ # Dependency manager script
+ assertInHTML('', rendered, count=1)
+
+ assertInHTML("", rendered, count=1) # Inlined CSS
+ assertInHTML('', rendered, count=1) # Inlined JS
+
+ assertInHTML('', rendered, count=1) # Media.css
+ assert rendered.count("', rendered_raw, count=0)
+
+ assertInHTML("", rendered_raw, count=0) # Inlined CSS
+ assertInHTML('', rendered_raw, count=0) # Media.css
+
+ assertInHTML(
+ '',
+ rendered_raw,
+ count=0,
+ ) # Inlined JS
+
+ # Check that `Component.render_to_response()` renders dependencies
+ def test_component_render_to_response(self):
+ class SimpleComponentWithDeps(SimpleComponent):
+ template: types.django_html = (
+ """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ """
+ + SimpleComponent.template
+ )
+
+ registry.register(name="test", component=SimpleComponentWithDeps)
+
+ response = SimpleComponentWithDeps.render_to_response(
+ kwargs={"variable": "foo"},
+ )
+ rendered = response.content.decode()
+
+ # Dependency manager script
+ assertInHTML('', rendered, count=1)
+
+ assertInHTML("", rendered, count=1) # Inlined CSS
+ assertInHTML('', rendered, count=1) # Inlined JS
+
+ assert rendered.count('') == 1 # Media.css
+ assert rendered.count("
+
+
+
+ {% component "test" variable="foo" / %}
+
+
+ """
+ rendered_raw = Template(template_str).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw)
+
+ assert rendered.count("
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ body_re = re.compile(r"(.*?)", re.DOTALL)
+ rendered_body = body_re.search(rendered).group(1) # type: ignore[union-attr]
+
+ assertInHTML(
+ """',
+ rendered_body,
+ count=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: str = render_dependencies(rendered_raw)
+
+ 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,
+ )
+
+ # NOTE: Some HTML parser libraries like selectolax or lxml try to "correct" the given HTML.
+ # We want to avoid this behavior, so user gets the exact same HTML back.
+ def test_does_not_try_to_add_close_tags(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+
+ """
+
+ rendered_raw = Template(template_str).render(Context({"formset": [1], "DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw, strategy="fragment")
+
+ assertHTMLEqual(rendered, "")
+
+ def test_does_not_modify_html_when_no_component_used(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+
+
+
+
+ """
+
+ rendered_raw = Template(template_str).render(Context({"formset": [1], "DJC_DEPS_STRATEGY": "ignore"}))
+ rendered = render_dependencies(rendered_raw, strategy="fragment")
+
+ expected = """
+
+
+
+
+ """
+
+ 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,
+ # nor defines a `` or `` tag. In which case, the dependencies are not rendered.
+ def test_does_not_modify_html_when_component_used_but_nowhere_to_insert(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+
+
+
+ """
+
+ 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
+ # `PGxpbmsgaHJlZj0iL2NvbXBvbmVudHMvY2FjaGUvU2ltcGxlQ29tcG9uZW50XzMxMTA5Ny5jc3MiIG1lZGlhPSJhbGwiIHJlbD0ic3R5bGVzaGVldCI+` -> `` # noqa: E501
+ # `PHNjcmlwdCBzcmM9InNjcmlwdC5qcyI+PC9zY3JpcHQ+` -> ``
+ # `PHNjcmlwdCBzcmM9Ii9jb21wb25lbnRzL2NhY2hlL1NpbXBsZUNvbXBvbmVudF8zMTEwOTcuanMiPjwvc2NyaXB0Pg==` -> `` # noqa: E501
+ expected = """
+
+
+
+
+
+ """ # noqa: E501
+
+ assertHTMLEqual(expected, rendered)
+
+ def test_raises_if_script_end_tag_inside_component_js(self):
+ class ComponentWithScript(SimpleComponent):
+ js: types.js = """
+ console.log("");
+ """
+
+ registry.register(name="test", component=ComponentWithScript)
+
+ with pytest.raises(
+ RuntimeError,
+ match=re.escape("Content of `Component.js` for component 'ComponentWithScript' contains '' end tag."), # noqa: E501
+ ):
+ ComponentWithScript.render(kwargs={"variable": "foo"})
+
+ def test_raises_if_script_end_tag_inside_component_css(self):
+ class ComponentWithScript(SimpleComponent):
+ css: types.css = """
+ /* */
+ .xyz {
+ color: red;
+ }
+ """
+
+ registry.register(name="test", component=ComponentWithScript)
+
+ with pytest.raises(
+ RuntimeError,
+ match=re.escape("Content of `Component.css` for component 'ComponentWithScript' contains '' end tag."), # noqa: E501
+ ):
+ ComponentWithScript.render(kwargs={"variable": "foo"})
+
+
+@djc_test
+class TestDependenciesStrategyDocument:
+ def test_inserts_styles_and_script_to_default_places_if_not_overriden(self):
+ registry.register(name="test", component=SimpleComponent)
+
+ 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")
+
+ assert rendered.count("
+
+
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ body_re = re.compile(r"(.*?)", re.DOTALL)
+ rendered_body = body_re.search(rendered).group(1) # type: ignore[union-attr]
+
+ assertInHTML(
+ """',
+ rendered_body,
+ count=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
new file mode 100644
index 00000000..7b293f3f
--- /dev/null
+++ b/tests/test_dependency_manager.py
@@ -0,0 +1,461 @@
+import re
+from typing import List
+
+import pytest
+from playwright.async_api import Browser, Error, Page
+
+from django_components import types
+from django_components.testing import djc_test
+from tests.testutils import setup_test_config
+from tests.e2e.utils import TEST_SERVER_URL, with_playwright
+
+setup_test_config(
+ components={"autodiscover": False},
+ extra_settings={
+ "ROOT_URLCONF": "tests.test_dependency_manager",
+ },
+)
+
+urlpatterns: List = []
+
+
+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)
+
+ # 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 = '';
+ }
+ """
+ )
+
+ return page
+
+
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestDependencyManager:
+ @with_playwright
+ async def test_script_loads(self):
+ 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)"))
+ assert keys == ["createComponentsManager", "manager", "unescapeJs"]
+
+ keys = await page.evaluate("Object.keys(Components.manager)")
+ assert keys == [
+ "callComponent",
+ "registerComponent",
+ "registerComponentData",
+ "loadJs",
+ "loadCss",
+ "markScriptLoaded",
+ ]
+
+ await page.close()
+
+
+# Tests for `manager.loadJs()` / `manager.loadCss()` / `manager.markAsLoaded()`
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestLoadScript:
+ @with_playwright
+ async def test_load_js_scripts(self):
+ 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 = """() => {
+ const manager = Components.createComponentsManager();
+
+ const headBeforeFirstLoad = document.head.innerHTML;
+
+ // Adds a script the first time
+ manager.loadJs("");
+ const bodyAfterFirstLoad = document.body.innerHTML;
+
+ // Does not add it the second time
+ manager.loadJs("");
+ const bodyAfterSecondLoad = document.body.innerHTML;
+
+ // Adds different script
+ manager.loadJs("");
+ const bodyAfterThirdLoad = document.body.innerHTML;
+
+ const headAfterThirdLoad = document.head.innerHTML;
+
+ return {
+ bodyAfterFirstLoad,
+ bodyAfterSecondLoad,
+ bodyAfterThirdLoad,
+ headBeforeFirstLoad,
+ headAfterThirdLoad,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ assert data["bodyAfterFirstLoad"] == ''
+ assert data["bodyAfterSecondLoad"] == ''
+ assert data["bodyAfterThirdLoad"] == ''
+
+ assert data["headBeforeFirstLoad"] == data["headAfterThirdLoad"]
+ assert data["headBeforeFirstLoad"] == ""
+
+ await page.close()
+
+ @with_playwright
+ async def test_load_css_scripts(self):
+ 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 = """() => {
+ const manager = Components.createComponentsManager();
+
+ const bodyBeforeFirstLoad = document.body.innerHTML;
+
+ // Adds a script the first time
+ manager.loadCss("");
+ const headAfterFirstLoad = document.head.innerHTML;
+
+ // Does not add it the second time
+ manager.loadCss("");
+ const headAfterSecondLoad = document.head.innerHTML;
+
+ // Adds different script
+ manager.loadCss("");
+ const headAfterThirdLoad = document.head.innerHTML;
+
+ const bodyAfterThirdLoad = document.body.innerHTML;
+
+ return {
+ headAfterFirstLoad,
+ headAfterSecondLoad,
+ headAfterThirdLoad,
+ bodyBeforeFirstLoad,
+ bodyAfterThirdLoad,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ assert data["headAfterFirstLoad"] == ''
+ assert data["headAfterSecondLoad"] == ''
+ assert data["headAfterThirdLoad"] == ''
+
+ 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 _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 = """() => {
+ const manager = Components.createComponentsManager();
+
+ // Adds a script the first time
+ manager.markScriptLoaded('css', '/one/two');
+ manager.markScriptLoaded('js', '/one/three');
+
+ manager.loadCss("");
+ const headAfterFirstLoad = document.head.innerHTML;
+
+ manager.loadJs("");
+ const bodyAfterSecondLoad = document.body.innerHTML;
+
+ return {
+ headAfterFirstLoad,
+ bodyAfterSecondLoad,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ assert data["headAfterFirstLoad"] == ""
+ assert data["bodyAfterSecondLoad"] == ""
+
+ await page.close()
+
+
+# Tests for `manager.registerComponent()` / `registerComponentData()` / `callComponent()`
+@djc_test(
+ django_settings={
+ "STATIC_URL": "static/",
+ }
+)
+class TestCallComponent:
+ @with_playwright
+ async def test_calls_component_successfully(self):
+ 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 = '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):
@@ -89,8 +137,21 @@ class ComponentMediaRenderingTests(BaseTestCase):
{% load component_tags %}{% component_js_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=0)
+
+ assert rendered.count("'
def test_no_css_dependencies_when_no_components_used(self):
registry.register(name="test", component=SimpleComponent)
@@ -99,125 +160,116 @@ class ComponentMediaRenderingTests(BaseTestCase):
{% load component_tags %}{% component_css_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML(
- '',
- rendered,
- count=0,
- )
+ rendered: str = template.render(Context({}))
- def test_preload_dependencies_render_when_no_components_used(self):
+ assert rendered.count("'
+
+ def test_single_component_dependencies(self):
registry.register(name="test", component=SimpleComponent)
template_str: types.django_html = """
- {% load component_tags %}{% component_dependencies preload='test' %}
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' variable='foo' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=1)
+
+ assert rendered.count('') == 1 # Media.css
+ assert rendered.count("
+ {"loadedCssUrls": ["c3R5bGUuY3Nz"],
+ "loadedJsUrls": ["c2NyaXB0Lmpz"],
+ "toLoadCssTags": [],
+ "toLoadJsTags": []}
+
+ """,
rendered,
count=1,
)
- def test_preload_css_dependencies_render_when_no_components_used(self):
- registry.register(name="test", component=SimpleComponent)
-
- template_str: types.django_html = """
- {% load component_tags %}{% component_css_dependencies preload='test' %}
- """
- template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML(
- '',
- rendered,
- count=1,
- )
-
- def test_single_component_dependencies_render_when_used(self):
- registry.register(name="test", component=SimpleComponent)
-
- template_str: types.django_html = """
- {% load component_tags %}{% component_dependencies %}
- {% component 'test' variable='foo' %}{% endcomponent %}
- """
- template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML(
- '',
- rendered,
- count=1,
- )
- self.assertInHTML('', rendered, count=1)
+
+ assert rendered.count('') == 1 # Media.css
+ assert rendered.count("
+ {"loadedCssUrls": ["c3R5bGUuY3Nz"],
+ "loadedJsUrls": ["c2NyaXB0Lmpz"],
+ "toLoadCssTags": [],
+ "toLoadJsTags": []}
+
+ """,
rendered,
count=1,
)
- self.assertInHTML('', rendered, count=0)
+
+ assert rendered.count("') == 1 # Media.css
def test_single_component_js_dependencies(self):
registry.register(name="test", component=SimpleComponent)
@@ -227,228 +279,355 @@ class ComponentMediaRenderingTests(BaseTestCase):
{% component 'test' variable='foo' %}{% endcomponent %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=1)
+
+ # CSS NOT included
+ assert rendered.count("
+ {"loadedCssUrls": ["c3R5bGUuY3Nz"],
+ "loadedJsUrls": ["c2NyaXB0Lmpz"],
+ "toLoadCssTags": [],
+ "toLoadJsTags": []}
+
+ """,
+ rendered,
+ count=1,
+ )
def test_all_dependencies_are_rendered_for_component_with_multiple_dependencies(
self,
):
registry.register(name="test", component=MultistyleComponent)
template_str: types.django_html = """
- {% load component_tags %}{% component_dependencies %}
- {% component 'test' %}{% endcomponent %}
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'test' / %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=1)
+
+ assert rendered.count("
+
+ """,
rendered,
count=1,
)
- def test_all_js_dependencies_are_rendered_for_component_with_multiple_dependencies(
- self,
- ):
- registry.register(name="test", component=MultistyleComponent)
- template_str: types.django_html = """
- {% load component_tags %}{% component_js_dependencies %}
- {% component 'test' %}{% endcomponent %}
- """
- template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('
+
+ """,
rendered,
count=1,
)
- self.assertInHTML(
- '',
+
+ # Base64 encoding:
+ # `c3R5bGUuY3Nz` -> `style.css`
+ # `c3R5bGUyLmNzcw==` -> `style2.css`
+ # `c2NyaXB0Lmpz` -> `script.js`
+ # `c2NyaXB0Mi5qcw==` -> `script2.js`
+ assertInHTML(
+ """
+
+ """,
rendered,
count=1,
)
def test_no_dependencies_with_multiple_unused_components(self):
- registry.register(name="test1", component=SimpleComponent)
- registry.register(name="test2", component=SimpleComponentAlternate)
+ registry.register(name="inner", component=SimpleComponent)
+ registry.register(name="outer", component=SimpleComponentNested)
template_str: types.django_html = """
- {% load component_tags %}{% component_dependencies %}
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=0)
+
+ assert rendered.count("\n'
+ ' '
)
- def test_correct_css_dependencies_with_multiple_components(self):
- registry.register(name="test1", component=SimpleComponent)
- registry.register(name="test2", component=SimpleComponentAlternate)
+ def test_multiple_components_dependencies(self):
+ 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_css_dependencies %}
- {% component 'test1' 'variable' %}{% endcomponent %}
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'outer' variable='variable' %}
+ {% component 'other' variable='variable_inner' / %}
+ {% endcomponent %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML(
- '',
- rendered,
- count=1,
- )
- self.assertInHTML(
- '',
- rendered,
- count=0,
- )
+ rendered: str = template.render(Context({}))
- def test_correct_js_dependencies_with_multiple_components(self):
- registry.register(name="test1", component=SimpleComponent)
- registry.register(name="test2", component=SimpleComponentAlternate)
+ # Dependency manager script
+ # NOTE: Should be present only ONCE!
+ assertInHTML('', rendered, count=1)
- template_str: types.django_html = """
- {% load component_tags %}{% component_js_dependencies %}
- {% component 'test1' 'variable' %}{% endcomponent %}
- """
- template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML(''
- ''
- "Variable: value\n"
- ),
- )
+
+
+ """,
+ 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,
+ )
+
+ # Base64 encoding:
+ # `c3R5bGUuY3Nz` -> `style.css`
+ # `c3R5bGUyLmNzcw==` -> `style2.css`
+ # `eHl6MS5jc3M=` -> `xyz1.css`
+ # `L2NvbXBvbmVudHMvY2FjaGUvT3RoZXJDb21wb25lbnRfNjMyOWFlLmNzcw==` -> `/components/cache/OtherComponent_6329ae.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`
+ assertInHTML(
+ """
+
+ """,
+ rendered,
+ count=1,
+ )
+
+ def test_multiple_components_all_placeholders_removed(self):
+ registry.register(name="inner", component=SimpleComponent)
+ registry.register(name="outer", component=SimpleComponentNested)
+ registry.register(name="test", component=SimpleComponentWithSharedDependency)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component 'inner' variable='variable' / %}
+ {% component 'outer' variable='variable' / %}
+ {% component 'test' variable='variable' / %}
+ """
+ template = Template(template_str)
+ 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:
injected: {{ data|safe }}
+ {% slot 'content' default / %}
"
+
+ class Cache:
+ enabled = True
+ include_slots = True
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"input": kwargs["input"]}
+
+ Template(
+ """
+ {% component "test_component" input="cake" %}
+ ONE
+ {% endcomponent %}
+ """
+ ).render(Context({}))
+
+ Template(
+ """
+ {% component "test_component" input="cake" %}
+ ONE
+ {% endcomponent %}
+ """
+ ).render(Context({}))
+
+ # Check if the cache entry is set
+ component = TestComponent()
+ cache = caches["default"]
+
+ assert len(cache._cache) == 1
+ assert (
+ component.cache.get_entry("components:cache:87b9e27abdd3c6ef70982d065fc836a9")
+ == 'Hello cake \n ONE\n
' # noqa: E501
+ )
+
+ Template(
+ """
+ {% component "test_component" input="cake" %}
+ TWO
+ {% endcomponent %}
+ """
+ ).render(Context({}))
+
+ assert len(cache._cache) == 2
+ assert (
+ component.cache.get_entry("components:cache:1d7e3a58972550cf9bec18f457fb1a61")
+ == 'Hello cake \n TWO\n
' # noqa: E501
+ )
+
+ def test_cache_slots__strings(self):
+ class TestComponent(Component):
+ template = "Hello {{ input }} {% slot 'content' default / %}
"
+
+ class Cache:
+ enabled = True
+ include_slots = True
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"input": kwargs["input"]}
+
+ TestComponent.render(
+ kwargs={"input": "cake"},
+ slots={"content": "ONE"},
+ )
+ TestComponent.render(
+ kwargs={"input": "cake"},
+ slots={"content": "ONE"},
+ )
+
+ # Check if the cache entry is set
+ component = TestComponent()
+ cache = caches["default"]
+
+ assert len(cache._cache) == 1
+ assert (
+ component.cache.get_entry("components:cache:362766726cd0e991f33b0527ef8a513c")
+ == 'Hello cake ONE
'
+ )
+
+ TestComponent.render(
+ kwargs={"input": "cake"},
+ slots={"content": "TWO"},
+ )
+
+ assert len(cache._cache) == 2
+ assert (
+ component.cache.get_entry("components:cache:468e3f122ac305cff5d9096a3c548faf")
+ == 'Hello cake TWO
'
+ )
+
+ def test_cache_slots_raises_on_func(self):
+ class TestComponent(Component):
+ template = "Hello {{ input }} {% slot 'content' default / %}
"
+
+ class Cache:
+ enabled = True
+ include_slots = True
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"input": kwargs["input"]}
+
+ with pytest.raises(
+ ValueError,
+ match=re.escape(
+ "Cannot hash slot 'content' of component 'TestComponent' - Slot functions are unhashable."
+ ),
+ ):
+ TestComponent.render(
+ kwargs={"input": "cake"},
+ slots={"content": lambda ctx: "ONE"},
+ )
diff --git a/tests/test_component_defaults.py b/tests/test_component_defaults.py
new file mode 100644
index 00000000..e8ec6d6f
--- /dev/null
+++ b/tests/test_component_defaults.py
@@ -0,0 +1,171 @@
+from dataclasses import field
+
+from django.template import Context
+
+from django_components import Component, Default
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestComponentDefaults:
+ def test_input_defaults(self):
+ did_call_context = False
+
+ class TestComponent(Component):
+ template = ""
+
+ class Defaults:
+ variable = "test"
+ another = 1
+ extra = "extra"
+ fn = lambda: "fn_as_val" # noqa: E731
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_context
+ did_call_context = True
+
+ assert kwargs == {
+ "variable": "test", # User-given
+ "another": 1, # Default because missing
+ "extra": "extra", # Default because `None` was given
+ "fn": self.Defaults.fn, # Default because missing
+ }
+ assert self.raw_kwargs == {
+ "variable": "test", # User-given
+ "another": 1, # Default because missing
+ "extra": "extra", # Default because `None` was given
+ "fn": self.Defaults.fn, # Default because missing
+ }
+
+ # Check that args and slots are NOT affected by the defaults
+ assert args == [123]
+ assert [*slots.keys()] == ["my_slot"]
+ assert slots["my_slot"](Context(), None, None) == "MY_SLOT" # type: ignore[arg-type]
+
+ assert self.raw_args == [123]
+ assert [*self.raw_slots.keys()] == ["my_slot"]
+ assert self.raw_slots["my_slot"](Context(), None, None) == "MY_SLOT" # type: ignore[arg-type]
+
+ assert isinstance(self.context, Context)
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ TestComponent.render(
+ args=(123,),
+ kwargs={"variable": "test", "extra": None},
+ slots={"my_slot": "MY_SLOT"},
+ )
+
+ assert did_call_context
+
+ def test_factory_from_class(self):
+ did_call_context = False
+
+ class TestComponent(Component):
+ template = ""
+
+ class Defaults:
+ variable = "test"
+ fn = Default(lambda: "fn_as_factory")
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_context
+ did_call_context = True
+
+ assert kwargs == {
+ "variable": "test", # User-given
+ "fn": "fn_as_factory", # Default because missing
+ }
+ assert self.raw_kwargs == {
+ "variable": "test", # User-given
+ "fn": "fn_as_factory", # Default because missing
+ }
+ assert isinstance(self.context, Context)
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ TestComponent.render(
+ kwargs={"variable": "test"},
+ )
+
+ assert did_call_context
+
+ def test_factory_from_dataclass_field_value(self):
+ did_call_context = False
+
+ class TestComponent(Component):
+ template = ""
+
+ class Defaults:
+ variable = "test"
+ fn = field(default=lambda: "fn_as_factory")
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_context
+ did_call_context = True
+
+ assert kwargs == {
+ "variable": "test", # User-given
+ # NOTE: NOT a factory, because it was set as `field(default=...)`
+ "fn": self.Defaults.fn.default, # type: ignore[attr-defined]
+ }
+ assert self.raw_kwargs == {
+ "variable": "test", # User-given
+ # NOTE: NOT a factory, because it was set as `field(default=...)`
+ "fn": self.Defaults.fn.default, # type: ignore[attr-defined]
+ }
+ assert isinstance(self.context, Context)
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ TestComponent.render(
+ kwargs={"variable": "test"},
+ )
+
+ assert did_call_context
+
+ def test_factory_from_dataclass_field_factory(self):
+ did_call_context = False
+
+ class TestComponent(Component):
+ template = ""
+
+ class Defaults:
+ variable = "test"
+ fn = field(default_factory=lambda: "fn_as_factory")
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal did_call_context
+ did_call_context = True
+
+ assert kwargs == {
+ "variable": "test", # User-given
+ # NOTE: IS a factory, because it was set as `field(default_factory=...)`
+ "fn": "fn_as_factory", # Default because missing
+ }
+ assert self.raw_kwargs == {
+ "variable": "test", # User-given
+ # NOTE: IS a factory, because it was set as `field(default_factory=...)`
+ "fn": "fn_as_factory", # Default because missing
+ }
+ assert isinstance(self.context, Context)
+
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ TestComponent.render(
+ kwargs={"variable": "test"},
+ )
+
+ assert did_call_context
diff --git a/tests/test_component_highlight.py b/tests/test_component_highlight.py
new file mode 100644
index 00000000..7aa1c65a
--- /dev/null
+++ b/tests/test_component_highlight.py
@@ -0,0 +1,449 @@
+from django.template import Context, Template
+from pytest_django.asserts import assertHTMLEqual
+
+from django_components import Component, register, types
+from django_components.extensions.debug_highlight import apply_component_highlight, COLORS
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+def _prepare_template() -> Template:
+ @register("inner")
+ class InnerComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+ """
+
+ @register("outer")
+ class OuterComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ 1: {% slot "content" default / %}
+
+
+ 2: {% slot "content" default / %}
+
+
+ {% component "inner" %}
+ {{ content }}
+ {% endcomponent %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "content": kwargs["content"],
+ }
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% for item in items %}
+
+ {% component "outer" content=item / %}
+
+ {% endfor %}
+ """
+ template = Template(template_str)
+ return template
+
+
+@djc_test
+class TestComponentHighlight:
+ def test_component_highlight_fn(self):
+ # Test component highlighting
+ test_html = "Test content
"
+ component_name = "TestComponent"
+ result = apply_component_highlight("component", test_html, component_name)
+
+ # Check that the output contains the component name
+ assert component_name in result
+ # Check that the output contains the original HTML
+ assert test_html in result
+ # Check that the component colors are used
+ assert COLORS["component"].text_color in result
+ assert COLORS["component"].border_color in result
+
+ def test_slot_highlight_fn(self):
+ # Test slot highlighting
+ test_html = "Slot content"
+ slot_name = "content-slot"
+ result = apply_component_highlight("slot", test_html, slot_name)
+
+ # Check that the output contains the slot name
+ assert slot_name in result
+ # Check that the output contains the original HTML
+ assert test_html in result
+ # Check that the slot colors are used
+ assert COLORS["slot"].text_color in result
+ assert COLORS["slot"].border_color in result
+
+ @djc_test(
+ components_settings={
+ "extensions_defaults": {
+ "debug_highlight": {"highlight_components": True},
+ },
+ }
+ )
+ def test_component_highlight_extension(self):
+ template = _prepare_template()
+ rendered = template.render(Context({"items": [1, 2]}))
+
+ expected = """
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 1: 1
+
+
+ 2: 1
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # TODO_v1 - Remove this test once we've removed the `debug_highlight_components` setting.
+ @djc_test(components_settings={"debug_highlight_components": True})
+ def test_component_highlight_extension__legacy(self):
+ template = _prepare_template()
+ rendered = template.render(Context({"items": [1, 2]}))
+
+ expected = """
+
+
+
+
+
+
+
+
+
+
+ 1: 2
+
+
+ 2: 2
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 1: 1
+
+
+ 2: 1
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(
+ components_settings={
+ "extensions_defaults": {
+ "debug_highlight": {"highlight_slots": True},
+ },
+ }
+ )
+ def test_slot_highlight_extension(self):
+ template = _prepare_template()
+ rendered = template.render(Context({"items": [1, 2]}))
+
+ expected = """
+
+
+
+
+
+
+
+
+
+
+ 1: 2
+
+
+ 2: 2
+
+
+
+
+
+
+
+
+ 1:
+
+
+
+ 1
+
+
+ 2:
+
+
+
+ 1
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # TODO_v1 - Remove this test once we've removed the `debug_highlight_slots` setting.
+ @djc_test(components_settings={"debug_highlight_slots": True})
+ def test_slot_highlight_extension__legacy(self):
+ template = _prepare_template()
+ rendered = template.render(Context({"items": [1, 2]}))
+
+ expected = """
+
+
+
+
+
+ 1:
+
+
+
+ 2
+
+
+ 2:
+
+
+
+ 2
+
+
+
+
+
+
+
+
+ 1:
+
+
+
+ 1
+
+
+ 2:
+
+
+
+ 1
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ def test_highlight_on_component_class(self):
+ @register("inner")
+ class InnerComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+
+
+
+ 1:
+
+
+
+ 2
+
+
+ 2:
+
+
+
+ 2
+
+
+
+ """
+
+ class DebugHighlight:
+ highlight_components = True
+ highlight_slots = True
+
+ template = Template("""
+ {% load component_tags %}
+ {% component "inner" %}
+ {{ content }}
+ {% endcomponent %}
+ """)
+ rendered = template.render(Context({"content": "Hello, world!"}))
+
+ expected = """
+
+
+ 1: {% slot "content" default / %}
+
+
+ 2: {% slot "content" default / %}
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
diff --git a/tests/test_component_media.py b/tests/test_component_media.py
index 07f285e2..3bce7716 100644
--- a/tests/test_component_media.py
+++ b/tests/test_component_media.py
@@ -1,137 +1,239 @@
import os
+import re
import sys
from pathlib import Path
+from textwrap import dedent
+from typing import Optional
+import pytest
+from django.core.exceptions import ImproperlyConfigured
from django.forms.widgets import Media
from django.template import Context, Template
from django.templatetags.static import static
-from django.test import override_settings
from django.utils.html import format_html, html_safe
from django.utils.safestring import mark_safe
+from pytest_django.asserts import assertHTMLEqual, assertInHTML
-from django_components import Component, registry, types
+from django_components import Component, autodiscover, registry, render_dependencies, types
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase, autodiscover_with_cleanup
+from django_components.testing import djc_test
+from .testutils import setup_test_config
-setup_test_config()
+setup_test_config({"autodiscover": False})
-class InlineComponentTest(BaseTestCase):
- def test_html(self):
- class InlineHTMLComponent(Component):
- template = "
+
+
+ 1:
+
+
+
+ Hello, world!
+
+
+ 2:
+
+
+
+ Hello, world!
+
+ Hello Inline
"
-
- comp = InlineHTMLComponent("inline_html_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Hello Inline
",
- )
-
- def test_html_and_css(self):
- class HTMLCSSComponent(Component):
- template = "Content
"
+# "Main media" refer to the HTML, JS, and CSS set on the Component class itself
+# (as opposed via the `Media` class). These have special handling in the Component.
+@djc_test
+class TestMainMedia:
+ def test_html_js_css_inlined(self):
+ class TestComponent(Component):
+ template = dedent(
+ """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ Content
+ """
+ )
css = ".html-css-only { color: blue; }"
+ js = "console.log('HTML and JS only');"
- comp = HTMLCSSComponent("html_css_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Content
",
+ assert TestComponent.css == ".html-css-only { color: blue; }"
+ assert TestComponent.js == "console.log('HTML and JS only');"
+
+ rendered = TestComponent.render()
+
+ assertInHTML(
+ 'Content
',
+ rendered,
)
- self.assertHTMLEqual(
- comp.render_css_dependencies(),
+ assertInHTML(
"",
+ rendered,
)
-
- def test_html_and_js(self):
- class HTMLJSComponent(Component):
- template = "Content
"
- js = "console.log('HTML and JS only');"
-
- comp = HTMLJSComponent("html_js_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Content
",
- )
- self.assertHTMLEqual(
- comp.render_js_dependencies(),
+ assertInHTML(
"",
+ rendered,
)
- def test_html_inline_and_css_js_files(self):
- class HTMLStringFileCSSJSComponent(Component):
- template = "Content
"
-
- class Media:
- css = "path/to/style.css"
- js = "path/to/script.js"
-
- comp = HTMLStringFileCSSJSComponent("html_string_file_css_js_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Content
",
- )
- self.assertHTMLEqual(
- comp.render_dependencies(),
+ # Check that the HTML / JS / CSS can be accessed on the component class
+ assert TestComponent.template == dedent(
"""
-
-
- """,
- )
-
- def test_html_js_inline_and_css_file(self):
- class HTMLStringFileCSSJSComponent(Component):
- template = "Content
"
- js = "console.log('HTML and JS only');"
-
- class Media:
- css = "path/to/style.css"
-
- comp = HTMLStringFileCSSJSComponent("html_string_file_css_js_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Content
",
- )
- self.assertHTMLEqual(
- comp.render_dependencies(),
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ Content
"""
-
-
- """,
)
+ assert TestComponent.css == ".html-css-only { color: blue; }"
+ assert TestComponent.js == "console.log('HTML and JS only');"
- def test_html_css_inline_and_js_file(self):
- class HTMLStringFileCSSJSComponent(Component):
- template = "Content
"
- css = ".html-string-file { color: blue; }"
+ assert isinstance(TestComponent._template, Template)
+ assert TestComponent._template.origin.component_cls is TestComponent
- class Media:
- js = "path/to/script.js"
+ @djc_test(
+ django_settings={
+ "STATICFILES_DIRS": [
+ os.path.join(Path(__file__).resolve().parent, "static_root"),
+ ],
+ }
+ )
+ def test_html_js_css_filepath_rel_to_component(self):
+ from tests.test_app.components.app_lvl_comp.app_lvl_comp import AppLvlCompComponent
- comp = HTMLStringFileCSSJSComponent("html_string_file_css_js_component")
- self.assertHTMLEqual(
- comp.render(Context({})),
- "Content
",
- )
- self.assertHTMLEqual(
- comp.render_dependencies(),
+ class TestComponent(AppLvlCompComponent):
+ pass
+
+ registry.register("test", TestComponent)
+
+ assert ".html-css-only {\n color: blue;\n}" in TestComponent.css # type: ignore[operator]
+ assert 'console.log("JS file");' in TestComponent.js # type: ignore[operator]
+
+ rendered = Template(
"""
-
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component "test" variable="test" / %}
+ """
+ ).render(Context())
+
+ assertInHTML(
+ """
+
""",
+ rendered,
+ )
+ assertInHTML(
+ "",
+ rendered,
+ )
+ assertInHTML(
+ '',
+ rendered,
)
- def test_html_variable(self):
- class VariableHTMLComponent(Component):
- def get_template(self, context):
- return Template("{{ variable }}
")
-
- comp = VariableHTMLComponent("variable_html_component")
- context = Context({"variable": "Dynamic Content"})
- self.assertHTMLEqual(
- comp.render(context),
- "Dynamic Content
",
+ # Check that the HTML / JS / CSS can be accessed on the component class
+ assert TestComponent.template == (
+ '\n"
)
+ assert TestComponent.css == ".html-css-only {\n color: blue;\n}\n"
+ assert TestComponent.js == 'console.log("JS file");\n'
+
+ assert isinstance(TestComponent._template, Template)
+ assert TestComponent._template.origin.component_cls is TestComponent
+
+ @djc_test(
+ django_settings={
+ "STATICFILES_DIRS": [
+ os.path.join(Path(__file__).resolve().parent, "static_root"),
+ ],
+ }
+ )
+ def test_html_js_css_filepath_from_static(self):
+ class TestComponent(Component):
+ template_file = "test_app_simple_template.html"
+ css_file = "style.css"
+ js_file = "script.js"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs["variable"],
+ }
+
+ registry.register("test", TestComponent)
+
+ assert "Variable: {{ variable }}" in TestComponent.template # type: ignore[operator]
+ assert ".html-css-only {\n color: blue;\n}" in TestComponent.css # type: ignore[operator]
+ assert 'console.log("HTML and JS only");' in TestComponent.js # type: ignore[operator]
+
+ assert isinstance(TestComponent._template, Template)
+ assert TestComponent._template.origin.component_cls is TestComponent
+
+ rendered = Template(
+ """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
+ {% component "test" variable="test" / %}
+ """
+ ).render(Context())
+
+ assert 'Variable: test' in rendered
+ assertInHTML(
+ "",
+ rendered,
+ )
+ assertInHTML(
+ '',
+ rendered,
+ )
+
+ # Check that the HTML / JS / CSS can be accessed on the component class
+ assert TestComponent.template == "Variable: {{ variable }}\n"
+ assert TestComponent.css == (
+ "/* Used in `MainMediaTest` tests in `test_component_media.py` */\n"
+ ".html-css-only {\n"
+ " color: blue;\n"
+ "}"
+ )
+ assert TestComponent.js == (
+ '/* Used in `MainMediaTest` tests in `test_component_media.py` */\nconsole.log("HTML and JS only");\n'
+ )
+
+ @djc_test(
+ django_settings={
+ "STATICFILES_DIRS": [
+ os.path.join(Path(__file__).resolve().parent, "static_root"),
+ ],
+ }
+ )
+ def test_html_js_css_filepath_lazy_loaded(self):
+ from tests.test_app.components.app_lvl_comp.app_lvl_comp import AppLvlCompComponent
+
+ class TestComponent(AppLvlCompComponent):
+ pass
+
+ # NOTE: Currently the components' JS/CSS are loaded eagerly, to make the JS/CSS
+ # files available via endpoints. If that is no longer true, uncomment the
+ # following lines to test the lazy loading of the CSS.
+ #
+ # # Since this is a subclass, actual CSS is defined on the parent class, and thus
+ # # the corresponding ComponentMedia instance is also on the parent class.
+ # assert AppLvlCompComponent._component_media.css is UNSET # type: ignore[attr-defined]
+ # assert AppLvlCompComponent._component_media.css_file == "app_lvl_comp.css" # type: ignore[attr-defined]
+ # assert AppLvlCompComponent._component_media._template is UNSET # type: ignore[attr-defined]
+ #
+ # # Access the property to load the CSS
+ # _ = TestComponent.css
+
+ assert AppLvlCompComponent._component_media.css == (".html-css-only {\n" " color: blue;\n" "}\n") # type: ignore[attr-defined]
+ assert AppLvlCompComponent._component_media.css_file == "app_lvl_comp/app_lvl_comp.css" # type: ignore[attr-defined]
+
+ # Also check JS and HTML while we're at it
+ assert AppLvlCompComponent._component_media.template == ( # type: ignore[attr-defined]
+ '\n"
+ )
+ assert AppLvlCompComponent._component_media.template_file == "app_lvl_comp/app_lvl_comp.html" # type: ignore[attr-defined]
+ assert AppLvlCompComponent._component_media.js == 'console.log("JS file");\n' # type: ignore[attr-defined]
+ assert AppLvlCompComponent._component_media.js_file == "app_lvl_comp/app_lvl_comp.js" # type: ignore[attr-defined]
+
+ assert isinstance(AppLvlCompComponent._component_media._template, Template) # type: ignore[attr-defined]
+ assert AppLvlCompComponent._component_media._template.origin.component_cls is AppLvlCompComponent # type: ignore[attr-defined]
+
def test_html_variable_filtered(self):
class FilteredComponent(Component):
template: types.django_html = """
@@ -139,134 +241,87 @@ class InlineComponentTest(BaseTestCase):
Var2 (uppercased): {{ var2|upper }}
"""
- def get_context_data(self, var1=None, var2=None):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "var1": var1,
- "var2": var2,
+ "var1": kwargs["var1"],
+ "var2": kwargs["var2"],
}
rendered = FilteredComponent.render(kwargs={"var1": "test1", "var2": "test2"})
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- Var1: test1
- Var2 (uppercased): TEST2
+ Var1: test1
+ Var2 (uppercased): TEST2
""",
)
-class ComponentMediaTests(BaseTestCase):
- def test_css_and_js(self):
- class SimpleComponent(Component):
- template: types.django_html = """
- Variable: {{ variable }}
- """
-
- class Media:
- css = "style.css"
- js = "script.js"
-
- comp = SimpleComponent("simple_component")
- self.assertHTMLEqual(
- comp.render_dependencies(),
- """
-
-
- """,
- )
-
- def test_css_only(self):
- class SimpleComponent(Component):
- template: types.django_html = """
- Variable: {{ variable }}
- """
-
- class Media:
- css = "style.css"
-
- comp = SimpleComponent("simple_component")
-
- self.assertHTMLEqual(
- comp.render_dependencies(),
- """
-
- """,
- )
-
- def test_js_only(self):
- class SimpleComponent(Component):
- template: types.django_html = """
- Variable: {{ variable }}
- """
-
- class Media:
- js = "script.js"
-
- comp = SimpleComponent("simple_component")
-
- self.assertHTMLEqual(
- comp.render_dependencies(),
- """
-
- """,
- )
-
+@djc_test
+class TestComponentMedia:
def test_empty_media(self):
class SimpleComponent(Component):
template: types.django_html = """
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
Variable: {{ variable }}
"""
class Media:
pass
- comp = SimpleComponent("simple_component")
+ rendered = SimpleComponent.render()
- self.assertHTMLEqual(comp.render_dependencies(), "")
+ assert rendered.count("
-
- Parent content
- {% component name="variable_display" shadowing_variable='override' new_variable='unique_val' %} - {% endcomponent %} -
- {% slot 'content' %}
-
+ Slot content
- {% component name="variable_display" shadowing_variable='slot_default_override' new_variable='slot_default_unique' %} +@djc_test +class TestMediaRelativePath: + def _gen_parent_component(self): + class ParentComponent(Component): + template: types.django_html = """ + {% load component_tags %} +
+
- """ # noqa
+ Parent content
+ {% component "variable_display" shadowing_variable='override' new_variable='unique_val' %} {% endcomponent %} - {% endslot %} -
+ {% slot 'content' %}
+
+ """ # noqa
- def get_context_data(self):
- return {"shadowing_variable": "NOT SHADOWED"}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"shadowing_variable": "NOT SHADOWED"}
- class VariableDisplay(Component):
- template: types.django_html = """
- {% load component_tags %}
- Slot content
+ {% component "variable_display" shadowing_variable='slot_default_override' new_variable='slot_default_unique' %} + {% endcomponent %} + {% endslot %} +Shadowing variable = {{ shadowing_variable }}
-Uniquely named variable = {{ unique_variable }}
- """ + return ParentComponent - def get_context_data(self, shadowing_variable=None, new_variable=None): - context = {} - if shadowing_variable is not None: - context["shadowing_variable"] = shadowing_variable - if new_variable is not None: - context["unique_variable"] = new_variable - return context + def _gen_variable_display_component(self): + class VariableDisplay(Component): + template: types.django_html = """ + {% load component_tags %} +Shadowing variable = {{ shadowing_variable }}
+Uniquely named variable = {{ unique_variable }}
+ """ - def setUp(self): - super().setUp() - registry.register(name="parent_component", component=self.ParentComponent) - registry.register(name="variable_display", component=self.VariableDisplay) + def get_template_data(self, args, kwargs, slots, context): + context = {} + if kwargs["shadowing_variable"] is not None: + context["shadowing_variable"] = kwargs["shadowing_variable"] + if kwargs["new_variable"] is not None: + context["unique_variable"] = kwargs["new_variable"] + return context + + return VariableDisplay # Settings required for autodiscover to work - @override_settings( - BASE_DIR=Path(__file__).resolve().parent, - STATICFILES_DIRS=[ - Path(__file__).resolve().parent / "components", - ], + @djc_test( + django_settings={ + "BASE_DIR": Path(__file__).resolve().parent, + "STATICFILES_DIRS": [ + Path(__file__).resolve().parent / "components", + ], + } ) def test_component_with_relative_media_paths(self): + registry.register(name="parent_component", component=self._gen_parent_component()) + registry.register(name="variable_display", component=self._gen_variable_display_component()) + # Ensure that the module is executed again after import in autodiscovery if "tests.components.relative_file.relative_file" in sys.modules: del sys.modules["tests.components.relative_file.relative_file"] # Fix the paths, since the "components" dir is nested - with autodiscover_with_cleanup(map_module=lambda p: f"tests.{p}"): - # Make sure that only relevant components are registered: - comps_to_remove = [ - comp_name - for comp_name in registry.all() - if comp_name not in ["relative_file_component", "parent_component", "variable_display"] - ] - for comp_name in comps_to_remove: - registry.unregister(comp_name) + autodiscover(map_module=lambda p: f"tests.{p}" if p.startswith("components") else p) - template_str: types.django_html = """ - {% load component_tags %}{% component_dependencies %} - {% component name='relative_file_component' variable=variable %} - {% endcomponent %} + # Make sure that only relevant components are registered: + comps_to_remove = [ + comp_name + for comp_name in registry.all() + if comp_name not in ["relative_file_component", "parent_component", "variable_display"] + ] + for comp_name in comps_to_remove: + registry.unregister(comp_name) + + template_str: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + {% component 'relative_file_component' variable=variable / %} + """ + template = Template(template_str) + rendered = render_dependencies(template.render(Context({"variable": "test"}))) + + assertInHTML('', rendered) + + assertInHTML( """ - template = Template(template_str) - rendered = template.render(Context({"variable": "test"})) - self.assertHTMLEqual( - rendered, - """ - - - - """, - ) + + """, + rendered, + ) + + assertInHTML('', rendered) # Settings required for autodiscover to work - @override_settings( - BASE_DIR=Path(__file__).resolve().parent, - STATICFILES_DIRS=[ - Path(__file__).resolve().parent / "components", - ], + @djc_test( + django_settings={ + "BASE_DIR": Path(__file__).resolve().parent, + "STATICFILES_DIRS": [ + Path(__file__).resolve().parent / "components", + ], + } ) def test_component_with_relative_media_paths_as_subcomponent(self): + registry.register(name="parent_component", component=self._gen_parent_component()) + registry.register(name="variable_display", component=self._gen_variable_display_component()) + # Ensure that the module is executed again after import in autodiscovery if "tests.components.relative_file.relative_file" in sys.modules: del sys.modules["tests.components.relative_file.relative_file"] # Fix the paths, since the "components" dir is nested - with autodiscover_with_cleanup(map_module=lambda p: f"tests.{p}"): - registry.unregister("relative_file_pathobj_component") + autodiscover(map_module=lambda p: f"tests.{p}" if p.startswith("components") else p) - template_str: types.django_html = """ - {% load component_tags %}{% component_dependencies %} - {% component 'parent_component' %} - {% fill 'content' %} - {% component name='relative_file_component' variable='hello' %} - {% endcomponent %} - {% endfill %} - {% endcomponent %} - """ - template = Template(template_str) - rendered = template.render(Context({})) - self.assertIn('', rendered, rendered) + registry.unregister("relative_file_pathobj_component") + + template_str: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + {% component 'parent_component' %} + {% fill 'content' %} + {% component 'relative_file_component' variable='hello' %} + {% endcomponent %} + {% endfill %} + {% endcomponent %} + """ + template = Template(template_str) + rendered = template.render(Context({})) + assertInHTML('', rendered) # Settings required for autodiscover to work - @override_settings( - BASE_DIR=Path(__file__).resolve().parent, - STATICFILES_DIRS=[ - Path(__file__).resolve().parent / "components", - ], + @djc_test( + django_settings={ + "BASE_DIR": Path(__file__).resolve().parent, + "STATICFILES_DIRS": [ + Path(__file__).resolve().parent / "components", + ], + } ) def test_component_with_relative_media_does_not_trigger_safestring_path_at__new__(self): """ @@ -841,26 +1021,725 @@ class MediaRelativePathTests(BaseTestCase): then we force to call `static`. And if this happens during `collectstatic` run, then this triggers an error, because `static` is called before the static files exist. - https://github.com/EmilStenstrom/django-components/issues/522#issuecomment-2173577094 + https://github.com/django-components/django-components/issues/522#issuecomment-2173577094 """ + registry.register(name="parent_component", component=self._gen_parent_component()) + registry.register(name="variable_display", component=self._gen_variable_display_component()) # Ensure that the module is executed again after import in autodiscovery if "tests.components.relative_file_pathobj.relative_file_pathobj" in sys.modules: del sys.modules["tests.components.relative_file_pathobj.relative_file_pathobj"] # Fix the paths, since the "components" dir is nested - with autodiscover_with_cleanup(map_module=lambda p: f"tests.{p}"): - # Mark the PathObj instances of 'relative_file_pathobj_component' so they won raise - # error PathObj.__str__ is triggered. - CompCls = registry.get("relative_file_pathobj_component") - CompCls.Media.js[0].throw_on_calling_str = False # type: ignore - CompCls.Media.css["all"][0].throw_on_calling_str = False # type: ignore + autodiscover(map_module=lambda p: f"tests.{p}" if p.startswith("components") else p) - rendered = CompCls().render_dependencies() - self.assertHTMLEqual( - rendered, - """ - - - """, - ) + # Mark the PathObj instances of 'relative_file_pathobj_component' so they won't raise + # error if PathObj.__str__ is triggered. + CompCls = registry.get("relative_file_pathobj_component") + CompCls.Media.js[0].throw_on_calling_str = False # type: ignore + CompCls.Media.css["all"][0].throw_on_calling_str = False # type: ignore + + rendered = CompCls.render(kwargs={"variable": "abc"}) + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + + +@djc_test +class TestSubclassingAttributes: + def test_both_js_and_js_file_none(self): + class TestComp(Component): + js = None + js_file = None + template = None + template_file = None + + assert TestComp.js is None + assert TestComp.js_file is None + assert TestComp.template is None + assert TestComp.template_file is None + + def test_mixing_none_and_non_none_raises(self): + with pytest.raises( + ImproperlyConfigured, + match=re.escape("Received non-empty value from both 'template' and 'template_file' in Component TestComp"), + ): + + class TestComp(Component): + js = "console.log('hi')" + js_file = None + template = "hi
" + template_file = None + + def test_both_non_none_raises(self): + with pytest.raises( + ImproperlyConfigured, + match=re.escape("Received non-empty value from both 'template' and 'template_file' in Component TestComp"), + ): + + class TestComp(Component): + js = "console.log('hi')" + js_file = "file.js" + template = "hi
" + template_file = "file.html" + + def test_parent_non_null_child_non_null(self): + class ParentComp(Component): + js = "console.log('parent')" + template = "parent
" + + class TestComp(ParentComp): + js = "console.log('child')" + template = "child
" + + assert TestComp.js == "console.log('child')" + assert TestComp.js_file is None + assert TestComp.template == "child
" + assert TestComp.template_file is None + + assert isinstance(ParentComp._template, Template) + assert ParentComp._template.source == "parent
" + assert ParentComp._template.origin.component_cls == ParentComp + + assert isinstance(TestComp._template, Template) + assert TestComp._template.source == "child
" + assert TestComp._template.origin.component_cls == TestComp + + def test_parent_null_child_non_null(self): + class ParentComp(Component): + js = None + template = None + + class TestComp(ParentComp): + js = "console.log('child')" + template = "child
" + + assert TestComp.js == "console.log('child')" + assert TestComp.js_file is None + assert TestComp.template == "child
" + assert TestComp.template_file is None + + assert ParentComp._template is None + + assert isinstance(TestComp._template, Template) + assert TestComp._template.source == "child
" + assert TestComp._template.origin.component_cls == TestComp + + def test_parent_non_null_child_null(self): + class ParentComp(Component): + js: Optional[str] = "console.log('parent')" + template: Optional[str] = "parent
" + + class TestComp(ParentComp): + js = None + template = None + + assert TestComp.js is None + assert TestComp.js_file is None + assert TestComp.template is None + assert TestComp.template_file is None + + assert TestComp._template is None + + assert isinstance(ParentComp._template, Template) + assert ParentComp._template.source == "parent
" + assert ParentComp._template.origin.component_cls == ParentComp + + def test_parent_null_child_null(self): + class ParentComp(Component): + js = None + template = None + + class TestComp(ParentComp): + js = None + template = None + + assert TestComp.js is None + assert TestComp.js_file is None + assert TestComp.template is None + assert TestComp.template_file is None + + assert TestComp._template is None + assert ParentComp._template is None + + def test_grandparent_non_null_parent_pass_child_pass(self): + class GrandParentComp(Component): + js = "console.log('grandparent')" + template = "grandparent
" + + class ParentComp(GrandParentComp): + pass + + class TestComp(ParentComp): + pass + + assert TestComp.js == "console.log('grandparent')" + assert TestComp.js_file is None + assert TestComp.template == "grandparent
" + assert TestComp.template_file is None + + assert isinstance(GrandParentComp._template, Template) + assert GrandParentComp._template.source == "grandparent
" + assert GrandParentComp._template.origin.component_cls == GrandParentComp + + assert isinstance(ParentComp._template, Template) + assert ParentComp._template.source == "grandparent
" + assert ParentComp._template.origin.component_cls == ParentComp + + assert isinstance(TestComp._template, Template) + assert TestComp._template.source == "grandparent
" + assert TestComp._template.origin.component_cls == TestComp + + def test_grandparent_non_null_parent_null_child_pass(self): + class GrandParentComp(Component): + js: Optional[str] = "console.log('grandparent')" + template: Optional[str] = "grandparent
" + + class ParentComp(GrandParentComp): + js = None + template = None + + class TestComp(ParentComp): + pass + + assert TestComp.js is None + assert TestComp.js_file is None + assert TestComp.template is None + assert TestComp.template_file is None + + assert isinstance(GrandParentComp._template, Template) + assert GrandParentComp._template.source == "grandparent
" + assert GrandParentComp._template.origin.component_cls == GrandParentComp + + assert ParentComp._template is None + assert TestComp._template is None + + def test_grandparent_non_null_parent_pass_child_non_null(self): + class GrandParentComp(Component): + js = "console.log('grandparent')" + template = "grandparent
" + + class ParentComp(GrandParentComp): + pass + + class TestComp(ParentComp): + js = "console.log('child')" + template = "child
" + + assert TestComp.js == "console.log('child')" + assert TestComp.js_file is None + assert TestComp.template == "child
" + assert TestComp.template_file is None + + assert isinstance(GrandParentComp._template, Template) + assert GrandParentComp._template.source == "grandparent
" + assert GrandParentComp._template.origin.component_cls == GrandParentComp + + assert isinstance(ParentComp._template, Template) + assert ParentComp._template.source == "grandparent
" + assert ParentComp._template.origin.component_cls == ParentComp + + assert isinstance(TestComp._template, Template) + assert TestComp._template.source == "child
" + assert TestComp._template.origin.component_cls == TestComp + + def test_grandparent_null_parent_pass_child_non_null(self): + class GrandParentComp(Component): + js = None + template = None + + class ParentComp(GrandParentComp): + pass + + class TestComp(ParentComp): + js = "console.log('child')" + template = "child
" + + assert TestComp.js == "console.log('child')" + assert TestComp.js_file is None + assert TestComp.template == "child
" + assert TestComp.template_file is None + + assert GrandParentComp._template is None + assert ParentComp._template is None + + assert isinstance(TestComp._template, Template) + assert TestComp._template.source == "child
" + assert TestComp._template.origin.component_cls == TestComp + + +@djc_test +class TestSubclassingMedia: + def test_media_in_child_and_parent(self): + class ParentComponent(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "parent.css" + js = "parent.js" + + class ChildComponent(ParentComponent): + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '' + ) + + def test_media_in_child_and_grandparent(self): + class GrandParentComponent(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "grandparent.css" + js = "grandparent.js" + + # `pass` means that we inherit `Media` from `GrandParentComponent` + class ParentComponent(GrandParentComponent): + pass + + class ChildComponent(ParentComponent): + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '' + ) + + # Check that setting `Media = None` on a child class means that we will NOT inherit `Media` from the parent class + def test_media_in_child_and_grandparent__inheritance_off(self): + class GrandParentComponent(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "grandparent.css" + js = "grandparent.js" + + # `None` means that we will NOT inherit `Media` from `GrandParentComponent` + class ParentComponent(GrandParentComponent): + Media = None # type: ignore[assignment] + + class ChildComponent(ParentComponent): + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert "grandparent.css" not in rendered + assert "grandparent.js" not in rendered + + assert str(ChildComponent.media) == ( + '\n' + ) + + def test_media_in_parent_and_grandparent(self): + class GrandParentComponent(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "grandparent.css" + js = "grandparent.js" + + class ParentComponent(GrandParentComponent): + class Media: + css = "parent.css" + js = "parent.js" + + class ChildComponent(ParentComponent): + pass + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '' + ) + + def test_media_in_multiple_bases(self): + class GrandParent1Component(Component): + class Media: + css = "grandparent1.css" + js = "grandparent1.js" + + class GrandParent2Component(Component): + pass + + # NOTE: The bases don't even have to be Component classes, + # as long as they have the nested `Media` class. + class GrandParent3Component: + # NOTE: When we don't subclass `Component`, we have to correctly format the `Media` class + class Media: + css = {"all": ["grandparent3.css"]} + js = ["grandparent3.js"] + + class GrandParent4Component: + pass + + class Parent1Component(GrandParent1Component, GrandParent2Component): + class Media: + css = "parent1.css" + js = "parent1.js" + + # `pass` means that we inherit `Media` from `GrandParent3Component` and `GrandParent4Component` + class Parent2Component(GrandParent3Component, GrandParent4Component): + pass + + class ChildComponent(Parent1Component, Parent2Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '' + ) + + # Check that setting `Media = None` on a child class means that we will NOT inherit `Media` from the parent class + def test_media_in_multiple_bases__inheritance_off(self): + class GrandParent1Component(Component): + class Media: + css = "grandparent1.css" + js = "grandparent1.js" + + class GrandParent2Component(Component): + pass + + # NOTE: The bases don't even have to be Component classes, + # as long as they have the nested `Media` class. + class GrandParent3Component: + # NOTE: When we don't subclass `Component`, we have to correctly format the `Media` class + class Media: + css = {"all": ["grandparent3.css"]} + js = ["grandparent3.js"] + + class GrandParent4Component: + pass + + class Parent1Component(GrandParent1Component, GrandParent2Component): + class Media: + css = "parent1.css" + js = "parent1.js" + + # `None` means that we will NOT inherit `Media` from `GrandParent3Component` and `GrandParent4Component` + class Parent2Component(GrandParent3Component, GrandParent4Component): + Media = None # type: ignore[assignment] + + class ChildComponent(Parent1Component, Parent2Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert "grandparent3.css" not in rendered + assert "grandparent3.js" not in rendered + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '\n' + '\n' + '' + ) + + def test_extend_false_in_child(self): + class Parent1Component(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "parent1.css" + js = "parent1.js" + + class Parent2Component(Component): + class Media: + css = "parent2.css" + js = "parent2.js" + + class ChildComponent(Parent1Component, Parent2Component): + class Media: + extend = False + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assert "parent1.css" not in rendered + assert "parent2.css" not in rendered + assertInHTML('', rendered) + + assert "parent1.js" not in rendered + assert "parent2.js" not in rendered + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + ) + + def test_extend_false_in_parent(self): + class GrandParentComponent(Component): + class Media: + css = "grandparent.css" + js = "grandparent.js" + + class Parent1Component(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "parent1.css" + js = "parent1.js" + + class Parent2Component(GrandParentComponent): + class Media: + extend = False + css = "parent2.css" + js = "parent2.js" + + class ChildComponent(Parent1Component, Parent2Component): + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assert "grandparent.css" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert "grandparent.js" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '\n' + '\n' + '' + ) + + def test_extend_list_in_child(self): + class Parent1Component(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "parent1.css" + js = "parent1.js" + + class Parent2Component(Component): + class Media: + css = "parent2.css" + js = "parent2.js" + + class Other1Component(Component): + class Media: + css = "other1.css" + js = "other1.js" + + class Other2Component: + class Media: + css = {"all": ["other2.css"]} + js = ["other2.js"] + + class ChildComponent(Parent1Component, Parent2Component): + class Media: + extend = [Other1Component, Other2Component] + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assert "parent1.css" not in rendered + assert "parent2.css" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert "parent1.js" not in rendered + assert "parent2.js" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '\n' + '\n' + '' + ) + + def test_extend_list_in_parent(self): + class Other1Component(Component): + class Media: + css = "other1.css" + js = "other1.js" + + class Other2Component: + class Media: + css = {"all": ["other2.css"]} + js = ["other2.js"] + + class GrandParentComponent(Component): + class Media: + css = "grandparent.css" + js = "grandparent.js" + + class Parent1Component(Component): + template: types.django_html = """ + {% load component_tags %} + {% component_js_dependencies %} + {% component_css_dependencies %} + """ + + class Media: + css = "parent1.css" + js = "parent1.js" + + class Parent2Component(GrandParentComponent): + class Media: + extend = [Other1Component, Other2Component] + css = "parent2.css" + js = "parent2.js" + + class ChildComponent(Parent1Component, Parent2Component): + class Media: + css = "child.css" + js = "child.js" + + rendered = ChildComponent.render() + + assert "grandparent.css" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert "grandparent.js" not in rendered + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + assertInHTML('', rendered) + + assert str(ChildComponent.media) == ( + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '\n' + '' + ) diff --git a/tests/test_component_typing.py b/tests/test_component_typing.py new file mode 100644 index 00000000..33a9297d --- /dev/null +++ b/tests/test_component_typing.py @@ -0,0 +1,640 @@ +import re +from dataclasses import dataclass +from typing import NamedTuple, Optional +from typing_extensions import NotRequired, TypedDict + +import pytest +from django.template import Context + +from django_components import Component, Empty, Slot, SlotInput + +from django_components.testing import djc_test +from .testutils import setup_test_config + +setup_test_config({"autodiscover": False}) + + +@djc_test +class TestComponentTyping: + def test_data_methods_input_typed(self): + template_called = False + js_called = False + css_called = False + + class ButtonFooterSlotData(TypedDict): + value: int + + class Button(Component): + class Args(NamedTuple): + arg1: str + arg2: str + + @dataclass + class Kwargs: + name: str + age: int + maybe_var: Optional[int] = None + + class Slots(TypedDict): + # Use `SlotInput` when you want to pass slot as string + header: SlotInput + # Use `Slot` for slot functions. + # The generic specifies the data available to the slot function + footer: NotRequired[Slot[ButtonFooterSlotData]] + + def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + nonlocal template_called + template_called = True + + assert isinstance(args, Button.Args) + assert isinstance(kwargs, Button.Kwargs) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + def get_js_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + nonlocal js_called + js_called = True + + assert isinstance(args, Button.Args) + assert isinstance(kwargs, Button.Kwargs) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + def get_css_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + nonlocal css_called + css_called = True + + assert isinstance(args, Button.Args) + assert isinstance(kwargs, Button.Kwargs) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + template = "" + + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), + kwargs=Button.Kwargs(name="name", age=123), + slots=Button.Slots( + header="HEADER", + footer=Slot(lambda ctx: "FOOTER"), + ), + ) + + assert template_called + assert js_called + assert css_called + + def test_data_methods_input_not_typed_by_default(self): + template_called = False + js_called = False + css_called = False + + class Button(Component): + def get_template_data(self, args, kwargs, slots, context): + nonlocal template_called + template_called = True + + assert isinstance(args, list) + assert isinstance(kwargs, dict) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + def get_js_data(self, args, kwargs, slots, context): + nonlocal js_called + js_called = True + + assert isinstance(args, list) + assert isinstance(kwargs, dict) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + def get_css_data(self, args, kwargs, slots, context): + nonlocal css_called + css_called = True + + assert isinstance(args, list) + assert isinstance(kwargs, dict) + assert isinstance(slots, dict) + assert isinstance(context, Context) + + template = "" + + Button.render( + args=["arg1", "arg2"], + kwargs={"name": "name", "age": 123}, + slots={ + "header": "HEADER", + "footer": Slot(lambda ctx: "FOOTER"), + }, + ) + + assert template_called + assert js_called + assert css_called + + def test_data_methods_output_typed(self): + template_called = False + js_called = False + css_called = False + + template_data_instance = None + js_data_instance = None + css_data_instance = None + + class Button(Component): + # Data returned from `get_template_data` + @dataclass + class TemplateData: + data1: str + data2: int + + def __post_init__(self): + nonlocal template_data_instance + template_data_instance = self + + # Data returned from `get_js_data` + @dataclass + class JsData: + js_data1: str + js_data2: int + + def __post_init__(self): + nonlocal js_data_instance + js_data_instance = self + + # Data returned from `get_css_data` + @dataclass + class CssData: + css_data1: str + css_data2: int + + def __post_init__(self): + nonlocal css_data_instance + css_data_instance = self + + def get_template_data(self, args, kwargs, slots, context): + nonlocal template_called + template_called = True + + return { + "data1": "data1", + "data2": 123, + } + + def get_js_data(self, args, kwargs, slots, context): + nonlocal js_called + js_called = True + + return { + "js_data1": "js_data1", + "js_data2": 123, + } + + def get_css_data(self, args, kwargs, slots, context): + nonlocal css_called + css_called = True + + return { + "css_data1": "css_data1", + "css_data2": 123, + } + + template = "" + + Button.render( + args=["arg1", "arg2"], + kwargs={"name": "name", "age": 123}, + slots={ + "header": "HEADER", + "footer": Slot(lambda ctx: "FOOTER"), + }, + ) + + assert template_called + assert js_called + assert css_called + + assert isinstance(template_data_instance, Button.TemplateData) + assert isinstance(js_data_instance, Button.JsData) + assert isinstance(css_data_instance, Button.CssData) + + assert template_data_instance == Button.TemplateData(data1="data1", data2=123) + assert js_data_instance == Button.JsData(js_data1="js_data1", js_data2=123) + assert css_data_instance == Button.CssData(css_data1="css_data1", css_data2=123) + + def test_data_methods_output_typed_reuses_instances(self): + template_called = False + js_called = False + css_called = False + + template_data_instance = None + js_data_instance = None + css_data_instance = None + + class Button(Component): + # Data returned from `get_template_data` + @dataclass + class TemplateData: + data1: str + data2: int + + def __post_init__(self): + nonlocal template_data_instance + template_data_instance = self + + # Data returned from `get_js_data` + @dataclass + class JsData: + js_data1: str + js_data2: int + + def __post_init__(self): + nonlocal js_data_instance + js_data_instance = self + + # Data returned from `get_css_data` + @dataclass + class CssData: + css_data1: str + css_data2: int + + def __post_init__(self): + nonlocal css_data_instance + css_data_instance = self + + def get_template_data(self, args, kwargs, slots, context): + nonlocal template_called + template_called = True + + data = Button.TemplateData( + data1="data1", + data2=123, + ) + + # Reset the instance to None to check if the instance is reused + nonlocal template_data_instance + template_data_instance = None + + return data + + def get_js_data(self, args, kwargs, slots, context): + nonlocal js_called + js_called = True + + data = Button.JsData( + js_data1="js_data1", + js_data2=123, + ) + + # Reset the instance to None to check if the instance is reused + nonlocal js_data_instance + js_data_instance = None + + return data + + def get_css_data(self, args, kwargs, slots, context): + nonlocal css_called + css_called = True + + data = Button.CssData( + css_data1="css_data1", + css_data2=123, + ) + + # Reset the instance to None to check if the instance is reused + nonlocal css_data_instance + css_data_instance = None + + return data + + template = "" + + Button.render( + args=["arg1", "arg2"], + kwargs={"name": "name", "age": 123}, + slots={ + "header": "HEADER", + "footer": Slot(lambda ctx: "FOOTER"), + }, + ) + + assert template_called + assert js_called + assert css_called + + assert template_data_instance is not None + assert js_data_instance is not None + assert css_data_instance is not None + + def test_builtin_classes(self): + class ButtonFooterSlotData(TypedDict): + value: int + + class Button(Component): + class Args(NamedTuple): + arg1: str + arg2: str + + @dataclass + class Kwargs: + name: str + age: int + maybe_var: Optional[int] = None + + class Slots(TypedDict): + # Use `SlotInput` when you want to pass slot as string + header: SlotInput + # Use `Slot` for slot functions. + # The generic specifies the data available to the slot function + footer: NotRequired[Slot[ButtonFooterSlotData]] + + # Data returned from `get_template_data` + class TemplateData(NamedTuple): + data1: str + data2: int + data3: str + + # Data returned from `get_js_data` + @dataclass + class JsData: + js_data1: str + js_data2: int + js_data3: str + + # Data returned from `get_css_data` + @dataclass + class CssData: + css_data1: str + css_data2: int + css_data3: str + + def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + return self.TemplateData( + data1=kwargs.name, + data2=kwargs.age, + data3=args.arg1, + ) + + def get_js_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + return self.JsData( + js_data1=kwargs.name, + js_data2=kwargs.age, + js_data3=args.arg1, + ) + + def get_css_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context): + return self.CssData( + css_data1=kwargs.name, + css_data2=kwargs.age, + css_data3=args.arg1, + ) + + template = "" + + # Success case + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), + kwargs=Button.Kwargs(name="name", age=123), + slots=Button.Slots( + header="HEADER", + footer=Slot(lambda ctx: "FOOTER"), + ), + ) + + # Failure case 1: NamedTuple raises error when a required argument is missing + with pytest.raises( + TypeError, + match=re.escape("missing 1 required positional argument: 'arg2'"), + ): + Button.render( + # Missing arg2 + args=Button.Args(arg1="arg1"), # type: ignore[call-arg] + kwargs=Button.Kwargs(name="name", age=123), + slots=Button.Slots( + header="HEADER", + footer=Slot(lambda ctx: "FOOTER"), + ), + ) + + # Failure case 2: Dataclass raises error when a required argument is missing + with pytest.raises( + TypeError, + match=re.escape("missing 1 required positional argument: 'name'"), + ): + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), + # Name missing + kwargs=Button.Kwargs(age=123), # type: ignore[call-arg] + slots=Button.Slots( + header="HEADER", + footer=Slot(lambda ctx: "FOOTER"), + ), + ) + + # Failure case 3 + # NOTE: While we would expect this to raise, seems that TypedDict (`Slots`) + # does NOT raise an error when a required key is missing. + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), + kwargs=Button.Kwargs(name="name", age=123), + slots=Button.Slots( # type: ignore[typeddict-item] + footer=Slot(lambda ctx: "FOOTER"), # Missing header + ), + ) + + # Failure case 4: Data object is not of the expected type + class ButtonBad(Button): + class TemplateData(NamedTuple): + data1: str + data2: int # Removed data3 + + with pytest.raises( + TypeError, + match=re.escape("got an unexpected keyword argument 'data3'"), + ): + ButtonBad.render( + args=ButtonBad.Args(arg1="arg1", arg2="arg2"), + kwargs=ButtonBad.Kwargs(name="name", age=123), + ) + + def test_empty_type(self): + template_called = False + + class Button(Component): + template = "Hello" + + Args = Empty + Kwargs = Empty + + def get_template_data(self, args, kwargs, slots, context): + nonlocal template_called + template_called = True + + assert isinstance(args, Empty) + assert isinstance(kwargs, Empty) + + # Success case + Button.render() + assert template_called + + # Failure cases + with pytest.raises(TypeError, match=re.escape("got an unexpected keyword argument 'arg1'")): + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + with pytest.raises(TypeError, match=re.escape("got an unexpected keyword argument 'arg1'")): + Button.render( + kwargs=Button.Kwargs(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + def test_custom_args_class_raises_on_invalid(self): + class Button(Component): + template = "Hello" + + class Args: + arg1: str + arg2: str + + with pytest.raises(TypeError, match=re.escape("Args() takes no arguments")): + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + class Button2(Component): + template = "Hello" + + class Args: + arg1: str + arg2: str + + def __init__(self, arg1: str, arg2: str): + self.arg1 = arg1 + self.arg2 = arg2 + + with pytest.raises(TypeError, match=re.escape("'Args' object is not iterable")): + Button2.render( + args=Button2.Args(arg1="arg1", arg2="arg2"), + ) + + class Button3(Component): + template = "Hello" + + class Args: + arg1: str + arg2: str + + def __iter__(self): + return iter([self.arg1, self.arg2]) + + with pytest.raises(TypeError, match=re.escape("Args() takes no arguments")): + Button3.render( + args=Button3.Args(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + def test_custom_args_class_custom(self): + class Button(Component): + template = "Hello" + + class Args: + arg1: str + arg2: str + + def __init__(self, arg1: str, arg2: str): + self.arg1 = arg1 + self.arg2 = arg2 + + def __iter__(self): + return iter([self.arg1, self.arg2]) + + Button.render( + args=Button.Args(arg1="arg1", arg2="arg2"), + ) + + def test_custom_kwargs_class_raises_on_invalid(self): + class Button(Component): + template = "Hello" + + class Kwargs: + arg1: str + arg2: str + + with pytest.raises(TypeError, match=re.escape("Kwargs() takes no arguments")): + Button.render( + kwargs=Button.Kwargs(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + class Button2(Component): + template = "Hello" + + class Kwargs: + arg1: str + arg2: str + + def __init__(self, arg1: str, arg2: str): + self.arg1 = arg1 + self.arg2 = arg2 + + with pytest.raises(TypeError, match=re.escape("'Kwargs' object is not iterable")): + Button2.render( + kwargs=Button2.Kwargs(arg1="arg1", arg2="arg2"), + ) + + class Button3(Component): + template = "Hello" + + class Kwargs: + arg1: str + arg2: str + + def _asdict(self): + return {"arg1": self.arg1, "arg2": self.arg2} + + with pytest.raises(TypeError, match=re.escape("Kwargs() takes no arguments")): + Button3.render( + kwargs=Button3.Kwargs(arg1="arg1", arg2="arg2"), # type: ignore[call-arg] + ) + + def test_custom_kwargs_class_custom(self): + class Button(Component): + template = "Hello" + + class Kwargs: + arg1: str + arg2: str + + def __init__(self, arg1: str, arg2: str): + self.arg1 = arg1 + self.arg2 = arg2 + + def _asdict(self): + return {"arg1": self.arg1, "arg2": self.arg2} + + Button.render( + kwargs=Button.Kwargs(arg1="arg1", arg2="arg2"), + ) + + def test_subclass_overrides_parent_type(self): + class Button(Component): + template = "Hello" + + class Args(NamedTuple): + size: int + + class Kwargs(NamedTuple): + color: str + + class ButtonExtra(Button): + class Args(NamedTuple): + name: str + size: int + + def get_template_data(self, args: Args, kwargs: "ButtonExtra.Kwargs", slots, context): + assert isinstance(args, ButtonExtra.Args) + assert isinstance(kwargs, ButtonExtra.Kwargs) + assert ButtonExtra.Kwargs is Button.Kwargs + + ButtonExtra.render( + args=ButtonExtra.Args(name="John", size=30), + kwargs=ButtonExtra.Kwargs(color="red"), + ) diff --git a/tests/test_component_as_view.py b/tests/test_component_view.py similarity index 50% rename from tests/test_component_as_view.py rename to tests/test_component_view.py index eea2ca94..1b1a7662 100644 --- a/tests/test_component_as_view.py +++ b/tests/test_component_view.py @@ -1,15 +1,35 @@ -from typing import Any, Dict +from typing import Any +import pytest from django.conf import settings -from django.http import HttpResponse +from django.http import HttpRequest, HttpResponse from django.template import Context, Template -from django.test import Client +from django.test import Client, SimpleTestCase from django.urls import path -from django_components import Component, ComponentView, register, types +from django_components import Component, ComponentView, get_component_url, register, types +from django_components.urls import urlpatterns as dc_urlpatterns +from django_components.util.misc import format_url + +from django_components.testing import djc_test +from .testutils import setup_test_config + +# DO NOT REMOVE! +# +# This is intentionally defined before `setup_test_config()` in order to test that +# the URL extension works even before the Django has been set up. +# +# Because if we define the component before `django.setup()`, then we store it in +# event queue, and will register it when `AppConfig.ready()` is finally called. +# +# This test relies on the "url" extension calling `add_extension_urls()` from within +# the `on_component_class_created()` hook. +class ComponentBeforeReady(Component): + class View: + public = True + + template = "Hello" -from .django_test_setup import setup_test_config -from .testutils import BaseTestCase, parametrize_context_behavior setup_test_config({"autodiscover": False}) @@ -20,7 +40,7 @@ class CustomClient(Client): if urlpatterns: urls_module = types.ModuleType("urls") - urls_module.urlpatterns = urlpatterns # type: ignore + urls_module.urlpatterns = urlpatterns + dc_urlpatterns # type: ignore settings.ROOT_URLCONF = urls_module else: settings.ROOT_URLCONF = __name__ @@ -28,7 +48,8 @@ class CustomClient(Client): super().__init__(*args, **kwargs) -class TestComponentAsView(BaseTestCase): +@djc_test +class TestComponentAsView(SimpleTestCase): def test_render_component_from_template(self): @register("testcomponent") class MockComponentRequest(Component): @@ -40,8 +61,8 @@ class TestComponentAsView(BaseTestCase): """ - def get_context_data(self, variable, *args, **kwargs) -> Dict[str, Any]: - return {"variable": variable} + def get_template_data(self, args, kwargs, slots, context): + return {"variable": kwargs["variable"]} def render_template_view(request): template = Template( @@ -55,9 +76,9 @@ class TestComponentAsView(BaseTestCase): client = CustomClient(urlpatterns=[path("test_template/", render_template_view)]) response = client.get("/test_template/") self.assertEqual(response.status_code, 200) - self.assertIn( - b'', - response.content, + self.assertInHTML( + '', + response.content.decode(), ) def test_get_request(self): @@ -70,8 +91,8 @@ class TestComponentAsView(BaseTestCase): """ - def get_context_data(self, variable): - return {"inner_var": variable} + def get_template_data(self, args, kwargs, slots, context): + return {"inner_var": kwargs["variable"]} class View(ComponentView): def get(self, request, *args, **kwargs) -> HttpResponse: @@ -80,9 +101,9 @@ class TestComponentAsView(BaseTestCase): client = CustomClient(urlpatterns=[path("test/", MockComponentRequest.as_view())]) response = client.get("/test/") self.assertEqual(response.status_code, 200) - self.assertIn( - b'', - response.content, + self.assertInHTML( + '', + response.content.decode(), ) def test_get_request_shortcut(self): @@ -95,8 +116,8 @@ class TestComponentAsView(BaseTestCase): """ - def get_context_data(self, variable): - return {"inner_var": variable} + def get_template_data(self, args, kwargs, slots, context): + return {"inner_var": kwargs["variable"]} def get(self, request, *args, **kwargs) -> HttpResponse: return self.render_to_response(kwargs={"variable": "GET"}) @@ -104,9 +125,9 @@ class TestComponentAsView(BaseTestCase): client = CustomClient(urlpatterns=[path("test/", MockComponentRequest.as_view())]) response = client.get("/test/") self.assertEqual(response.status_code, 200) - self.assertIn( - b'', - response.content, + self.assertInHTML( + '', + response.content.decode(), ) def test_post_request(self): @@ -119,8 +140,8 @@ class TestComponentAsView(BaseTestCase): """ - def get_context_data(self, variable): - return {"inner_var": variable} + def get_template_data(self, args, kwargs, slots, context): + return {"inner_var": kwargs["variable"]} class View(ComponentView): def post(self, request, *args, **kwargs) -> HttpResponse: @@ -130,9 +151,9 @@ class TestComponentAsView(BaseTestCase): client = CustomClient(urlpatterns=[path("test/", MockComponentRequest.as_view())]) response = client.post("/test/", {"variable": "POST"}) self.assertEqual(response.status_code, 200) - self.assertIn( - b'', - response.content, + self.assertInHTML( + '', + response.content.decode(), ) def test_post_request_shortcut(self): @@ -145,8 +166,8 @@ class TestComponentAsView(BaseTestCase): """ - def get_context_data(self, variable): - return {"inner_var": variable} + def get_template_data(self, args, kwargs, slots, context): + return {"inner_var": kwargs["variable"]} def post(self, request, *args, **kwargs) -> HttpResponse: variable = request.POST.get("variable") @@ -155,12 +176,34 @@ class TestComponentAsView(BaseTestCase): client = CustomClient(urlpatterns=[path("test/", MockComponentRequest.as_view())]) response = client.post("/test/", {"variable": "POST"}) self.assertEqual(response.status_code, 200) - self.assertIn( - b'', - response.content, + self.assertInHTML( + '', + response.content.decode(), + ) + + def test_instantiate_component(self): + class MockComponentRequest(Component): + template = """ + + """ + + def get_template_data(self, args, kwargs, slots, context): + return {"inner_var": kwargs["variable"]} + + def get(self, request, *args, **kwargs) -> HttpResponse: + return self.render_to_response(kwargs={"variable": self.name}) + + view = MockComponentRequest.as_view() + client = CustomClient(urlpatterns=[path("test/", view)]) + response = client.get("/test/") + self.assertEqual(response.status_code, 200) + self.assertInHTML( + '', + response.content.decode(), ) - @parametrize_context_behavior(["django", "isolated"]) def test_replace_slot_in_view(self): class MockComponentSlot(Component): template = """ @@ -175,7 +218,10 @@ class TestComponentAsView(BaseTestCase): """ def get(self, request, *args, **kwargs) -> HttpResponse: - return self.render_to_response({"name": "Bob"}, {"second_slot": "Nice to meet you, Bob"}) + return self.render_to_response( + context={"name": "Bob"}, + slots={"second_slot": "Nice to meet you, Bob"}, + ) client = CustomClient(urlpatterns=[path("test_slot/", MockComponentSlot.as_view())]) response = client.get("/test_slot/") @@ -189,7 +235,6 @@ class TestComponentAsView(BaseTestCase): response.content, ) - @parametrize_context_behavior(["django", "isolated"]) def test_replace_slot_in_view_with_insecure_content(self): class MockInsecureComponentSlot(Component): template = """ @@ -201,7 +246,10 @@ class TestComponentAsView(BaseTestCase): """ def get(self, request, *args, **kwargs) -> HttpResponse: - return self.render_to_response({}, {"test_slot": ""}) + return self.render_to_response( + context={}, + slots={"test_slot": ""}, + ) client = CustomClient(urlpatterns=[path("test_slot_insecure/", MockInsecureComponentSlot.as_view())]) response = client.get("/test_slot_insecure/") @@ -211,7 +259,6 @@ class TestComponentAsView(BaseTestCase): response.content, ) - @parametrize_context_behavior(["django", "isolated"]) def test_replace_context_in_view(self): class TestComponent(Component): template = """ @@ -232,7 +279,6 @@ class TestComponentAsView(BaseTestCase): response.content, ) - @parametrize_context_behavior(["django", "isolated"]) def test_replace_context_in_view_with_insecure_content(self): class MockInsecureComponentContext(Component): template = """ @@ -252,3 +298,99 @@ class TestComponentAsView(BaseTestCase): b"', rendered, count=0) + + # Check that it contains inlined JS and CSS, and Media.css + assert rendered.strip() == ( + 'Variable: foo\n' + ' ' + ) + + +@djc_test +class TestRenderDependencies: + # Check that `render_dependencies()` works when called directly + def test_render_dependencies(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) + # NOTE: `"ignore"` is a special value that means "do not render dependencies" + 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("| # | +
|---|
| + {{ row_number }} + | +
| # | +
|---|
| + 1 + | +
| # | +
|---|
| + {{ row_number }} + {% component "test" variable="hi" / %} + | +
| # | +
|---|
| + 1 + Variable: hi + | +
+ {% 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
');
+
+ let captured = null;
+ manager.registerComponent(compName, (data, ctx) => {
+ captured = { ctx, data };
+ return 123;
+ });
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ const result = manager.callComponent(compName, compId, inputHash);
+
+ // Serialize the HTML elements
+ captured.ctx.els = captured.ctx.els.map((el) => el.outerHTML);
+
+ return {
+ result,
+ captured,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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 _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 = 'c12345';
+ const inputHash = 'input-abc';
+
+ // Pretend that this HTML belongs to our component
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
+
+ manager.registerComponent(compName, (data, ctx) => {
+ return Promise.resolve(123);
+ });
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ // Should be Promise
+ const result = manager.callComponent(compName, compId, inputHash);
+ const isPromise = `${result}` === '[object Promise]';
+
+ // Wrap the whole response in Promise, so we can add extra fields
+ return Promise.resolve(result).then((res) => ({
+ result: res,
+ isPromise,
+ }));
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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 _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 = 'c12345';
+ const inputHash = 'input-abc';
+
+ // Pretend that this HTML belongs to our component
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
+
+ manager.registerComponent(compName, (data, ctx) => {
+ throw Error('Oops!');
+ return 123;
+ });
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ const result = manager.callComponent(compName, compId, inputHash);
+
+ return result;
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ assert data is None
+
+ await page.close()
+
+ @with_playwright
+ async def test_error_in_component_call_do_not_propagate_async(self):
+ 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 = 'c12345';
+ const inputHash = 'input-abc';
+
+ // Pretend that this HTML belongs to our component
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
+
+ manager.registerComponent(compName, async (data, ctx) => {
+ throw Error('Oops!');
+ return 123;
+ });
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ const result = manager.callComponent(compName, compId, inputHash);
+ return Promise.allSettled([result]);
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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 _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 inputHash = 'input-abc';
+
+ manager.registerComponent(compName, (data, ctx) => {
+ return 123;
+ });
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ // Should raise Error
+ manager.callComponent(compName, compId, inputHash);
+ }"""
+
+ with pytest.raises(
+ Error,
+ match=re.escape("Error: [Components] 'my_comp': No elements with component ID '12345' found"),
+ ):
+ await page.evaluate(test_js)
+
+ await page.close()
+
+ @with_playwright
+ async def test_raises_if_input_hash_not_registered(self):
+ 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 = 'c12345';
+ const inputHash = 'input-abc';
+
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
+
+ manager.registerComponent(compName, (data, ctx) => {
+ return Promise.resolve(123);
+ });
+
+ // Should raise Error
+ manager.callComponent(compName, compId, inputHash);
+ }"""
+
+ 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 _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 inputHash = 'input-abc';
+
+ document.body.insertAdjacentHTML('beforeend', ' abc
');
+
+ manager.registerComponentData(compName, inputHash, () => {
+ return { hello: 'world' };
+ });
+
+ // Should raise Error
+ manager.callComponent(compName, compId, inputHash);
+ }"""
+
+ 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 e23186e3..336d6fd9 100644
--- a/tests/test_dependency_rendering.py
+++ b/tests/test_dependency_rendering.py
@@ -1,16 +1,23 @@
-from unittest.mock import Mock
+"""
+Here we check that the logic around dependency rendering outputs correct HTML.
+During actual rendering, the HTML is then picked up by the JS-side dependency manager.
+"""
-from django.http import HttpResponseNotModified
-from django.template import Template
-from django.test import override_settings
+import re
+
+from django.template import Context, Template
+from pytest_django.asserts import assertHTMLEqual, assertInHTML
from django_components import Component, registry, types
-from django_components.middleware import ComponentDependencyMiddleware
+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()
+setup_test_config({"autodiscover": False})
+
+
+def to_spaces(s: str):
+ return re.compile(r"\s+").sub(" ", s)
class SimpleComponent(Component):
@@ -18,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:
@@ -29,27 +36,55 @@ class SimpleComponent(Component):
js = "script.js"
-class SimpleComponentAlternate(Component):
+class SimpleComponentNested(Component):
template: types.django_html = """
- Variable: {{ variable }}
+ {% load component_tags %}
+
+ {% component "inner" variable=variable / %}
+ {% slot "default" default / %}
+
"""
- def get_context_data(self, variable):
- return {}
+ css: types.css = """
+ .my-class {
+ color: red;
+ }
+ """
+
+ js: types.js = """
+ console.log("Hello");
+ """
class Media:
- css = "style2.css"
+ 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"
+
+
class SimpleComponentWithSharedDependency(Component):
template: types.django_html = """
Variable: {{ variable }}
"""
- def get_context_data(self, variable, variable2="default"):
- return {}
-
class Media:
css = ["style.css", "style2.css"]
js = ["script.js", "script2.js"]
@@ -65,21 +100,34 @@ class MultistyleComponent(Component):
js = ["script.js", "script2.js"]
-@override_settings(COMPONENTS={"RENDER_DEPENDENCIES": True})
-class ComponentMediaRenderingTests(BaseTestCase):
+@djc_test
+class TestDependencyRendering:
def test_no_dependencies_when_no_components_used(self):
registry.register(name="test", component=SimpleComponent)
template_str: types.django_html = """
- {% load component_tags %}{% component_dependencies %}
+ {% load component_tags %}
+ {% component_js_dependencies %}
+ {% component_css_dependencies %}
"""
template = Template(template_str)
- rendered = create_and_process_template_response(template)
- self.assertInHTML('', rendered, count=0)
+
+ assert 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
new file mode 100644
index 00000000..f53ceb72
--- /dev/null
+++ b/tests/test_dependency_rendering_e2e.py
@@ -0,0 +1,588 @@
+"""
+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 django_components.testing import djc_test
+from tests.testutils import setup_test_config
+from tests.e2e.utils import TEST_SERVER_URL, with_playwright
+
+setup_test_config({"autodiscover": False})
+
+
+# NOTE: All views, components, and associated JS and CSS are defined in
+# `tests/e2e/testserver/testserver`
+@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() # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ const bodyHTML = document.body.innerHTML;
+
+ const innerEl = document.querySelector(".inner");
+ const innerFontSize = globalThis.getComputedStyle(innerEl).getPropertyValue('font-size');
+
+ const myStyleEl = document.querySelector(".my-style");
+ const myStyleBg = globalThis.getComputedStyle(myStyleEl).getPropertyValue('background');
+
+ return {
+ bodyHTML,
+ componentJsMsg: globalThis.testSimpleComponent,
+ scriptJsMsg: globalThis.testMsg,
+ innerFontSize,
+ myStyleBg,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check that the actual HTML content was loaded
+ 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
+ assert data["componentJsMsg"] == "kapowww!"
+
+ # Check JS from Media.js got loaded
+ assert data["scriptJsMsg"] == {"hello": "world"}
+
+ # Check components' inlined CSS got loaded
+ assert data["innerFontSize"] == "4px"
+
+ # Check CSS from Media.css got loaded
+ assert "rgb(0, 0, 255)" in data["myStyleBg"] # AKA 'background: blue'
+
+ await page.close()
+
+ @with_playwright
+ async def test_multiple_component_dependencies(self):
+ single_comp_url = TEST_SERVER_URL + "/multi"
+
+ page: Page = await self.browser.new_page() # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ const bodyHTML = document.body.innerHTML;
+
+ // Get the stylings defined via CSS
+ const innerEl = document.querySelector(".inner");
+ const innerFontSize = globalThis.getComputedStyle(innerEl).getPropertyValue('font-size');
+
+ const outerEl = document.querySelector(".outer");
+ const outerFontSize = globalThis.getComputedStyle(outerEl).getPropertyValue('font-size');
+
+ const otherEl = document.querySelector(".other");
+ const otherDisplay = globalThis.getComputedStyle(otherEl).getPropertyValue('display');
+
+ const myStyleEl = document.querySelector(".my-style");
+ const myStyleBg = globalThis.getComputedStyle(myStyleEl).getPropertyValue('background');
+
+ const myStyle2El = document.querySelector(".my-style2");
+ const myStyle2Color = globalThis.getComputedStyle(myStyle2El).getPropertyValue('color');
+
+ return {
+ bodyHTML,
+ component1JsMsg: globalThis.testSimpleComponent,
+ component2JsMsg: globalThis.testSimpleComponentNested,
+ component3JsMsg: globalThis.testOtherComponent,
+ scriptJs1Msg: globalThis.testMsg,
+ scriptJs2Msg: globalThis.testMsg2,
+ innerFontSize,
+ outerFontSize,
+ myStyleBg,
+ myStyle2Color,
+ otherDisplay,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check that the actual HTML content was loaded
+ 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
+ assert data["component1JsMsg"] == "kapowww!"
+ assert data["component2JsMsg"] == "bongo!"
+ assert data["component3JsMsg"] == "wowzee!"
+
+ # Check JS from Media.js got loaded
+ assert data["scriptJs1Msg"] == {"hello": "world"}
+ assert data["scriptJs2Msg"] == {"hello2": "world2"}
+
+ # Check components' inlined CSS got loaded
+ assert data["innerFontSize"] == "4px"
+ assert data["outerFontSize"] == "40px"
+ assert data["otherDisplay"] == "flex"
+
+ # Check CSS from Media.css got loaded
+ assert "rgb(0, 0, 255)" in data["myStyleBg"] # AKA 'background: blue'
+ assert data["myStyle2Color"] == "rgb(255, 0, 0)" # AKA 'color: red'
+
+ await page.close()
+
+ @with_playwright
+ 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) # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ const bodyHTML = document.body.innerHTML;
+
+ // Get the stylings defined via CSS
+ const innerEl = document.querySelector(".inner");
+ const innerFontSize = globalThis.getComputedStyle(innerEl).getPropertyValue('font-size');
+
+ const outerEl = document.querySelector(".outer");
+ const outerFontSize = globalThis.getComputedStyle(outerEl).getPropertyValue('font-size');
+
+ const otherEl = document.querySelector(".other");
+ const otherDisplay = globalThis.getComputedStyle(otherEl).getPropertyValue('display');
+
+ const myStyleEl = document.querySelector(".my-style");
+ const myStyleBg = globalThis.getComputedStyle(myStyleEl).getPropertyValue('background');
+
+ const myStyle2El = document.querySelector(".my-style2");
+ const myStyle2Color = globalThis.getComputedStyle(myStyle2El).getPropertyValue('color');
+
+ return {
+ bodyHTML,
+ component1JsMsg: globalThis.testSimpleComponent,
+ component2JsMsg: globalThis.testSimpleComponentNested,
+ component3JsMsg: globalThis.testOtherComponent,
+ scriptJs1Msg: globalThis.testMsg,
+ scriptJs2Msg: globalThis.testMsg2,
+ innerFontSize,
+ outerFontSize,
+ myStyleBg,
+ myStyle2Color,
+ otherDisplay,
+ };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check that the actual HTML content was loaded
+ #
+ #
+ # 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
+ assert data["component1JsMsg"] is None
+ assert data["component2JsMsg"] is None
+ assert data["component3JsMsg"] is None
+
+ # Check JS from Media.js did NOT get loaded
+ assert data["scriptJs1Msg"] is None
+ assert data["scriptJs2Msg"] is None
+
+ # Check components' inlined CSS got loaded
+ assert data["innerFontSize"] == "4px"
+ assert data["outerFontSize"] == "40px"
+ assert data["otherDisplay"] == "flex"
+
+ # Check CSS from Media.css got loaded
+ 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()
+
+ @with_playwright
+ 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() # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ // NOTE: This variable should be defined by `check_script_order` component,
+ // and it should contain all other variables defined by the previous components
+ return checkVars;
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check components' inlined JS got loaded
+ assert data["testSimpleComponent"] == "kapowww!"
+ assert data["testSimpleComponentNested"] == "bongo!"
+ assert data["testOtherComponent"] == "wowzee!"
+
+ # Check JS from Media.js got loaded
+ assert data["testMsg"] == {"hello": "world"}
+ assert data["testMsg2"] == {"hello2": "world2"}
+
+ await page.close()
+
+ @with_playwright
+ 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() # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ // NOTE: This variable should be defined by `check_script_order` component,
+ // and it should contain all other variables defined by the previous components
+ return checkVars;
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check components' inlined JS got loaded
+ # NOTE: The Media JS are loaded BEFORE the components' JS, so they should be empty
+ assert data["testSimpleComponent"] is None
+ assert data["testSimpleComponentNested"] is None
+ assert data["testOtherComponent"] is None
+
+ # Check JS from Media.js
+ assert data["testMsg"] == {"hello": "world"}
+ assert data["testMsg2"] == {"hello2": "world2"}
+
+ await page.close()
+
+ # In this case the component whose JS is accessing data from other components
+ # is used in the template before the other components. So the JS should
+ # not be able to access the data from the other components.
+ @with_playwright
+ 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() # type: ignore[attr-defined]
+ await page.goto(single_comp_url)
+
+ test_js: types.js = """() => {
+ // checkVars was defined BEFORE other components, so it should be empty!
+ return checkVars;
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # Check components' inlined JS got loaded
+ assert data["testSimpleComponent"] is None
+ assert data["testSimpleComponentNested"] is None
+ assert data["testOtherComponent"] is None
+
+ # Check JS from Media.js got loaded
+ 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() # type: ignore[attr-defined]
+ await page.goto(f"{TEST_SERVER_URL}/fragment/base/js?frag=comp")
+
+ test_before_js: types.js = """() => {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ return { targetHtml, fragHtml };
+ }"""
+
+ data_before = await page.evaluate(test_before_js)
+
+ assert 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(),
- "
OLD
'
+ assert data_before["fragHtml"] is None
+
+ # Clicking button should load and insert the fragment
+ await page.locator("button").click()
+
+ # Wait until both JS and CSS are loaded
+ await page.locator(".frag").wait_for(state="visible")
+ await page.wait_for_function(
+ "() => document.head.innerHTML.includes(' {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ // Get the stylings defined via CSS
+ const fragBg = fragEl ? globalThis.getComputedStyle(fragEl).getPropertyValue('background') : null;
+
+ return { targetHtml, fragHtml, fragBg };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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() # type: ignore[attr-defined]
+ await page.goto(f"{TEST_SERVER_URL}/fragment/base/js?frag=media")
+
+ test_before_js: types.js = """() => {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ return { targetHtml, fragHtml };
+ }"""
+
+ data_before = await page.evaluate(test_before_js)
+
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
+
+ # Clicking button should load and insert the fragment
+ await page.locator("button").click()
+
+ # Wait until both JS and CSS are loaded
+ await page.locator(".frag").wait_for(state="visible")
+ await page.wait_for_function("() => document.head.innerHTML.includes(' {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ // Get the stylings defined via CSS
+ const fragBg = fragEl ? globalThis.getComputedStyle(fragEl).getPropertyValue('background') : null;
+
+ return { targetHtml, fragHtml, fragBg };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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() # type: ignore[attr-defined]
+ await page.goto(f"{TEST_SERVER_URL}/fragment/base/alpine?frag=comp")
+
+ test_before_js: types.js = """() => {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ return { targetHtml, fragHtml };
+ }"""
+
+ data_before = await page.evaluate(test_before_js)
+
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
+
+ # Clicking button should load and insert the fragment
+ await page.locator("button").click()
+
+ # Wait until both JS and CSS are loaded
+ await page.locator(".frag").wait_for(state="visible")
+ await page.wait_for_function(
+ "() => document.head.innerHTML.includes(' {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ // Get the stylings defined via CSS
+ const fragBg = fragEl ? globalThis.getComputedStyle(fragEl).getPropertyValue('background') : null;
+
+ return { targetHtml, fragHtml, fragBg };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ # NOTE: Unlike the vanilla JS tests, for the Alpine test we don't remove the targetHtml,
+ # but only change its contents.
+ 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() # type: ignore[attr-defined]
+ await page.goto(f"{TEST_SERVER_URL}/fragment/base/htmx?frag=comp")
+
+ test_before_js: types.js = """() => {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragHtml = fragEl ? fragEl.outerHTML : null;
+
+ return { targetHtml, fragHtml };
+ }"""
+
+ data_before = await page.evaluate(test_before_js)
+
+ assert data_before["targetHtml"] == 'OLD
'
+ assert data_before["fragHtml"] is None
+
+ # Clicking button should load and insert the fragment
+ await page.locator("button").click()
+
+ # Wait until both JS and CSS are loaded
+ await page.locator(".frag").wait_for(state="visible")
+ await page.wait_for_function(
+ "() => document.head.innerHTML.includes(' {
+ const targetEl = document.querySelector("#target");
+ const targetHtml = targetEl ? targetEl.outerHTML : null;
+ const fragEl = document.querySelector(".frag");
+ const fragInnerHtml = fragEl ? fragEl.innerHTML : null;
+
+ // Get the stylings defined via CSS
+ const fragBg = fragEl ? globalThis.getComputedStyle(fragEl).getPropertyValue('background') : null;
+
+ return { targetHtml, fragInnerHtml, fragBg };
+ }"""
+
+ data = await page.evaluate(test_js)
+
+ 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.
+ 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()
+
+ @with_playwright
+ async def test_alpine__head(self):
+ single_comp_url = TEST_SERVER_URL + "/alpine/head"
+
+ 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()
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+
+ await page.close()
+
+ @with_playwright
+ async def test_alpine__body(self):
+ single_comp_url = TEST_SERVER_URL + "/alpine/body"
+
+ 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()
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+
+ await page.close()
+
+ @with_playwright
+ async def test_alpine__body2(self):
+ single_comp_url = TEST_SERVER_URL + "/alpine/body2"
+
+ 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()
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST: 123")
+
+ await page.close()
+
+ @with_playwright
+ async def test_alpine__invalid(self):
+ single_comp_url = TEST_SERVER_URL + "/alpine/invalid"
+
+ 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()
+ assertHTMLEqual(component_text.strip(), "ALPINE_TEST:")
+
+ await page.close()
diff --git a/tests/test_expression.py b/tests/test_expression.py
index 38c77b24..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(),
- "lorem
\n True
\n [{'a': 1}, {'a': 2}]
",
+ 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(),
- "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 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 True
',
+ 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 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,
"""
-
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_later_spreads_overwrite_earlier(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_later_spreads_do_not_overwrite_earlier(self, components_settings):
@register("test")
class SimpleComponent(Component):
- def get_context_data(
- self,
- *args: Any,
- **kwargs: Any,
- ):
+ def get_template_data(self, args, kwargs, slots, context):
return {
**kwargs,
}
@@ -717,7 +662,20 @@ class SpreadOperatorTests(BaseTestCase):
//", handler=dummy_view_2, name="dummy-2"),
+ ]
+
+ def on_component_class_created(self, ctx: OnComponentClassCreatedContext) -> None:
+ # NOTE: Store only component name to avoid strong references
+ self.calls["on_component_class_created"].append(ctx.component_cls.__name__)
+
+ def on_component_class_deleted(self, ctx: OnComponentClassDeletedContext) -> None:
+ # NOTE: Store only component name to avoid strong references
+ self.calls["on_component_class_deleted"].append(ctx.component_cls.__name__)
+
+ def on_registry_created(self, ctx: OnRegistryCreatedContext) -> None:
+ # NOTE: Store only registry object ID to avoid strong references
+ self.calls["on_registry_created"].append(id(ctx.registry))
+
+ def on_registry_deleted(self, ctx: OnRegistryDeletedContext) -> None:
+ # NOTE: Store only registry object ID to avoid strong references
+ self.calls["on_registry_deleted"].append(id(ctx.registry))
+
+ def on_component_registered(self, ctx: OnComponentRegisteredContext) -> None:
+ self.calls["on_component_registered"].append(ctx)
+
+ def on_component_unregistered(self, ctx: OnComponentUnregisteredContext) -> None:
+ self.calls["on_component_unregistered"].append(ctx)
+
+ def on_component_input(self, ctx: OnComponentInputContext) -> None:
+ self.calls["on_component_input"].append(ctx)
+
+ def on_component_data(self, ctx: OnComponentDataContext) -> None:
+ self.calls["on_component_data"].append(ctx)
+
+ def on_component_rendered(self, ctx: OnComponentRenderedContext) -> None:
+ self.calls["on_component_rendered"].append(ctx)
+
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext) -> None:
+ self.calls["on_slot_rendered"].append(ctx)
+
+ def on_template_loaded(self, ctx):
+ self.calls["on_template_loaded"].append(ctx)
+
+ def on_template_compiled(self, ctx):
+ self.calls["on_template_compiled"].append(ctx)
+
+ def on_js_loaded(self, ctx):
+ self.calls["on_js_loaded"].append(ctx)
+
+ def on_css_loaded(self, ctx):
+ self.calls["on_css_loaded"].append(ctx)
+
+
+class DummyNestedExtension(ComponentExtension):
+ name = "test_nested_extension"
+
+ urls = [
+ URLRoute(
+ path="nested-view/",
+ children=[
+ URLRoute(path="//", handler=dummy_view_2, name="dummy-2"),
+ ],
+ name="dummy",
+ ),
+ ]
+
+
+class RenderExtension(ComponentExtension):
+ name = "render"
+
+
+class SlotOverrideExtension(ComponentExtension):
+ name = "slot_override"
+
+ def on_slot_rendered(self, ctx: OnSlotRenderedContext):
+ return "OVERRIDEN BY EXTENSION"
+
+
+class ErrorOnComponentRenderedExtension(ComponentExtension):
+ name = "error_on_component_rendered"
+
+ def on_component_rendered(self, ctx: OnComponentRenderedContext):
+ raise RuntimeError("Custom error from extension")
+
+
+class ReturnHtmlOnComponentRenderedExtension(ComponentExtension):
+ name = "return_html_on_component_rendered"
+
+ def on_component_rendered(self, ctx: OnComponentRenderedContext):
+ return f""
+ result, _ = set_html_attributes(html, root_attributes=["data-root"], all_attributes=["data-all"])
+
+ assertHTMLEqual(
+ result,
+ """
+
", "
"),
+ ('
', ''),
+ ]
+
+ for input_html, expected in test_cases:
+ result, _ = set_html_attributes(input_html, ["data-root"], ["data-v-123"])
+ assertHTMLEqual(result, expected)
+
+ def test_html_head_with_meta(self):
+ html = """
+
+
+ Test Page
+
+
+ """
+
+ result, _ = set_html_attributes(html, ["data-root"], ["data-v-123"])
+
+ assertHTMLEqual(
+ result,
+ """
+
+
+ Test Page
+
+
+
+ """,
+ )
+
+ def test_watch_attribute(self):
+ html = """
+ : 3" in warn_inputs[0]
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "dirs": [],
+ },
+ )
+ def test_get_dirs__components_dirs__empty(self):
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = dirs
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 2
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-2:] == ("django_components", "components")
+ assert apps_dirs[1].parts[-3:] == ("tests", "test_app", "components")
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "dirs": ["components"],
+ },
+ )
+ def test_get_dirs__componenents_dirs__raises_on_relative_path_1(self):
+ with pytest.raises(ValueError, match=re.escape("COMPONENTS.dirs must contain absolute paths")):
+ get_component_dirs()
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "dirs": [("with_alias", "components")],
+ },
+ )
+ def test_get_dirs__component_dirs__raises_on_relative_path_2(self):
+ with pytest.raises(ValueError, match=re.escape("COMPONENTS.dirs must contain absolute paths")):
+ get_component_dirs()
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "app_dirs": ["custom_comps_dir"],
+ },
+ )
+ def test_get_dirs__app_dirs(self):
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = dirs[1:]
+ own_dirs = dirs[:1]
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 1
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-3:] == ("tests", "test_app", "custom_comps_dir")
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "app_dirs": [],
+ },
+ )
+ def test_get_dirs__app_dirs_empty(self):
+ dirs = sorted(get_component_dirs())
+
+ own_dirs = dirs
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ components_settings={
+ "app_dirs": ["this_dir_does_not_exist"],
+ },
+ )
+ def test_get_dirs__app_dirs_not_found(self):
+ dirs = sorted(get_component_dirs())
+
+ own_dirs = dirs
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ "INSTALLED_APPS": ("django_components", "tests.test_app_nested.app"),
+ },
+ )
+ def test_get_dirs__nested_apps(self):
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = [dirs[0], *dirs[2:]]
+ own_dirs = [dirs[1]]
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 2
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-2:] == ("django_components", "components")
+ assert apps_dirs[1].parts[-4:] == ("tests", "test_app_nested", "app", "components")
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+
+@djc_test
+class TestComponentFiles:
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ )
+ def test_get_files__py(self):
+ files = sorted(get_component_files(".py"))
+
+ dot_paths = [f.dot_path for f in files]
+ file_paths = [f.filepath for f in files]
+
+ assert dot_paths == [
+ "components",
+ "components.glob.glob",
+ "components.multi_file.multi_file",
+ "components.relative_file.relative_file",
+ "components.relative_file_pathobj.relative_file_pathobj",
+ "components.single_file",
+ "components.staticfiles.staticfiles",
+ "components.urls",
+ "django_components.components",
+ "django_components.components.dynamic",
+ "tests.test_app.components.app_lvl_comp.app_lvl_comp",
+ ]
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert file_paths[0].parts[-3:] == ("tests", "components", "__init__.py")
+ assert file_paths[1].parts[-4:] == ("tests", "components", "glob", "glob.py")
+ assert file_paths[2].parts[-4:] == ("tests", "components", "multi_file", "multi_file.py")
+ assert file_paths[3].parts[-4:] == ("tests", "components", "relative_file", "relative_file.py")
+ assert file_paths[4].parts[-4:] == ("tests", "components", "relative_file_pathobj", "relative_file_pathobj.py")
+ assert file_paths[5].parts[-3:] == ("tests", "components", "single_file.py")
+ assert file_paths[6].parts[-4:] == ("tests", "components", "staticfiles", "staticfiles.py")
+ assert file_paths[7].parts[-3:] == ("tests", "components", "urls.py")
+ assert file_paths[8].parts[-3:] == ("django_components", "components", "__init__.py")
+ assert file_paths[9].parts[-3:] == ("django_components", "components", "dynamic.py")
+ assert file_paths[10].parts[-5:] == ("tests", "test_app", "components", "app_lvl_comp", "app_lvl_comp.py")
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ )
+ def test_get_files__js(self):
+ files = sorted(get_component_files(".js"))
+
+ dot_paths = [f.dot_path for f in files]
+ file_paths = [f.filepath for f in files]
+
+ assert dot_paths == [
+ "components.glob.glob_1",
+ "components.glob.glob_2",
+ "components.relative_file.relative_file",
+ "components.relative_file_pathobj.relative_file_pathobj",
+ "components.staticfiles.staticfiles",
+ "tests.test_app.components.app_lvl_comp.app_lvl_comp",
+ ]
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert file_paths[0].parts[-4:] == ("tests", "components", "glob", "glob_1.js")
+ assert file_paths[1].parts[-4:] == ("tests", "components", "glob", "glob_2.js")
+ assert file_paths[2].parts[-4:] == ("tests", "components", "relative_file", "relative_file.js")
+ assert file_paths[3].parts[-4:] == ("tests", "components", "relative_file_pathobj", "relative_file_pathobj.js")
+ assert file_paths[4].parts[-4:] == ("tests", "components", "staticfiles", "staticfiles.js")
+ assert file_paths[5].parts[-5:] == ("tests", "test_app", "components", "app_lvl_comp", "app_lvl_comp.js")
+
+
+@djc_test
+class TestFilepathToPythonModule:
+ def test_prepares_path(self):
+ base_path = str(settings.BASE_DIR)
+
+ the_path = os.path.join(base_path, "tests.py")
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests"
+
+ the_path = os.path.join(base_path, "tests/components/relative_file/relative_file.py")
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests.components.relative_file.relative_file"
+
+ def test_handles_separators_based_on_os_name(self):
+ base_path = str(settings.BASE_DIR)
+
+ with patch("os.name", new="posix"):
+ the_path = base_path + "/" + "tests.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests"
+
+ the_path = base_path + "/" + "tests/components/relative_file/relative_file.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests.components.relative_file.relative_file" # noqa: E501
+
+ base_path = str(settings.BASE_DIR).replace("/", "\\")
+ with patch("os.name", new="nt"):
+ the_path = base_path + "\\" + "tests.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests"
+
+ the_path = base_path + "\\" + "tests\\components\\relative_file\\relative_file.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests.components.relative_file.relative_file" # noqa: E501
+
+ # NOTE: Windows should handle also POSIX separator
+ the_path = base_path + "/" + "tests.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests"
+
+ the_path = base_path + "/" + "tests/components/relative_file/relative_file.py"
+ assert _filepath_to_python_module(the_path, base_path, None) == "tests.components.relative_file.relative_file" # noqa: E501
diff --git a/tests/test_node.py b/tests/test_node.py
new file mode 100644
index 00000000..e62e4fb7
--- /dev/null
+++ b/tests/test_node.py
@@ -0,0 +1,1239 @@
+import inspect
+import os
+import re
+from typing import cast
+
+import pytest
+from django.template import Context, Template
+from django.template.base import TextNode, VariableNode
+from django.template.defaulttags import IfNode, LoremNode
+from django.template.exceptions import TemplateSyntaxError
+
+from django_components import Component, types
+from django_components.node import BaseNode, template_tag
+from django_components.templatetags import component_tags
+from django_components.util.tag_parser import TagAttr
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestNode:
+ def test_node_class_requires_tag(self):
+ with pytest.raises(ValueError):
+
+ class CaptureNode(BaseNode):
+ pass
+
+ # Test that the template tag can be used within the template under the registered tag
+ def test_node_class_tags(self):
+ class TestNode(BaseNode):
+ tag = "mytag"
+ end_tag = "endmytag"
+
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ # Works with end tag and self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assert rendered.strip() == "Hello, John!\n Shorthand: Hello, Mary!"
+
+ # But raises if missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ with pytest.raises(TemplateSyntaxError, match=re.escape("Unclosed tag on line 3: 'mytag'")):
+ Template(template_str2)
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_class_no_end_tag(self):
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ # Raises with end tag or self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ with pytest.raises(TemplateSyntaxError, match=re.escape("Invalid block tag on line 4: 'endmytag'")):
+ Template(template_str)
+
+ # Works when missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ template2 = Template(template_str2)
+ rendered2 = template2.render(Context({}))
+ assert rendered2.strip() == "Hello, John!"
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_class_flags(self):
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+ end_tag = "endmytag"
+ allowed_flags = ["required", "default"]
+
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ nonlocal captured
+ captured = self.allowed_flags, self.flags, self.active_flags
+
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ template_str = """
+ {% load component_tags %}
+ {% mytag 'John' required / %}
+ """
+ template = Template(template_str)
+ template.render(Context({}))
+
+ allowed_flags, flags, active_flags = captured # type: ignore
+ assert allowed_flags == ["required", "default"]
+ assert flags == {"required": True, "default": False}
+ assert active_flags == ["required"]
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_render(self):
+ # Check that the render function is called with the context
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ def render(self, context: Context) -> str:
+ nonlocal captured
+ captured = context.flatten()
+
+ return f"Hello, {context['name']}!"
+
+ TestNode.register(component_tags.register)
+
+ template_str = """
+ {% load component_tags %}
+ {% mytag / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({"name": "John"}))
+
+ assert captured == {"False": False, "None": None, "True": True, "name": "John"}
+ assert rendered.strip() == "Hello, John!"
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_render_raises_if_no_context_arg(self):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("`render()` method of TestNode must have at least two parameters"),
+ ):
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ def render(self) -> str: # type: ignore
+ return ""
+
+ def test_node_render_accepted_params_set_by_render_signature(self):
+ captured = None
+
+ class TestNode1(BaseNode):
+ tag = "mytag"
+ allowed_flags = ["required", "default"]
+
+ def render(self, context: Context, name: str, count: int = 1, *, msg: str, mode: str = "default") -> str:
+ nonlocal captured
+ captured = name, count, msg, mode
+ return ""
+
+ TestNode1.register(component_tags.register)
+
+ # Set only required params
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' required %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == ("John", 1, "Hello", "default")
+
+ # Set all params
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John2' count=2 msg='Hello' mode='custom' required %}
+ """
+ )
+ template2.render(Context({}))
+ assert captured == ("John2", 2, "Hello", "custom")
+
+ # Set no params
+ template3 = Template(
+ """
+ {% load component_tags %}
+ {% mytag %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template3.render(Context({}))
+
+ # Omit required arg
+ template4 = Template(
+ """
+ {% load component_tags %}
+ {% mytag msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template4.render(Context({}))
+
+ # Omit required kwarg
+ template5 = Template(
+ """
+ {% load component_tags %}
+ {% mytag name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'msg'"),
+ ):
+ template5.render(Context({}))
+
+ # Extra args
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 123 count=1 name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got multiple values for argument 'name'"),
+ ):
+ template6.render(Context({}))
+
+ # Extra args after kwargs
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag count=1 name='John' 123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template6.render(Context({}))
+
+ # Extra kwargs
+ template7 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' var=123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'var'"),
+ ):
+ template7.render(Context({}))
+
+ # Extra kwargs - non-identifier or kwargs
+ template8 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' data-id=123 class="pa-4" @click.once="myVar" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'data-id'"),
+ ):
+ template8.render(Context({}))
+
+ # Extra arg after special kwargs
+ template9 = Template(
+ """
+ {% load component_tags %}
+ {% mytag data-id=123 'John' msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ SyntaxError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template9.render(Context({}))
+
+ TestNode1.unregister(component_tags.register)
+
+ def test_node_render_extra_args_and_kwargs(self):
+ captured = None
+
+ class TestNode1(BaseNode):
+ tag = "mytag"
+ allowed_flags = ["required", "default"]
+
+ def render(self, context: Context, name: str, *args, msg: str, **kwargs) -> str:
+ nonlocal captured
+ captured = name, args, msg, kwargs
+ return ""
+
+ TestNode1.register(component_tags.register)
+
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John'
+ 123 456 789 msg='Hello' a=1 b=2 c=3 required
+ data-id=123 class="pa-4" @click.once="myVar"
+ %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == (
+ "John",
+ (123, 456, 789),
+ "Hello",
+ {"a": 1, "b": 2, "c": 3, "data-id": 123, "class": "pa-4", "@click.once": "myVar"},
+ )
+
+ TestNode1.unregister(component_tags.register)
+
+ def test_node_render_kwargs_only(self):
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ def render(self, context: Context, **kwargs) -> str:
+ nonlocal captured
+ captured = kwargs
+ return ""
+
+ TestNode.register(component_tags.register)
+
+ # Test with various kwargs including non-identifier keys
+ template = Template(
+ """
+ {% load component_tags %}
+ {% mytag
+ name='John'
+ age=25
+ data-id=123
+ class="header"
+ @click="handleClick"
+ v-if="isVisible"
+ %}
+ """
+ )
+ template.render(Context({}))
+
+ # All kwargs should be accepted since the function accepts **kwargs
+ assert captured == {
+ "name": "John",
+ "age": 25,
+ "data-id": 123,
+ "class": "header",
+ "@click": "handleClick",
+ "v-if": "isVisible",
+ }
+
+ # Test with positional args (should fail since function only accepts kwargs)
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag "John" name="Mary" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': takes 0 positional arguments but 1 was given"),
+ ):
+ template2.render(Context({}))
+
+ TestNode.unregister(component_tags.register)
+
+
+@djc_test
+class TestDecorator:
+ def test_decorator_requires_tag(self):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("template_tag() missing 1 required positional argument: 'tag'"),
+ ):
+
+ @template_tag(component_tags.register) # type: ignore
+ def mytag(node: BaseNode, context: Context) -> str:
+ return ""
+
+ # Test that the template tag can be used within the template under the registered tag
+ def test_decorator_tags(self):
+ @template_tag(component_tags.register, tag="mytag", end_tag="endmytag")
+ def render(node: BaseNode, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ # Works with end tag and self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assert rendered.strip() == "Hello, John!\n Shorthand: Hello, Mary!"
+
+ # But raises if missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Unclosed tag on line 3: 'mytag'"),
+ ):
+ Template(template_str2)
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_no_end_tag(self):
+ @template_tag(component_tags.register, tag="mytag") # type: ignore
+ def render(node: BaseNode, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ # Raises with end tag or self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Invalid block tag on line 4: 'endmytag'"),
+ ):
+ Template(template_str)
+
+ # Works when missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ template2 = Template(template_str2)
+ rendered2 = template2.render(Context({}))
+ assert rendered2.strip() == "Hello, John!"
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_flags(self):
+ @template_tag(component_tags.register, tag="mytag", end_tag="endmytag", allowed_flags=["required", "default"])
+ def render(node: BaseNode, context: Context, name: str, **kwargs) -> str:
+ return ""
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_render(self):
+ # Check that the render function is called with the context
+ captured = None
+
+ @template_tag(component_tags.register, tag="mytag") # type: ignore
+ def render(node: BaseNode, context: Context) -> str:
+ nonlocal captured
+ captured = context.flatten()
+ return f"Hello, {context['name']}!"
+
+ template_str = """
+ {% load component_tags %}
+ {% mytag / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({"name": "John"}))
+
+ assert captured == {"False": False, "None": None, "True": True, "name": "John"}
+ assert rendered.strip() == "Hello, John!"
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_render_raises_if_no_context_arg(self):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Failed to create node class in 'template_tag()' for 'render'"),
+ ):
+
+ @template_tag(component_tags.register, tag="mytag") # type: ignore
+ def render(node: BaseNode) -> str: # type: ignore
+ return ""
+
+ def test_decorator_render_accepted_params_set_by_render_signature(self):
+ captured = None
+
+ @template_tag(component_tags.register, tag="mytag", allowed_flags=["required", "default"]) # type: ignore
+ def render(
+ node: BaseNode, context: Context, name: str, count: int = 1, *, msg: str, mode: str = "default"
+ ) -> str:
+ nonlocal captured
+ captured = name, count, msg, mode
+ return ""
+
+ # Set only required params
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' required %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == ("John", 1, "Hello", "default")
+
+ # Set all params
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John2' count=2 msg='Hello' mode='custom' required %}
+ """
+ )
+ template2.render(Context({}))
+ assert captured == ("John2", 2, "Hello", "custom")
+
+ # Set no params
+ template3 = Template(
+ """
+ {% load component_tags %}
+ {% mytag %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template3.render(Context({}))
+
+ # Omit required arg
+ template4 = Template(
+ """
+ {% load component_tags %}
+ {% mytag msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template4.render(Context({}))
+
+ # Omit required kwarg
+ template5 = Template(
+ """
+ {% load component_tags %}
+ {% mytag name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'msg'"),
+ ):
+ template5.render(Context({}))
+
+ # Extra args
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 123 count=1 name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got multiple values for argument 'name'"),
+ ):
+ template6.render(Context({}))
+
+ # Extra args after kwargs
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag count=1 name='John' 123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template6.render(Context({}))
+
+ # Extra kwargs
+ template7 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' var=123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'var'"),
+ ):
+ template7.render(Context({}))
+
+ # Extra kwargs - non-identifier or kwargs
+ template8 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' data-id=123 class="pa-4" @click.once="myVar" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'data-id'"),
+ ):
+ template8.render(Context({}))
+
+ # Extra arg after special kwargs
+ template9 = Template(
+ """
+ {% load component_tags %}
+ {% mytag data-id=123 'John' msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ SyntaxError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template9.render(Context({}))
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_render_extra_args_and_kwargs(self):
+ captured = None
+
+ @template_tag(component_tags.register, tag="mytag", allowed_flags=["required", "default"]) # type: ignore
+ def render(node: BaseNode, context: Context, name: str, *args, msg: str, **kwargs) -> str:
+ nonlocal captured
+ captured = name, args, msg, kwargs
+ return ""
+
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John'
+ 123 456 789 msg='Hello' a=1 b=2 c=3 required
+ data-id=123 class="pa-4" @click.once="myVar"
+ %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == (
+ "John",
+ (123, 456, 789),
+ "Hello",
+ {"a": 1, "b": 2, "c": 3, "data-id": 123, "class": "pa-4", "@click.once": "myVar"},
+ )
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+ def test_decorator_render_kwargs_only(self):
+ captured = None
+
+ @template_tag(component_tags.register, tag="mytag") # type: ignore
+ def render(node: BaseNode, context: Context, **kwargs) -> str:
+ nonlocal captured
+ captured = kwargs
+ return ""
+
+ # Test with various kwargs including non-identifier keys
+ template = Template(
+ """
+ {% load component_tags %}
+ {% mytag
+ name='John'
+ age=25
+ data-id=123
+ class="header"
+ @click="handleClick"
+ v-if="isVisible"
+ %}
+ """
+ )
+ template.render(Context({}))
+
+ # All kwargs should be accepted since the function accepts **kwargs
+ assert captured == {
+ "name": "John",
+ "age": 25,
+ "data-id": 123,
+ "class": "header",
+ "@click": "handleClick",
+ "v-if": "isVisible",
+ }
+
+ # Test with positional args (should fail since function only accepts kwargs)
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag "John" name="Mary" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': takes 0 positional arguments but 1 was given"),
+ ):
+ template2.render(Context({}))
+
+ render._node.unregister(component_tags.register) # type: ignore[attr-defined]
+
+
+def force_signature_validation(fn):
+ """
+ Creates a proxy around a function that makes __code__ inaccessible,
+ forcing the use of signature-based validation.
+ """
+
+ class SignatureOnlyFunction:
+ def __init__(self, fn):
+ self.__wrapped__ = fn
+ self.__signature__ = inspect.signature(fn)
+
+ def __call__(self, *args, **kwargs):
+ return self.__wrapped__(*args, **kwargs)
+
+ def __getattr__(self, name):
+ # Return None for __code__ to force signature-based validation
+ if name == "__code__":
+ return None
+ # For all other attributes, delegate to the wrapped function
+ return getattr(self.__wrapped__, name)
+
+ return SignatureOnlyFunction(fn)
+
+
+@djc_test
+class TestSignatureBasedValidation:
+ # Test that the template tag can be used within the template under the registered tag
+ def test_node_class_tags(self):
+ class TestNode(BaseNode):
+ tag = "mytag"
+ end_tag = "endmytag"
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ # Works with end tag and self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assert rendered.strip() == "Hello, John!\n Shorthand: Hello, Mary!"
+
+ # But raises if missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Unclosed tag on line 3: 'mytag'"),
+ ):
+ Template(template_str2)
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_class_no_end_tag(self):
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ # Raises with end tag or self-closing
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ {% endmytag %}
+ Shorthand: {% mytag 'Mary' / %}
+ """
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Invalid block tag on line 4: 'endmytag'"),
+ ):
+ Template(template_str)
+
+ # Works when missing end tag
+ template_str2: types.django_html = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ """
+ template2 = Template(template_str2)
+ rendered2 = template2.render(Context({}))
+ assert rendered2.strip() == "Hello, John!"
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_class_flags(self):
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+ end_tag = "endmytag"
+ allowed_flags = ["required", "default"]
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ nonlocal captured
+ captured = self.allowed_flags, self.flags, self.active_flags
+ return f"Hello, {name}!"
+
+ TestNode.register(component_tags.register)
+
+ template_str = """
+ {% load component_tags %}
+ {% mytag 'John' required / %}
+ """
+ template = Template(template_str)
+ template.render(Context({}))
+
+ allowed_flags, flags, active_flags = captured # type: ignore
+ assert allowed_flags == ["required", "default"]
+ assert flags == {"required": True, "default": False}
+ assert active_flags == ["required"]
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_class_attributes(self):
+ captured = None
+
+ class TestNodeWithEndTag(BaseNode):
+ tag = "mytag"
+ end_tag = "endmytag"
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ nonlocal captured
+ captured = (
+ self.params,
+ self.nodelist,
+ self.node_id,
+ self.contents,
+ self.template_name,
+ self.template_component,
+ )
+ return f"Hello, {name}!"
+
+ # Case 1 - Node with end tag and NOT self-closing
+ TestNodeWithEndTag.register(component_tags.register)
+
+ template_str1 = """
+ {% load component_tags %}
+ {% mytag 'John' %}
+ INSIDE TAG {{ my_var }} {# comment #} {% lorem 1 w %} {% if True %} henlo {% endif %}
+ {% endmytag %}
+ """
+ template1 = Template(template_str1)
+ template1.render(Context({}))
+
+ params1, nodelist1, node_id1, contents1, template_name1, template_component1 = captured # type: ignore
+ assert len(params1) == 1
+ assert isinstance(params1[0], TagAttr)
+ # NOTE: The comment node is not included in the nodelist
+ assert len(nodelist1) == 8
+ assert isinstance(nodelist1[0], TextNode)
+ assert isinstance(nodelist1[1], VariableNode)
+ assert isinstance(nodelist1[2], TextNode)
+ assert isinstance(nodelist1[3], TextNode)
+ assert isinstance(nodelist1[4], LoremNode)
+ assert isinstance(nodelist1[5], TextNode)
+ assert isinstance(nodelist1[6], IfNode)
+ assert isinstance(nodelist1[7], TextNode)
+ assert contents1 == "\n INSIDE TAG {{ my_var }} {# comment #} {% lorem 1 w %} {% if True %} henlo {% endif %}\n " # noqa: E501
+ assert node_id1 == "a1bc3e"
+ assert template_name1 == ''
+ assert template_component1 is None
+
+ captured = None # Reset captured
+
+ # Case 2 - Node with end tag and NOT self-closing
+ template_str2 = """
+ {% load component_tags %}
+ {% mytag 'John' / %}
+ """
+ template2 = Template(template_str2)
+ template2.render(Context({}))
+
+ params2, nodelist2, node_id2, contents2, template_name2, template_component2 = captured # type: ignore
+ assert len(params2) == 1 # type: ignore
+ assert isinstance(params2[0], TagAttr) # type: ignore
+ assert len(nodelist2) == 0 # type: ignore
+ assert contents2 is None # type: ignore
+ assert node_id2 == "a1bc3f" # type: ignore
+ assert template_name2 == '' # type: ignore
+ assert template_component2 is None # type: ignore
+
+ captured = None # Reset captured
+
+ # Case 3 - Node without end tag
+ class TestNodeWithoutEndTag(BaseNode):
+ tag = "mytag2"
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, **kwargs) -> str:
+ nonlocal captured
+ captured = self.params, self.nodelist, self.node_id, self.contents, self.template_name, self.template_component # noqa: E501
+ return f"Hello, {name}!"
+
+ TestNodeWithoutEndTag.register(component_tags.register)
+
+ template_str3 = """
+ {% load component_tags %}
+ {% mytag2 'John' %}
+ """
+ template3 = Template(template_str3)
+ template3.render(Context({}))
+
+ params3, nodelist3, node_id3, contents3, template_name3, template_component3 = captured # type: ignore
+ assert len(params3) == 1 # type: ignore
+ assert isinstance(params3[0], TagAttr) # type: ignore
+ assert len(nodelist3) == 0 # type: ignore
+ assert contents3 is None # type: ignore
+ assert node_id3 == "a1bc40" # type: ignore
+ assert template_name3 == '' # type: ignore
+ assert template_component3 is None # type: ignore
+
+ # Case 4 - Node nested in Component end tag
+ class TestComponent(Component):
+ template = """
+ {% load component_tags %}
+ {% mytag2 'John' %}
+ """
+
+ TestComponent.render(Context({}))
+
+ params4, nodelist4, node_id4, contents4, template_name4, template_component4 = captured # type: ignore
+ assert len(params4) == 1 # type: ignore
+ assert isinstance(params4[0], TagAttr) # type: ignore
+ assert len(nodelist4) == 0 # type: ignore
+ assert contents4 is None # type: ignore
+ assert node_id4 == "a1bc42" # type: ignore
+
+ if os.name == "nt":
+ assert cast(str, template_name4).endswith("\\tests\\test_node.py::TestComponent") # type: ignore
+ else:
+ assert cast(str, template_name4).endswith("/tests/test_node.py::TestComponent") # type: ignore
+
+ assert template_name4 == f"{__file__}::TestComponent" # type: ignore
+ assert template_component4 is TestComponent # type: ignore
+
+ # Cleanup
+ TestNodeWithEndTag.unregister(component_tags.register)
+ TestNodeWithoutEndTag.unregister(component_tags.register)
+
+ def test_node_render(self):
+ # Check that the render function is called with the context
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ @force_signature_validation
+ def render(self, context: Context) -> str:
+ nonlocal captured
+ captured = context.flatten()
+ return f"Hello, {context['name']}!"
+
+ TestNode.register(component_tags.register)
+
+ template_str = """
+ {% load component_tags %}
+ {% mytag / %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({"name": "John"}))
+
+ assert captured == {"False": False, "None": None, "True": True, "name": "John"}
+ assert rendered.strip() == "Hello, John!"
+
+ TestNode.unregister(component_tags.register)
+
+ def test_node_render_raises_if_no_context_arg(self):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("`render()` method of TestNode must have at least two parameters"),
+ ):
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ def render(self) -> str: # type: ignore
+ return ""
+
+ def test_node_render_accepted_params_set_by_render_signature(self):
+ captured = None
+
+ class TestNode1(BaseNode):
+ tag = "mytag"
+ allowed_flags = ["required", "default"]
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, count: int = 1, *, msg: str, mode: str = "default") -> str:
+ nonlocal captured
+ captured = name, count, msg, mode
+ return ""
+
+ TestNode1.register(component_tags.register)
+
+ # Set only required params
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' required %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == ("John", 1, "Hello", "default")
+
+ # Set all params
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John2' count=2 msg='Hello' mode='custom' required %}
+ """
+ )
+ template2.render(Context({}))
+ assert captured == ("John2", 2, "Hello", "custom")
+
+ # Set no params
+ template3 = Template(
+ """
+ {% load component_tags %}
+ {% mytag %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template3.render(Context({}))
+
+ # Omit required arg
+ template4 = Template(
+ """
+ {% load component_tags %}
+ {% mytag msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'name'"),
+ ):
+ template4.render(Context({}))
+
+ # Omit required kwarg
+ template5 = Template(
+ """
+ {% load component_tags %}
+ {% mytag name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': missing a required argument: 'msg'"),
+ ):
+ template5.render(Context({}))
+
+ # Extra args
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 123 count=1 name='John' %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got multiple values for argument 'name'"),
+ ):
+ template6.render(Context({}))
+
+ # Extra args after kwargs
+ template6 = Template(
+ """
+ {% load component_tags %}
+ {% mytag count=1 name='John' 123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template6.render(Context({}))
+
+ # Extra kwargs
+ template7 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' var=123 %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'var'"),
+ ):
+ template7.render(Context({}))
+
+ # Extra kwargs - non-identifier or kwargs
+ template8 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John' msg='Hello' mode='custom' data-id=123 class="pa-4" @click.once="myVar" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': got an unexpected keyword argument 'data-id'"),
+ ):
+ template8.render(Context({}))
+
+ # Extra arg after special kwargs
+ template9 = Template(
+ """
+ {% load component_tags %}
+ {% mytag data-id=123 'John' msg='Hello' %}
+ """
+ )
+ with pytest.raises(
+ SyntaxError,
+ match=re.escape("positional argument follows keyword argument"),
+ ):
+ template9.render(Context({}))
+
+ TestNode1.unregister(component_tags.register)
+
+ def test_node_render_extra_args_and_kwargs(self):
+ captured = None
+
+ class TestNode1(BaseNode):
+ tag = "mytag"
+ allowed_flags = ["required", "default"]
+
+ @force_signature_validation
+ def render(self, context: Context, name: str, *args, msg: str, **kwargs) -> str:
+ nonlocal captured
+ captured = name, args, msg, kwargs
+ return ""
+
+ TestNode1.register(component_tags.register)
+
+ template1 = Template(
+ """
+ {% load component_tags %}
+ {% mytag 'John'
+ 123 456 789 msg='Hello' a=1 b=2 c=3 required
+ data-id=123 class="pa-4" @click.once="myVar"
+ %}
+ """
+ )
+ template1.render(Context({}))
+ assert captured == (
+ "John",
+ (123, 456, 789),
+ "Hello",
+ {"a": 1, "b": 2, "c": 3, "data-id": 123, "class": "pa-4", "@click.once": "myVar"},
+ )
+
+ TestNode1.unregister(component_tags.register)
+
+ def test_node_render_kwargs_only(self):
+ captured = None
+
+ class TestNode(BaseNode):
+ tag = "mytag"
+
+ @force_signature_validation
+ def render(self, context: Context, **kwargs) -> str:
+ nonlocal captured
+ captured = kwargs
+ return ""
+
+ TestNode.register(component_tags.register)
+
+ # Test with various kwargs including non-identifier keys
+ template = Template(
+ """
+ {% load component_tags %}
+ {% mytag
+ name='John'
+ age=25
+ data-id=123
+ class="header"
+ @click="handleClick"
+ v-if="isVisible"
+ %}
+ """
+ )
+ template.render(Context({}))
+
+ # All kwargs should be accepted since the function accepts **kwargs
+ assert captured == {
+ "name": "John",
+ "age": 25,
+ "data-id": 123,
+ "class": "header",
+ "@click": "handleClick",
+ "v-if": "isVisible",
+ }
+
+ # Test with positional args (should fail since function only accepts kwargs)
+ template2 = Template(
+ """
+ {% load component_tags %}
+ {% mytag "John" name="Mary" %}
+ """
+ )
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'mytag': takes 0 positional arguments but 1 was given"),
+ ):
+ template2.render(Context({}))
+
+ TestNode.unregister(component_tags.register)
diff --git a/tests/test_registry.py b/tests/test_registry.py
index b3f4b88a..d9b240c5 100644
--- a/tests/test_registry.py
+++ b/tests/test_registry.py
@@ -1,7 +1,5 @@
-import unittest
-
+import pytest
from django.template import Context, Engine, Library, Template
-from django.test import override_settings
from django_components import (
AlreadyRegistered,
@@ -11,15 +9,17 @@ from django_components import (
NotRegistered,
RegistrySettings,
TagProtectedError,
+ all_registries,
component_formatter,
component_shorthand_formatter,
register,
registry,
types,
)
+from pytest_django.asserts import assertHTMLEqual
-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})
@@ -37,117 +37,123 @@ class MockComponentView(Component):
pass
-class ComponentRegistryTest(unittest.TestCase):
- def setUp(self):
- super().setUp()
- self.registry = ComponentRegistry()
-
+@djc_test
+class TestComponentRegistry:
def test_register_class_decorator(self):
+ assert not registry.has("decorated_component")
+
@register("decorated_component")
class TestComponent(Component):
pass
- self.assertEqual(registry.get("decorated_component"), TestComponent)
+ assert registry.has("decorated_component")
+ assert registry.get("decorated_component") == TestComponent
# Cleanup
registry.unregister("decorated_component")
+ assert not registry.has("decorated_component")
def test_register_class_decorator_custom_registry(self):
my_lib = Library()
my_reg = ComponentRegistry(library=my_lib)
- self.assertDictEqual(my_reg.all(), {})
- self.assertDictEqual(registry.all(), {})
+ default_registry_comps_before = len(registry.all())
+
+ assert my_reg.all() == {}
@register("decorated_component", registry=my_reg)
class TestComponent(Component):
pass
- self.assertDictEqual(my_reg.all(), {"decorated_component": TestComponent})
- self.assertDictEqual(registry.all(), {})
+ assert my_reg.all() == {"decorated_component": TestComponent}
+
+ # Check that the component was NOT added to the default registry
+ default_registry_comps_after = len(registry.all())
+ assert default_registry_comps_before == default_registry_comps_after
def test_simple_register(self):
- self.registry.register(name="testcomponent", component=MockComponent)
- self.assertEqual(self.registry.all(), {"testcomponent": MockComponent})
+ custom_registry = ComponentRegistry()
+ custom_registry.register(name="testcomponent", component=MockComponent)
+ assert custom_registry.all() == {"testcomponent": MockComponent}
def test_register_two_components(self):
- self.registry.register(name="testcomponent", component=MockComponent)
- self.registry.register(name="testcomponent2", component=MockComponent)
- self.assertEqual(
- self.registry.all(),
- {
- "testcomponent": MockComponent,
- "testcomponent2": MockComponent,
- },
- )
+ custom_registry = ComponentRegistry()
+ custom_registry.register(name="testcomponent", component=MockComponent)
+ custom_registry.register(name="testcomponent2", component=MockComponent)
+ assert custom_registry.all() == {
+ "testcomponent": MockComponent,
+ "testcomponent2": MockComponent,
+ }
def test_unregisters_only_unused_tags(self):
- self.assertDictEqual(self.registry._tags, {})
+ custom_library = Library()
+ custom_registry = ComponentRegistry(library=custom_library)
+ assert custom_registry._tags == {}
+
# NOTE: We preserve the default component tags
- self.assertNotIn("component", self.registry.library.tags)
+ assert "component" not in custom_registry.library.tags
# Register two components that use the same tag
- self.registry.register(name="testcomponent", component=MockComponent)
- self.registry.register(name="testcomponent2", component=MockComponent)
+ custom_registry.register(name="testcomponent", component=MockComponent)
+ custom_registry.register(name="testcomponent2", component=MockComponent)
- self.assertDictEqual(
- self.registry._tags,
- {
- "component": {"testcomponent", "testcomponent2"},
- },
- )
+ assert custom_registry._tags == {
+ "component": {"testcomponent", "testcomponent2"},
+ }
- self.assertIn("component", self.registry.library.tags)
+ assert "component" in custom_registry.library.tags
# Unregister only one of the components. The tags should remain
- self.registry.unregister(name="testcomponent")
+ custom_registry.unregister(name="testcomponent")
- self.assertDictEqual(
- self.registry._tags,
- {
- "component": {"testcomponent2"},
- },
- )
+ assert custom_registry._tags == {
+ "component": {"testcomponent2"},
+ }
- self.assertIn("component", self.registry.library.tags)
+ assert "component" in custom_registry.library.tags
# Unregister the second components. The tags should be removed
- self.registry.unregister(name="testcomponent2")
+ custom_registry.unregister(name="testcomponent2")
- self.assertDictEqual(self.registry._tags, {})
- self.assertNotIn("component", self.registry.library.tags)
+ assert custom_registry._tags == {}
+ assert "component" not in custom_registry.library.tags
def test_prevent_registering_different_components_with_the_same_name(self):
- self.registry.register(name="testcomponent", component=MockComponent)
- with self.assertRaises(AlreadyRegistered):
- self.registry.register(name="testcomponent", component=MockComponent2)
+ custom_registry = ComponentRegistry()
+ custom_registry.register(name="testcomponent", component=MockComponent)
+ with pytest.raises(AlreadyRegistered):
+ custom_registry.register(name="testcomponent", component=MockComponent2)
def test_allow_duplicated_registration_of_the_same_component(self):
+ custom_registry = ComponentRegistry()
try:
- self.registry.register(name="testcomponent", component=MockComponentView)
- self.registry.register(name="testcomponent", component=MockComponentView)
+ custom_registry.register(name="testcomponent", component=MockComponentView)
+ custom_registry.register(name="testcomponent", component=MockComponentView)
except AlreadyRegistered:
- self.fail("Should not raise AlreadyRegistered")
+ pytest.fail("Should not raise AlreadyRegistered")
def test_simple_unregister(self):
- self.registry.register(name="testcomponent", component=MockComponent)
- self.registry.unregister(name="testcomponent")
- self.assertEqual(self.registry.all(), {})
+ custom_registry = ComponentRegistry()
+ custom_registry.register(name="testcomponent", component=MockComponent)
+ custom_registry.unregister(name="testcomponent")
+ assert custom_registry.all() == {}
def test_raises_on_failed_unregister(self):
- with self.assertRaises(NotRegistered):
- self.registry.unregister(name="testcomponent")
+ custom_registry = ComponentRegistry()
+ with pytest.raises(NotRegistered):
+ custom_registry.unregister(name="testcomponent")
-class MultipleComponentRegistriesTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_different_registries_have_different_settings(self):
+@djc_test
+class TestMultipleComponentRegistries:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_different_registries_have_different_settings(self, components_settings):
library_a = Library()
registry_a = ComponentRegistry(
library=library_a,
settings=RegistrySettings(
- CONTEXT_BEHAVIOR=ContextBehavior.ISOLATED,
- TAG_FORMATTER=component_shorthand_formatter,
+ context_behavior=ContextBehavior.ISOLATED.value,
+ tag_formatter=component_shorthand_formatter,
),
)
@@ -155,8 +161,8 @@ class MultipleComponentRegistriesTest(BaseTestCase):
registry_b = ComponentRegistry(
library=library_b,
settings=RegistrySettings(
- CONTEXT_BEHAVIOR=ContextBehavior.DJANGO,
- TAG_FORMATTER=component_formatter,
+ context_behavior=ContextBehavior.DJANGO.value,
+ tag_formatter=component_formatter,
),
)
@@ -176,9 +182,9 @@ class MultipleComponentRegistriesTest(BaseTestCase):
Slot: {% slot "default" default / %}
"""
- def get_context_data(self, variable=None):
+ def get_template_data(self, args, kwargs, slots, context):
return {
- "variable": variable,
+ "variable": kwargs.get("variable", None),
}
registry_a.register("simple_a", SimpleComponent)
@@ -196,14 +202,14 @@ class MultipleComponentRegistriesTest(BaseTestCase):
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- Variable: 123
+ Variable: 123
Slot:
SLOT 123
- Variable: 123
+ Variable: 123
Slot:
SLOT ABC
""",
@@ -214,17 +220,17 @@ class MultipleComponentRegistriesTest(BaseTestCase):
engine.template_builtins.remove(library_b)
-class ProtectedTagsTest(unittest.TestCase):
- def setUp(self):
- super().setUp()
- self.registry = ComponentRegistry()
-
+@djc_test
+class TestProtectedTags:
# NOTE: Use the `component_shorthand_formatter` formatter, so the components
# are registered under that tag
- @override_settings(COMPONENTS={"tag_formatter": "django_components.component_shorthand_formatter"})
+ @djc_test(
+ components_settings={
+ "tag_formatter": "django_components.component_shorthand_formatter",
+ },
+ )
def test_raises_on_overriding_our_tags(self):
for tag in [
- "component_dependencies",
"component_css_dependencies",
"component_js_dependencies",
"fill",
@@ -232,7 +238,7 @@ class ProtectedTagsTest(unittest.TestCase):
"provide",
"slot",
]:
- with self.assertRaises(TagProtectedError):
+ with pytest.raises(TagProtectedError):
@register(tag)
class TestComponent(Component):
@@ -244,3 +250,18 @@ class ProtectedTagsTest(unittest.TestCase):
# Cleanup
registry.unregister("sth_else")
+
+
+@djc_test
+class TestRegistryHelpers:
+ def test_all_registries(self):
+ # Default registry
+ assert len(all_registries()) == 1
+
+ reg = ComponentRegistry()
+
+ assert len(all_registries()) == 2
+
+ del reg
+
+ assert len(all_registries()) == 1
diff --git a/tests/test_safer_staticfiles.py b/tests/test_safer_staticfiles.py
deleted file mode 100644
index 63926345..00000000
--- a/tests/test_safer_staticfiles.py
+++ /dev/null
@@ -1,103 +0,0 @@
-from pathlib import Path
-
-from django.contrib.staticfiles.management.commands.collectstatic import Command
-from django.test import SimpleTestCase, override_settings
-
-from .django_test_setup import * # NOQA
-
-
-# This subclass allows us to call the `collectstatic` command from within Python.
-# We call the `collect` method, which returns info about what files were collected.
-#
-# The methods below are overriden to ensure we don't make any filesystem changes
-# (copy/delete), as the original command copies files. Thus we can safely test that
-# our `safer_staticfiles` app works as intended.
-class MockCollectstaticCommand(Command):
- # NOTE: We do not expect this to be called
- def clear_dir(self, path):
- raise NotImplementedError()
-
- # NOTE: We do not expect this to be called
- def link_file(self, path, prefixed_path, source_storage):
- raise NotImplementedError()
-
- def copy_file(self, path, prefixed_path, source_storage):
- # Skip this file if it was already copied earlier
- if prefixed_path in self.copied_files:
- return self.log("Skipping '%s' (already copied earlier)" % path)
- # Delete the target file if needed or break
- if not self.delete_file(path, prefixed_path, source_storage):
- return
- # The full path of the source file
- source_path = source_storage.path(path)
- # Finally start copying
- if self.dry_run:
- self.log("Pretending to copy '%s'" % source_path, level=1)
- else:
- self.log("Copying '%s'" % source_path, level=2)
- # ############# OUR CHANGE ##############
- # with source_storage.open(path) as source_file:
- # self.storage.save(prefixed_path, source_file)
- # ############# OUR CHANGE ##############
- self.copied_files.append(prefixed_path)
-
-
-def do_collect():
- cmd = MockCollectstaticCommand()
- cmd.set_options(
- interactive=False,
- verbosity=1,
- link=False,
- clear=False,
- dry_run=False,
- ignore_patterns=[],
- use_default_ignore_patterns=True,
- post_process=True,
- )
- collected = cmd.collect()
- return collected
-
-
-common_settings = {
- "STATIC_URL": "static/",
- "STATICFILES_DIRS": [Path(__file__).resolve().parent / "components"],
- "STATIC_ROOT": "staticfiles",
- "ROOT_URLCONF": __name__,
- "SECRET_KEY": "secret",
-}
-
-
-# Check that .py and .html files are INCLUDED with the original staticfiles app
-@override_settings(
- **common_settings,
- INSTALLED_APPS=("django_components", "django.contrib.staticfiles"),
-)
-class OrigStaticFileTests(SimpleTestCase):
- def test_python_and_html_included(self):
- collected = do_collect()
-
- self.assertIn("safer_staticfiles/safer_staticfiles.css", collected["modified"])
- self.assertIn("safer_staticfiles/safer_staticfiles.js", collected["modified"])
- self.assertIn("safer_staticfiles/safer_staticfiles.html", collected["modified"])
- self.assertIn("safer_staticfiles/safer_staticfiles.py", collected["modified"])
-
- self.assertListEqual(collected["unmodified"], [])
- self.assertListEqual(collected["post_processed"], [])
-
-
-# Check that .py and .html files are OMITTED from our version of staticfiles app
-@override_settings(
- **common_settings,
- INSTALLED_APPS=("django_components", "django_components.safer_staticfiles"),
-)
-class SaferStaticFileTests(SimpleTestCase):
- def test_python_and_html_omitted(self):
- collected = do_collect()
-
- self.assertIn("safer_staticfiles/safer_staticfiles.css", collected["modified"])
- self.assertIn("safer_staticfiles/safer_staticfiles.js", collected["modified"])
- self.assertNotIn("safer_staticfiles/safer_staticfiles.html", collected["modified"])
- self.assertNotIn("safer_staticfiles/safer_staticfiles.py", collected["modified"])
-
- self.assertListEqual(collected["unmodified"], [])
- self.assertListEqual(collected["post_processed"], [])
diff --git a/tests/test_settings.py b/tests/test_settings.py
index 34f4a7d3..2968b98c 100644
--- a/tests/test_settings.py
+++ b/tests/test_settings.py
@@ -1,19 +1,66 @@
+import re
+from pathlib import Path
+
+import pytest
from django.test import override_settings
-from django_components.app_settings import app_settings
+from django_components.app_settings import ComponentsSettings, app_settings
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase
+from django_components.testing import djc_test
+from .testutils import setup_test_config
-setup_test_config()
+setup_test_config(components={"autodiscover": False})
-class SettingsTestCase(BaseTestCase):
- @override_settings(COMPONENTS={"context_behavior": "isolated"})
+@djc_test
+class TestSettings:
+ @djc_test(
+ components_settings={
+ "context_behavior": "isolated",
+ },
+ )
def test_valid_context_behavior(self):
- self.assertEqual(app_settings.CONTEXT_BEHAVIOR, "isolated")
+ assert app_settings.CONTEXT_BEHAVIOR == "isolated"
- @override_settings(COMPONENTS={"context_behavior": "invalid_value"})
+ # NOTE: Since the part that we want to test here is otherwise part of the test setup
+ # this test places the `override_settings` and `_load_settings` (which is called by `djc_test`)
+ # inside the test.
def test_raises_on_invalid_context_behavior(self):
- with self.assertRaises(ValueError):
- app_settings.CONTEXT_BEHAVIOR
+ with override_settings(COMPONENTS={"context_behavior": "invalid_value"}):
+ with pytest.raises(
+ ValueError,
+ match=re.escape("Invalid context behavior: invalid_value. Valid options are ['django', 'isolated']"),
+ ):
+ app_settings._load_settings()
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": "base_dir",
+ },
+ )
+ def test_works_when_base_dir_is_string(self):
+ assert app_settings.DIRS == [Path("base_dir/components")]
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path("base_dir"),
+ },
+ )
+ def test_works_when_base_dir_is_path(self):
+ assert app_settings.DIRS == [Path("base_dir/components")]
+
+ @djc_test(
+ components_settings={
+ "context_behavior": "isolated",
+ },
+ )
+ def test_settings_as_dict(self):
+ assert app_settings.CONTEXT_BEHAVIOR == "isolated"
+
+ # NOTE: Since the part that we want to test here is otherwise part of the test setup
+ # this test places the `override_settings` and `_load_settings` (which is called by `djc_test`)
+ # inside the test.
+ def test_settings_as_instance(self):
+ with override_settings(COMPONENTS=ComponentsSettings(context_behavior="isolated")):
+ app_settings._load_settings()
+ assert app_settings.CONTEXT_BEHAVIOR == "isolated"
diff --git a/tests/test_signals.py b/tests/test_signals.py
new file mode 100644
index 00000000..6dcabfe9
--- /dev/null
+++ b/tests/test_signals.py
@@ -0,0 +1,114 @@
+from functools import wraps
+
+from django.template import Context, Template
+
+from django_components import Component, registry, types
+
+from django_components.testing import djc_test
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+def _get_templates_used_to_render(subject_template, render_context=None):
+ """Emulate django.test.client.Client (see request method)."""
+ from django.test.signals import template_rendered
+
+ templates_used = []
+
+ def receive_template_signal(sender, template, context, **_kwargs):
+ templates_used.append(template.name)
+
+ template_rendered.connect(receive_template_signal, dispatch_uid="test_method")
+ subject_template.render(render_context or Context({}))
+ template_rendered.disconnect(dispatch_uid="test_method")
+ return templates_used
+
+
+def with_template_signal(func):
+ @wraps(func)
+ def wrapper(*args, **kwargs):
+ # Emulate Django test instrumentation for TestCase (see setup_test_environment)
+ from django.test.utils import instrumented_test_render
+ from django.template import Template
+
+ original_template_render = Template._render
+ Template._render = instrumented_test_render
+
+ func(*args, **kwargs)
+
+ Template._render = original_template_render
+
+ return wrapper
+
+
+@djc_test
+class TestTemplateSignal:
+ def gen_slotted_component(self):
+ class SlottedComponent(Component):
+ template_file = "slotted_template.html"
+
+ return SlottedComponent
+
+ def gen_inner_component(self):
+ class InnerComponent(Component):
+ template_file = "simple_template.html"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs["variable"],
+ "variable2": kwargs.get("variable2", "default"),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ return InnerComponent
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ @with_template_signal
+ def test_template_rendered(self, components_settings):
+ registry.register("test_component", self.gen_slotted_component())
+ registry.register("inner_component", self.gen_inner_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test_component' %}{% endcomponent %}
+ """
+ template = Template(template_str, name="root")
+ templates_used = _get_templates_used_to_render(template)
+ assert "slotted_template.html" in templates_used
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ @with_template_signal
+ def test_template_rendered_nested_components(self, components_settings):
+ registry.register("test_component", self.gen_slotted_component())
+ registry.register("inner_component", self.gen_inner_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test_component' %}
+ {% fill "header" %}
+ {% component 'inner_component' variable='foo' %}{% endcomponent %}
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str, name="root")
+ templates_used = _get_templates_used_to_render(template)
+ assert "slotted_template.html" in templates_used
+ assert "simple_template.html" in templates_used
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ @with_template_signal
+ def test_template_rendered_skipped_when_no_template(self, components_settings):
+ class EmptyComponent(Component):
+ pass
+
+ registry.register("empty", EmptyComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'empty' / %}
+ """
+ template = Template(template_str, name="root")
+ templates_used = _get_templates_used_to_render(template)
+ assert templates_used == ["root"]
diff --git a/tests/test_slots.py b/tests/test_slots.py
new file mode 100644
index 00000000..eb6f0fce
--- /dev/null
+++ b/tests/test_slots.py
@@ -0,0 +1,743 @@
+"""
+Tests focusing on the Python part of slots.
+For tests focusing on the `{% slot %}` tag, see `test_templatetags_slot_fill.py`
+"""
+
+import re
+
+import pytest
+from django.template import Context, Template, TemplateSyntaxError
+from django.utils.safestring import mark_safe
+from django.template.base import NodeList, TextNode
+from pytest_django.asserts import assertHTMLEqual
+
+from django_components import Component, register, types
+from django_components.component import ComponentNode
+from django_components.slots import FillNode, Slot, SlotContext, SlotFallback
+
+from django_components.testing import djc_test
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# Test interaction of the `Slot` instances with Component rendering
+@djc_test
+class TestSlot:
+ @djc_test(
+ parametrize=(
+ ["components_settings", "is_isolated"],
+ [
+ [{"context_behavior": "django"}, False],
+ [{"context_behavior": "isolated"}, True],
+ ],
+ ["django", "isolated"],
+ )
+ )
+ def test_render_slot_as_func(self, components_settings, is_isolated):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required data1="abc" data2:hello="world" data2:one=123 %}
+ SLOT_DEFAULT
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "the_arg": args[0],
+ "the_kwarg": kwargs.pop("the_kwarg", None),
+ "kwargs": kwargs,
+ }
+
+ def slot_fn(ctx: SlotContext):
+ context = ctx.context
+ assert isinstance(context, Context)
+ # NOTE: Since the slot has access to the Context object, it should behave
+ # the same way as it does in templates - when in "isolated" mode, then the
+ # slot fill has access only to the "root" context, but not to the data of
+ # get_template_data() of SimpleComponent.
+ if is_isolated:
+ assert context.get("the_arg") is None
+ assert context.get("the_kwarg") is None
+ assert context.get("kwargs") is None
+ assert context.get("abc") is None
+ else:
+ assert context["the_arg"] == "1"
+ assert context["the_kwarg"] == 3
+ assert context["kwargs"] == {}
+ assert context["abc"] == "def"
+
+ slot_data_expected = {
+ "data1": "abc",
+ "data2": {"hello": "world", "one": 123},
+ }
+ assert slot_data_expected == ctx.data
+
+ assert isinstance(ctx.fallback, SlotFallback)
+ assert "SLOT_DEFAULT" == str(ctx.fallback).strip()
+
+ return f"FROM_INSIDE_SLOT_FN | {ctx.fallback}"
+
+ rendered = SimpleComponent.render(
+ context={"abc": "def"},
+ args=["1"],
+ kwargs={"the_kwarg": 3},
+ slots={"first": slot_fn},
+ )
+ assertHTMLEqual(
+ rendered,
+ "FROM_INSIDE_SLOT_FN | SLOT_DEFAULT",
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_render_raises_on_missing_slot(self, components_settings):
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Slot 'first' is marked as 'required' (i.e. non-optional), yet no fill is provided."),
+ ):
+ SimpleComponent.render()
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Slot 'first' is marked as 'required' (i.e. non-optional), yet no fill is provided."),
+ ):
+ SimpleComponent.render(
+ slots={"first": None},
+ )
+
+ SimpleComponent.render(
+ slots={"first": "SLOT_FN"},
+ )
+
+ def test_render_raises_on_slot_instance_in_slot_constructor(self):
+ slot: Slot = Slot(lambda ctx: "SLOT_FN")
+
+ with pytest.raises(
+ ValueError,
+ match=re.escape("Slot received another Slot instance as `contents`"),
+ ):
+ Slot(slot)
+
+ def test_render_slot_in_python__minimal(self):
+ def slot_fn(ctx: SlotContext):
+ assert ctx.context is None
+ assert ctx.data == {}
+ assert ctx.fallback is None
+
+ return "FROM_INSIDE_SLOT_FN"
+
+ slot: Slot = Slot(slot_fn)
+ rendered = slot()
+ assertHTMLEqual(
+ rendered,
+ "FROM_INSIDE_SLOT_FN",
+ )
+
+ def test_render_slot_in_python__with_data(self):
+ def slot_fn(ctx: SlotContext):
+ assert ctx.context is not None
+ assert ctx.context["the_arg"] == "1"
+ assert ctx.context["the_kwarg"] == 3
+ assert ctx.context["kwargs"] == {}
+ assert ctx.context["abc"] == "def"
+
+ slot_data_expected = {
+ "data1": "abc",
+ "data2": {"hello": "world", "one": 123},
+ }
+ assert slot_data_expected == ctx.data
+
+ assert isinstance(ctx.fallback, str)
+ assert "SLOT_DEFAULT" == ctx.fallback
+
+ return f"FROM_INSIDE_SLOT_FN | {ctx.fallback}"
+
+ slot: Slot = Slot(slot_fn)
+ context = Context({"the_arg": "1", "the_kwarg": 3, "kwargs": {}, "abc": "def"})
+
+ # Test positional arguments
+ rendered = slot(
+ {"data1": "abc", "data2": {"hello": "world", "one": 123}},
+ "SLOT_DEFAULT",
+ context,
+ )
+ assertHTMLEqual(
+ rendered,
+ "FROM_INSIDE_SLOT_FN | SLOT_DEFAULT",
+ )
+
+ # Test keyword arguments
+ rendered2 = slot(
+ data={"data1": "abc", "data2": {"hello": "world", "one": 123}},
+ fallback="SLOT_DEFAULT",
+ context=context,
+ )
+ assertHTMLEqual(
+ rendered2,
+ "FROM_INSIDE_SLOT_FN | SLOT_DEFAULT",
+ )
+
+ def test_render_slot_unsafe_content__func(self):
+ def slot_fn1(ctx: SlotContext):
+ return mark_safe("")
+
+ def slot_fn2(ctx: SlotContext):
+ return ""
+
+ slot1: Slot = Slot(slot_fn1)
+ slot2: Slot = Slot(slot_fn2)
+
+ rendered1 = slot1()
+ rendered2 = slot2()
+ assert rendered1 == ""
+ assert rendered2 == "<script>alert('XSS')</script>"
+
+ def test_render_slot_unsafe_content__string(self):
+ slot1: Slot = Slot(mark_safe(""))
+ slot2: Slot = Slot("")
+
+ rendered1 = slot1()
+ rendered2 = slot2()
+ assert rendered1 == ""
+ assert rendered2 == "<script>alert('XSS')</script>"
+
+ # Part of the slot caching feature - test that static content slots reuse the slot function.
+ # See https://github.com/django-components/django-components/issues/1164#issuecomment-2854682354
+ def test_slots_same_contents__string(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ SimpleComponent.render(
+ slots={"first": "FIRST_SLOT"},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.content_func is not None
+ assert first_slot_func.contents == "FIRST_SLOT"
+
+ captured_slots = {}
+ SimpleComponent.render(
+ slots={"first": "FIRST_SLOT"},
+ )
+
+ second_slot_func = captured_slots["first"]
+ assert isinstance(second_slot_func, Slot)
+ assert second_slot_func.content_func is not None
+ assert second_slot_func.contents == "FIRST_SLOT"
+
+ assert first_slot_func.contents == second_slot_func.contents
+
+ # Part of the slot caching feature - test that consistent functions passed as slots
+ # reuse the slot function.
+ def test_slots_same_contents__func(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ slot_func = lambda ctx: "FROM_INSIDE_SLOT" # noqa: E731
+
+ SimpleComponent.render(
+ slots={"first": slot_func},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert callable(first_slot_func.content_func)
+ assert callable(first_slot_func.contents)
+
+ captured_slots = {}
+ SimpleComponent.render(
+ slots={"first": slot_func},
+ )
+
+ second_slot_func = captured_slots["first"]
+ assert isinstance(second_slot_func, Slot)
+ assert callable(second_slot_func.content_func)
+ assert callable(second_slot_func.contents)
+
+ assert first_slot_func.contents is second_slot_func.contents
+
+ # Part of the slot caching feature - test that `Slot` instances with identical function
+ # passed as slots reuse the slot function.
+ def test_slots_same_contents__slot(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ slot_func = lambda ctx: "FROM_INSIDE_SLOT" # noqa: E731
+
+ SimpleComponent.render(
+ slots={"first": Slot(slot_func)},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert callable(first_slot_func.content_func)
+ assert callable(first_slot_func.contents)
+
+ captured_slots = {}
+ SimpleComponent.render(
+ slots={"first": Slot(slot_func)},
+ )
+
+ second_slot_func = captured_slots["first"]
+ assert isinstance(second_slot_func, Slot)
+ assert callable(second_slot_func.content_func)
+ assert callable(second_slot_func.contents)
+
+ assert first_slot_func.contents == second_slot_func.contents
+
+ # Part of the slot caching feature - test that identical slot fill content
+ # slots reuse the slot function.
+ def test_slots_same_contents__fill_tag_default(self):
+ captured_slots = {}
+
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ FROM_INSIDE_DEFAULT_SLOT
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ template.render(Context())
+
+ first_slot_func = captured_slots["default"]
+ assert isinstance(first_slot_func, Slot)
+ assert callable(first_slot_func.content_func)
+ assert first_slot_func.contents == "\n FROM_INSIDE_DEFAULT_SLOT\n "
+
+ captured_slots = {}
+ template.render(Context())
+
+ second_slot_func = captured_slots["default"]
+ assert isinstance(second_slot_func, Slot)
+ assert callable(second_slot_func.content_func)
+ assert second_slot_func.contents == "\n FROM_INSIDE_DEFAULT_SLOT\n "
+
+ assert first_slot_func.contents == second_slot_func.contents
+
+ # Part of the slot caching feature - test that identical slot fill content
+ # slots reuse the slot function.
+ def test_slots_same_contents__fill_tag_named(self):
+ captured_slots = {}
+
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" %}
+ FROM_INSIDE_NAMED_SLOT
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ template.render(Context())
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert callable(first_slot_func.content_func)
+ assert first_slot_func.contents == "\n FROM_INSIDE_NAMED_SLOT\n "
+
+ captured_slots = {}
+ template.render(Context())
+
+ second_slot_func = captured_slots["first"]
+ assert isinstance(second_slot_func, Slot)
+ assert callable(second_slot_func.content_func)
+ assert second_slot_func.contents == "\n FROM_INSIDE_NAMED_SLOT\n "
+
+ assert first_slot_func.contents == second_slot_func.contents
+
+ def test_slot_metadata__string(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ SimpleComponent.render(
+ slots={"first": "FIRST_SLOT"},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "SimpleComponent"
+ assert first_slot_func.slot_name == "first"
+ assert first_slot_func.fill_node is None
+ assert first_slot_func.extra == {}
+
+ first_nodelist: NodeList = first_slot_func.nodelist
+ assert len(first_nodelist) == 1
+ assert isinstance(first_nodelist[0], TextNode)
+ assert first_nodelist[0].s == "FIRST_SLOT"
+
+ # Part of the slot caching feature - test that consistent functions passed as slots
+ # reuse the slot function.
+ def test_slot_metadata__func(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ slot_func = lambda ctx: "FROM_INSIDE_SLOT" # noqa: E731
+
+ SimpleComponent.render(
+ slots={"first": slot_func},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "SimpleComponent"
+ assert first_slot_func.slot_name == "first"
+ assert first_slot_func.fill_node is None
+ assert first_slot_func.extra == {}
+ assert first_slot_func.nodelist is None
+
+ # Part of the slot caching feature - test that `Slot` instances with identical function
+ # passed as slots reuse the slot function.
+ def test_slot_metadata__slot(self):
+ captured_slots = {}
+
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" required %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ slot_func = lambda ctx: "FROM_INSIDE_SLOT" # noqa: E731
+
+ SimpleComponent.render(
+ slots={"first": Slot(slot_func, extra={"foo": "bar"}, slot_name="whoop")},
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "SimpleComponent"
+ assert first_slot_func.slot_name == "whoop"
+ assert first_slot_func.fill_node is None
+ assert first_slot_func.extra == {"foo": "bar"}
+ assert first_slot_func.nodelist is None
+
+ # Part of the slot caching feature - test that identical slot fill content
+ # slots reuse the slot function.
+ def test_slot_metadata__fill_tag_default(self):
+ captured_slots = {}
+
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ FROM_INSIDE_DEFAULT_SLOT
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ template.render(Context())
+
+ first_slot_func = captured_slots["default"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "test"
+ assert first_slot_func.slot_name == "default"
+ assert isinstance(first_slot_func.fill_node, ComponentNode)
+ assert first_slot_func.extra == {}
+
+ first_nodelist: NodeList = first_slot_func.nodelist
+ assert len(first_nodelist) == 1
+ assert isinstance(first_nodelist[0], TextNode)
+ assert first_nodelist[0].s == "\n FROM_INSIDE_DEFAULT_SLOT\n "
+
+ # Part of the slot caching feature - test that identical slot fill content
+ # slots reuse the slot function.
+ def test_slot_metadata__fill_tag_named(self):
+ captured_slots = {}
+
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" %}
+ FROM_INSIDE_NAMED_SLOT
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ template.render(Context())
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "test"
+ assert first_slot_func.slot_name == "first"
+ assert isinstance(first_slot_func.fill_node, FillNode)
+ assert first_slot_func.extra == {}
+
+ first_nodelist: NodeList = first_slot_func.nodelist
+ assert len(first_nodelist) == 1
+ assert isinstance(first_nodelist[0], TextNode)
+ assert first_nodelist[0].s == "\n FROM_INSIDE_NAMED_SLOT\n "
+
+ # Part of the slot caching feature - test that identical slot fill content
+ # slots reuse the slot function.
+ def test_slot_metadata__fill_tag_body(self):
+ captured_slots = {}
+
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured_slots
+ captured_slots = slots
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" body=my_slot / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ template.render(
+ Context(
+ {
+ "my_slot": Slot(lambda ctx: "FROM_INSIDE_NAMED_SLOT", extra={"foo": "bar"}, slot_name="whoop"),
+ }
+ )
+ )
+
+ first_slot_func = captured_slots["first"]
+ assert isinstance(first_slot_func, Slot)
+ assert first_slot_func.component_name == "test"
+ assert first_slot_func.slot_name == "whoop"
+ assert isinstance(first_slot_func.fill_node, FillNode)
+ assert first_slot_func.extra == {"foo": "bar"}
+ assert first_slot_func.nodelist is None
+
+ def test_pass_body_to_fill__slot(self):
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" body=my_slot / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ my_slot: Slot = Slot(lambda ctx: "FROM_INSIDE_NAMED_SLOT")
+ rendered: str = template.render(Context({"my_slot": my_slot}))
+
+ assert rendered.strip() == "FROM_INSIDE_NAMED_SLOT"
+
+ def test_pass_body_to_fill__string(self):
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" body=my_slot / %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ rendered: str = template.render(Context({"my_slot": "FROM_INSIDE_NAMED_SLOT"}))
+
+ assert rendered.strip() == "FROM_INSIDE_NAMED_SLOT"
+
+ def test_pass_body_to_fill_raises_on_body(self):
+ @register("test")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "first" default %}
+ {% endslot %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "first" body=my_slot %}
+ FROM_INSIDE_NAMED_SLOT
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ my_slot: Slot = Slot(lambda ctx: "FROM_INSIDE_NAMED_SLOT")
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Fill 'first' received content both through 'body' kwarg and '{% fill %}' body."),
+ ):
+ template.render(Context({"my_slot": my_slot}))
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_call_outside_render_context(self, components_settings):
+ from django_components import register, Component
+
+ seen_slots = []
+
+ @register("MyTopLevelComponent")
+ class MyTopLevelComponent(Component):
+ template = """
+ {% for thing in words %}
+ {% component "MyComponentBeingLooped" / %}
+ {% endfor %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "words": ["apple", "car", "russia"],
+ }
+
+ @register("MyComponentBeingLooped")
+ class MyComponentBeingLooped(Component):
+ template = """
+ {% component "MyComponentWithASlot" %}
+ {% fill "my_slot" %}
+ {% component "MyInnerComponent" / %}
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ @register("MyInnerComponent")
+ class MyInnerComponent(Component):
+ template = "Hello!"
+
+ @register("MyComponentWithASlot")
+ class MyComponentWithASlot(Component):
+ template = "CAPTURER"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ seen_slots.append(self.slots["my_slot"])
+
+ MyTopLevelComponent.render()
+
+ assert len(seen_slots) == 3
+
+ results = [slot().strip() for slot in seen_slots]
+ assert results == [
+ "Hello!",
+ "Hello!",
+ "Hello!",
+ ]
diff --git a/tests/test_tag_formatter.py b/tests/test_tag_formatter.py
index 96c8ef78..82a3ec1a 100644
--- a/tests/test_tag_formatter.py
+++ b/tests/test_tag_formatter.py
@@ -1,10 +1,14 @@
+import re
+
+import pytest
from django.template import Context, Template
+from pytest_django.asserts import assertHTMLEqual
from django_components import Component, register, types
from django_components.tag_formatter import ShorthandComponentFormatter
-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})
@@ -19,6 +23,11 @@ class MultiwordBlockEndTagFormatter(ShorthandComponentFormatter):
return f"end {name}"
+class SlashEndTagFormatter(ShorthandComponentFormatter):
+ def end_tag(self, name):
+ return f"/{name}"
+
+
# Create a TagFormatter class to validate the public interface
def create_validator_tag_formatter(tag_name: str):
class ValidatorTagFormatter(ShorthandComponentFormatter):
@@ -38,9 +47,10 @@ def create_validator_tag_formatter(tag_name: str):
return ValidatorTagFormatter()
-class ComponentTagTests(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_formatter_default_inline(self):
+@djc_test
+class TestComponentTag:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_formatter_default_inline(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -59,19 +69,19 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
{{ x }}
"""
- template_str: types.django_html = (
+ context = Context(
+ {
+ "my_dict": {
+ "attrs:@click": "() => {}",
+ "attrs:style": "height: 20px",
+ "items": [1, 2, 3],
+ },
+ "list": [{"a": 1, "x": "OVERWRITTEN_X"}, {"a": 2}, {"a": 3}],
+ }
+ )
+
+ # Mergingg like this will raise TypeError, because it's like
+ # a function receiving multiple kwargs with the same name.
+ template_str1: types.django_html = (
"""
{% load component_tags %}
{% component 'test'
@@ -726,62 +684,45 @@ class SpreadOperatorTests(BaseTestCase):
x=123
..."{{ list|first }}"
/ %}
- """.replace(
- "\n", " "
- )
- )
-
- template = Template(template_str)
- rendered = template.render(
- Context(
- {
- "my_dict": {
- "attrs:@click": "() => {}",
- "attrs:style": "height: 20px",
- "items": [1, 2, 3],
- },
- "list": [{"a": 1, "x": "OVERWRITTEN_X"}, {"a": 2}, {"a": 3}],
- }
- ),
- )
-
- self.assertHTMLEqual(
- rendered,
"""
- {'@click': '() => {}', 'style': 'OVERWRITTEN'}
- [1, 2, 3]
- 1
- OVERWRITTEN_X
- """,
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_raises_if_positional_arg_after_spread(self):
- @register("test")
- class SimpleComponent(Component):
- pass
+ template1 = Template(template_str1)
- template_str: types.django_html = (
+ with pytest.raises(TypeError, match=re.escape("got multiple values for argument 'x'")):
+ template1.render(context)
+
+ # But, similarly to python, we can merge multiple **kwargs by instead
+ # merging them into a single dict, and spreading that.
+ template_str2: types.django_html = (
"""
{% load component_tags %}
{% component 'test'
- ...my_dict
- var_a
- ..."{{ list|first }}"
- x=123
+ ...{
+ **my_dict,
+ "x": 123,
+ **"{{ list|first }}",
+ }
+ attrs:style="OVERWRITTEN"
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
- with self.assertRaisesMessage(
- TemplateSyntaxError, "'component' received some positional argument(s) after some keyword argument(s)"
- ):
- Template(template_str)
+ template2 = Template(template_str2)
+ rendered2 = template2.render(context)
- @parametrize_context_behavior(["django", "isolated"])
- def test_raises_on_missing_value(self):
+ assertHTMLEqual(
+ rendered2,
+ """
+ {'@click': '() => {}', 'style': 'OVERWRITTEN'}
+ [1, 2, 3]
+ 1
+ OVERWRITTEN_X
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_missing_value(self, components_settings):
@register("test")
class SimpleComponent(Component):
pass
@@ -793,16 +734,51 @@ class SpreadOperatorTests(BaseTestCase):
var_a
...
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
- with self.assertRaisesMessage(TemplateSyntaxError, "Syntax operator is missing a value"):
+ with pytest.raises(TemplateSyntaxError, match=re.escape("Spread syntax '...' is missing a value")):
Template(template_str)
- @parametrize_context_behavior(["django", "isolated"])
- def test_raises_on_non_dict(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_spread_list_and_iterables(self, components_settings):
+ captured = None
+
+ @register("test")
+ class SimpleComponent(Component):
+ template = ""
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured
+ captured = args, kwargs
+
+ template_str: types.django_html = (
+ """
+ {% load component_tags %}
+ {% component 'test'
+ ...var_a
+ ...var_b
+ / %}
+ """
+ )
+ template = Template(template_str)
+
+ context = Context(
+ {
+ "var_a": "abc",
+ "var_b": [1, 2, 3],
+ }
+ )
+
+ template.render(context)
+
+ assert captured == (
+ ["a", "b", "c", 1, 2, 3],
+ {},
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_non_dict(self, components_settings):
@register("test")
class SimpleComponent(Component):
pass
@@ -811,36 +787,71 @@ class SpreadOperatorTests(BaseTestCase):
"""
{% load component_tags %}
{% component 'test'
- var_a
...var_b
/ %}
- """.replace(
- "\n", " "
- )
+ """
)
template = Template(template_str)
# List
- with self.assertRaisesMessage(
- RuntimeError, "Spread operator expression must resolve to a Dict, got [1, 2, 3]"
+ with pytest.raises(
+ ValueError,
+ match=re.escape("Cannot spread non-iterable value: '...var_b' resolved to 123")
):
- template.render(
- Context(
- {
- "var_a": "abc",
- "var_b": [1, 2, 3],
- }
- )
- )
+ template.render(Context({"var_b": 123}))
- # String
- with self.assertRaisesMessage(RuntimeError, "Spread operator expression must resolve to a Dict, got def"):
- template.render(
- Context(
- {
- "var_a": "abc",
- "var_b": "def",
- }
- )
- )
+
+@djc_test
+class TestAggregateKwargs:
+ def test_aggregate_kwargs(self):
+ captured = None
+
+ @register("test")
+ class Test(Component):
+ template = ""
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured
+ captured = args, kwargs
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test'
+ attrs:@click.stop="dispatch('click_event')"
+ attrs:x-data="{hello: 'world'}"
+ attrs:class=class_var
+ attrs::placeholder="No text"
+ my_dict:one=2
+ three=four
+ / %}
+ """
+
+ template = Template(template_str)
+ template.render(Context({"class_var": "padding-top-8", "four": 4}))
+
+ assert captured == (
+ [],
+ {
+ "attrs": {
+ "@click.stop": "dispatch('click_event')",
+ "x-data": "{hello: 'world'}",
+ "class": "padding-top-8",
+ ":placeholder": "No text",
+ },
+ "my_dict": {"one": 2},
+ "three": 4,
+ },
+ )
+
+ def test_is_aggregate_key(self):
+ assert not is_aggregate_key("")
+ assert not is_aggregate_key(" ")
+ assert not is_aggregate_key(" : ")
+ assert not is_aggregate_key("attrs")
+ assert not is_aggregate_key(":attrs")
+ assert not is_aggregate_key(" :attrs ")
+ assert not is_aggregate_key("attrs:")
+ assert not is_aggregate_key(":attrs:")
+ assert is_aggregate_key("at:trs")
+ assert not is_aggregate_key(":at:trs")
diff --git a/tests/test_extension.py b/tests/test_extension.py
new file mode 100644
index 00000000..cfd1c1cc
--- /dev/null
+++ b/tests/test_extension.py
@@ -0,0 +1,711 @@
+import gc
+from typing import Any, Callable, Dict, List, cast
+
+import pytest
+from django.http import HttpRequest, HttpResponse
+from django.template import Context, Origin, Template
+from django.test import Client
+
+from django_components import Component, Slot, SlotNode, register, registry
+from django_components.app_settings import app_settings
+from django_components.component_registry import ComponentRegistry
+from django_components.extension import (
+ URLRoute,
+ ComponentExtension,
+ ExtensionComponentConfig,
+ OnComponentClassCreatedContext,
+ OnComponentClassDeletedContext,
+ OnRegistryCreatedContext,
+ OnRegistryDeletedContext,
+ OnComponentRegisteredContext,
+ OnComponentUnregisteredContext,
+ OnComponentInputContext,
+ OnComponentDataContext,
+ OnComponentRenderedContext,
+ OnSlotRenderedContext,
+ OnTemplateLoadedContext,
+ OnTemplateCompiledContext,
+ OnJsLoadedContext,
+ OnCssLoadedContext,
+)
+from django_components.extensions.cache import CacheExtension
+from django_components.extensions.debug_highlight import DebugHighlightExtension
+from django_components.extensions.defaults import DefaultsExtension
+from django_components.extensions.dependencies import DependenciesExtension
+from django_components.extensions.view import ViewExtension
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+def dummy_view(request: HttpRequest):
+ # Test that the request object is passed to the view
+ assert isinstance(request, HttpRequest)
+ return HttpResponse("Hello, world!")
+
+
+def dummy_view_2(request: HttpRequest, id: int, name: str):
+ return HttpResponse(f"Hello, world! {id} {name}")
+
+
+# TODO_V1 - Remove
+class LegacyExtension(ComponentExtension):
+ name = "legacy"
+
+ class ExtensionClass(ExtensionComponentConfig):
+ foo = "1"
+ bar = "2"
+
+ @classmethod
+ def baz(cls):
+ return "3"
+
+
+class DummyExtension(ComponentExtension):
+ """
+ Test extension that tracks all hook calls and their arguments.
+ """
+
+ name = "test_extension"
+
+ class ComponentConfig(ExtensionComponentConfig):
+ foo = "1"
+ bar = "2"
+
+ @classmethod
+ def baz(cls):
+ return "3"
+
+ def __init__(self) -> None:
+ self.calls: Dict[str, List[Any]] = {
+ "on_component_class_created": [],
+ "on_component_class_deleted": [],
+ "on_registry_created": [],
+ "on_registry_deleted": [],
+ "on_component_registered": [],
+ "on_component_unregistered": [],
+ "on_component_input": [],
+ "on_component_data": [],
+ "on_component_rendered": [],
+ "on_slot_rendered": [],
+ "on_template_loaded": [],
+ "on_template_compiled": [],
+ "on_js_loaded": [],
+ "on_css_loaded": [],
+ }
+
+ urls = [
+ URLRoute(path="dummy-view/", handler=dummy_view, name="dummy"),
+ URLRoute(path="dummy-view-2/OVERRIDDEN: {ctx.result}
"
+
+
+def with_component_cls(on_created: Callable):
+ class TempComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ on_created()
+
+
+def with_registry(on_created: Callable):
+ registry = ComponentRegistry()
+
+ on_created(registry)
+
+
+class OverrideAssetExtension(ComponentExtension):
+ name = "override_asset_extension"
+
+ def on_template_loaded(self, ctx):
+ return "OVERRIDDEN TEMPLATE"
+
+ def on_js_loaded(self, ctx):
+ return "OVERRIDDEN JS"
+
+ def on_css_loaded(self, ctx):
+ return "OVERRIDDEN CSS"
+
+
+@djc_test
+class TestExtension:
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_extensions_setting(self):
+ assert len(app_settings.EXTENSIONS) == 6
+ assert isinstance(app_settings.EXTENSIONS[0], CacheExtension)
+ assert isinstance(app_settings.EXTENSIONS[1], DefaultsExtension)
+ assert isinstance(app_settings.EXTENSIONS[2], DependenciesExtension)
+ assert isinstance(app_settings.EXTENSIONS[3], ViewExtension)
+ assert isinstance(app_settings.EXTENSIONS[4], DebugHighlightExtension)
+ assert isinstance(app_settings.EXTENSIONS[5], DummyExtension)
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_access_component_from_extension(self):
+ class TestAccessComp(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ ext_class = TestAccessComp.TestExtension # type: ignore[attr-defined]
+ assert issubclass(ext_class, ComponentExtension.ComponentConfig)
+ assert ext_class.component_class is TestAccessComp
+
+ # NOTE: Required for test_component_class_lifecycle_hooks to work
+ del TestAccessComp
+ gc.collect()
+
+ def test_raises_on_extension_name_conflict(self):
+ @djc_test(components_settings={"extensions": [RenderExtension]})
+ def inner():
+ pass
+
+ with pytest.raises(ValueError, match="Extension name 'render' conflicts with existing Component class API"):
+ inner()
+
+ def test_raises_on_multiple_extensions_with_same_name(self):
+ @djc_test(components_settings={"extensions": [DummyExtension, DummyExtension]})
+ def inner():
+ pass
+
+ with pytest.raises(ValueError, match="Multiple extensions cannot have the same name 'test_extension'"):
+ inner()
+
+
+@djc_test
+class TestExtensionHooks:
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_component_class_lifecycle_hooks(self):
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ assert len(extension.calls["on_component_class_created"]) == 0
+ assert len(extension.calls["on_component_class_deleted"]) == 0
+
+ did_call_on_comp_cls_created = False
+
+ def on_comp_cls_created():
+ nonlocal did_call_on_comp_cls_created
+ did_call_on_comp_cls_created = True
+
+ # Verify on_component_class_created was called
+ assert len(extension.calls["on_component_class_created"]) == 1
+ assert extension.calls["on_component_class_created"][0] == "TempComponent"
+
+ # Create a component class in a separate scope, to avoid any references from within
+ # this test function, so we can garbage collect it after the function returns
+ with_component_cls(on_comp_cls_created)
+ assert did_call_on_comp_cls_created
+
+ # This should trigger the garbage collection of the component class
+ gc.collect()
+
+ # Verify on_component_class_deleted was called
+ # NOTE: The previous test, `test_access_component_from_extension`, is sometimes
+ # garbage-collected too late, in which case it's included in `on_component_class_deleted`.
+ # So in the test we check only for the last call.
+ assert len(extension.calls["on_component_class_deleted"]) >= 1
+ assert extension.calls["on_component_class_deleted"][-1] == "TempComponent"
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_registry_lifecycle_hooks(self):
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ assert len(extension.calls["on_registry_created"]) == 0
+ assert len(extension.calls["on_registry_deleted"]) == 0
+
+ did_call_on_registry_created = False
+ reg_id = None
+
+ def on_registry_created(reg):
+ nonlocal did_call_on_registry_created
+ nonlocal reg_id
+ did_call_on_registry_created = True
+ reg_id = id(reg)
+
+ # Verify on_registry_created was called
+ assert len(extension.calls["on_registry_created"]) == 1
+ assert extension.calls["on_registry_created"][0] == reg_id
+
+ with_registry(on_registry_created)
+ assert did_call_on_registry_created
+ assert reg_id is not None
+
+ gc.collect()
+
+ # Verify on_registry_deleted was called
+ assert len(extension.calls["on_registry_deleted"]) == 1
+ assert extension.calls["on_registry_deleted"][0] == reg_id
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_component_registration_hooks(self):
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ registry.register("test_comp", TestComponent)
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # Verify on_component_registered was called
+ assert len(extension.calls["on_component_registered"]) == 1
+ reg_call: OnComponentRegisteredContext = extension.calls["on_component_registered"][0]
+ assert reg_call.registry == registry
+ assert reg_call.name == "test_comp"
+ assert reg_call.component_cls == TestComponent
+
+ registry.unregister("test_comp")
+
+ # Verify on_component_unregistered was called
+ assert len(extension.calls["on_component_unregistered"]) == 1
+ unreg_call: OnComponentUnregisteredContext = extension.calls["on_component_unregistered"][0]
+ assert unreg_call.registry == registry
+ assert unreg_call.name == "test_comp"
+ assert unreg_call.component_cls == TestComponent
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_component_render_hooks(self):
+ @register("test_comp")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ def get_js_data(self, args, kwargs, slots, context):
+ return {"script": "console.log('Hello!')"}
+
+ def get_css_data(self, args, kwargs, slots, context):
+ return {"style": "body { color: blue; }"}
+
+ # Render the component with some args and kwargs
+ test_context = Context({"foo": "bar"})
+ test_slots = {"content": "Some content"}
+ TestComponent.render(context=test_context, args=("arg1", "arg2"), kwargs={"name": "Test"}, slots=test_slots)
+
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # Verify on_component_input was called with correct args
+ assert len(extension.calls["on_component_input"]) == 1
+ input_call: OnComponentInputContext = extension.calls["on_component_input"][0]
+ assert input_call.component_cls == TestComponent
+ assert isinstance(input_call.component_id, str)
+ assert input_call.args == ["arg1", "arg2"]
+ assert input_call.kwargs == {"name": "Test"}
+ assert len(input_call.slots) == 1
+ assert isinstance(input_call.slots["content"], Slot)
+ assert input_call.context == test_context
+
+ # Verify on_component_data was called with correct args
+ assert len(extension.calls["on_component_data"]) == 1
+ data_call: OnComponentDataContext = extension.calls["on_component_data"][0]
+ assert data_call.component_cls == TestComponent
+ assert isinstance(data_call.component_id, str)
+ assert data_call.template_data == {"name": "Test"}
+ assert data_call.js_data == {"script": "console.log('Hello!')"}
+ assert data_call.css_data == {"style": "body { color: blue; }"}
+
+ # Verify on_component_rendered was called with correct args
+ assert len(extension.calls["on_component_rendered"]) == 1
+ rendered_call: OnComponentRenderedContext = extension.calls["on_component_rendered"][0]
+ assert rendered_call.component_cls == TestComponent
+ assert isinstance(rendered_call.component, TestComponent)
+ assert isinstance(rendered_call.component_id, str)
+ assert rendered_call.result == "Hello Test!"
+ assert rendered_call.error is None
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_component_render_hooks__error(self):
+ @register("test_comp")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def on_render_after(self, context, template, result, error):
+ raise Exception("Oopsie woopsie")
+
+ with pytest.raises(Exception, match="Oopsie woopsie"):
+ # Render the component with some args and kwargs
+ TestComponent.render(
+ context=Context({"foo": "bar"}),
+ args=("arg1", "arg2"),
+ kwargs={"name": "Test"},
+ slots={"content": "Some content"},
+ )
+
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # Verify on_component_rendered was called with correct args
+ assert len(extension.calls["on_component_rendered"]) == 1
+ rendered_call: OnComponentRenderedContext = extension.calls["on_component_rendered"][0]
+ assert rendered_call.component_cls == TestComponent
+ assert isinstance(rendered_call.component, TestComponent)
+ assert isinstance(rendered_call.component_id, str)
+ assert rendered_call.result is None
+ assert isinstance(rendered_call.error, Exception)
+ assert str(rendered_call.error) == "An error occured while rendering components TestComponent:\nOopsie woopsie"
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_on_slot_rendered(self):
+ @register("test_comp")
+ class TestComponent(Component):
+ template = "Hello {% slot 'content' required default / %}!"
+
+ # Render the component with some args and kwargs
+ test_context = Context({"foo": "bar"})
+ rendered = TestComponent.render(
+ context=test_context,
+ args=("arg1", "arg2"),
+ kwargs={"name": "Test"},
+ slots={"content": "Some content"},
+ )
+
+ assert rendered == "Hello Some content!"
+
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # Verify on_slot_rendered was called with correct args
+ assert len(extension.calls["on_slot_rendered"]) == 1
+ slot_call: OnSlotRenderedContext = extension.calls["on_slot_rendered"][0]
+ assert isinstance(slot_call.component, TestComponent)
+ assert slot_call.component_cls == TestComponent
+
+ assert slot_call.component_id == "ca1bc3e"
+ assert isinstance(slot_call.slot, Slot)
+ assert slot_call.slot_name == "content"
+ assert isinstance(slot_call.slot_node, SlotNode)
+ assert slot_call.slot_node.template_name.endswith("test_extension.py::TestComponent") # type: ignore
+ assert slot_call.slot_node.template_component == TestComponent
+ assert slot_call.slot_is_required is True
+ assert slot_call.slot_is_default is True
+ assert slot_call.result == "Some content"
+
+ @djc_test(components_settings={"extensions": [SlotOverrideExtension]})
+ def test_on_slot_rendered__override(self):
+ @register("test_comp")
+ class TestComponent(Component):
+ template = "Hello {% slot 'content' required default / %}!"
+
+ rendered = TestComponent.render(
+ slots={"content": "Some content"},
+ )
+
+ assert rendered == "Hello OVERRIDEN BY EXTENSION!"
+
+ @djc_test(components_settings={"extensions": [ErrorOnComponentRenderedExtension]})
+ def test_on_component_rendered__error_from_extension(self):
+ @register("test_comp_error_ext")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ with pytest.raises(RuntimeError, match="Custom error from extension"):
+ TestComponent.render(args=(), kwargs={"name": "Test"})
+
+ @djc_test(components_settings={"extensions": [ReturnHtmlOnComponentRenderedExtension]})
+ def test_on_component_rendered__return_html_from_extension(self):
+ @register("test_comp_html_ext")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ rendered = TestComponent.render(args=(), kwargs={"name": "Test"})
+ assert rendered == "OVERRIDDEN: Hello Test!
"
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_asset_hooks__inlined(self):
+ @register("test_comp_hooks")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+ js = "console.log('hi');"
+ css = "body { color: red; }"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ # Render the component to trigger all hooks
+ TestComponent.render(args=(), kwargs={"name": "Test"})
+
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # on_template_loaded
+ assert len(extension.calls["on_template_loaded"]) == 1
+ ctx1: OnTemplateLoadedContext = extension.calls["on_template_loaded"][0]
+ assert ctx1.component_cls == TestComponent
+ assert ctx1.content == "Hello {{ name }}!"
+ assert isinstance(ctx1.origin, Origin)
+ assert ctx1.origin.name.endswith("test_extension.py::TestComponent")
+ assert ctx1.name is None
+
+ # on_template_compiled
+ assert len(extension.calls["on_template_compiled"]) == 1
+ ctx2: OnTemplateCompiledContext = extension.calls["on_template_compiled"][0]
+ assert ctx2.component_cls == TestComponent
+ assert isinstance(ctx2.template, Template)
+
+ # on_js_loaded
+ assert len(extension.calls["on_js_loaded"]) == 1
+ ctx3: OnJsLoadedContext = extension.calls["on_js_loaded"][0]
+ assert ctx3.component_cls == TestComponent
+ assert ctx3.content == "console.log('hi');"
+
+ # on_css_loaded
+ assert len(extension.calls["on_css_loaded"]) == 1
+ ctx4: OnCssLoadedContext = extension.calls["on_css_loaded"][0]
+ assert ctx4.component_cls == TestComponent
+ assert ctx4.content == "body { color: red; }"
+
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_asset_hooks__file(self):
+ @register("test_comp_hooks")
+ class TestComponent(Component):
+ template_file = "relative_file/relative_file.html"
+ js_file = "relative_file/relative_file.js"
+ css_file = "relative_file/relative_file.css"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ # Render the component to trigger all hooks
+ TestComponent.render(args=(), kwargs={"name": "Test"})
+
+ extension = cast(DummyExtension, app_settings.EXTENSIONS[5])
+
+ # on_template_loaded
+ # NOTE: The template file gets picked up by 'django.template.loaders.filesystem.Loader',
+ # as well as our own loader, so we get two calls here.
+ assert len(extension.calls["on_template_loaded"]) == 2
+ ctx1: OnTemplateLoadedContext = extension.calls["on_template_loaded"][0]
+ assert ctx1.component_cls == TestComponent
+ assert ctx1.content == (
+ '\n'
+ )
+ assert isinstance(ctx1.origin, Origin)
+ assert ctx1.origin.name.endswith("relative_file.html")
+ assert ctx1.name == "relative_file/relative_file.html"
+
+ # on_template_compiled
+ assert len(extension.calls["on_template_compiled"]) == 2
+ ctx2: OnTemplateCompiledContext = extension.calls["on_template_compiled"][0]
+ assert ctx2.component_cls == TestComponent
+ assert isinstance(ctx2.template, Template)
+
+ # on_js_loaded
+ assert len(extension.calls["on_js_loaded"]) == 1
+ ctx3: OnJsLoadedContext = extension.calls["on_js_loaded"][0]
+ assert ctx3.component_cls == TestComponent
+ assert ctx3.content == 'console.log("JS file");\n'
+
+ # on_css_loaded
+ assert len(extension.calls["on_css_loaded"]) == 1
+ ctx4: OnCssLoadedContext = extension.calls["on_css_loaded"][0]
+ assert ctx4.component_cls == TestComponent
+ assert ctx4.content == (
+ '.html-css-only {\n'
+ ' color: blue;\n'
+ '}\n'
+ )
+
+ @djc_test(components_settings={"extensions": [OverrideAssetExtension]})
+ def test_asset_hooks_override(self):
+ @register("test_comp_override")
+ class TestComponent(Component):
+ template = "Hello {{ name }}!"
+ js = "console.log('hi');"
+ css = "body { color: red; }"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"name": kwargs.get("name", "World")}
+
+ # No need to render, accessing the attributes should trigger the hooks
+ assert TestComponent.template == "OVERRIDDEN TEMPLATE"
+ assert TestComponent.js == "OVERRIDDEN JS"
+ assert TestComponent.css == "OVERRIDDEN CSS"
+
+
+@djc_test
+class TestExtensionViews:
+ @djc_test(components_settings={"extensions": [DummyExtension]})
+ def test_views(self):
+ client = Client()
+
+ # Check basic view
+ response = client.get("/components/ext/test_extension/dummy-view/")
+ assert response.status_code == 200
+ assert response.content == b"Hello, world!"
+
+ # Check that URL parameters are passed to the view
+ response2 = client.get("/components/ext/test_extension/dummy-view-2/123/John/")
+ assert response2.status_code == 200
+ assert response2.content == b"Hello, world! 123 John"
+
+ @djc_test(components_settings={"extensions": [DummyNestedExtension]})
+ def test_nested_views(self):
+ client = Client()
+
+ # Check basic view
+ # NOTE: Since the parent route contains child routes, the parent route should not be matched
+ response = client.get("/components/ext/test_nested_extension/nested-view/")
+ assert response.status_code == 404
+
+ # Check that URL parameters are passed to the view
+ response2 = client.get("/components/ext/test_nested_extension/nested-view/123/John/")
+ assert response2.status_code == 200
+ assert response2.content == b"Hello, world! 123 John"
+
+
+@djc_test
+class TestExtensionDefaults:
+ @djc_test(
+ components_settings={
+ "extensions": [DummyExtension],
+ "extensions_defaults": {
+ "test_extension": {},
+ },
+ }
+ )
+ def test_no_defaults(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ dummy_ext_cls: DummyExtension.ComponentConfig = TestComponent.TestExtension # type: ignore[attr-defined]
+ assert dummy_ext_cls.foo == "1"
+ assert dummy_ext_cls.bar == "2"
+ assert dummy_ext_cls.baz() == "3"
+
+ @djc_test(
+ components_settings={
+ "extensions": [DummyExtension],
+ "extensions_defaults": {
+ "test_extension": {
+ "foo": "NEW_FOO",
+ "baz": classmethod(lambda self: "OVERRIDEN"),
+ },
+ "nonexistent": {
+ "1": "2",
+ },
+ },
+ }
+ )
+ def test_defaults(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ dummy_ext_cls: DummyExtension.ComponentConfig = TestComponent.TestExtension # type: ignore[attr-defined]
+ assert dummy_ext_cls.foo == "NEW_FOO"
+ assert dummy_ext_cls.bar == "2"
+ assert dummy_ext_cls.baz() == "OVERRIDEN"
+
+
+@djc_test
+class TestLegacyApi:
+ # TODO_V1 - Remove
+ @djc_test(
+ components_settings={
+ "extensions": [LegacyExtension],
+ }
+ )
+ def test_extension_class(self):
+ class TestComponent(Component):
+ template = "Hello"
+
+ dummy_ext_cls: LegacyExtension.ExtensionClass = TestComponent.Legacy # type: ignore[attr-defined]
+ assert dummy_ext_cls.foo == "1"
+ assert dummy_ext_cls.bar == "2"
+ assert dummy_ext_cls.baz() == "3"
diff --git a/tests/test_finders.py b/tests/test_finders.py
new file mode 100644
index 00000000..32d3a3ee
--- /dev/null
+++ b/tests/test_finders.py
@@ -0,0 +1,254 @@
+import re
+from pathlib import Path
+
+from django.contrib.staticfiles import finders
+from django.contrib.staticfiles.management.commands.collectstatic import Command
+from django.test import SimpleTestCase
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# This subclass allows us to call the `collectstatic` command from within Python.
+# We call the `collect` method, which returns info about what files were collected.
+#
+# The methods below are overriden to ensure we don't make any filesystem changes
+# (copy/delete), as the original command copies files. Thus we can safely test that
+# our app works as intended.
+class MockCollectstaticCommand(Command):
+ # NOTE: We do not expect this to be called
+ def clear_dir(self, path):
+ raise NotImplementedError()
+
+ # NOTE: We do not expect this to be called
+ def link_file(self, path, prefixed_path, source_storage):
+ raise NotImplementedError()
+
+ def copy_file(self, path, prefixed_path, source_storage):
+ # Skip this file if it was already copied earlier
+ if prefixed_path in self.copied_files:
+ return self.log("Skipping '%s' (already copied earlier)" % path)
+ # Delete the target file if needed or break
+ if not self.delete_file(path, prefixed_path, source_storage):
+ return
+ # The full path of the source file
+ source_path = source_storage.path(path)
+ # Finally start copying
+ if self.dry_run:
+ self.log("Pretending to copy '%s'" % source_path, level=1)
+ else:
+ self.log("Copying '%s'" % source_path, level=2)
+ # ############# OUR CHANGE ##############
+ # with source_storage.open(path) as source_file:
+ # self.storage.save(prefixed_path, source_file)
+ # ############# OUR CHANGE ##############
+ self.copied_files.append(prefixed_path)
+
+
+def do_collect():
+ cmd = MockCollectstaticCommand()
+ cmd.set_options(
+ interactive=False,
+ verbosity=1,
+ link=False,
+ clear=False,
+ dry_run=False,
+ ignore_patterns=[],
+ use_default_ignore_patterns=True,
+ post_process=True,
+ )
+ collected = cmd.collect()
+
+ # Convert collected paths from string to Path, so we can run tests on both Unix and Windows
+ collected = {key: [Path(item) for item in items] for key, items in collected.items()}
+ return collected
+
+
+common_settings = {
+ "STATIC_URL": "static/",
+ "STATIC_ROOT": "staticfiles",
+ "ROOT_URLCONF": __name__,
+ "INSTALLED_APPS": ("django_components", "django.contrib.staticfiles"),
+}
+COMPONENTS = {
+ "dirs": [Path(__file__).resolve().parent / "components"],
+}
+
+urlpatterns: list = []
+
+
+class StaticFilesFinderTests(SimpleTestCase):
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ ],
+ },
+ components_settings=COMPONENTS,
+ )
+ def test_python_and_html_included(self):
+ collected = do_collect()
+
+ # Check that the component files are NOT loaded when our finder is NOT added
+ self.assertNotIn(Path("staticfiles/staticfiles.css"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.js"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.html"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.py"), collected["modified"])
+
+ self.assertListEqual(collected["unmodified"], [])
+ self.assertListEqual(collected["post_processed"], [])
+
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+ ],
+ },
+ components_settings=COMPONENTS,
+ )
+ def test_python_and_html_omitted(self):
+ collected = do_collect()
+
+ # Check that our staticfiles_finder finds the files and OMITS .py and .html files
+ self.assertIn(Path("staticfiles/staticfiles.css"), collected["modified"])
+ self.assertIn(Path("staticfiles/staticfiles.js"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.html"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.py"), collected["modified"])
+
+ self.assertListEqual(collected["unmodified"], [])
+ self.assertListEqual(collected["post_processed"], [])
+
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+ ],
+ },
+ components_settings={
+ **COMPONENTS,
+ "static_files_allowed": [
+ ".js",
+ ],
+ "static_files_forbidden": [],
+ },
+ )
+ def test_set_static_files_allowed(self):
+ collected = do_collect()
+
+ # Check that our staticfiles_finder finds the files and OMITS .py and .html files
+ self.assertNotIn(Path("staticfiles/staticfiles.css"), collected["modified"])
+ self.assertIn(Path("staticfiles/staticfiles.js"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.html"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.py"), collected["modified"])
+
+ self.assertListEqual(collected["unmodified"], [])
+ self.assertListEqual(collected["post_processed"], [])
+
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+ ],
+ },
+ components_settings={
+ **COMPONENTS,
+ "static_files_allowed": [
+ re.compile(r".*"),
+ ],
+ "static_files_forbidden": [
+ re.compile(r"\.(?:js)$"),
+ ],
+ },
+ )
+ def test_set_forbidden_files(self):
+ collected = do_collect()
+
+ # Check that our staticfiles_finder finds the files and OMITS .py and .html files
+ self.assertIn(Path("staticfiles/staticfiles.css"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.js"), collected["modified"])
+ self.assertIn(Path("staticfiles/staticfiles.html"), collected["modified"])
+ self.assertIn(Path("staticfiles/staticfiles.py"), collected["modified"])
+
+ self.assertListEqual(collected["unmodified"], [])
+ self.assertListEqual(collected["post_processed"], [])
+
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+ ],
+ },
+ components_settings={
+ **COMPONENTS,
+ "static_files_allowed": [
+ ".js",
+ ".css",
+ ],
+ "static_files_forbidden": [
+ ".js",
+ ],
+ },
+ )
+ def test_set_both_allowed_and_forbidden_files(self):
+ collected = do_collect()
+
+ # Check that our staticfiles_finder finds the files and OMITS .py and .html files
+ self.assertIn(Path("staticfiles/staticfiles.css"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.js"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.html"), collected["modified"])
+ self.assertNotIn(Path("staticfiles/staticfiles.py"), collected["modified"])
+
+ self.assertListEqual(collected["unmodified"], [])
+ self.assertListEqual(collected["post_processed"], [])
+
+ # Handle deprecated `all` parameter:
+ # - In Django 5.2, the `all` parameter was deprecated in favour of `find_all`.
+ # - Between Django 5.2 (inclusive) and 6.1 (exclusive), the `all` parameter was still
+ # supported, but an error was raised if both were provided.
+ # - In Django 6.1, the `all` parameter was removed.
+ #
+ # See https://github.com/django/django/blob/5.2/django/contrib/staticfiles/finders.py#L58C9-L58C37
+ # And https://github.com/django-components/django-components/issues/1119
+ @djc_test(
+ django_settings={
+ **common_settings,
+ "STATICFILES_FINDERS": [
+ # Default finders
+ "django.contrib.staticfiles.finders.FileSystemFinder",
+ "django.contrib.staticfiles.finders.AppDirectoriesFinder",
+ # Django components
+ "django_components.finders.ComponentsFileSystemFinder",
+ ],
+ },
+ components_settings=COMPONENTS,
+ )
+ def test_find_compat(self):
+ # NOTE: This would raise an error in Django 5.2 without a fix
+ result = finders.find("staticfiles/staticfiles.css")
+
+ assert Path(result) == Path("./tests/components/staticfiles/staticfiles.css").resolve()
diff --git a/tests/test_html_parser.py b/tests/test_html_parser.py
new file mode 100644
index 00000000..ca989365
--- /dev/null
+++ b/tests/test_html_parser.py
@@ -0,0 +1,166 @@
+from pytest_django.asserts import assertHTMLEqual
+
+from djc_core_html_parser import set_html_attributes
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# This same set of tests is also found in djc_html_parser, to ensure that
+# this implementation can be replaced with the djc_html_parser's Rust-based implementation
+@djc_test
+class TestHTMLParser:
+ def test_basic_transformation(self):
+ html = "Hello
+
+ """,
+ )
+
+ def test_multiple_roots(self):
+ html = "Hello
+First
Second"
+ result, _ = set_html_attributes(html, root_attributes=["data-root"], all_attributes=["data-all"])
+
+ assertHTMLEqual(
+ result,
+ """
+ First
+ Second
+ """,
+ )
+
+ def test_complex_html(self):
+ html = """
+
+
+
+
+
+
+
+
+
+
+ """
+
+ result, _ = set_html_attributes(html, ["data-root"], ["data-all", "data-v-123"])
+
+ expected = """
+ Hello & Welcome
+ +Article 1
+Some text with bold and emphasis
+
+
+
+
+
+
+
+
+
+
+
+ """ # noqa: E501
+ assertHTMLEqual(result, expected)
+
+ def test_void_elements(self):
+ test_cases = [
+ ('', ''),
+ ('', ''),
+ ("Hello & Welcome
+ +Article 1
+Some text with bold and emphasis
+
+ ', ''),
+ ]
+
+ for input_html, expected in test_cases:
+ result, _ = set_html_attributes(input_html, ["data-root"], ["data-v-123"])
+ assertHTMLEqual(result, expected)
+
+ def test_html_head_with_meta(self):
+ html = """
+
+
+
+
+
"""
+
+ result, captured = set_html_attributes(html, ["data-root"], ["data-v-123"], watch_on_attribute="data-id")
+
+ assertHTMLEqual(
+ result,
+ """
+ Regular element
+ Nested element +
+
+
+
+ """,
+ )
+
+ # Verify attribute capturing
+ assert len(captured) == 3
+
+ # Root element should have both root and all attributes
+ assert captured["123"] == ["data-root", "data-v-123"]
+
+ # Non-root elements should only have all attributes
+ assert captured["456"] == ["data-v-123"]
+ assert captured["789"] == ["data-v-123"]
+
+ def test_whitespace_preservation(self):
+ html = """Regular element
+ Nested element +
+
+
"""
+
+ result, _ = set_html_attributes(html, ["data-root"], ["data-all"])
+ expected = """Hello World
+ Text with spaces +
+
"""
+
+ assert result == expected
diff --git a/tests/test_loader.py b/tests/test_loader.py
new file mode 100644
index 00000000..227ec04d
--- /dev/null
+++ b/tests/test_loader.py
@@ -0,0 +1,338 @@
+import re
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from django.conf import settings
+
+from django_components.util.loader import _filepath_to_python_module, get_component_dirs, get_component_files
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestComponentDirs:
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ },
+ )
+ def test_get_dirs__base_dir(self):
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = [dirs[0], dirs[2]]
+ own_dirs = [dirs[1], *dirs[3:]]
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 2
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-2:] == ("django_components", "components")
+ assert apps_dirs[1].parts[-3:] == ("tests", "test_app", "components")
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve() / "test_structures" / "test_structure_1", # noqa
+ },
+ )
+ def test_get_dirs__base_dir__complex(self):
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = dirs[:2]
+ own_dirs = dirs[2:]
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 2
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-2:] == ("django_components", "components")
+ assert apps_dirs[1].parts[-3:] == ("tests", "test_app", "components")
+
+ expected = [
+ Path(__file__).parent.resolve() / "test_structures" / "test_structure_1" / "components",
+ ]
+ assert own_dirs == expected
+
+ @djc_test(
+ django_settings={
+ "BASE_DIR": Path(__file__).parent.resolve(),
+ "STATICFILES_DIRS": [
+ Path(__file__).parent.resolve() / "components",
+ ("with_alias", Path(__file__).parent.resolve() / "components"),
+ ("too_many", Path(__file__).parent.resolve() / "components", Path(__file__).parent.resolve()),
+ ("with_not_str_alias", 3),
+ ], # noqa
+ },
+ )
+ @patch("django_components.util.loader.logger.warning")
+ def test_get_dirs__components_dirs(self, mock_warning: MagicMock):
+ mock_warning.reset_mock()
+ dirs = sorted(get_component_dirs())
+
+ apps_dirs = [dirs[0], dirs[2]]
+ own_dirs = [dirs[1], *dirs[3:]]
+
+ # Apps with a `components` dir
+ assert len(apps_dirs) == 2
+
+ # NOTE: Compare parts so that the test works on Windows too
+ assert apps_dirs[0].parts[-2:] == ("django_components", "components")
+ assert apps_dirs[1].parts[-3:] == ("tests", "test_app", "components")
+
+ assert own_dirs == [
+ # Top-level /components dir
+ Path(__file__).parent.resolve()
+ / "components",
+ ]
+
+ warn_inputs = [warn.args[0] for warn in mock_warning.call_args_list]
+ assert "Got Hello World
+ Text with spaces +
+
SLOT_DEFAULT
hello2
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_formatter_default_block(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_formatter_default_block(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -92,26 +102,24 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
OVERRIDEN!
hello2
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": "django_components.component_formatter",
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": "django_components.component_formatter",
},
)
- def test_formatter_component_inline(self):
+ def test_formatter_component_inline(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -130,26 +138,24 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
SLOT_DEFAULT
hello2
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": "django_components.component_formatter",
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": "django_components.component_formatter",
},
)
- def test_formatter_component_block(self):
+ def test_formatter_component_block(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -170,26 +176,24 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
OVERRIDEN!
hello2
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": "django_components.component_shorthand_formatter",
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": "django_components.component_shorthand_formatter",
},
)
- def test_formatter_shorthand_inline(self):
+ def test_formatter_shorthand_inline(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -208,26 +212,24 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
SLOT_DEFAULT
hello2
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": "django_components.component_shorthand_formatter",
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": "django_components.component_shorthand_formatter",
},
)
- def test_formatter_shorthand_block(self):
+ def test_formatter_shorthand_block(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -248,26 +250,62 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
OVERRIDEN!
hello2
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": ShorthandComponentFormatter(),
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": SlashEndTagFormatter(),
},
)
- def test_import_formatter_by_value(self):
+ def test_forward_slash_in_end_tag(self, components_settings):
+ @register("simple")
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ hello1
+
+ {% slot "content" default %} SLOT_DEFAULT {% endslot %}
+
+ hello2
+ """
+
+ template = Template(
+ """
+ {% load component_tags %}
+ {% simple %}
+ OVERRIDEN!
+ {% /simple %}
+ """
+ )
+ rendered = template.render(Context())
+ assertHTMLEqual(
+ rendered,
+ """
+ hello1
+
+ OVERRIDEN!
+
+ hello2
+ """,
+ )
+
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": ShorthandComponentFormatter(),
+ },
+ )
+ def test_import_formatter_by_value(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -286,43 +324,41 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
OVERRIDEN!
""",
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": MultiwordStartTagFormatter(),
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": MultiwordStartTagFormatter(),
},
)
- def test_raises_on_invalid_start_tag(self):
- with self.assertRaisesMessage(
- ValueError, "MultiwordStartTagFormatter returned an invalid tag for start_tag: 'simple comp'"
+ def test_raises_on_invalid_start_tag(self, components_settings):
+ with pytest.raises(
+ ValueError,
+ match=re.escape("MultiwordStartTagFormatter returned an invalid tag for start_tag: 'simple comp'"),
):
@register("simple")
class SimpleComponent(Component):
template = """{% load component_tags %}"""
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": MultiwordBlockEndTagFormatter(),
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": MultiwordBlockEndTagFormatter(),
},
)
- def test_raises_on_invalid_block_end_tag(self):
- with self.assertRaisesMessage(
- ValueError, "MultiwordBlockEndTagFormatter returned an invalid tag for end_tag: 'end simple'"
+ def test_raises_on_invalid_block_end_tag(self, components_settings):
+ with pytest.raises(
+ ValueError,
+ match=re.escape("MultiwordBlockEndTagFormatter returned an invalid tag for end_tag: 'end simple'"),
):
@register("simple")
@@ -343,15 +379,13 @@ class ComponentTagTests(BaseTestCase):
"""
)
- @parametrize_context_behavior(
- cases=["django", "isolated"],
- settings={
- "COMPONENTS": {
- "tag_formatter": create_validator_tag_formatter("simple"),
- },
+ @djc_test(
+ parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR,
+ components_settings={
+ "tag_formatter": create_validator_tag_formatter("simple"),
},
)
- def test_method_args(self):
+ def test_method_args(self, components_settings):
@register("simple")
class SimpleComponent(Component):
template: types.django_html = """
@@ -370,11 +404,11 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+
SLOT_DEFAULT
hello2
@@ -390,11 +424,11 @@ class ComponentTagTests(BaseTestCase):
"""
)
rendered = template.render(Context())
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
hello1
-
+ : ('too_many', 'items', {repr(comps_path)})" in warn_inputs[0]
- assert "Got : 3" in warn_inputs[1]
-
- @override_settings(STATICFILES_DIRS=["components"])
- def test_get_dirs__staticfiles_dirs__raises_on_relative_path_1(self):
- current_engine = Engine.get_default()
- loader = Loader(current_engine)
- with self.assertRaisesMessage(ValueError, "STATICFILES_DIRS must contain absolute paths"):
- loader.get_dirs()
-
- @override_settings(STATICFILES_DIRS=[("with_alias", "components")])
- def test_get_dirs__staticfiles_dirs__raises_on_relative_path_2(self):
- current_engine = Engine.get_default()
- loader = Loader(current_engine)
- with self.assertRaisesMessage(ValueError, "STATICFILES_DIRS must contain absolute paths"):
- loader.get_dirs()
diff --git a/tests/test_template_parser.py b/tests/test_template_parser.py
index 79d65fe8..1c630643 100644
--- a/tests/test_template_parser.py
+++ b/tests/test_template_parser.py
@@ -1,131 +1,249 @@
-from django.template import Context, Template
-from django.template.base import Lexer, Parser
+from django.template import Context
+from django.template.base import Template, Token, TokenType
+from pytest_django.asserts import assertHTMLEqual
-from django_components import Component, registry, types
-from django_components.expression import (
- is_aggregate_key,
- process_aggregate_kwargs,
- safe_resolve_dict,
- safe_resolve_list,
-)
-from django_components.templatetags.component_tags import _parse_tag
+from django_components import Component, register, types
+from django_components.util.template_parser import parse_template
-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 setup_test_config
setup_test_config({"autodiscover": False})
-class ParserTest(BaseTestCase):
- def test_parses_args_kwargs(self):
- template_str = "{% component 42 myvar key='val' key2=val2 %}"
- tokens = Lexer(template_str).tokenize()
- parser = Parser(tokens=tokens)
- tag = _parse_tag("component", parser, parser.tokens[0], params=["num", "var"], keywordonly_kwargs=True)
+def token2tuple(token: Token):
+ return (
+ token.token_type,
+ token.contents,
+ (token.position[0], token.position[1]),
+ token.lineno,
+ )
- ctx = {"myvar": {"a": "b"}, "val2": 1}
- args = safe_resolve_list(ctx, tag.args)
- named_args = safe_resolve_dict(ctx, tag.named_args)
- kwargs = tag.kwargs.resolve(ctx)
- self.assertListEqual(args, [42, {"a": "b"}])
- self.assertDictEqual(named_args, {"num": 42, "var": {"a": "b"}})
- self.assertDictEqual(kwargs, {"key": "val", "key2": 1})
+@djc_test
+class TestTemplateParser:
+ def test_template_text(self):
+ tokens = parse_template("Hello world")
- def test_parses_special_kwargs(self):
- template_str = "{% component date=date @lol=2 na-me=bzz @event:na-me.mod=bzz #my-id=True %}"
- tokens = Lexer(template_str).tokenize()
- parser = Parser(tokens=tokens)
- tag = _parse_tag("component", parser, parser.tokens[0], keywordonly_kwargs=True)
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "Hello world", (0, 11), 1),
+ ]
- ctx = Context({"date": 2024, "bzz": "fzz"})
- args = safe_resolve_list(ctx, tag.args)
- kwargs = tag.kwargs.resolve(ctx)
+ assert token_tuples == expected_tokens
- self.assertListEqual(args, [])
- self.assertDictEqual(
- kwargs,
- {
- "@event": {"na-me.mod": "fzz"},
- "@lol": 2,
- "date": 2024,
- "na-me": "fzz",
- "#my-id": True,
- },
+ def test_template_variable(self):
+ tokens = parse_template("Hello {{ name }}")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "Hello ", (0, 6), 1),
+ (TokenType.VAR, "name", (6, 16), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ # NOTE(Juro): IMO this should be a TemplateSyntaxError, but Django doesn't raise it
+ def test_template_variable_unterminated(self):
+ tokens = parse_template("Hello {{ name")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "Hello {{ name", (0, 13), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_template_tag(self):
+ tokens = parse_template("{% component 'my_comp' key=val %}")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.BLOCK, "component 'my_comp' key=val", (0, 33), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ # NOTE(Juro): IMO this should be a TemplateSyntaxError, but Django doesn't raise it
+ def test_template_tag_unterminated(self):
+ tokens = parse_template("{% if true")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "{% if true", (0, 10), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_template_comment(self):
+ tokens = parse_template("Hello{# this is a comment #}World")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "Hello", (0, 5), 1),
+ (TokenType.COMMENT, "this is a comment", (5, 28), 1),
+ (TokenType.TEXT, "World", (28, 33), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ # NOTE(Juro): IMO this should be a TemplateSyntaxError, but Django doesn't raise it
+ def test_template_comment_unterminated(self):
+ tokens = parse_template("{# comment")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.TEXT, "{# comment", (0, 10), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_template_verbatim(self):
+ tokens = parse_template(
+ """{% verbatim %}
+ {{ this_is_not_a_var }}
+ {% this_is_not_a_tag %}
+ {% endverbatim %}"""
)
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.BLOCK, "verbatim", (0, 14), 1),
+ (TokenType.TEXT, "\n ", (14, 31), 1),
+ (TokenType.TEXT, "{{ this_is_not_a_var }}", (31, 54), 2),
+ (TokenType.TEXT, "\n ", (54, 71), 2),
+ (TokenType.TEXT, "{% this_is_not_a_tag %}", (71, 94), 3),
+ (TokenType.TEXT, "\n ", (94, 107), 3),
+ (TokenType.BLOCK, "endverbatim", (107, 124), 4),
+ ]
-class ParserComponentTest(BaseTestCase):
- class SimpleComponent(Component):
- template: types.django_html = """
- {{ date }}
- {{ id }}
- {{ on_click }}
- """
+ assert token_tuples == expected_tokens
- def get_context_data(self, **kwargs):
- return {
- "date": kwargs["my-date"],
- "id": kwargs["#some_id"],
- "on_click": kwargs["@click.native"],
- }
+ def test_template_verbatim_with_name(self):
+ tokens = parse_template(
+ """{% verbatim myblock %}
+ {{ this_is_not_a_var }}
+ {% verbatim %}
+ {% endverbatim %}
+ {% endverbatim blockname %}
+ {% endverbatim myblock %}"""
+ )
- @parametrize_context_behavior(["django", "isolated"])
- def test_special_chars_accessible_via_kwargs(self):
- registry.register("test", self.SimpleComponent)
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.BLOCK, "verbatim myblock", (0, 22), 1),
+ (TokenType.TEXT, "\n ", (22, 39), 1),
+ (TokenType.TEXT, "{{ this_is_not_a_var }}", (39, 62), 2),
+ (TokenType.TEXT, "\n ", (62, 79), 2),
+ (TokenType.TEXT, "{% verbatim %}", (79, 93), 3),
+ (TokenType.TEXT, "\n ", (93, 110), 3),
+ (TokenType.TEXT, "{% endverbatim %}", (110, 127), 4),
+ (TokenType.TEXT, "\n ", (127, 144), 4),
+ (TokenType.TEXT, "{% endverbatim blockname %}", (144, 171), 5),
+ (TokenType.TEXT, "\n ", (171, 184), 5),
+ (TokenType.BLOCK, "endverbatim myblock", (184, 209), 6),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_template_nested_tags(self):
+ tokens = parse_template("""{% component 'test' "{% lorem var_a w %}" %}""")
+
+ token_tuples = [token2tuple(token) for token in tokens]
+ expected_tokens = [
+ (TokenType.BLOCK, "component 'test' \"{% lorem var_a w %}\"", (0, 44), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_brackets_and_percent_in_text(self):
+ tokens = parse_template('{% component \'test\' \'"\' "{%}" bool_var="{% noop is_active %}" / %}')
+
+ token_tuples = [token2tuple(token) for token in tokens]
+
+ expected_tokens = [
+ (TokenType.BLOCK, 'component \'test\' \'"\' "{%}" bool_var="{% noop is_active %}" /', (0, 66), 1),
+ ]
+
+ assert token_tuples == expected_tokens
+
+ def test_template_mixed(self):
+ tokens = parse_template(
+ """Hello {{ name }}
+ {# greeting #}
+ {% if show_greeting %}
+
- BODY_FROM_FILL
-
-
-
-
+ Variable: 123
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slots_inside_include(self):
- registry.register("slotted_component", SlottedComponent)
- @register("slot_inside_include")
- class SlotInsideIncludeComponent(Component):
- template: types.django_html = """
- {% include "block_in_slot_in_component.html" %}
- """
+@djc_test
+class TestNestedTags:
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ Variable: {{ var }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "var": kwargs["var"],
+ }
+
+ # See https://github.com/django-components/django-components/discussions/671
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_tags(self, components_settings):
+ registry.register("test", self.SimpleComponent)
template: types.django_html = """
{% load component_tags %}
- {% component "slot_inside_include" %}
- {% fill "body" %}
- BODY_FROM_FILL
- {% endfill %}
- {% endcomponent %}
+ {% component "test" var="{% lorem 1 w %}" %}{% endcomponent %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
-
- BODY_FROM_FILL
-
-
-
-
+ Variable: lorem
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_component_inside_block(self):
- registry.register("slotted_component", SlottedComponent)
- template: types.django_html = """
- {% extends "block.html" %}
- {% load component_tags %}
- {% block body %}
- {% component "slotted_component" %}
- {% fill "header" %}{% endfill %}
- {% fill "main" %}
- TEST
- {% endfill %}
- {% fill "footer" %}{% endfill %}
- {% endcomponent %}
- {% endblock %}
- """
- rendered = Template(template).render(Context())
- expected = """
-
-
-
-
-
-
-
- """
- self.assertHTMLEqual(rendered, expected)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_block_inside_component(self):
- registry.register("slotted_component", SlottedComponent)
-
- template: types.django_html = """
- {% extends "block_in_component.html" %}
- {% load component_tags %}
- {% block body %}
-
-
-
-
-
-
-
- """
- self.assertHTMLEqual(rendered, expected)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_block_inside_component_parent(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("block_in_component_parent")
- class BlockInCompParent(Component):
- template_name = "block_in_component_parent.html"
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_quote_single(self, components_settings):
+ registry.register("test", self.SimpleComponent)
template: types.django_html = """
{% load component_tags %}
- {% component "block_in_component_parent" %}{% endcomponent %}
+ {% component "test" var=_("organisation's") %} {% endcomponent %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
-
-
-
-
-
-
-
+ Variable: organisation's
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_block_does_not_affect_inside_component(self):
- """
- Assert that when we call a component with `{% component %}`, that
- the `{% block %}` will NOT affect the inner component.
- """
- registry.register("slotted_component", SlottedComponent)
-
- @register("block_inside_slot_v1")
- class BlockInSlotInComponent(Component):
- template_name = "block_in_slot_in_component.html"
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_quote_single_self_closing(self, components_settings):
+ registry.register("test", self.SimpleComponent)
template: types.django_html = """
{% load component_tags %}
- {% component "block_inside_slot_v1" %}
- {% fill "body" %}
- BODY_FROM_FILL
- {% endfill %}
- {% endcomponent %}
- {% block inner %}
- wow
- {% endblock %}
+ {% component "test" var=_("organisation's") / %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
-
- BODY_FROM_FILL
-
-
-
-
- wow
+ Variable: organisation's
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_inside_block__slot_default_block_default(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("slot_inside_block")
- class _SlotInsideBlockComponent(Component):
- template: types.django_html = """
- {% extends "slot_inside_block.html" %}
- """
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_quote_double(self, components_settings):
+ registry.register("test", self.SimpleComponent)
template: types.django_html = """
{% load component_tags %}
- {% component "slot_inside_block" %}{% endcomponent %}
+ {% component "test" var=_('organisation"s') %} {% endcomponent %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
-
-
- Helloodiddoo
- Default inner
-
-
-
-
-
+ Variable: organisation"s
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_inside_block__slot_default_block_override(self):
- registry.clear()
- registry.register("slotted_component", SlottedComponent)
-
- @register("slot_inside_block")
- class _SlotInsideBlockComponent(Component):
- template: types.django_html = """
- {% extends "slot_inside_block.html" %}
- {% block inner %}
- INNER BLOCK OVERRIDEN
- {% endblock %}
- """
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_quote_double_self_closing(self, components_settings):
+ registry.register("test", self.SimpleComponent)
template: types.django_html = """
{% load component_tags %}
- {% component "slot_inside_block" %}{% endcomponent %}
+ {% component "test" var=_('organisation"s') / %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
-
-
- Helloodiddoo
- INNER BLOCK OVERRIDEN
-
-
-
-
-
+ Variable: organisation"s
"""
- self.assertHTMLEqual(rendered, expected)
-
- @parametrize_context_behavior(["isolated", "django"])
- def test_slot_inside_block__slot_overriden_block_default(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("slot_inside_block")
- class _SlotInsideBlockComponent(Component):
- template: types.django_html = """
- {% extends "slot_inside_block.html" %}
- """
-
- template: types.django_html = """
- {% load component_tags %}
- {% component "slot_inside_block" %}
- {% fill "body" %}
- SLOT OVERRIDEN
- {% endfill %}
- {% endcomponent %}
- """
- rendered = Template(template).render(Context())
- expected = """
-
-
-
-
-
- Helloodiddoo
- SLOT OVERRIDEN
-
-
-
-
-
- """
- self.assertHTMLEqual(rendered, expected)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_inside_block__slot_overriden_block_overriden(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("slot_inside_block")
- class _SlotInsideBlockComponent(Component):
- template: types.django_html = """
- {% extends "slot_inside_block.html" %}
- {% block inner %}
- {% load component_tags %}
- {% slot "new_slot" %}{% endslot %}
- {% endblock %}
- whut
- """
-
- # NOTE: The "body" fill will NOT show up, because we override the `inner` block
- # with a different slot. But the "new_slot" WILL show up.
- template: types.django_html = """
- {% load component_tags %}
- {% component "slot_inside_block" %}
- {% fill "body" %}
- SLOT_BODY__OVERRIDEN
- {% endfill %}
- {% fill "new_slot" %}
- SLOT_NEW__OVERRIDEN
- {% endfill %}
- {% endcomponent %}
- """
- rendered = Template(template).render(Context())
- expected = """
-
-
-
-
-
- Helloodiddoo
- SLOT_NEW__OVERRIDEN
-
-
-
-
-
- """
- self.assertHTMLEqual(rendered, expected)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_inside_block(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("injectee")
- class InjectComponent(Component):
- template: types.django_html = """
-
-
-
-
-
-
-
- """
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
diff --git a/tests/test_templatetags_component.py b/tests/test_templatetags_component.py
index e1c3419d..bf5addcd 100644
--- a/tests/test_templatetags_component.py
+++ b/tests/test_templatetags_component.py
@@ -1,278 +1,26 @@
-import textwrap
+import re
+from typing import NamedTuple
+import pytest
from django.template import Context, Template, TemplateSyntaxError
+from pytest_django.asserts import assertHTMLEqual
+from django_components import AlreadyRegistered, Component, NotRegistered, register, registry, types
-from django_components import Component, NotRegistered, register, registry, types
+from django_components.testing import djc_test
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase, parametrize_context_behavior
-
-setup_test_config()
+setup_test_config({"autodiscover": False})
-class SlottedComponent(Component):
- template_name = "slotted_template.html"
-
-
-class SlottedComponentWithContext(Component):
- template: types.django_html = """
- {% load component_tags %}
-
- {% slot "header" %}Default header{% endslot %}
- {% slot "main" %}Default main{% endslot %}
-
-
- """
-
- def get_context_data(self, variable):
- return {"variable": variable}
-
-
-#######################
-# TESTS
-#######################
-
-
-class ComponentTemplateTagTest(BaseTestCase):
- 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 = "style.css"
- js = "script.js"
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_single_component(self):
- registry.register(name="test", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component name="test" variable="variable" %}{% endcomponent %}
- """
-
- template = Template(simple_tag_template)
- rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, "Variable: variable\n")
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_single_component_self_closing(self):
- registry.register(name="test", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component name="test" variable="variable" /%}
- """
-
- template = Template(simple_tag_template)
- rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, "Variable: variable\n")
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_raises_on_no_registered_components(self):
- # Note: No tag registered
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component name="test" variable="variable" %}{% endcomponent %}
- """
-
- with self.assertRaisesMessage(TemplateSyntaxError, "Invalid block tag on line 3: 'component'"):
- Template(simple_tag_template)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_call_with_invalid_name(self):
- registry.register(name="test_one", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component name="test" variable="variable" %}{% endcomponent %}
- """
-
- template = Template(simple_tag_template)
- with self.assertRaises(NotRegistered):
- template.render(Context({}))
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_component_called_with_positional_name(self):
- registry.register(name="test", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component "test" variable="variable" %}{% endcomponent %}
- """
-
- template = Template(simple_tag_template)
- rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, "Variable: variable\n")
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_call_component_with_two_variables(self):
- @register("test")
- class IffedComponent(Component):
- template: types.django_html = """
- Variable: {{ variable }}
- {% if variable2 != "default" %}
- Variable2: {{ variable2 }}
- {% endif %}
- """
-
- def get_context_data(self, variable, variable2="default"):
- return {
- "variable": variable,
- "variable2": variable2,
- }
-
- class Media:
- css = "style.css"
- js = "script.js"
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component name="test" variable="variable" variable2="hej" %}{% endcomponent %}
- """
-
- template = Template(simple_tag_template)
- rendered = template.render(Context({}))
- expected_outcome = """Variable: variable\n""" """Variable2: hej"""
- self.assertHTMLEqual(rendered, textwrap.dedent(expected_outcome))
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_component_called_with_singlequoted_name(self):
- registry.register(name="test", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% component 'test' variable="variable" %}{% endcomponent %}
- """
-
- template = Template(simple_tag_template)
- rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, "Variable: variable\n")
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_raises_on_component_called_with_variable_as_name(self):
- registry.register(name="test", component=self.SimpleComponent)
-
- simple_tag_template: types.django_html = """
- {% load component_tags %}
- {% with component_name="test" %}
- {% component component_name variable="variable" %}{% endcomponent %}
- {% endwith %}
- """
-
- with self.assertRaisesMessage(
- TemplateSyntaxError,
- "Component name must be a string 'literal', got: component_name",
- ):
- Template(simple_tag_template)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_component_accepts_provided_and_default_parameters(self):
- @register("test")
- class ComponentWithProvidedAndDefaultParameters(Component):
- template: types.django_html = """
- Provided variable: {{ variable }}
- Default:
- {first_slot}
- Default main
-
-
-
- {second_slot}
- Default main
-
-
- """
-
- def wrap_with_slot_tags(self, s):
- return '{% fill "header" %}' + s + "{% endfill %}"
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_both_components_render_correctly_with_no_slots(self):
- self.register_components()
- rendered = self.make_template().render(Context({}))
- self.assertHTMLEqual(rendered, self.expected_result())
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_both_components_render_correctly_with_slots(self):
- self.register_components()
- first_slot_content = "
@@ -282,12 +30,662 @@ class ComponentIsolationTests(BaseTestCase):
"""
- def setUp(self):
- super().setUp()
- registry.register("test", self.SlottedComponent)
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
+
+ return SlottedComponentWithContext
+
+
+#######################
+# TESTS
+#######################
+
+
+@djc_test
+class TestComponentTemplateTag:
+ class SimpleComponent(Component):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs["variable"],
+ "variable2": kwargs.get("variable2", "default"),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_single_component(self, components_settings):
+ registry.register(name="test", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" variable="variable" %}{% endcomponent %}
+ """
+
+ template = Template(simple_tag_template)
+ rendered = template.render(Context({}))
+ assertHTMLEqual(rendered, "Variable: variable\n")
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_single_component_self_closing(self, components_settings):
+ registry.register(name="test", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" variable="variable" /%}
+ """
+
+ template = Template(simple_tag_template)
+ rendered = template.render(Context({}))
+ assertHTMLEqual(rendered, "Variable: variable\n")
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_call_with_invalid_name(self, components_settings):
+ registry.register(name="test_one", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" variable="variable" %}{% endcomponent %}
+ """
+
+ template = Template(simple_tag_template)
+ with pytest.raises(NotRegistered):
+ template.render(Context({}))
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_called_with_positional_name(self, components_settings):
+ registry.register(name="test", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" variable="variable" %}{% endcomponent %}
+ """
+
+ template = Template(simple_tag_template)
+ rendered = template.render(Context({}))
+ assertHTMLEqual(rendered, "Variable: variable\n")
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_call_component_with_two_variables(self, components_settings):
+ @register("test")
+ class IffedComponent(Component):
+ template: types.django_html = """
+ Variable: {{ variable }}
+ {% if variable2 != "default" %}
+ Variable2: {{ variable2 }}
+ {% endif %}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs["variable"],
+ "variable2": kwargs.get("variable2", "default"),
+ }
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" variable="variable" variable2="hej" %}{% endcomponent %}
+ """
+
+ template = Template(simple_tag_template)
+ rendered = template.render(Context({}))
+ assertHTMLEqual(
+ rendered,
+ """
+ Variable: variable
+ Variable2: hej
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_called_with_singlequoted_name(self, components_settings):
+ registry.register(name="test", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' variable="variable" %}{% endcomponent %}
+ """
+
+ template = Template(simple_tag_template)
+ rendered = template.render(Context({}))
+ assertHTMLEqual(rendered, "Variable: variable\n")
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_component_called_with_variable_as_name(self, components_settings):
+ registry.register(name="test", component=self.SimpleComponent)
+
+ simple_tag_template: types.django_html = """
+ {% load component_tags %}
+ {% with component_name="test" %}
+ {% component component_name variable="variable" %}{% endcomponent %}
+ {% endwith %}
+ """
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Component name must be a string 'literal', got: component_name"),
+ ):
+ Template(simple_tag_template)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_accepts_provided_and_default_parameters(self, components_settings):
+ @register("test")
+ class ComponentWithProvidedAndDefaultParameters(Component):
+ template: types.django_html = """
+ Provided variable: {{ variable }}
+ Default:
+
+ Default header
+
+ Default main
+
+
+
+
+ Default header
+
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_both_components_render_correctly_with_slots(self, components_settings):
+ registry.register("first_component", gen_slotted_component())
+ registry.register("second_component", gen_slotted_component_with_context())
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'first_component' %}
+ {% fill "header" %}
+
+
+ Default main
+
+
+
+
+
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_both_components_render_correctly_when_only_first_has_slots(self, components_settings):
+ registry.register("first_component", gen_slotted_component())
+ registry.register("second_component", gen_slotted_component_with_context())
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'first_component' %}
+ {% fill "header" %}
+
+
+ Default main
+
+
+
+
+ Default header
+
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_both_components_render_correctly_when_only_second_has_slots(self, components_settings):
+ registry.register("first_component", gen_slotted_component())
+ registry.register("second_component", gen_slotted_component_with_context())
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'first_component' %}
+ {% endcomponent %}
+ {% component 'second_component' variable='xyz' %}
+ {% fill "header" %}
+
+ Default header
+
+ Default main
+
+
+
+
+
+ Default main
+
+
+ """,
+ )
+
+
+@djc_test
+class TestComponentIsolation:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_instances_of_component_do_not_share_slots(self, components_settings):
+ @register("test")
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
- @parametrize_context_behavior(["django", "isolated"])
- def test_instances_of_component_do_not_share_slots(self):
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
@@ -305,20 +703,20 @@ class ComponentIsolationTests(BaseTestCase):
template.render(Context({}))
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Override header
Default main
-
+
Default header
Override main
-
+
Default header
Default main
@@ -327,9 +725,10 @@ class ComponentIsolationTests(BaseTestCase):
)
-class AggregateInputTests(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_agg_input_accessible_in_get_context_data(self):
+@djc_test
+class TestAggregateInput:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_agg_input_accessible_in_get_context_data(self, components_settings):
@register("test")
class AttrsComponent(Component):
template: types.django_html = """
@@ -340,8 +739,11 @@ class AggregateInputTests(BaseTestCase):
"""
- def get_context_data(self, *args, attrs, my_dict):
- return {"attrs": attrs, "my_dict": my_dict}
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "attrs": kwargs["attrs"],
+ "my_dict": kwargs["my_dict"],
+ }
template_str: types.django_html = """
{% load component_tags %}
@@ -350,10 +752,10 @@ class AggregateInputTests(BaseTestCase):
""" # noqa: E501
template = Template(template_str)
rendered = template.render(Context({"class_var": "padding-top-8"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
OVERRIDEN!
hello2
diff --git a/tests/test_tag_parser.py b/tests/test_tag_parser.py
new file mode 100644
index 00000000..859715d3
--- /dev/null
+++ b/tests/test_tag_parser.py
@@ -0,0 +1,2813 @@
+import re
+from unittest import skip
+
+import pytest
+from django.template import Context, Template, TemplateSyntaxError
+from django.template.base import Parser
+from django.template.engine import Engine
+
+from django_components import Component, register, types
+from django_components.util.tag_parser import TagAttr, TagValue, TagValuePart, TagValueStruct, parse_tag
+
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+# NOTE: We have to define the parser to be able to resolve filters
+def _get_parser() -> Parser:
+ engine = Engine.get_default()
+ return Parser(
+ tokens=[],
+ libraries=engine.template_libraries,
+ builtins=engine.template_builtins,
+ origin=None,
+ )
+
+
+@djc_test
+class TestTagParser:
+ def test_args_kwargs(self):
+ _, attrs = parse_tag("component 'my_comp' key=val key2='val2 two' ", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ start_index=0,
+ value=TagValueStruct(
+ type="simple",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ ),
+ TagAttr(
+ key=None,
+ start_index=10,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted="'", spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ ),
+ TagAttr(
+ key="key",
+ start_index=20,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ ),
+ TagAttr(
+ key="key2",
+ start_index=28,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val2 two", quoted="'", spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "'my_comp'",
+ "key=val",
+ "key2='val2 two'",
+ ]
+
+ def test_nested_quotes(self):
+ _, attrs = parse_tag("component 'my_comp' key=val key2='val2 \"two\"' text=\"organisation's\" ", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted="'", spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value='val2 "two"', quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=28,
+ ),
+ TagAttr(
+ key="text",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="organisation's", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=46,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "'my_comp'",
+ "key=val",
+ "key2='val2 \"two\"'",
+ 'text="organisation\'s"',
+ ]
+
+ def test_trailing_quote_single(self):
+ _, attrs = parse_tag("component 'my_comp' key=val key2='val2 \"two\"' text=\"organisation's\" 'abc", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted="'", spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value='val2 "two"', quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=28,
+ ),
+ TagAttr(
+ key="text",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="organisation's", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=46,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="'abc", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=68,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "'my_comp'",
+ "key=val",
+ "key2='val2 \"two\"'",
+ 'text="organisation\'s"',
+ "'abc",
+ ]
+
+ def test_trailing_quote_double(self):
+ _, attrs = parse_tag('component "my_comp" key=val key2="val2 \'two\'" text=\'organisation"s\' "abc', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="val2 'two'", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=28,
+ ),
+ TagAttr(
+ key="text",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value='organisation"s', quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=46,
+ ), # noqa: E501
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value='"abc', quoted=None, spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=68,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '"my_comp"',
+ "key=val",
+ "key2=\"val2 'two'\"",
+ "text='organisation\"s'",
+ '"abc',
+ ]
+
+ def test_trailing_quote_as_value_single(self):
+ _, attrs = parse_tag(
+ "component 'my_comp' key=val key2='val2 \"two\"' text=\"organisation's\" value='abc",
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted="'", spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value='val2 "two"', quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=28,
+ ),
+ TagAttr(
+ key="text",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="organisation's", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=46,
+ ),
+ TagAttr(
+ key="value",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="'abc", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=68,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "'my_comp'",
+ "key=val",
+ "key2='val2 \"two\"'",
+ 'text="organisation\'s"',
+ "value='abc",
+ ]
+
+ def test_trailing_quote_as_value_double(self):
+ _, attrs = parse_tag(
+ 'component "my_comp" key=val key2="val2 \'two\'" text=\'organisation"s\' value="abc',
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="val2 'two'", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=28,
+ ),
+ TagAttr(
+ key="text",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value='organisation"s', quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=46,
+ ),
+ TagAttr(
+ key="value",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value='"abc', quoted=None, spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=68,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '"my_comp"',
+ "key=val",
+ "key2=\"val2 'two'\"",
+ "text='organisation\"s'",
+ 'value="abc',
+ ]
+
+ def test_translation(self):
+ _, attrs = parse_tag('component "my_comp" _("one") key=_("two")', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="one", quoted='"', spread=None, translation=True, filter=None)]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="two", quoted='"', spread=None, translation=True, filter=None)]
+ )
+ ],
+ ),
+ start_index=29,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '"my_comp"',
+ '_("one")',
+ 'key=_("two")',
+ ]
+
+ def test_tag_parser_filters(self):
+ _, attrs = parse_tag(
+ 'component "my_comp" value|lower key=val|yesno:"yes,no" key2=val2|default:"N/A"|upper',
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="my_comp", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="value", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="lower", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ )
+ ],
+ ),
+ start_index=20,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="yesno", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="yes,no", quoted='"', spread=None, translation=False, filter=":"),
+ ]
+ )
+ ],
+ ),
+ start_index=32,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val2", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="default", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="N/A", quoted='"', spread=None, translation=False, filter=":"),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ )
+ ],
+ ),
+ start_index=55,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '"my_comp"',
+ "value|lower",
+ 'key=val|yesno:"yes,no"',
+ 'key2=val2|default:"N/A"|upper',
+ ]
+
+ def test_translation_whitespace(self):
+ _, attrs = parse_tag('component value=_( "test" )', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="value",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="test", quoted='"', spread=None, translation=True, filter=None),
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ def test_filter_whitespace(self):
+ _, attrs = parse_tag("component value | lower key=val | upper key2=val2", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="value", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="lower", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="key",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ )
+ ],
+ ),
+ start_index=29,
+ ),
+ TagAttr(
+ key="key2",
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val2", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ )
+ ],
+ ),
+ start_index=50,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_filter_argument_must_follow_filter(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Filter argument (':arg') must follow a filter ('|filter')"),
+ ):
+ parse_tag('component value=val|yesno:"yes,no":arg', None)
+
+ def test_dict_simple(self):
+ _, attrs = parse_tag('component data={ "key": "val" }', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_dict_trailing_comma(self):
+ _, attrs = parse_tag('component data={ "key": "val", }', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_dict_missing_colon(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Dictionary key is missing a value"),
+ ):
+ parse_tag('component data={ "key" }', None)
+
+ def test_dict_missing_colon_2(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Dictionary key is missing a value"),
+ ):
+ parse_tag('component data={ "key", "val" }', None)
+
+ def test_dict_extra_colon(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Unexpected colon"),
+ ):
+ _, attrs = parse_tag("component data={ key:: key }", None)
+
+ def test_dict_spread(self):
+ _, attrs = parse_tag("component data={ **spread }", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="spread", quoted=None, spread="**", translation=False, filter=None),
+ ]
+ )
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_dict_spread_between_key_value_pairs(self):
+ _, attrs = parse_tag('component data={ "key": val, **spread, "key2": val2 }', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="spread", quoted=None, spread="**", translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="key2", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val2", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ # Test that dictionary keys cannot have filter arguments - The `:` is parsed as dictionary key separator
+ # So instead, the content below will be parsed as key `"key"|filter`, and value `"arg":"value"'
+ # And the latter is invalid because it's missing the `|` separator.
+ def test_colon_in_dictionary_keys(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Filter argument (':arg') must follow a filter ('|filter')"),
+ ):
+ _, attrs = parse_tag('component data={"key"|filter:"arg": "value"}', None)
+
+ def test_list_simple(self):
+ _, attrs = parse_tag("component data=[1, 2, 3]", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="1", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="2", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="3", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_list_trailing_comma(self):
+ _, attrs = parse_tag("component data=[1, 2, 3, ]", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="1", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="2", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="3", quoted=None, spread=None, translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+
+ def test_lists_complex(self):
+ _, attrs = parse_tag(
+ """
+ component
+ nums=[
+ 1,
+ 2|add:3,
+ *spread
+ ]
+ items=[
+ "a"|upper,
+ 'b'|lower,
+ c|default:"d"
+ ]
+ mixed=[
+ 1,
+ [*nested],
+ {"key": "val"}
+ ]
+ """,
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ )
+ ],
+ ),
+ start_index=17,
+ ),
+ TagAttr(
+ key="nums",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="1", quoted=None, spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="2", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="add", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="3", quoted=None, spread=None, translation=False, filter=":"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="spread", quoted=None, spread="*", translation=False, filter=None)
+ ]
+ ),
+ ],
+ ),
+ start_index=43,
+ ),
+ TagAttr(
+ key="items",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="a", quoted='"', spread=None, translation=False, filter=None),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="b", quoted="'", spread=None, translation=False, filter=None),
+ TagValuePart(value="lower", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="c", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="default", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="d", quoted='"', spread=None, translation=False, filter=":"),
+ ]
+ ),
+ ],
+ ),
+ start_index=164,
+ ),
+ TagAttr(
+ key="mixed",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="1", quoted=None, spread=None, translation=False, filter=None)]
+ ),
+ TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="nested",
+ quoted=None,
+ spread="*",
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ ],
+ ),
+ TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="key",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="val",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ ],
+ ),
+ ],
+ ),
+ start_index=302,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "nums=[1, 2|add:3, *spread]",
+ 'items=["a"|upper, \'b\'|lower, c|default:"d"]',
+ 'mixed=[1, [*nested], {"key": "val"}]',
+ ]
+
+ def test_dicts_complex(self):
+ _, attrs = parse_tag(
+ """
+ component
+ simple={
+ "a": 1|add:2
+ }
+ nested={
+ "key"|upper: val|lower,
+ **spread,
+ "obj": {"x": 1|add:2}
+ }
+ filters={
+ "a"|lower: "b"|upper,
+ c|default: "e"|yesno:"yes,no"
+ }
+ """,
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ ),
+ ],
+ ),
+ start_index=13,
+ ),
+ TagAttr(
+ key="simple",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="a", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="1", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="add", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="2", quoted=None, spread=None, translation=False, filter=":"),
+ ]
+ ),
+ ],
+ ),
+ start_index=35,
+ ),
+ TagAttr(
+ key="nested",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="lower", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="spread", quoted=None, spread="**", translation=False, filter=None)
+ ]
+ ),
+ TagValue(
+ parts=[TagValuePart(value="obj", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="x", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="1", quoted=None, spread=None, translation=False, filter=None
+ ),
+ TagValuePart(
+ value="add",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="2", quoted=None, spread=None, translation=False, filter=":"
+ ),
+ ]
+ ),
+ ],
+ ),
+ ],
+ ),
+ start_index=99,
+ ),
+ TagAttr(
+ key="filters",
+ value=TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="a", quoted='"', spread=None, translation=False, filter=None),
+ TagValuePart(value="lower", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="b", quoted='"', spread=None, translation=False, filter=None),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="c", quoted=None, spread=None, translation=False, filter=None),
+ TagValuePart(value="default", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="e", quoted='"', spread=None, translation=False, filter=None),
+ TagValuePart(value="yesno", quoted=None, spread=None, translation=False, filter="|"),
+ TagValuePart(value="yes,no", quoted='"', spread=None, translation=False, filter=":"),
+ ]
+ ),
+ ],
+ ),
+ start_index=238,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ 'simple={"a": 1|add:2}',
+ 'nested={"key"|upper: val|lower, **spread, "obj": {"x": 1|add:2}}',
+ 'filters={"a"|lower: "b"|upper, c|default: "e"|yesno:"yes,no"}',
+ ]
+
+ def test_mixed_complex(self):
+ _, attrs = parse_tag(
+ """
+ component
+ data={
+ "items": [
+ 1|add:2,
+ {"x"|upper: 2|add:3},
+ *spread_items|default:""
+ ],
+ "nested": {
+ "a": [
+ 1|add:2,
+ *nums|default:""
+ ],
+ "b": {
+ "x": [
+ *more|default:""
+ ]
+ }
+ },
+ **rest|default,
+ "key": _('value')|upper
+ }
+ """,
+ None,
+ )
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ ),
+ ],
+ ),
+ start_index=13,
+ ),
+ TagAttr(
+ key="data",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="items", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ ),
+ TagValueStruct(
+ type="list",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="1", quoted=None, spread=None, translation=False, filter=None
+ ),
+ TagValuePart(
+ value="add",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="2", quoted=None, spread=None, translation=False, filter=":"
+ ),
+ ]
+ ),
+ TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="x",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="upper",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="2",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="add",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="3",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=":",
+ ),
+ ]
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="spread_items",
+ quoted=None,
+ spread="*",
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="default",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(value="", quoted='"', spread=None, translation=False, filter=":"),
+ ]
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="nested", quoted='"', spread=None, translation=False, filter=None)
+ ]
+ ),
+ TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="a", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ ),
+ TagValueStruct(
+ type="list",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="1",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="add",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="2",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=":",
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="nums",
+ quoted=None,
+ spread="*",
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="default",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=":",
+ ),
+ ]
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="b", quoted='"', spread=None, translation=False, filter=None
+ )
+ ]
+ ),
+ TagValueStruct(
+ type="dict",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="x",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="more",
+ quoted=None,
+ spread="*",
+ translation=False,
+ filter=None,
+ ),
+ TagValuePart(
+ value="default",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter="|",
+ ),
+ TagValuePart(
+ value="",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=":",
+ ),
+ ]
+ ),
+ ],
+ ),
+ ],
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="rest", quoted=None, spread="**", translation=False, filter=None),
+ TagValuePart(value="default", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ TagValue(
+ parts=[TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="value", quoted="'", spread=None, translation=True, filter=None),
+ TagValuePart(value="upper", quoted=None, spread=None, translation=False, filter="|"),
+ ]
+ ),
+ ],
+ ),
+ start_index=35,
+ ),
+ ]
+
+ assert attrs == expected_attrs
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ 'data={"items": [1|add:2, {"x"|upper: 2|add:3}, *spread_items|default:""], "nested": {"a": [1|add:2, *nums|default:""], "b": {"x": [*more|default:""]}}, **rest|default, "key": _(\'value\')|upper}', # noqa: E501
+ ]
+
+ # Test that spread operator cannot be used as dictionary value
+ def test_spread_as_dictionary_value(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax cannot be used in place of a dictionary value"),
+ ):
+ parse_tag('component data={"key": **spread}', None)
+
+ def test_spread_with_colon_interpreted_as_key(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax cannot be used in place of a dictionary key"),
+ ):
+ _, attrs = parse_tag("component data={**spread|abc: 123 }", None)
+
+ def test_spread_in_filter_position(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax cannot be used inside of a filter"),
+ ):
+ _, attrs = parse_tag("component data=val|...spread|abc }", None)
+
+ def test_spread_whitespace(self):
+ # NOTE: Separating `...` from its variable is NOT valid, and will result in error.
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' is missing a value"),
+ ):
+ _, attrs = parse_tag("component ... attrs", None)
+
+ _, attrs = parse_tag('component dict={"a": "b", ** my_attr} list=["a", * my_list]', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ),
+ ]
+ ),
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key="dict",
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="a", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="b", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="my_attr", quoted=None, spread="**", translation=False, filter=None
+ ),
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ TagAttr(
+ key="list",
+ value=TagValueStruct(
+ type="list",
+ meta={},
+ spread=None,
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="a", quoted='"', spread=None, translation=False, filter=None),
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="my_list", quoted=None, spread="*", translation=False, filter=None),
+ ]
+ ),
+ ],
+ ),
+ start_index=38,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ # Test that one cannot use e.g. `...`, `**`, `*` in wrong places
+ def test_spread_incorrect_syntax(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '*' found outside of a list"),
+ ):
+ _, attrs = parse_tag('component dict={"a": "b", *my_attr}', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' found in dict. It must be used on tag attributes only"),
+ ):
+ _, attrs = parse_tag('component dict={"a": "b", ...my_attr}', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '**' found outside of a dictionary"),
+ ):
+ _, attrs = parse_tag('component list=["a", "b", **my_list]', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' found in list. It must be used on tag attributes only"),
+ ):
+ _, attrs = parse_tag('component list=["a", "b", ...my_list]', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '*' found outside of a list"),
+ ):
+ _, attrs = parse_tag("component *attrs", None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '**' found outside of a dictionary"),
+ ):
+ _, attrs = parse_tag("component **attrs", None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '*' found outside of a list"),
+ ):
+ _, attrs = parse_tag("component key=*attrs", None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '**' found outside of a dictionary"),
+ ):
+ _, attrs = parse_tag("component key=**attrs", None)
+
+ # Test that one cannot do `key=...{"a": "b"}`
+ def test_spread_onto_key(self):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' cannot follow a key ('key=...attrs')"),
+ ):
+ _, attrs = parse_tag('component key=...{"a": "b"}', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' cannot follow a key ('key=...attrs')"),
+ ):
+ _, attrs = parse_tag('component key=...["a", "b"]', None)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Spread syntax '...' cannot follow a key ('key=...attrs')"),
+ ):
+ _, attrs = parse_tag("component key=...attrs", None)
+
+ def test_spread_dict_literal_nested(self):
+ _, attrs = parse_tag('component { **{"key": val2}, "key": val1 }', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ spread=None,
+ meta={},
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="dict",
+ spread=None,
+ parser=None,
+ meta={},
+ entries=[
+ TagValueStruct(
+ type="dict",
+ spread="**",
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="key",
+ quoted='"',
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="val2",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val1", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '{**{"key": val2}, "key": val1}',
+ ]
+
+ def test_spread_dict_literal_as_attribute(self):
+ _, attrs = parse_tag('component ...{"key": val2}', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ spread=None,
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="dict",
+ spread="...",
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val2", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ '...{"key": val2}',
+ ]
+
+ def test_spread_list_literal_nested(self):
+ _, attrs = parse_tag("component [ *[val1], val2 ]", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ spread=None,
+ meta={},
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="list",
+ spread=None,
+ parser=None,
+ meta={},
+ entries=[
+ TagValueStruct(
+ type="list",
+ spread="*",
+ meta={},
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="val1",
+ quoted=None,
+ spread=None,
+ translation=False,
+ filter=None,
+ )
+ ]
+ ),
+ ],
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(value="val2", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "[*[val1], val2]",
+ ]
+
+ def test_spread_list_literal_as_attribute(self):
+ _, attrs = parse_tag("component ...[val1]", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ parser=None,
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ spread=None,
+ meta={},
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="list",
+ spread="...",
+ parser=None,
+ meta={},
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(value="val1", quoted=None, spread=None, translation=False, filter=None)
+ ]
+ ),
+ ],
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ assert [a.serialize() for a in attrs] == [
+ "component",
+ "...[val1]",
+ ]
+
+ def test_dynamic_expressions(self):
+ _, attrs = parse_tag("component '{% lorem w 4 %}'", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ) # noqa: E501
+ ],
+ )
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="{% lorem w 4 %}", quoted="'", spread=None, translation=False, filter=None
+ )
+ ],
+ )
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ def test_dynamic_expressions_in_dict(self):
+ _, attrs = parse_tag('component { "key": "{% lorem w 4 %}" }', None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ) # noqa: E501
+ ]
+ )
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="dict",
+ entries=[
+ TagValue(
+ parts=[TagValuePart(value="key", quoted='"', spread=None, translation=False, filter=None)]
+ ),
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="{% lorem w 4 %}", quoted='"', spread=None, translation=False, filter=None
+ ) # noqa: E501
+ ]
+ ),
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+ def test_dynamic_expressions_in_list(self):
+ _, attrs = parse_tag("component [ '{% lorem w 4 %}' ]", None)
+
+ expected_attrs = [
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="simple",
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="component", quoted=None, spread=None, translation=False, filter=None
+ ) # noqa: E501
+ ],
+ )
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=0,
+ ),
+ TagAttr(
+ key=None,
+ value=TagValueStruct(
+ type="list",
+ entries=[
+ TagValue(
+ parts=[
+ TagValuePart(
+ value="{% lorem w 4 %}", quoted="'", spread=None, translation=False, filter=None
+ )
+ ]
+ )
+ ],
+ spread=None,
+ meta={},
+ parser=None,
+ ),
+ start_index=10,
+ ),
+ ]
+ assert attrs == expected_attrs
+
+
+@djc_test
+class TestResolver:
+ def test_resolve_simple(self):
+ _, attrs = parse_tag("123", None)
+ resolved = attrs[0].value.resolve(Context())
+ assert resolved == 123
+
+ _, attrs = parse_tag("'123'", None)
+ resolved = attrs[0].value.resolve(Context())
+ assert resolved == "123"
+
+ _, attrs = parse_tag("abc", None)
+ resolved = attrs[0].value.resolve(Context({"abc": "foo"}))
+ assert resolved == "foo"
+
+ def test_resolve_list(self):
+ _, attrs = parse_tag("[1, 2, 3,]", None)
+ resolved = attrs[0].value.resolve(Context())
+ assert resolved == [1, 2, 3]
+
+ def test_resolve_list_with_spread(self):
+ _, attrs = parse_tag("[ 1, 2, *[3, val1, *val2, 5], val3, 6 ]", None)
+ resolved = attrs[0].value.resolve(Context({"val1": "foo", "val2": ["bar", "baz"], "val3": "qux"}))
+ assert resolved == [1, 2, 3, "foo", "bar", "baz", 5, "qux", 6]
+
+ def test_resolve_dict(self):
+ _, attrs = parse_tag('{"a": 1, "b": 2,}', None)
+ resolved = attrs[0].value.resolve(Context())
+ assert resolved == {"a": 1, "b": 2}
+
+ def test_resolve_dict_with_spread(self):
+ _, attrs = parse_tag('{ **{"key": val2, **{ val3: val4 }, "key3": val4 } }', None)
+ context = Context({"val2": "foo", "val3": "bar", "val4": "baz"})
+ resolved = attrs[0].value.resolve(context)
+ assert resolved == {"key": "foo", "bar": "baz", "key3": "baz"}
+
+ def test_resolve_dynamic_expr(self):
+ parser = _get_parser()
+ _, attrs = parse_tag("'{% lorem 4 w %}'", parser)
+ resolved = attrs[0].value.resolve(Context())
+ assert resolved == "lorem ipsum dolor sit"
+
+ def test_resolve_complex(self):
+ parser = _get_parser()
+
+ _, attrs = parse_tag(
+ """
+ data={
+ "items": [
+ 1|add:2,
+ {"x"|upper: 2|add:3},
+ *spread_items
+ ],
+ "nested": {
+ "a": [
+ 1|add:2,
+ *nums|default:"",
+ *"{% lorem 1 w %}",
+ ],
+ "b": {
+ "x": [
+ *more|first,
+ ],
+ "{% lorem 2 w %}": "{% lorem 3 w %}",
+ }
+ },
+ **rest,
+ "key": _('value')|upper
+ }
+ """,
+ parser,
+ )
+
+ context = Context(
+ {
+ "spread_items": ["foo", "bar"],
+ "nums": [1, 2, 3],
+ "more": ["baz", "qux"],
+ "rest": {"a": "b"},
+ }
+ )
+ resolved = attrs[0].value.resolve(context)
+
+ assert resolved == {
+ "items": [3, {"X": 5}, "foo", "bar"],
+ "nested": {
+ "a": [3, 1, 2, 3, "l", "o", "r", "e", "m"],
+ "b": {
+ "x": ["b", "a", "z"],
+ "lorem ipsum": "lorem ipsum dolor",
+ },
+ },
+ "a": "b",
+ "key": "VALUE",
+ }
+
+ @skip("TODO: Enable once template parsing is fixed by us")
+ def test_resolve_complex_as_component(self):
+ captured = None
+
+ @register("test")
+ class Test(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured
+ captured = kwargs
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test"
+ data={
+ "items": [
+ 1|add:2,
+ {"x"|upper: 2|add:3},
+ *spread_items
+ ],
+ "nested": {
+ "a": [
+ 1|add:2,
+ *nums|default:"",
+ *"{% lorem 1 w %}",
+ ],
+ "b": {
+ "x": [
+ *more|first,
+ ],
+ "{% lorem 2 w %}": "{% lorem 3 w %}",
+ }
+ },
+ **rest,
+ "key": _('value')|upper
+ }
+ / %}
+ """
+
+ template = Template(template_str)
+ template.render(
+ Context(
+ {
+ "spread_items": ["foo", "bar"],
+ "nums": [1, 2, 3],
+ "more": ["baz", "qux"],
+ "rest": {"a": "b"},
+ }
+ )
+ )
+
+ assert captured == {
+ "items": [3, {"X": 5}, "foo", "bar"],
+ "nested": {
+ "a": [3, 1, 2, 3, "l", "o", "r", "e", "m"],
+ "b": {
+ "x": ["b", "a", "z"],
+ "lorem ipsum": "lorem ipsum dolor",
+ },
+ },
+ "a": "b",
+ "key": "VALUE",
+ }
+
+ def test_component_args_kwargs(self):
+ captured = None
+
+ @register("test")
+ class Test(Component):
+ template = "var"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured
+ captured = args, kwargs
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' 42 myvar key='val' key2=val2 %}
+ {% endcomponent %}
+ """
+ Template(template_str).render(Context({"myvar": "myval", "val2": [1, 2, 3]}))
+
+ assert captured == ([42, "myval"], {"key": "val", "key2": [1, 2, 3]})
+
+ def test_component_special_kwargs(self):
+ captured = None
+
+ @register("test")
+ class Test(Component):
+ template = "var"
+
+ def get_template_data(self, args, kwargs, slots, context):
+ nonlocal captured
+ captured = args, kwargs
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' date=date @lol=2 na-me=bzz @event:na-me.mod=bzz #my-id=True %}
+ {% endcomponent %}
+ """
+ Template(template_str).render(Context({"date": 2024, "bzz": "fzz"}))
+
+ assert captured == (
+ [],
+ {
+ "date": 2024,
+ "@lol": 2,
+ "na-me": "fzz",
+ "@event": {"na-me.mod": "fzz"},
+ "#my-id": True,
+ },
+ )
diff --git a/tests/test_template.py b/tests/test_template.py
new file mode 100644
index 00000000..a7a250a7
--- /dev/null
+++ b/tests/test_template.py
@@ -0,0 +1,53 @@
+from django.template import Template
+
+from django_components import Component, cached_template, types
+
+from django_components.template import _get_component_template
+from django_components.testing import djc_test
+from .testutils import setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+@djc_test
+class TestTemplateCache:
+ # TODO_v1 - Remove
+ def test_cached_template(self):
+ template_1 = cached_template("Variable: {{ variable }}")
+ template_1._test_id = "123"
+
+ template_2 = cached_template("Variable: {{ variable }}")
+
+ assert template_2._test_id == "123"
+
+ # TODO_v1 - Remove
+ def test_cached_template_accepts_class(self):
+ class MyTemplate(Template):
+ pass
+
+ template = cached_template("Variable: {{ variable }}", MyTemplate)
+ assert isinstance(template, MyTemplate)
+
+ # TODO_v1 - Move to `test_component.py`. While `cached_template()` will be removed,
+ # we will internally still cache templates by class, and we will want to test for that.
+ def test_component_template_is_cached(self):
+ class SimpleComponent(Component):
+ def get_template(self, context):
+ content: types.django_html = """
+ Variable: {{ variable }}
+ """
+ return content
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "variable": kwargs.get("variable", None),
+ }
+
+ comp = SimpleComponent(kwargs={"variable": "test"})
+
+ # Check that we get the same template instance
+ template_1 = _get_component_template(comp)
+ template_1._test_id = "123" # type: ignore[union-attr]
+
+ template_2 = _get_component_template(comp)
+ assert template_2._test_id == "123" # type: ignore[union-attr]
diff --git a/tests/test_template_loader.py b/tests/test_template_loader.py
deleted file mode 100644
index 3cebefbd..00000000
--- a/tests/test_template_loader.py
+++ /dev/null
@@ -1,76 +0,0 @@
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-from django.template.engine import Engine
-from django.test import override_settings
-
-from django_components.template_loader import Loader
-
-from .django_test_setup import setup_test_config
-from .testutils import BaseTestCase
-
-setup_test_config({"autodiscover": False})
-
-
-@override_settings(
- BASE_DIR=Path(__file__).parent.resolve(),
-)
-class TemplateLoaderTest(BaseTestCase):
- def test_get_dirs__base_dir(self):
- current_engine = Engine.get_default()
- loader = Loader(current_engine)
- dirs = loader.get_dirs()
- self.assertEqual(
- sorted(dirs),
- sorted(
- [
- Path(__file__).parent.resolve() / "components",
- ]
- ),
- )
-
- @override_settings(
- BASE_DIR=Path(__file__).parent.resolve() / "test_structures" / "test_structure_1", # noqa
- )
- def test_get_dirs__base_dir__complex(self):
- current_engine = Engine.get_default()
- loader = Loader(current_engine)
- dirs = loader.get_dirs()
- expected = [
- Path(__file__).parent.resolve() / "test_structures" / "test_structure_1" / "components",
- ]
- self.assertEqual(sorted(dirs), sorted(expected))
-
- @override_settings(
- STATICFILES_DIRS=[
- Path(__file__).parent.resolve() / "components",
- ("with_alias", Path(__file__).parent.resolve() / "components"),
- ("too_many", "items", Path(__file__).parent.resolve() / "components"),
- ("with_not_str_alias", 3),
- ] # noqa
- )
- @patch("django_components.template_loader.logger.warning")
- def test_get_dirs__staticfiles_dirs(self, mock_warning: MagicMock):
- mock_warning.reset_mock()
- current_engine = Engine.get_default()
- Loader(current_engine).get_dirs()
-
- comps_path = Path(__file__).parent.resolve() / "components"
-
- warn_inputs = [warn.args[0] for warn in mock_warning.call_args_list]
- assert f"Got Welcome!
+ {% component 'test' key="{% lorem var_a w %}" %} + {% verbatim %} + {% endcomponent %} + {% endverbatim %} + {% endcomponent %} + {% endif %}""" + ) + + token_tuples = [token2tuple(token) for token in tokens] + expected_tokens = [ + (TokenType.TEXT, "Hello ", (0, 6), 1), + (TokenType.VAR, "name", (6, 16), 1), + (TokenType.TEXT, "\n ", (16, 29), 1), + (TokenType.COMMENT, "greeting", (29, 43), 2), + (TokenType.TEXT, "\n ", (43, 56), 2), + (TokenType.BLOCK, "if show_greeting", (56, 78), 3), + (TokenType.TEXT, "\nWelcome!
\n ", (78, 129), 3), + (TokenType.BLOCK, "component 'test' key=\"{% lorem var_a w %}\"", (129, 177), 5), + (TokenType.TEXT, "\n ", (177, 198), 5), + (TokenType.BLOCK, "verbatim", (198, 212), 6), + (TokenType.TEXT, "\n ", (212, 237), 6), + (TokenType.TEXT, "{% endcomponent %}", (237, 255), 7), + (TokenType.TEXT, "\n ", (255, 276), 7), + (TokenType.BLOCK, "endverbatim", (276, 293), 8), + (TokenType.TEXT, "\n ", (293, 310), 8), + (TokenType.BLOCK, "endcomponent", (310, 328), 9), + (TokenType.TEXT, "\n ", (328, 341), 9), + (TokenType.BLOCK, "endif", (341, 352), 10), + ] + + assert token_tuples == expected_tokens + + # Check that a template that contains `{% %}` inside of a component tag is parsed correctly + def test_component_mixed(self): + @register("test") + class Test(Component): + template: types.django_html = """ + {% load component_tags %} + Var: {{ var }} + Slot: {% slot "content" default / %} + """ + + def get_template_data(self, args, kwargs, slots, context): + return {"var": kwargs["var"]} template_str: types.django_html = """ {% load component_tags %} - {% component "test" my-date="2015-06-19" @click.native=do_something #some_id=True %} - {% endcomponent %} +
+ Hello {{ name }}
+ {# greeting #}
+ {% if show_greeting %}
+
"""
template = Template(template_str)
- rendered = template.render(Context({"do_something": "abc"}))
- self.assertHTMLEqual(
+ rendered = template.render(Context({"name": "John", "show_greeting": True, "var_a": 2}))
+
+ assertHTMLEqual(
rendered,
"""
- 2015-06-19
- True
- abc
+ Welcome!
+ {% component 'test' var="{% lorem var_a w %}" %} + {% verbatim %} + {% endcomponent %} + {% endverbatim %} + {% endcomponent %} + {% endif %} +
+ Hello John
+
""",
)
-
-
-class AggregateKwargsTest(BaseTestCase):
- def test_aggregate_kwargs(self):
- processed = process_aggregate_kwargs(
- {
- "attrs:@click.stop": "dispatch('click_event')",
- "attrs:x-data": "{hello: 'world'}",
- "attrs:class": "class_var",
- "my_dict:one": 2,
- "three": "four",
- ":placeholder": "No text",
- }
- )
-
- self.assertDictEqual(
- processed,
- {
- "attrs": {
- "@click.stop": "dispatch('click_event')",
- "x-data": "{hello: 'world'}",
- "class": "class_var",
- },
- "my_dict": {"one": 2},
- "three": "four",
- ":placeholder": "No text",
- },
- )
-
- def is_aggregate_key(self):
- self.assertEqual(is_aggregate_key(""), False)
- self.assertEqual(is_aggregate_key(" "), False)
- self.assertEqual(is_aggregate_key(" : "), False)
- self.assertEqual(is_aggregate_key("attrs"), False)
- self.assertEqual(is_aggregate_key(":attrs"), False)
- self.assertEqual(is_aggregate_key(" :attrs "), False)
- self.assertEqual(is_aggregate_key("attrs:"), False)
- self.assertEqual(is_aggregate_key(":attrs:"), False)
- self.assertEqual(is_aggregate_key("at:trs"), True)
- self.assertEqual(is_aggregate_key(":at:trs"), False)
diff --git a/tests/test_templatetags.py b/tests/test_templatetags.py
index af242546..3c494ea3 100644
--- a/tests/test_templatetags.py
+++ b/tests/test_templatetags.py
@@ -1,19 +1,13 @@
"""Catch-all for tests that use template tags and don't fit other files"""
-from typing import Callable
-
from django.template import Context, Template
-
+from pytest_django.asserts import assertHTMLEqual
from django_components import Component, register, registry, types
-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()
-
-
-class SlottedComponent(Component):
- template_name = "slotted_template.html"
+setup_test_config({"autodiscover": False})
#######################
@@ -21,462 +15,117 @@ class SlottedComponent(Component):
#######################
-class TemplateInstrumentationTest(BaseTestCase):
- saved_render_method: Callable # Assigned during setup.
-
- def tearDown(self):
- super().tearDown()
- Template._render = self.saved_render_method
-
- def setUp(self):
- """Emulate Django test instrumentation for TestCase (see setup_test_environment)"""
- from django.test.utils import instrumented_test_render
-
- self.saved_render_method = Template._render
- Template._render = instrumented_test_render
-
- registry.clear()
- registry.register("test_component", SlottedComponent)
-
- @register("inner_component")
+@djc_test
+class TestMultilineTags:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_multiline_tags(self, components_settings):
+ @register("test_component")
class SimpleComponent(Component):
- template_name = "simple_template.html"
+ template: types.django_html = """
+ 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:
- css = "style.css"
- js = "script.js"
-
- def templates_used_to_render(self, subject_template, render_context=None):
- """Emulate django.test.client.Client (see request method)."""
- from django.test.signals import template_rendered
-
- templates_used = []
-
- def receive_template_signal(sender, template, context, **_kwargs):
- templates_used.append(template.name)
-
- template_rendered.connect(receive_template_signal, dispatch_uid="test_method")
- subject_template.render(render_context or Context({}))
- template_rendered.disconnect(dispatch_uid="test_method")
- return templates_used
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_template_shown_as_used(self):
- template_str: types.django_html = """
- {% load component_tags %}
- {% component 'test_component' %}{% endcomponent %}
- """
- template = Template(template_str, name="root")
- templates_used = self.templates_used_to_render(template)
- self.assertIn("slotted_template.html", templates_used)
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_nested_component_templates_all_shown_as_used(self):
- template_str: types.django_html = """
- {% load component_tags %}
- {% component 'test_component' %}
- {% fill "header" %}
- {% component 'inner_component' variable='foo' %}{% endcomponent %}
- {% endfill %}
- {% endcomponent %}
- """
- template = Template(template_str, name="root")
- templates_used = self.templates_used_to_render(template)
- self.assertIn("slotted_template.html", templates_used)
- self.assertIn("simple_template.html", templates_used)
-
-
-class BlockCompatTests(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_slots_inside_extends(self):
- registry.register("slotted_component", SlottedComponent)
-
- @register("slot_inside_extends")
- class SlotInsideExtendsComponent(Component):
- template: types.django_html = """
- {% extends "block_in_slot_in_component.html" %}
- """
-
template: types.django_html = """
{% load component_tags %}
- {% component "slot_inside_extends" %}
- {% fill "body" %}
- BODY_FROM_FILL
- {% endfill %}
+ {% component
+ "test_component"
+ variable=123
+ variable2="abc"
+ %}
{% endcomponent %}
"""
rendered = Template(template).render(Context())
expected = """
-
-
-
- Welcome!
+ Var: lorem ipsum + Slot: {% endcomponent %} +
-
- TEST
-
-
-
-
- 58 giraffes and 2 pantaloons
-
- {% endblock %}
- """
- rendered = Template(template).render(Context())
- expected = """
-
-
-
- 58 giraffes and 2 pantaloons
- 58 giraffes and 2 pantaloons
- injected: {{ var|safe }}
- """
-
- def get_context_data(self):
- var = self.inject("block_provide")
- return {"var": var}
-
- template: types.django_html = """
- {% extends "block_in_component_provide.html" %}
- {% load component_tags %}
- {% block body %}
- {% component "injectee" %}
- {% endcomponent %}
- {% endblock %}
- """
- rendered = Template(template).render(Context())
- expected = """
-
-
-
- injected: DepInject(hello='from_block')
- {{ default_param }}
- """ - - def get_context_data(self, variable, default_param="default text"): - return {"variable": variable, "default_param": default_param} - - template_str: types.django_html = """ - {% load component_tags %} - {% component "test" variable="provided value" %} - {% endcomponent %} - """ - template = Template(template_str) - rendered = template.render(Context({})) - self.assertHTMLEqual( - rendered, - "Provided variable: provided value\nDefault:default text
", - ) - - -class MultiComponentTests(BaseTestCase): - def register_components(self): - registry.register("first_component", SlottedComponent) - registry.register("second_component", SlottedComponentWithContext) - - def make_template(self, first_slot: str = "", second_slot: str = "") -> Template: - template_str: types.django_html = f""" - {{% load component_tags %}} - {{% component 'first_component' %}} - {first_slot} - {{% endcomponent %}} - {{% component 'second_component' variable='xyz' %}} - {second_slot} - {{% endcomponent %}} - """ - return Template(template_str) - - def expected_result(self, first_slot: str = "", second_slot: str = "") -> str: - first_slot = first_slot or "Default header" - second_slot = second_slot or "Default header" - return f""" -Slot #1
" - second_slot_content = "Slot #2
"
- first_slot = self.wrap_with_slot_tags(first_slot_content)
- second_slot = self.wrap_with_slot_tags(second_slot_content)
- rendered = self.make_template(first_slot, second_slot).render(Context({}))
- self.assertHTMLEqual(
- rendered,
- self.expected_result(first_slot_content, second_slot_content),
- )
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_both_components_render_correctly_when_only_first_has_slots(self):
- self.register_components()
- first_slot_content = "Slot #1
" - first_slot = self.wrap_with_slot_tags(first_slot_content) - rendered = self.make_template(first_slot).render(Context({})) - self.assertHTMLEqual(rendered, self.expected_result(first_slot_content)) - - @parametrize_context_behavior(["django", "isolated"]) - def test_both_components_render_correctly_when_only_second_has_slots(self): - self.register_components() - second_slot_content = "Slot #2
"
- second_slot = self.wrap_with_slot_tags(second_slot_content)
- rendered = self.make_template("", second_slot).render(Context({}))
- self.assertHTMLEqual(rendered, self.expected_result("", second_slot_content))
-
-
-class ComponentIsolationTests(BaseTestCase):
+def gen_slotted_component():
class SlottedComponent(Component):
+ template_file = "slotted_template.html"
+
+ return SlottedComponent
+
+
+def gen_slotted_component_with_context():
+ class SlottedComponentWithContext(Component):
template: types.django_html = """
{% load component_tags %}
{{ default_param }}
+ """ + + def get_template_data(self, args, kwargs, slots, context): + return { + "variable": kwargs["variable"], + "default_param": kwargs.get("default_param", "default text"), + } + + template_str: types.django_html = """ + {% load component_tags %} + {% component "test" variable="provided value" %} + {% endcomponent %} + """ + template = Template(template_str) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + """ + Provided variable: provided value + Default:default text
+ """, + ) + + +@djc_test +class TestDynamicComponentTemplateTag: + class SimpleComponent(Component): + template: types.django_html = """ + Variable: {{ variable }} + """ + + class Kwargs(NamedTuple): + variable: str + variable2: str + + class Defaults: + variable2 = "default" + + def get_template_data(self, args, kwargs: Kwargs, slots, context): + return { + "variable": kwargs.variable, + "variable2": kwargs.variable2, + } + + class Media: + css = "style.css" + js = "script.js" + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_basic(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% component "dynamic" is="test" variable="variable" %}{% endcomponent %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + "Variable: variable", + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_call_with_invalid_name(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% component "dynamic" is="haber_der_baber" variable="variable" %}{% endcomponent %} + """ + + template = Template(simple_tag_template) + with pytest.raises(NotRegistered, match=re.escape("The component 'haber_der_baber' was not found")): + template.render(Context({})) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_called_with_variable_as_name(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% with component_name="test" %} + {% component "dynamic" is=component_name variable="variable" %}{% endcomponent %} + {% endwith %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + "Variable: variable", + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_called_with_variable_as_spread(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% component "dynamic" ...props %}{% endcomponent %} + """ + + template = Template(simple_tag_template) + rendered = template.render( + Context( + { + "props": { + "is": "test", + "variable": "variable", + }, + } + ) + ) + assertHTMLEqual( + rendered, + "Variable: variable", + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_as_class(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% component "dynamic" is=comp_cls variable="variable" %}{% endcomponent %} + """ + + template = Template(simple_tag_template) + rendered = template.render( + Context( + { + "comp_cls": self.SimpleComponent, + } + ) + ) + assertHTMLEqual( + rendered, + "Variable: variable", + ) + + @djc_test( + parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR, + components_settings={ + "tag_formatter": "django_components.component_shorthand_formatter", + "autodiscover": False, + }, + ) + def test_shorthand_formatter(self, components_settings): + from django_components.apps import ComponentsConfig + + ComponentsConfig.ready(None) # type: ignore[arg-type] + + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% dynamic is="test" variable="variable" %}{% enddynamic %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual(rendered, "Variable: variable\n") + + @djc_test( + parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR, + components_settings={ + "dynamic_component_name": "uno_reverse", + "tag_formatter": "django_components.component_shorthand_formatter", + "autodiscover": False, + }, + ) + def test_component_name_is_configurable(self, components_settings): + from django_components.apps import ComponentsConfig + + ComponentsConfig.ready(None) # type: ignore[arg-type] + + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% uno_reverse is="test" variable="variable" %}{% enduno_reverse %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + "Variable: variable", + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_raises_already_registered_on_name_conflict(self, components_settings): + with pytest.raises( + AlreadyRegistered, + match=re.escape('The component "dynamic" has already been registered'), + ): + registry.register(name="dynamic", component=self.SimpleComponent) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_called_with_default_slot(self, components_settings): + class SimpleSlottedComponent(Component): + template: types.django_html = """ + {% load component_tags %} + Variable: {{ variable }} + Slot: {% slot "default" default / %} + """ + + def get_template_data(self, args, kwargs, slots, context): + return { + "variable": kwargs["variable"], + "variable2": kwargs.get("variable2", "default"), + } + + registry.register(name="test", component=SimpleSlottedComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% with component_name="test" %} + {% component "dynamic" is=component_name variable="variable" %} + HELLO_FROM_SLOT + {% endcomponent %} + {% endwith %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + """ + Variable: variable + Slot: HELLO_FROM_SLOT + """, + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_component_called_with_named_slots(self, components_settings): + class SimpleSlottedComponent(Component): + template: types.django_html = """ + {% load component_tags %} + Variable: {{ variable }} + Slot 1: {% slot "default" default / %} + Slot 2: {% slot "two" / %} + """ + + def get_template_data(self, args, kwargs, slots, context): + return { + "variable": kwargs["variable"], + "variable2": kwargs.get("variable2", "default"), + } + + registry.register(name="test", component=SimpleSlottedComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% with component_name="test" %} + {% component "dynamic" is=component_name variable="variable" %} + {% fill "default" %} + HELLO_FROM_SLOT_1 + {% endfill %} + {% fill "two" %} + HELLO_FROM_SLOT_2 + {% endfill %} + {% endcomponent %} + {% endwith %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + """ + Variable: variable + Slot 1: HELLO_FROM_SLOT_1 + Slot 2: HELLO_FROM_SLOT_2 + """, + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_ignores_invalid_slots(self, components_settings): + class SimpleSlottedComponent(Component): + template: types.django_html = """ + {% load component_tags %} + Variable: {{ variable }} + Slot 1: {% slot "default" default / %} + Slot 2: {% slot "two" / %} + """ + + def get_template_data(self, args, kwargs, slots, context): + return { + "variable": kwargs["variable"], + "variable2": kwargs.get("variable2", "default"), + } + + registry.register(name="test", component=SimpleSlottedComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% with component_name="test" %} + {% component "dynamic" is=component_name variable="variable" %} + {% fill "default" %} + HELLO_FROM_SLOT_1 + {% endfill %} + {% fill "three" %} + HELLO_FROM_SLOT_2 + {% endfill %} + {% endcomponent %} + {% endwith %} + """ + + template = Template(simple_tag_template) + rendered = template.render(Context({})) + assertHTMLEqual( + rendered, + """ + Variable: variable + Slot 1: HELLO_FROM_SLOT_1 + Slot 2: + """, + ) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_raises_on_invalid_input(self, components_settings): + registry.register(name="test", component=self.SimpleComponent) + + simple_tag_template: types.django_html = """ + {% load component_tags %} + {% with component_name="test" %} + {% component "dynamic" is=component_name invalid_variable="variable" %}{% endcomponent %} + {% endwith %} + """ + + template = Template(simple_tag_template) + with pytest.raises( + TypeError, + match=re.escape("got an unexpected keyword argument 'invalid_variable'"), + ): + template.render(Context({})) + + +@djc_test +class TestMultiComponent: + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_both_components_render_correctly_with_no_slots(self, components_settings): + registry.register("first_component", gen_slotted_component()) + registry.register("second_component", gen_slotted_component_with_context()) + + template_str: types.django_html = """ + {% load component_tags %} + {% component 'first_component' %} + {% endcomponent %} + {% component 'second_component' variable='xyz' %} + {% endcomponent %} + """ + template = Template(template_str) + rendered = template.render(Context()) + + assertHTMLEqual( + rendered, + """ +Slot #1
{% endfill %} + {% endcomponent %} + {% component 'second_component' variable='xyz' %} + {% fill "header" %}Slot #2
{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context())
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Slot #1
+Slot #2
+ Slot #1
{% endfill %} + {% endcomponent %} + {% component 'second_component' variable='xyz' %} + {% endcomponent %} + """ + template = Template(template_str) + rendered = template.render(Context({})) + + assertHTMLEqual( + rendered, + """ +Slot #1
+Slot #2
{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+ Slot #2
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_component_two_identical_components(self, components_settings):
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_component_two_different_components_same_parent(self, components_settings): # noqa: E501
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_component_two_different_components_different_parent(self, components_settings): # noqa: E501
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_extends_on_component_one_component(self, components_settings):
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_extends_on_component_two_component(self, components_settings):
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+ SLOT OVERRIDEN 2
+ Default main
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_nested_component(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+
+
+
+
+ """
+
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_nested_component_and_include(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template_file = "included.html"
+
+ template: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% include 'included.html' %}
+ {% component "extended_component" / %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # second rendering after cache built
+ rendered_2 = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected_2 = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered_2, expected_2)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slots_inside_extends(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_extends")
+ class SlotInsideExtendsComponent(Component):
+ template: types.django_html = """
+ {% extends "block_in_slot_in_component.html" %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_extends" %}
+ {% fill "body" %}
+ BODY_FROM_FILL
+ {% endfill %}
+ {% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+ BODY_FROM_FILL
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slots_inside_include(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_include")
+ class SlotInsideIncludeComponent(Component):
+ template: types.django_html = """
+ {% include "block_in_slot_in_component.html" %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_include" %}
+ {% fill "body" %}
+ BODY_FROM_FILL
+ {% endfill %}
+ {% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+ BODY_FROM_FILL
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # In this case, `{% include %}` is NOT nested inside a `{% component %}` tag.
+ # We need to ensure that the component inside the `{% include %}` is rendered as if with deps_strategy="ignore",
+ # so the parent template decides how to render the JS/CSS.
+ # See https://github.com/django-components/django-components/issues/1296
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_with_media_inside_include(self, components_settings):
+ registry.register("test_component", gen_component_inside_include())
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+ {% include "component_inside_include_sub.html" %}
+
+
+ """
+
+ rendered_raw = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected_raw = """
+
+
+
+
+ """
+ assertHTMLEqual(rendered_raw, expected_raw)
+
+ template_obj = Template(template)
+ context = Context()
+ rendered = template_obj.render(context)
+
+ # NOTE: It's important that the
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # In this case, because `{% include %}` is rendered inside a `{% component %}` tag,
+ # then the component inside the `{% include %}` knows it's inside another component.
+ # So it's always rendered as if with deps_strategy="ignore".
+ # See https://github.com/django-components/django-components/issues/1296
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_with_media_inside_include_inside_component(self, components_settings):
+ registry.register("test_component", gen_component_inside_include())
+
+ @register("component_inside_include")
+ class CompInsideIncludeComponent(Component):
+ template: types.django_html = """
+
+
+ {% include "component_inside_include_sub.html" %}
+
+
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% component "component_inside_include" / %}
+
+ """
+
+ rendered_raw = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected_raw = """
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered_raw, expected_raw)
+
+ template_obj = Template(template)
+ context = Context()
+ rendered = template_obj.render(context)
+ expected = """
+
+
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_inside_block(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+ template: types.django_html = """
+ {% extends "block.html" %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "slotted_component" %}
+ {% fill "header" %}{% endfill %}
+ {% fill "main" %}
+ TEST
+ {% endfill %}
+ {% fill "footer" %}{% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_block_inside_component(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ template: types.django_html = """
+ {% extends "block_in_component.html" %}
+ {% block body %}
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_block_inside_component_parent(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("block_in_component_parent")
+ class BlockInCompParent(Component):
+ template_file = "block_in_component_parent.html"
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "block_in_component_parent" %}{% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_block_does_not_affect_inside_component(self, components_settings):
+ """
+ Assert that when we call a component with `{% component %}`, that
+ the `{% block %}` will NOT affect the inner component.
+ """
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("block_inside_slot_v1")
+ class BlockInSlotInComponent(Component):
+ template_file = "block_in_slot_in_component.html"
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "block_inside_slot_v1" %}
+ {% fill "body" %}
+ BODY_FROM_FILL
+ {% endfill %}
+ {% endcomponent %}
+ {% block inner %}
+ wow
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+ BODY_FROM_FILL
+
+
+
+
+ wow
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_inside_block__slot_default_block_default(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_block")
+ class _SlotInsideBlockComponent(Component):
+ template: types.django_html = """
+ {% extends "slot_inside_block.html" %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_block" %}{% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+ Helloodiddoo
+ Default inner
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_inside_block__slot_default_block_override(self, components_settings):
+ registry.clear()
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_block")
+ class _SlotInsideBlockComponent(Component):
+ template: types.django_html = """
+ {% extends "slot_inside_block.html" %}
+ {% block inner %}
+ INNER BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_block" %}{% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+ Helloodiddoo
+ INNER BLOCK OVERRIDEN
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_inside_block__slot_overriden_block_default(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_block")
+ class _SlotInsideBlockComponent(Component):
+ template: types.django_html = """
+ {% extends "slot_inside_block.html" %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_block" %}
+ {% fill "body" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+ Helloodiddoo
+ SLOT OVERRIDEN
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_inside_block__slot_overriden_block_overriden(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("slot_inside_block")
+ class _SlotInsideBlockComponent(Component):
+ template: types.django_html = """
+ {% extends "slot_inside_block.html" %}
+ {% block inner %}
+ {% load component_tags %}
+ {% slot "new_slot" %}{% endslot %}
+ {% endblock %}
+ whut
+ """
+
+ # NOTE: The "body" fill will NOT show up, because we override the `inner` block
+ # with a different slot. But the "new_slot" WILL show up.
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "slot_inside_block" %}
+ {% fill "body" %}
+ SLOT_BODY__OVERRIDEN
+ {% endfill %}
+ {% fill "new_slot" %}
+ SLOT_NEW__OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+ Helloodiddoo
+ SLOT_NEW__OVERRIDEN
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_inside_block(self, components_settings):
+ registry.register("slotted_component", gen_slotted_component())
+
+ @register("injectee")
+ class InjectComponent(Component):
+ template: types.django_html = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_using_template_file_extends_relative_file(self, components_settings):
+ @register("relative_file_component_using_template_file")
+ class RelativeFileComponentUsingTemplateFile(Component):
+ template_file = "relative_extends.html"
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "relative_file_component_using_template_file" %}{% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_component_using_get_template_name_extends_relative_file(self, components_settings):
+ @register("relative_file_component_using_get_template_name")
+ class RelativeFileComponentUsingGetTemplateName(Component):
+ def get_template_name(self, context):
+ return "relative_extends.html"
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "relative_file_component_using_get_template_name" %}{% endcomponent %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
diff --git a/tests/test_templatetags_provide.py b/tests/test_templatetags_provide.py
index 34a25ac0..347c697e 100644
--- a/tests/test_templatetags_provide.py
+++ b/tests/test_templatetags_provide.py
@@ -1,29 +1,40 @@
+import re
+
+import pytest
from django.template import Context, Template, TemplateSyntaxError
+from pytest_django.asserts import assertHTMLEqual
from django_components import Component, register, types
+from django_components.perfutil.provide import provide_cache, provide_references, all_reference_ids
-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})
-class ProvideTemplateTagTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_basic(self):
+@djc_test
+class TestProvideTemplateTag:
+ def _assert_clear_cache(self):
+ assert provide_cache == {}
+ assert provide_references == {}
+ assert all_reference_ids == set()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_basic(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -1015,15 +1889,15 @@ class ScopedSlotTest(BaseTestCase):
)
expected = """
-
attrs: {'@click.stop': "dispatch('click_event')", 'x-data': "{hello: 'world'}", 'class': 'padding-top-8'}
my_dict: {'one': 2}
@@ -361,13 +763,41 @@ class AggregateInputTests(BaseTestCase):
)
-class ComponentTemplateSyntaxErrorTests(BaseTestCase):
- def setUp(self):
- super().setUp()
- registry.register("test", SlottedComponent)
+@djc_test
+class TestRecursiveComponent:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_recursive_component(self, components_settings):
+ DEPTH = 100
- @parametrize_context_behavior(["django", "isolated"])
- def test_variable_outside_fill_tag_compiles_w_out_error(self):
+ @register("recursive")
+ class Recursive(Component):
+ class Defaults:
+ depth = 0
+
+ def get_template_data(self, args, kwargs, slots, context):
+ print("depth:", kwargs["depth"])
+ return {"depth": kwargs["depth"] + 1, "DEPTH": DEPTH}
+
+ template: types.django_html = """
+
+ depth: {{ depth }}
+ {% if depth <= DEPTH %}
+ {% component "recursive" depth=depth / %}
+ {% endif %}
+
+ """
+
+ result = Recursive.render()
+
+ for i in range(DEPTH):
+ assert f" depth: {i + 1} " in result
+
+
+@djc_test
+class TestComponentTemplateSyntaxError:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_variable_outside_fill_tag_compiles_w_out_error(self, components_settings):
+ registry.register("test", gen_slotted_component())
# As of v0.28 this is valid, provided the component registered under "test"
# contains a slot tag marked as 'default'. This is verified outside
# template compilation time.
@@ -379,8 +809,9 @@ class ComponentTemplateSyntaxErrorTests(BaseTestCase):
"""
Template(template_str)
- @parametrize_context_behavior(["django", "isolated"])
- def test_text_outside_fill_tag_is_not_error(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_text_outside_fill_tag_is_not_error_when_no_fill_tags(self, components_settings):
+ registry.register("test", gen_slotted_component())
# As of v0.28 this is valid, provided the component registered under "test"
# contains a slot tag marked as 'default'. This is verified outside
# template compilation time.
@@ -392,22 +823,31 @@ class ComponentTemplateSyntaxErrorTests(BaseTestCase):
"""
Template(template_str)
- @parametrize_context_behavior(["django", "isolated"])
- def test_nonfill_block_outside_fill_tag_is_error(self):
- with self.assertRaises(TemplateSyntaxError):
- template_str: types.django_html = """
- {% load component_tags %}
- {% component "test" %}
- {% if True %}
- {% fill "header" %}{% endfill %}
- {% endif %}
- {% endcomponent %}
- """
- Template(template_str)
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_text_outside_fill_tag_is_error_when_fill_tags(self, components_settings):
+ registry.register("test", gen_slotted_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% lorem 3 w random %}
+ {% fill "header" %}{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
- @parametrize_context_behavior(["django", "isolated"])
- def test_unclosed_component_is_error(self):
- with self.assertRaises(TemplateSyntaxError):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Illegal content passed to component 'test'. Explicit 'fill' tags cannot occur alongside other text"), # noqa: E501
+ ):
+ template.render(Context())
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_unclosed_component_is_error(self, components_settings):
+ registry.register("test", gen_slotted_component())
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Unclosed tag on line 3: 'component'"),
+ ):
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
diff --git a/tests/test_templatetags_extends.py b/tests/test_templatetags_extends.py
new file mode 100644
index 00000000..d668f1f3
--- /dev/null
+++ b/tests/test_templatetags_extends.py
@@ -0,0 +1,1026 @@
+"""Catch-all for tests that use template tags and don't fit other files"""
+
+from django.template import Context, Template
+from pytest_django.asserts import assertHTMLEqual
+
+from django_components import Component, register, registry, types
+
+from django_components.testing import djc_test
+from .testutils import PARAMETRIZE_CONTEXT_BEHAVIOR, setup_test_config
+
+setup_test_config({"autodiscover": False})
+
+
+def gen_slotted_component():
+ class SlottedComponent(Component):
+ template_file = "slotted_template.html"
+
+ return SlottedComponent
+
+
+def gen_blocked_and_slotted_component():
+ class BlockedAndSlottedComponent(Component):
+ template_file = "blocked_and_slotted_template.html"
+
+ return BlockedAndSlottedComponent
+
+
+def gen_component_inside_include():
+ class ComponentInsideInclude(Component):
+ template: types.django_html = """Hello
"""
+
+ class Media:
+ css = "style.css"
+ js = "script.js"
+
+ return ComponentInsideInclude
+
+
+#######################
+# TESTS
+#######################
+
+
+@djc_test
+class TestExtendsCompat:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_double_extends_on_main_template_and_component_one_component(self, components_settings):
+ registry.register("blocked_and_slotted_component", gen_blocked_and_slotted_component())
+
+ @register("extended_component")
+ class _ExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN 2
+ {% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+ SLOT OVERRIDEN 2
+ Default main
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ @register("second_extended_component")
+ class _SecondExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template.html" %}
+ {% block before_custom %}
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template_str: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% component "second_extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN 2
+ {% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+ SLOT OVERRIDEN 2
+ Default main
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ @register("second_extended_component")
+ class _SecondExtendedComponent(Component):
+ template: types.django_html = """
+ {% extends "blocked_and_slotted_template_2.html" %}
+ {% block before_custom %}
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% component "second_extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN 2
+ {% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+ SLOT OVERRIDEN 2
+ Default main
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+
+
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN 2
+ {% endfill %}
+ {% endcomponent %}
+
+
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ BLOCK OVERRIDEN
+ {% endblock %}
+ """
+
+ template: types.django_html = """
+ {% extends 'block.html' %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "slotted_component" %}
+ {% fill "main" %}
+ {% component "extended_component" %}
+ {% fill "header" %}
+ SLOT OVERRIDEN
+ {% endfill %}
+ {% endcomponent %}
+ {% endfill %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+
+ expected = """
+
+
+
+
+
+ Default header
+
+
+ SLOT OVERRIDEN
+ Default main
+
+
+
+
+
+
+ BLOCK OVERRIDEN
+
+ Variable:
+ Variable:
+
+
+ Variable:
+ Variable:
+
+ Hello
+ Hello
+ Hello
+
+
+ TEST
+
+
+
+
+ 58 giraffes and 2 pantaloons
+
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+ 58 giraffes and 2 pantaloons
+ 58 giraffes and 2 pantaloons
+ injected: {{ var|safe }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ var = self.inject("block_provide")
+ return {"var": var}
+
+ template: types.django_html = """
+ {% extends "block_in_component_provide.html" %}
+ {% load component_tags %}
+ {% block body %}
+ {% component "injectee" %}
+ {% endcomponent %}
+ {% endblock %}
+ """
+ rendered = Template(template).render(Context({"DJC_DEPS_STRATEGY": "ignore"}))
+ expected = """
+
+
+
+ injected: DepInject(hello='from_block')
+
+ BLOCK OVERRIDEN
+
+
+ BLOCK OVERRIDEN
+
+ injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=1 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -31,33 +42,35 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi', another=123)
+ injected: DepInject(key='hi', another=1)
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_basic_self_closing(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_basic_self_closing(self, components_settings):
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 / %}
+ {% provide "my_provide" key="hi" another=2 / %}
"""
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_access_keys_in_python(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_access_keys_in_python(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
@@ -65,7 +78,7 @@ class ProvideTemplateTagTest(BaseTestCase):
another: {{ another }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
my_provide = self.inject("my_provide")
return {
"key": my_provide.key,
@@ -74,7 +87,7 @@ class ProvideTemplateTagTest(BaseTestCase):
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=3 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -82,16 +95,17 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- key: hi
- another: 123
+ key: hi
+ another: 3
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_access_keys_in_django(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_access_keys_in_django(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
@@ -99,7 +113,7 @@ class ProvideTemplateTagTest(BaseTestCase):
another: {{ my_provide.another }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
my_provide = self.inject("my_provide")
return {
"my_provide": my_provide,
@@ -107,7 +121,7 @@ class ProvideTemplateTagTest(BaseTestCase):
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=4 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -115,29 +129,30 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- key: hi
- another: 123
+ key: hi
+ another: 4
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_does_not_leak(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_does_not_leak(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=5 %}
{% endprovide %}
{% component "injectee" %}
{% endcomponent %}
@@ -145,15 +160,16 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: default
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_empty(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_empty(self, components_settings):
"""Check provide tag with no kwargs"""
@register("injectee")
@@ -162,7 +178,7 @@ class ProvideTemplateTagTest(BaseTestCase):
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
@@ -178,15 +194,16 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject()
- injected: default
+ injected: DepInject()
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
+ @djc_test(components_settings={"context_behavior": "django"})
def test_provide_no_inject(self):
"""Check that nothing breaks if we do NOT inject even if some data is provided"""
@@ -196,12 +213,9 @@ class ProvideTemplateTagTest(BaseTestCase):
"""
- def get_context_data(self):
- return {}
-
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=6 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -211,29 +225,30 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
-
+
+
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_name_single_quotes(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_name_single_quotes(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide 'my_provide' key="hi" another=123 %}
+ {% provide 'my_provide' key="hi" another=7 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -243,29 +258,30 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi', another=123)
- injected: default
+ injected: DepInject(key='hi', another=7)
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_name_as_var(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_name_as_var(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide var_a key="hi" another=123 %}
+ {% provide var_a key="hi" another=8 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -281,23 +297,24 @@ class ProvideTemplateTagTest(BaseTestCase):
)
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi', another=123)
- injected: default
+ injected: DepInject(key='hi', another=8)
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_name_as_spread(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_name_as_spread(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
@@ -317,83 +334,94 @@ class ProvideTemplateTagTest(BaseTestCase):
"provide_props": {
"name": "my_provide",
"key": "hi",
- "another": 123,
+ "another": 9,
},
}
)
)
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi', another=123)
- injected: default
+ injected: DepInject(key='hi', another=9)
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_no_name_raises(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_no_name_raises(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide key="hi" another=123 %}
+ {% provide key="hi" another=10 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
{% component "injectee" %}
{% endcomponent %}
"""
- with self.assertRaisesMessage(RuntimeError, "Provide tag kwarg 'name' is missing"):
+ with pytest.raises(
+ TypeError,
+ match=re.escape("Invalid parameters for tag 'provide': missing a required argument: 'name'"),
+ ):
Template(template_str).render(Context({}))
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_name_must_be_string_literal(self):
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_name_must_be_string_literal(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide my_var key="hi" another=123 %}
+ {% provide my_var key="hi" another=11 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
{% component "injectee" %}
{% endcomponent %}
"""
- with self.assertRaisesMessage(RuntimeError, "Provide tag kwarg 'name' is missing"):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Provide tag received an empty string. Key must be non-empty and a valid identifier"),
+ ):
Template(template_str).render(Context({}))
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_name_must_be_identifier(self):
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_name_must_be_identifier(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "%heya%" key="hi" another=123 %}
+ {% provide "%heya%" key="hi" another=12 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -401,24 +429,26 @@ class ProvideTemplateTagTest(BaseTestCase):
{% endcomponent %}
"""
template = Template(template_str)
- with self.assertRaises(TemplateSyntaxError):
- template.render(Context({}))
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_aggregate_dics(self):
+ with pytest.raises(TemplateSyntaxError):
+ template.render(Context({}))
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_aggregate_dics(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" var1:key="hi" var1:another=123 var2:x="y" %}
+ {% provide "my_provide" var1:key="hi" var1:another=13 var2:x="y" %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -426,15 +456,16 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(var1={'key': 'hi', 'another': 123}, var2={'x': 'y'})
+ injected: DepInject(var1={'key': 'hi', 'another': 13}, var2={'x': 'y'})
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_does_not_expose_kwargs_to_context(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_does_not_expose_kwargs_to_context(self, components_settings):
"""Check that `provide` tag doesn't assign the keys to the context like `with` tag does"""
@register("injectee")
@@ -443,7 +474,7 @@ class ProvideTemplateTagTest(BaseTestCase):
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
@@ -451,7 +482,7 @@ class ProvideTemplateTagTest(BaseTestCase):
{% load component_tags %}
var_out: {{ var }}
key_out: {{ key }}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=14 %}
var_in: {{ var }}
key_in: {{ key }}
{% endprovide %}
@@ -459,7 +490,7 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({"var": "123"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
var_out: 123
@@ -468,9 +499,10 @@ class ProvideTemplateTagTest(BaseTestCase):
key_in:
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_nested_in_provide_same_key(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_nested_in_provide_same_key(self, components_settings):
"""Check that inner `provide` with same key overshadows outer `provide`"""
@register("injectee")
@@ -479,14 +511,14 @@ class ProvideTemplateTagTest(BaseTestCase):
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 lost=0 %}
- {% provide "my_provide" key="hi1" another=1231 new=3 %}
+ {% provide "my_provide" key="hi" another=15 lost=0 %}
+ {% provide "my_provide" key="hi1" another=16 new=3 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -500,17 +532,19 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi1', another=1231, new=3)
- injected: DepInject(key='hi', another=123, lost=0)
- injected: default
+ injected: DepInject(key='hi1', another=16, new=3)
+ injected: DepInject(key='hi', another=15, lost=0)
+ injected: default
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_nested_in_provide_different_key(self):
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_nested_in_provide_different_key(self, components_settings):
"""Check that `provide` tag with different keys don't affect each other"""
@register("injectee")
@@ -520,7 +554,7 @@ class ProvideTemplateTagTest(BaseTestCase):
second_provide: {{ second_provide|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
first_provide = self.inject("first_provide", "default")
second_provide = self.inject("second_provide", "default")
return {
@@ -530,8 +564,8 @@ class ProvideTemplateTagTest(BaseTestCase):
template_str: types.django_html = """
{% load component_tags %}
- {% provide "first_provide" key="hi" another=123 lost=0 %}
- {% provide "second_provide" key="hi1" another=1231 new=3 %}
+ {% provide "first_provide" key="hi" another=17 lost=0 %}
+ {% provide "second_provide" key="hi1" another=18 new=3 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -540,53 +574,55 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- first_provide: DepInject(key='hi', another=123, lost=0)
- second_provide: DepInject(key='hi1', another=1231, new=3)
+ first_provide: DepInject(key='hi', another=17, lost=0)
+ second_provide: DepInject(key='hi1', another=18, new=3)
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_provide_in_include(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_provide_in_include(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=19 %}
{% include "inject.html" %}
{% endprovide %}
"""
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_in_provide(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_in_provide(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: DepInject(key='hi', another=123)
+ injected: DepInject(key='hi', another=19)
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide", "default")
return {"var": var}
@@ -594,7 +630,7 @@ class ProvideTemplateTagTest(BaseTestCase):
class ParentComponent(Component):
template: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=20 %}
{% slot "content" default %}{% endslot %}
{% endprovide %}
"""
@@ -608,32 +644,39 @@ class ProvideTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
- injected: DepInject(key='hi', another=123)
+
+ {% slot "content" default / %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ data = self.inject("my_provide")
+ return {"data": data}
+
+ @register("provider")
+ class Provider(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" data=data %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+ @register("parent")
+ class Parent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "provider" data=data %}
+ {% component "injectee" %}
+ {% slot "content" default / %}
+ {% endcomponent %}
+ {% endcomponent %}
+ """
+
+ @register("root")
+ class Root(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "parent" data=123 %}
+ {% fill "content" %}
+ 456
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Root.render()
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+ 456
+
+ """,
+ )
+ self._assert_clear_cache()
+
+ # See https://github.com/django-components/django-components/pull/786
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_in_slot_in_fill(self, components_settings):
+ @register("injectee")
+ class Injectee(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "content" default / %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ data = self.inject("my_provide")
+ return {"data": data}
+
+ @register("provider")
+ class Provider(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" data=data %}
+ {% slot "content" default / %}
+ {% endprovide %}
+ """
+
+ @register("parent")
+ class Parent(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"data": kwargs["data"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "provider" data=data %}
+ {% slot "content" default / %}
+ {% endcomponent %}
+ """
+
+ @register("root")
+ class Root(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "parent" data=123 %}
+ {% component "injectee" / %}
+ {% endcomponent %}
+ """
+
+ rendered = Root.render()
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+
+ """,
+ )
+ self._assert_clear_cache()
+
+
+# When there is `{% component %}` that's a descendant of `{% provide %}`,
+# then the cache entry is NOT removed as soon as we have rendered the children (nodelist)
+# of `{% provide %}`.
+#
+# Instead, we manage the state ourselves, and remove the cache entry
+# when the component rendered is done.
+@djc_test
+class TestProvideCache:
+ def _assert_clear_cache(self):
+ assert provide_cache == {}
+ assert provide_references == {}
+ assert all_reference_ids == set()
+
+ def test_provide_outside_component(self):
+ @register("injectee")
+ class Injectee(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
- {% slot "header" %}Default header{% endslot %}
- {% slot "main" %}Default main{% endslot %}
-
-
- """
-
-
-class SlottedComponentWithContext(SlottedComponent):
- def get_context_data(self, variable):
- return {"variable": variable}
-
+def _gen_slotted_component():
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+ return SlottedComponent
#######################
# TESTS
#######################
-class ComponentSlottedTemplateTagTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_slotted_template_basic(self):
- registry.register(name="test1", component=SlottedComponent)
+@djc_test
+class TestComponentSlot:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slotted_template_basic(self, components_settings):
+ registry.register(name="test1", component=_gen_slotted_component())
@register("test2")
class SimpleComponent(Component):
template = """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:
@@ -64,19 +64,21 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Custom header
- Variable: variable
+
+ Variable: variable
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slotted_template_basic_self_closing(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slotted_template_basic_self_closing(self, components_settings):
@register("test1")
class SlottedComponent(Component):
template: types.django_html = """
@@ -94,10 +96,10 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
class SimpleComponent(Component):
template = """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"),
}
template_str: types.django_html = """
@@ -114,11 +116,13 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
rendered = template.render(Context({}))
# NOTE: is empty, because the fill is provided, even if empty
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
- Variable: variable
+
+
+ Variable: variable
+
@@ -126,9 +130,30 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
)
# NOTE: Second arg is the expected output of `{{ variable }}`
- @parametrize_context_behavior([("django", "test456"), ("isolated", "")])
- def test_slotted_template_with_context_var(self, context_behavior_data):
- registry.register(name="test1", component=SlottedComponentWithContext)
+ @djc_test(
+ parametrize=(
+ ["components_settings", "expected"],
+ [
+ [{"context_behavior": "django"}, "test456"],
+ [{"context_behavior": "isolated"}, ""],
+ ],
+ ["django", "isolated"],
+ )
+ )
+ def test_slotted_template_with_context_var(self, components_settings, expected):
+ @register("test1")
+ class SlottedComponentWithContext(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"variable": kwargs["variable"]}
template_str: types.django_html = """
{% load component_tags %}
@@ -146,20 +171,20 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({"my_second_variable": "test321"}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
f"""
-
+
Default header
- test123 - {context_behavior_data}
+ test123 - {expected}
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slotted_template_no_slots_filled(self):
- registry.register(name="test", component=SlottedComponent)
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slotted_template_no_slots_filled(self, components_settings):
+ registry.register(name="test", component=_gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
@@ -168,10 +193,10 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Default header
Default main
@@ -179,8 +204,8 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slotted_template_without_slots(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slotted_template_without_slots(self, components_settings):
@register("test")
class SlottedComponentNoSlots(Component):
template: types.django_html = """
@@ -194,10 +219,10 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, "
+
Hi there!
Default main
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_missing_required_slot_raises_error(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_missing_required_slot_raises_error(self, components_settings):
class Comp(Component):
template: types.django_html = """
{% load component_tags %}
@@ -255,11 +280,293 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
"""
template = Template(template_str)
- with self.assertRaises(TemplateSyntaxError):
- template.render(Context({}))
+ with pytest.raises(TemplateSyntaxError, match=re.escape("Slot 'title' is marked as 'required'")):
+ template.render(Context())
- @parametrize_context_behavior(["django", "isolated"])
- def test_default_slot_is_fillable_by_implicit_fill_content(self):
+ # NOTE: This is relevant only for the "isolated" mode
+ @djc_test(components_settings={"context_behavior": "isolated"})
+ def test_slots_of_top_level_comps_can_access_full_outer_ctx(self):
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ ")
+ assertHTMLEqual(rendered2, "")
+
+ # 3. Specify the required slot by its name
+ rendered3 = TestComp.render(
+ kwargs={"required": True},
+ slots={
+ "main": "MAIN",
+ },
+ deps_strategy="ignore",
+ )
+ assertHTMLEqual(rendered3, "MAIN ")
+
+ # 4. RAISES: Specify the required slot by the "default" name
+ # This raises because the slot that is marked as 'required' is NOT marked as 'default'.
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Slot 'main' is marked as 'required'"),
+ ):
+ TestComp.render(
+ kwargs={"required": True},
+ slots={
+ "default": "MAIN",
+ },
+ deps_strategy="ignore",
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_in_include(self, components_settings):
+ @register("slotted")
+ class SlottedWithIncludeComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% include 'slotted_template.html' %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "slotted" %}
+ {% fill "header" %}Custom header{% endfill %}
+ {% fill "main" %}Custom main{% endfill %}
+ {% fill "footer" %}Custom footer{% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context({}))
+
+ expected = """
+
+ Custom header
+ Custom main
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_in_include_raises_if_isolated(self, components_settings):
+ @register("broken_component")
+ class BrokenComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% include 'slotted_template.html' with context=None only %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "broken_component" %}
+ {% fill "header" %}Custom header {% endfill %}
+ {% fill "main" %}Custom main{% endfill %}
+ {% fill "footer" %}Custom footer{% endfill %}
+ {% endcomponent %}
+ """
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Encountered a SlotNode outside of a Component context."),
+ ):
+ Template(template_str).render(Context({}))
+
+
+@djc_test
+class TestComponentSlotDefault:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_default_slot_is_fillable_by_implicit_fill_content(self, components_settings):
@register("test_comp")
class ComponentWithDefaultSlot(Component):
template: types.django_html = """
@@ -278,15 +585,17 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
template = Template(template_str)
expected = """
-
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -976,11 +1850,11 @@ class ScopedSlotTest(BaseTestCase):
{% endcomponent %}
"""
rendered = Template(template).render(Context())
- expected = "
+ injected: DepInject(key='hi', another=20)
""",
)
+ self._assert_clear_cache()
-class InjectTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_basic(self):
+@djc_test
+class TestInject:
+ def _assert_clear_cache(self):
+ assert provide_cache == {}
+ assert provide_references == {}
+ assert all_reference_ids == set()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_basic(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("my_provide")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=21 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -641,22 +684,23 @@ class InjectTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: DepInject(key='hi', another=123)
+ injected: DepInject(key='hi', another=21)
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_missing_key_raises_without_default(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_missing_key_raises_without_default(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("abc")
return {"var": var}
@@ -667,18 +711,20 @@ class InjectTest(BaseTestCase):
"""
template = Template(template_str)
- with self.assertRaises(KeyError):
+ with pytest.raises(KeyError):
template.render(Context({}))
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_missing_key_ok_with_default(self):
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_missing_key_ok_with_default(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("abc", "default")
return {"var": var}
@@ -689,28 +735,29 @@ class InjectTest(BaseTestCase):
"""
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- injected: default
+ injected: default
""",
)
+ self._assert_clear_cache()
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_empty_string(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_empty_string(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("")
return {"var": var}
template_str: types.django_html = """
{% load component_tags %}
- {% provide "my_provide" key="hi" another=123 %}
+ {% provide "my_provide" key="hi" another=22 %}
{% component "injectee" %}
{% endcomponent %}
{% endprovide %}
@@ -719,21 +766,313 @@ class InjectTest(BaseTestCase):
"""
template = Template(template_str)
- with self.assertRaises(KeyError):
+ with pytest.raises(KeyError):
template.render(Context({}))
- @parametrize_context_behavior(["django", "isolated"])
- def test_inject_raises_on_called_outside_get_context_data(self):
+ self._assert_clear_cache()
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_called_outside_rendering(self, components_settings):
@register("injectee")
class InjectComponent(Component):
template: types.django_html = """
injected: {{ var|safe }}
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
var = self.inject("abc", "default")
return {"var": var}
- comp = InjectComponent("")
- with self.assertRaises(RuntimeError):
- comp.inject("abc", "def")
+ comp = InjectComponent()
+ comp.inject("abc", "def")
+
+ self._assert_clear_cache()
+
+ # See https://github.com/django-components/django-components/pull/778
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_inject_in_fill(self, components_settings):
+ @register("injectee")
+ class Injectee(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ injected: {{ data|safe }}
+
+ injected: DepInject(key='hi', data=123)
+
+ injected: {{ data|safe }}
+
+ injected: DepInject(key='hi', data=123)
+
+ injected: {{ data|safe }}
+ Ran: {{ ran }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert len(provide_cache) == 1
+
+ data = self.inject("my_provide")
+ return {"data": data, "ran": True}
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" another=23 %}
+ {% component "injectee" / %}
+ {% endprovide %}
+ """
+
+ self._assert_clear_cache()
+
+ template = Template(template_str)
+ self._assert_clear_cache()
+
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+ injected: DepInject(key='hi', another=23)
+
+
+ Ran: True
+
+ """,
+ )
+ self._assert_clear_cache()
+
+ # Cache should be cleared even if there is an error.
+ def test_provide_outside_component_with_error(self):
+
+ @register("injectee")
+ class Injectee(Component):
+ template = ""
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert len(provide_cache) == 1
+ data = self.inject("my_provide")
+
+ raise ValueError("Oops")
+ return {"data": data, "ran": True}
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" another=24 %}
+ {% component "injectee" / %}
+ {% endprovide %}
+ """
+
+ self._assert_clear_cache()
+
+ template = Template(template_str)
+ self._assert_clear_cache()
+
+ with pytest.raises(ValueError, match=re.escape("Oops")):
+ template.render(Context({}))
+
+ self._assert_clear_cache()
+
+ def test_provide_inside_component(self):
+ @register("injectee")
+ class Injectee(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ injected: {{ data|safe }}
+ Ran: {{ ran }}
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert len(provide_cache) == 1
+
+ data = self.inject("my_provide")
+ return {"data": data, "ran": True}
+
+ @register("root")
+ class Root(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" another=25 %}
+ {% component "injectee" / %}
+ {% endprovide %}
+ """
+
+ self._assert_clear_cache()
+
+ rendered = Root.render()
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+ injected: DepInject(key='hi', another=25)
+
+
+ Ran: True
+
+ """,
+ )
+ self._assert_clear_cache()
+
+ def test_provide_inside_component_with_error(self):
+ @register("injectee")
+ class Injectee(Component):
+ template = ""
+
+ def get_template_data(self, args, kwargs, slots, context):
+ assert len(provide_cache) == 1
+
+ data = self.inject("my_provide")
+ raise ValueError("Oops")
+ return {"data": data, "ran": True}
+
+ @register("root")
+ class Root(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% provide "my_provide" key="hi" another=26 %}
+ {% component "injectee" / %}
+ {% endprovide %}
+ """
+
+ self._assert_clear_cache()
+
+ with pytest.raises(ValueError, match=re.escape("Oops")):
+ Root.render()
+
+ self._assert_clear_cache()
diff --git a/tests/test_templatetags_slot_fill.py b/tests/test_templatetags_slot_fill.py
index 37bdc16c..ffa57d90 100644
--- a/tests/test_templatetags_slot_fill.py
+++ b/tests/test_templatetags_slot_fill.py
@@ -1,49 +1,49 @@
-from typing import Any, Dict, List, Optional
+import re
+from typing import Dict
+import pytest
from django.template import Context, Template, TemplateSyntaxError
+from pytest_django.asserts import assertHTMLEqual
-from django_components import Component, register, registry, types
+from django_components import Component, Slot, register, registry, types
-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})
-class SlottedComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
-
+ {% slot "main" default %}Easy to override{% endslot %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "name": kwargs.get("name", None),
+ }
+
+ registry.register("test", SlottedComponent)
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+
+ {% component "test" %}
+ ABC: {{ name }} {{ some }}
+ {% endcomponent %}
+
+ """
+ self.template = Template(template_str)
+
+ nested_ctx = Context({"DJC_DEPS_STRATEGY": "ignore"})
+ # Check that the component can access vars across different context layers
+ nested_ctx.push({"some": "var"})
+ nested_ctx.push({"name": "carl"})
+ rendered = self.template.render(nested_ctx)
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+
+ ABC: carl var
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_target_default_slot_as_named(self, components_settings):
+ @register("test")
+ class Comp(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' %}
+ {% fill "default" %}Custom title{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ rendered = template.render(Context())
+ assertHTMLEqual(
+ rendered,
+ """
+ {% slot "title" default %}Default title{% endslot %}
+{% slot "subtitle" %}Default subtitle{% endslot %}
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_doubly_filled_slot__same_name(self, components_settings):
+ @register("test")
+ class Comp(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ Custom title
+Default subtitle
+
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' %}
+ {% fill "title" %}Custom title{% endfill %}
+ {% fill "title" %}Another title{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape(
+ "Multiple fill tags cannot target the same slot name in component 'test': "
+ "Detected duplicate fill tag name 'title'"
+ ),
+ ):
+ template.render(Context())
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_doubly_filled_slot__named_and_default(self, components_settings):
+ @register("test")
+ class Comp(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "title" default %}Default title{% endslot %}
+{% slot "subtitle" %}Default subtitle{% endslot %}
+
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' %}
+ {% fill "default" %}Custom title{% endfill %}
+ {% fill "title" %}Another title{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape(
+ "Slot 'title' of component 'test' was filled twice: once explicitly and once implicitly as 'default'"
+ ),
+ ):
+ template.render(Context())
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_raises_on_doubly_filled_slot__named_and_default_2(self, components_settings):
+ @register("test")
+ class Comp(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "title" default %}Default title{% endslot %}
+{% slot "subtitle" %}Default subtitle{% endslot %}
+
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test' %}
+ {% fill "default" %}Custom title{% endfill %}
+ {% fill "default" %}Another title{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape(
+ "Multiple fill tags cannot target the same slot name in component 'test': "
+ "Detected duplicate fill tag name 'default'"
+ ),
+ ):
+ template.render(Context())
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_multiple_slots_with_same_name_different_flags(self, components_settings):
+ class TestComp(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"required": kwargs["required"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "default" default %}Default title{% endslot %}
+{% slot "subtitle" %}Default subtitle{% endslot %}
+
+ {% if required %}
+ {% slot "main" required %}1{% endslot %}
+ {% endif %}
+
+ """
+
+ # 1. Specify the non-required slot by its name
+ rendered1 = TestComp.render(
+ kwargs={"required": False},
+ slots={
+ "main": "MAIN",
+ },
+ deps_strategy="ignore",
+ )
+
+ # 2. Specify the non-required slot by the "default" name
+ rendered2 = TestComp.render(
+ kwargs={"required": False},
+ slots={
+ "default": "MAIN",
+ },
+ deps_strategy="ignore",
+ )
+
+ assertHTMLEqual(rendered1, "{% slot "main" default %}2{% endslot %}
+ MAIN
MAIN
MAIN
-
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -927,11 +1801,11 @@ class ScopedSlotTest(BaseTestCase):
{% endcomponent %}
"""
rendered = Template(template).render(Context())
- expected = "This fills the 'main' slot.
+
+
"""
rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_default_slot_is_fillable_by_explicit_fill_content(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_default_slot_is_fillable_by_explicit_fill_content(self, components_settings):
@register("test_comp")
class ComponentWithDefaultSlot(Component):
template: types.django_html = """
@@ -304,15 +613,73 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
"""
template = Template(template_str)
expected = """
- This fills the 'main' slot.
+
-
+ Default header
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_implicit_fill_when_slot_marked_default_not_rendered(self, components_settings):
+ @register("test_comp")
+ class ConditionalSlotted(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {"var": kwargs["var"]}
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% if var %}
+ {% slot "header" default %}Default header{% endslot %}
+ {% endif %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test_comp' var=var %}
+ 123
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ rendered_truthy = template.render(Context({"var": True}))
+ assertHTMLEqual(
+ rendered_truthy,
+ """
+
+ 123
+ Default main
+
+
+ """,
+ )
+
+ rendered_falsy = template.render(Context({"var": False}))
+ assertHTMLEqual(
+ rendered_falsy,
+ """
+
+ Default main
+
+
""",
)
-class SlottedTemplateRegressionTests(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_slotted_template_that_uses_missing_variable(self):
+@djc_test
+class TestPassthroughSlots:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_if_for(self, components_settings):
+ @register("test")
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "name": kwargs.get("name", None),
+ }
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% if slot_names %}
+ {% for slot in slot_names %}
+ {% fill name=slot fallback="fallback" %}
+ OVERRIDEN_SLOT "{{ slot }}" - INDEX {{ forloop.counter0 }} - ORIGINAL "{{ fallback }}"
+ {% endfill %}
+ {% endfor %}
+ {% endif %}
+
+ {% if 1 > 2 %}
+ {% fill "footer" %}
+ FOOTER
+ {% endfill %}
+ {% endif %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ rendered = template.render(Context({"slot_names": ["header", "main"]}))
+ assertHTMLEqual(
+ rendered,
+ """
+
+
+ OVERRIDEN_SLOT "header" - INDEX 0 - ORIGINAL "Default header"
+
+
+ OVERRIDEN_SLOT "main" - INDEX 1 - ORIGINAL "Default main"
+
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_with(self, components_settings):
+ @register("test")
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "name": kwargs.get("name", None),
+ }
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% with slot="header" %}
+ {% fill name=slot fallback="fallback" %}
+ OVERRIDEN_SLOT "{{ slot }}" - ORIGINAL "{{ fallback }}"
+ {% endfill %}
+ {% endwith %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ rendered = template.render(Context())
+ assertHTMLEqual(
+ rendered,
+ """
+
+
+ OVERRIDEN_SLOT "header" - ORIGINAL "Default header"
+
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_if_for_raises_on_content_outside_fill(self, components_settings):
+ @register("test")
+ class SlottedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "header" %}Default header{% endslot %}
+ {% slot "main" %}Default main{% endslot %}
+
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "name": kwargs.get("name", None),
+ }
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% if slot_names %}
+ {% for slot in slot_names %}
+ {{ forloop.counter0 }}
+ {% fill name=slot fallback="fallback" %}
+ OVERRIDEN_SLOT
+ {% endfill %}
+ {% endfor %}
+ {% endif %}
+
+ {% if 1 > 2 %}
+ {% fill "footer" %}
+ FOOTER
+ {% endfill %}
+ {% endif %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape("Illegal content passed to component 'test'"),
+ ):
+ template.render(Context({"slot_names": ["header", "main"]}))
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slots_inside_loops(self, components_settings):
+ @register("test_comp")
+ class OuterComp(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "slots": ["header", "main", "footer"],
+ }
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% for slot_name in slots %}
+
+
Default header
Default main
@@ -556,13 +1364,13 @@ class SlottedTemplateRegressionTests(BaseTestCase):
)
-class SlotDefaultTests(BaseTestCase):
- def setUp(self):
- super().setUp()
- registry.register("test", SlottedComponent)
+@djc_test
+class TestSlotFallback:
- @parametrize_context_behavior(["django", "isolated"])
- def test_basic(self):
+ # TODO_v1 - REMOVE
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_basic_legacy(self, components_settings):
+ registry.register("test", _gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
@@ -574,10 +1382,10 @@ class SlotDefaultTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
Before: Default header
Default main
@@ -585,12 +1393,38 @@ class SlotDefaultTests(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_multiple_calls(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_basic(self, components_settings):
+ registry.register("test", _gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
- {% fill "header" default="header" %}
+ {% fill "header" fallback="header" %}Before: {{ header }}{% endfill %}
+ {% fill "main" fallback="main" %}{{ main }}{% endfill %}
+ {% fill "footer" fallback="footer" %}{{ footer }}, after{% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context({}))
+
+ assertHTMLEqual(
+ rendered,
+ """
+
+ Before: Default header
+ Default main
+
+
+ """,
+ )
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_multiple_calls(self, components_settings):
+ registry.register("test", _gen_slotted_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill "header" fallback="header" %}
First: {{ header }};
Second: {{ header }}
{% endfill %}
@@ -599,10 +1433,10 @@ class SlotDefaultTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
First: Default header; Second: Default header
Default main
@@ -610,12 +1444,13 @@ class SlotDefaultTests(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_under_if_and_forloop(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_under_if_and_forloop(self, components_settings):
+ registry.register("test", _gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
- {% fill "header" default="header" %}
+ {% fill "header" fallback="header" %}
{% for i in range %}
{% if forloop.first %}
First {{ header }}
@@ -629,10 +1464,10 @@ class SlotDefaultTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({"range": range(3)}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
First Default header Later Default header Later Default header
Default main
@@ -640,19 +1475,20 @@ class SlotDefaultTests(BaseTestCase):
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_nested_fills(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_fills(self, components_settings):
+ registry.register("test", _gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
{% component "test" %}
- {% fill "header" default="header1" %}
+ {% fill "header" fallback="header1" %}
header1_in_header1: {{ header1 }}
{% component "test" %}
- {% fill "header" default="header2" %}
+ {% fill "header" fallback="header2" %}
header1_in_header2: {{ header1 }}
header2_in_header2: {{ header2 }}
{% endfill %}
- {% fill "footer" default="footer2" %}
+ {% fill "footer" fallback="footer2" %}
header1_in_footer2: {{ header1 }}
footer2_in_footer2: {{ footer2 }}
{% endfill %}
@@ -663,13 +1499,13 @@ class SlotDefaultTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
header1_in_header1: Default header
-
+
header1_in_header2: Default header
header2_in_header2: Default header
@@ -688,9 +1524,10 @@ class SlotDefaultTests(BaseTestCase):
)
-class ScopedSlotTest(BaseTestCase):
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data(self):
+@djc_test
+class TestScopedSlot:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -700,7 +1537,7 @@ class ScopedSlotTest(BaseTestCase):
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -717,15 +1554,15 @@ class ScopedSlotTest(BaseTestCase):
"""
rendered = Template(template).render(Context())
expected = """
- This fills the 'main' slot.
+
+
"""
rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_error_raised_when_default_and_required_slot_not_filled(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_multiple_default_slots_with_same_name(self, components_settings):
+ @register("test_comp")
+ class ComponentWithDefaultSlot(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ This fills the 'main' slot.
+
+ {% slot "main" default %}1{% endslot %}
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test_comp' %}
+ {% fill "main" %}{% slot "main" default %}2{% endslot %}
+ This fills the 'main' slot.
{% endfill %} + {% endcomponent %} + """ + template = Template(template_str) + expected = """ +
+
+ """
+ rendered = template.render(Context({}))
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_multiple_default_slots_with_different_names(self, components_settings):
+ @register("test_comp")
+ class ComponentWithDefaultSlot(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ This fills the 'main' slot.
This fills the 'main' slot.
+ {% slot "main" default %}1{% endslot %}
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'test_comp' %}
+ {% fill "main" %}{% slot "other" default %}2{% endslot %}
+ This fills the 'main' slot.
{% endfill %} + {% endcomponent %} + """ + template = Template(template_str) + + with pytest.raises( + TemplateSyntaxError, + match=re.escape( + "Only one component slot may be marked as 'default', found 'main' and 'other'" + ), + ): + template.render(Context({})) + + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_error_raised_when_default_and_required_slot_not_filled(self, components_settings): @register("test_comp") class ComponentWithDefaultAndRequiredSlot(Component): template: types.django_html = """ @@ -330,12 +697,15 @@ class ComponentSlottedTemplateTagTest(BaseTestCase): """ template = Template(template_str) - with self.assertRaises(TemplateSyntaxError): - template.render(Context({})) + with pytest.raises( + TemplateSyntaxError, + match=re.escape("Slot 'main' is marked as 'required'"), + ): + template.render(Context()) - @parametrize_context_behavior(["django", "isolated"]) - def test_fill_tag_can_occur_within_component_nested_in_implicit_fill(self): - registry.register("slotted", SlottedComponent) + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_fill_tag_can_occur_within_component_nested_in_implicit_fill(self, components_settings): + registry.register("slotted", _gen_slotted_component()) @register("test_comp") class ComponentWithDefaultSlot(Component): @@ -358,21 +728,21 @@ class ComponentSlottedTemplateTagTest(BaseTestCase): """ template = Template(template_str) expected = """ -
-
-
- This Is Allowed
-
-
-
-
+
"""
- with self.assertRaises(TemplateSyntaxError):
+ with pytest.raises(
+ TemplateSyntaxError,
+ match=re.escape(
+ "Illegal content passed to component 'test_comp'. Explicit 'fill' tags cannot occur alongside other text" # noqa: E501
+ ),
+ ):
template_str: types.django_html = """
{% load component_tags %}
{% component 'test_comp' %}
@@ -390,10 +765,10 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
+
+
+ This Is Allowed
+
+
+
+
"""
rendered = template.render(Context({}))
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_error_from_mixed_implicit_and_explicit_fill_content(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_error_from_mixed_implicit_and_explicit_fill_content(self, components_settings):
@register("test_comp")
class ComponentWithDefaultSlot(Component):
template: types.django_html = """
@@ -382,7 +752,12 @@ class ComponentSlottedTemplateTagTest(BaseTestCase):
And add this too!
{% endcomponent %} """ - Template(template_str) + Template(template_str).render(Context({})) - @parametrize_context_behavior(["django", "isolated"]) - def test_comments_permitted_inside_implicit_fill_content(self): + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_comments_permitted_inside_implicit_fill_content(self, components_settings): @register("test_comp") class ComponentWithDefaultSlot(Component): template: types.django_html = """ @@ -413,118 +788,551 @@ class ComponentSlottedTemplateTagTest(BaseTestCase): {# Nor will this #} {% endcomponent %} """ - Template(template_str) - self.assertTrue(True) + rendered = Template(template_str).render(Context()) + assertHTMLEqual( + rendered, + """ +
+
+ """,
+ )
- @parametrize_context_behavior(["django", "isolated"])
- def test_component_without_default_slot_refuses_implicit_fill(self):
- registry.register("test_comp", SlottedComponent)
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_implicit_fill_when_no_slot_marked_default(self, components_settings):
+ registry.register("test_comp", _gen_slotted_component())
template_str: types.django_html = """
{% load component_tags %}
{% component 'test_comp' %}
- Main Content
This shouldn't work because the included component doesn't mark - any of its slots as 'default'
+Component with no 'default' slot still accepts the fill, it just won't render it
{% endcomponent %} """ template = Template(template_str) - - with self.assertRaises(TemplateSyntaxError): - template.render(Context({})) - - @parametrize_context_behavior(["django", "isolated"]) - def test_component_template_cannot_have_multiple_default_slots(self): - class BadComponent(Component): - def get_template(self, context, template_name: Optional[str] = None) -> Template: - template_str: types.django_html = """ - {% load django_components %} -
- {% slot "icon" %} {% endslot default %}
- {% slot "description" %} {% endslot default %}
-
- """
- return Template(template_str)
-
- c = BadComponent("name")
-
- with self.assertRaises(TemplateSyntaxError):
- c.render(Context({}))
-
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_name_fill_typo_gives_helpful_error_message(self):
- registry.register(name="test1", component=SlottedComponent)
-
- template_str: types.django_html = """
- {% load component_tags %}
- {% component "test1" %}
- {% fill "haeder" %}
- Custom header
- {% endfill %}
- {% fill "main" %}
- main content
- {% endfill %}
- {% endcomponent %}
- """
- template = Template(template_str)
-
- with self.assertRaisesMessage(
- TemplateSyntaxError,
- (
- "Component 'test1' passed fill that refers to undefined slot: 'haeder'.\\n"
- "Unfilled slot names are: ['footer', 'header'].\\n"
- "Did you mean 'header'?"
- ),
- ):
- template.render(Context({}))
-
- # NOTE: This is relevant only for the "isolated" mode
- @parametrize_context_behavior(["isolated"])
- def test_slots_of_top_level_comps_can_access_full_outer_ctx(self):
- class SlottedComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
-
- {% slot "main" default %}Easy to override{% endslot %}
-
- """
-
- def get_context_data(self, name: Optional[str] = None) -> Dict[str, Any]:
- return {
- "name": name,
- }
-
- registry.register("test", SlottedComponent)
-
- template_str: types.django_html = """
- {% load component_tags %}
-
- {% component "test" %}
- ABC: {{ name }} {{ some }}
- {% endcomponent %}
-
- """
- self.template = Template(template_str)
-
- nested_ctx = Context()
- # Check that the component can access vars across different context layers
- nested_ctx.push({"some": "var"})
- nested_ctx.push({"name": "carl"})
- rendered = self.template.render(nested_ctx)
-
- self.assertHTMLEqual(
+ rendered = template.render(Context())
+ assertHTMLEqual(
rendered,
"""
-
-
- ABC: carl var
-
-
+
+ {% slot name=slot_name %}
+ {{ slot_name }}
+ {% endslot %}
+
+ {% endfor %}
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test_comp" %}
+ {% fill "header" %}
+ CUSTOM HEADER
+ {% endfill %}
+ {% fill "main" %}
+ CUSTOM MAIN
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context())
+
+ expected = """
+ CUSTOM HEADER
+ CUSTOM MAIN
+ footer
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_passthrough_slots(self, components_settings):
+ registry.register("slotted", _gen_slotted_component())
+
+ @register("test_comp")
+ class OuterComp(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "slots": self.slots,
+ }
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% component "slotted" %}
+ {% for slot_name in slots %}
+ {% fill name=slot_name %}
+ {% slot name=slot_name / %}
+ {% endfill %}
+ {% endfor %}
+ {% endcomponent %}
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test_comp" %}
+ {% fill "header" %}
+ CUSTOM HEADER
+ {% endfill %}
+ {% fill "main" %}
+ CUSTOM MAIN
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context())
+
+ expected = """
+
+
+ CUSTOM HEADER
+ CUSTOM MAIN
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ # NOTE: Ideally we'd (optionally) raise an error / warning here, but it's not possible
+ # with current implementation. So this tests serves as a documentation of the current behavior.
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_passthrough_slots_unknown_fills_ignored(self, components_settings):
+ registry.register("slotted", _gen_slotted_component())
+
+ @register("test_comp")
+ class OuterComp(Component):
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "slots": self.slots,
+ }
+
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% component "slotted" %}
+ {% for slot_name in slots %}
+ {% fill name=slot_name %}
+ {% slot name=slot_name / %}
+ {% endfill %}
+ {% endfor %}
+ {% endcomponent %}
+
+ """
+
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component "test_comp" %}
+ {% fill "header1" %}
+ CUSTOM HEADER
+ {% endfill %}
+ {% fill "main" %}
+ CUSTOM MAIN
+ {% endfill %}
+ {% endcomponent %}
+ """
+ template = Template(template_str)
+ rendered = template.render(Context())
+
+ expected = """
+
+
+ Default header
+ CUSTOM MAIN
+
+
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+
+# See https://github.com/django-components/django-components/issues/698
+@djc_test
+class TestNestedSlots:
+ def _gen_nested_slots_component(self):
+ class NestedSlots(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot 'wrapper' %}
+
+ Wrapper Default
+ {% slot 'parent1' %}
+
+ {% endslot %}
+ """
+ return NestedSlots
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_empty(self, components_settings):
+ registry.register("example", self._gen_nested_slots_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'example' %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context())
+ expected = """
+
+ Parent1 Default
+ {% slot 'child1' %}
+
+ {% endslot %}
+ {% slot 'parent2' %}
+
+ Child 1 Default
+
+ {% endslot %}
+
+ Parent2 Default
+
+ {% endslot %}
+
+ Wrapper Default
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_override_outer(self, components_settings):
+ registry.register("example", self._gen_nested_slots_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'example' %}
+ {% fill 'wrapper' %}
+
+ Parent1 Default
+
+
+ Child 1 Default
+
+
+ Parent2 Default
+
+
+ Entire Wrapper Replaced
+
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context())
+ expected = """
+
+ Entire Wrapper Replaced
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_override_middle(self, components_settings):
+ registry.register("example", self._gen_nested_slots_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'example' %}
+ {% fill 'parent1' %}
+
+ Parent1 Replaced
+
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context())
+ expected = """
+
+ Wrapper Default
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_override_inner(self, components_settings):
+ registry.register("example", self._gen_nested_slots_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'example' %}
+ {% fill 'child1' %}
+
+ Parent1 Replaced
+
+
+ Parent2 Default
+
+
+ Child1 Replaced
+
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context())
+ expected = """
+
+ Wrapper Default
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_override_all(self, components_settings):
+ registry.register("example", self._gen_nested_slots_component())
+ template_str: types.django_html = """
+ {% load component_tags %}
+ {% component 'example' %}
+ {% fill 'child1' %}
+
+ Parent1 Default
+
+
+ Child1 Replaced
+
+
+ Parent2 Default
+
+
+ Child1 Replaced
+
+ {% endfill %}
+ {% fill 'parent1' %}
+
+ Parent1 Replaced
+
+ {% endfill %}
+ {% fill 'wrapper' %}
+
+ Entire Wrapper Replaced
+
+ {% endfill %}
+ {% endcomponent %}
+ """
+
+ rendered = Template(template_str).render(Context())
+ expected = """
+
+ Entire Wrapper Replaced
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+
+@djc_test
+class TestSlottedTemplateRegression:
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slotted_template_that_uses_missing_variable(self, components_settings):
@register("test")
class SlottedComponentWithMissingVariable(Component):
template: types.django_html = """
@@ -544,10 +1352,10 @@ class SlottedTemplateRegressionTests(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -752,15 +1589,15 @@ class ScopedSlotTest(BaseTestCase):
"""
rendered = Template(template).render(Context())
expected = """
-
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_with_flags(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_with_flags(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -735,7 +1572,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -779,8 +1616,8 @@ class ScopedSlotTest(BaseTestCase):
template: types.django_html = """
{% load component_tags %}
{% component "test" %}
- {% fill "my_slot" data="slot_data_in_fill" default="slot_var" %}
- {{ slot_var }}
+ {% fill "my_slot" data="slot_data_in_fill" fallback="fallback" %}
+ {{ fallback }}
{{ slot_data_in_fill.abc }}
{{ slot_data_in_fill.var123 }}
{% endfill %}
@@ -788,16 +1625,16 @@ class ScopedSlotTest(BaseTestCase):
"""
rendered = Template(template).render(Context())
expected = """
-
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_with_slot_default(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_with_slot_fallback(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -770,7 +1607,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"slot_name": "my_slot",
"abc": "def",
@@ -825,15 +1662,15 @@ class ScopedSlotTest(BaseTestCase):
"""
rendered = Template(template).render(Context())
expected = """
-
Default text
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_with_variable(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_with_variable(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -807,7 +1644,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"slot_props": {
"name": "my_slot",
@@ -863,15 +1700,52 @@ class ScopedSlotTest(BaseTestCase):
"""
rendered = Template(template).render(Context())
expected = """
-
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_with_spread(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_with_spread(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -843,7 +1680,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -890,19 +1764,19 @@ class ScopedSlotTest(BaseTestCase):
template: types.django_html = """
{% load component_tags %}
{% component "test" %}
- {% fill "my_slot" data="slot_var" default="slot_var" %}
+ {% fill "my_slot" data="slot_var" fallback="slot_var" %}
{{ slot_var }}
{% endfill %}
{% endcomponent %}
"""
- with self.assertRaisesMessage(
+ with pytest.raises(
RuntimeError,
- "Fill 'my_slot' received the same string for slot default (default=...) and slot data (data=...)",
+ match=re.escape("Fill 'my_slot' received the same string for slot fallback (fallback=...) and slot data (data=...)"), # noqa: E501
):
Template(template).render(Context())
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_fill_without_data(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_fill_without_data(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -912,7 +1786,7 @@ class ScopedSlotTest(BaseTestCase):
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_raises_on_slot_data_and_slot_default_same_var(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_and_fallback_on_default_slot(self, components_settings):
+ @register("test")
+ class TestComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+
+ {% slot "slot_a" abc=abc var123=var123 %} Default text A {% endslot %}
+ {% slot "slot_b" abc=abc var123=var123 default %} Default text B {% endslot %}
+
+ """
+
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "abc": "xyz",
+ "var123": 456,
+ }
+
+ template: types.django_html = """
+ {% load component_tags %}
+ {% component "test" %}
+ {% fill name="default" data="slot_data_in_fill" fallback="slot_var" %}
+ {{ slot_data_in_fill.abc }}
+ {{ slot_var }}
+ {{ slot_data_in_fill.var123 }}
+ {% endfill %}
+ {% endcomponent %}
+ """
+ rendered = Template(template).render(Context())
+ expected = """
+
+ Default text A
+ xyz Default text B 456
+
+ """
+ assertHTMLEqual(rendered, expected)
+
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_raises_on_slot_data_and_slot_fallback_same_var(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -881,7 +1755,7 @@ class ScopedSlotTest(BaseTestCase):
overriden
"
- self.assertHTMLEqual(rendered, expected)
+ expected = " overriden
"
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_fill_without_slot_data(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_fill_without_slot_data(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -950,11 +1824,11 @@ class ScopedSlotTest(BaseTestCase):
{% endcomponent %}
"""
rendered = Template(template).render(Context())
- expected = " {}
"
- self.assertHTMLEqual(rendered, expected)
+ expected = " {}
"
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_no_fill(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_no_fill(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -964,7 +1838,7 @@ class ScopedSlotTest(BaseTestCase):
Default text
"
- self.assertHTMLEqual(rendered, expected)
+ expected = " Default text
"
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_fill_with_variables(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_fill_with_variables(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -990,7 +1864,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
"var123": 456,
@@ -1060,15 +1934,15 @@ class ScopedSlotTest(BaseTestCase):
)
expected = """
-
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_slot_data_fill_with_spread(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_slot_data_fill_with_spread(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -1033,7 +1907,7 @@ class ScopedSlotTest(BaseTestCase):
+
"""
- def get_context_data(self, input):
+ def get_template_data(self, args, kwargs, slots, context):
return {
"abc": "def",
- "input": input,
+ "input": kwargs["input"],
}
template_str: types.django_html = """
@@ -1101,12 +1975,12 @@ class ScopedSlotTest(BaseTestCase):
template = Template(template_str)
rendered = template.render(Context({}))
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
-
def
456
"""
- self.assertHTMLEqual(rendered, expected)
+ assertHTMLEqual(rendered, expected)
- @parametrize_context_behavior(["django", "isolated"])
- def test_nested_fills(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_nested_fills(self, components_settings):
@register("test")
class TestComponent(Component):
template: types.django_html = """
@@ -1078,10 +1952,10 @@ class ScopedSlotTest(BaseTestCase):
+
data1_in_slot1: {'abc': 'def', 'input': 1}
-
+ {% slot "header" %}Default header{% endslot %}
- {# Slot name 'header' used twice. #}
- {% slot "header" %}Default main header{% endslot %}
-
- """
+@djc_test
+class TestDuplicateSlot:
+ def _gen_duplicate_slot_component(self):
+ class DuplicateSlotComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "header" %}Default header{% endslot %}
+ {# Slot name 'header' used twice. #}
+ {% slot "header" %}Default main header{% endslot %}
+
+ """
- def get_context_data(self, name: Optional[str] = None) -> Dict[str, Any]:
- return {
- "name": name,
- }
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "name": kwargs.get("name", None),
+ }
+ return DuplicateSlotComponent
- class DuplicateSlotNestedComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
- {% slot "header" %}START{% endslot %}
- Name: Jannete
- Name: Jannete
-
+ Name: Jannete
+ Name: Jannete
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_duplicate_slots_fallback(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_duplicate_slots_fallback(self, components_settings):
+ registry.register(name="duplicate_slot", component=self._gen_duplicate_slot_component())
+ registry.register(name="calendar", component=self._gen_calendar_component())
+
template_str: types.django_html = """
{% load component_tags %}
{% component "duplicate_slot" %}
@@ -1222,17 +2107,20 @@ class DuplicateSlotTest(BaseTestCase):
rendered = self.template.render(Context({}))
# NOTE: Slots should have different fallbacks even though they use the same name
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
- Default header
- Default main header
-
+ Default header
+ Default main header
+
""",
)
- @parametrize_context_behavior(["django", "isolated"])
- def test_duplicate_slots_nested(self):
+ @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR)
+ def test_duplicate_slots_nested(self, components_settings):
+ registry.register(name="duplicate_slot_nested", component=self._gen_duplicate_slot_nested_component())
+ registry.register(name="calendar", component=self._gen_calendar_component())
+
template_str: types.django_html = """
{% load component_tags %}
{% component "duplicate_slot_nested" items=items %}
@@ -1245,12 +2133,12 @@ class DuplicateSlotTest(BaseTestCase):
rendered = self.template.render(Context({"items": [1, 2, 3]}))
# NOTE: Slots should have different fallbacks even though they use the same name
- self.assertHTMLEqual(
+ assertHTMLEqual(
rendered,
"""
OVERRIDDEN!
-
data1_in_slot2: {'abc': 'def', 'input': 1}
data2_in_slot2: {'abc': 'def', 'input': 2}
@@ -1115,79 +1989,87 @@ class ScopedSlotTest(BaseTestCase):
)
-class DuplicateSlotTest(BaseTestCase):
- class DuplicateSlotComponent(Component):
- template: types.django_html = """
- {% load component_tags %}
-
- {% component "calendar" date="2020-06-06" %}
- {% fill "header" %} {# fills and slots with same name relate to diff. things. #}
- {% slot "header" %}NESTED{% endslot %}
- {% endfill %}
- {% fill "body" %}Here are your to-do items for today:{% endfill %}
- {% endcomponent %}
-
- """
+ def _gen_duplicate_slot_nested_component(self):
+ class DuplicateSlotNestedComponent(Component):
+ template: types.django_html = """
+ {% load component_tags %}
+ {% slot "header" %}START{% endslot %}
+ -
- {% for item in items %}
-
- {{ item }} - {% slot "header" %}LOOP {{ item }} {% endslot %} - {% endfor %} -
+ {% component "calendar" date="2020-06-06" %}
+ {% fill "header" %} {# fills and slots with same name relate to diff. things. #}
+ {% slot "header" %}NESTED{% endslot %}
+ {% endfill %}
+ {% fill "body" %}Here are your to-do items for today:{% endfill %}
+ {% endcomponent %}
+
+ """
- def get_context_data(self, items: List) -> Dict[str, Any]:
- return {
- "items": items,
- }
+ def get_template_data(self, args, kwargs, slots, context):
+ return {
+ "items": kwargs["items"],
+ }
+ return DuplicateSlotNestedComponent
- class CalendarComponent(Component):
- """Nested in ComponentWithNestedComponent"""
+ def _gen_calendar_component(self):
+ class CalendarComponent(Component):
+ """Nested in ComponentWithNestedComponent"""
- template: types.django_html = """
- {% load component_tags %}
- -
+ {% for item in items %}
+
- {{ item }} + {% slot "header" %}LOOP {{ item }} {% endslot %} + {% endfor %} +
-
- {% slot "body" %}
- You have no events today.
- {% endslot %}
-
-
- """
-
- def setUp(self):
- super().setUp()
- registry.register(name="duplicate_slot", component=self.DuplicateSlotComponent)
- registry.register(name="duplicate_slot_nested", component=self.DuplicateSlotNestedComponent)
- registry.register(name="calendar", component=self.CalendarComponent)
+ template: types.django_html = """
+ {% load component_tags %}
+ - {% slot "header" %}Today's date is {{ date }}{% endslot %} -
-
+
+ {% slot "body" %}
+ You have no events today.
+ {% endslot %}
+
+
+ """
+ return CalendarComponent
# NOTE: Second arg is the input for the "name" component kwarg
- @parametrize_context_behavior(
- [
- # In "django" mode, we MUST pass name as arg through the component
- ("django", "Jannete"),
- # In "isolated" mode, the fill is already using top-level's context, so we pass nothing
- ("isolated", None),
- ]
+ @djc_test(
+ parametrize=(
+ ["components_settings", "input"],
+ [
+ # In "django" mode, we MUST pass name as arg through the component
+ [{"context_behavior": "django"}, "Jannete"],
+ # In "isolated" mode, the fill is already using top-level's context, so we pass nothing
+ [{"context_behavior": "isolated"}, None],
+ ],
+ ["django", "isolated"],
+ )
)
- def test_duplicate_slots(self, context_behavior_data):
+ def test_duplicate_slots(self, components_settings, input):
+ registry.register(name="duplicate_slot", component=self._gen_duplicate_slot_component())
+ registry.register(name="calendar", component=self._gen_calendar_component())
+
template_str: types.django_html = """
{% load component_tags %}
{% component "duplicate_slot" name=comp_input %}
@@ -1201,18 +2083,21 @@ class DuplicateSlotTest(BaseTestCase):
"""
self.template = Template(template_str)
- rendered = self.template.render(Context({"name": "Jannete", "comp_input": context_behavior_data}))
- self.assertHTMLEqual(
+ rendered = self.template.render(Context({"name": "Jannete", "comp_input": input}))
+ assertHTMLEqual(
rendered,
"""
- + {% slot "header" %}Today's date is {{ date }}{% endslot %} +
+
-
+
+
OVERRIDDEN!
@@ -1271,8 +2159,11 @@ class DuplicateSlotTest(BaseTestCase): """, ) - @parametrize_context_behavior(["django", "isolated"]) - def test_duplicate_slots_nested_fallback(self): + @djc_test(parametrize=PARAMETRIZE_CONTEXT_BEHAVIOR) + def test_duplicate_slots_nested_fallback(self, components_settings): + registry.register(name="duplicate_slot_nested", component=self._gen_duplicate_slot_nested_component()) + registry.register(name="calendar", component=self._gen_calendar_component()) + template_str: types.django_html = """ {% load component_tags %} {% component "duplicate_slot_nested" items=items %} @@ -1282,12 +2173,12 @@ class DuplicateSlotTest(BaseTestCase): rendered = self.template.render(Context({"items": [1, 2, 3]})) # NOTE: Slots should have different fallbacks even though they use the same name - self.assertHTMLEqual( + assertHTMLEqual( rendered, """ START -
-
+
+
+
Name: Igor
Day: Monday