Extensions
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¤
Install extensions¤
Extensions are configured in the Django settings under COMPONENTS.extensions.
Extensions can be set by either as an import string or by passing in a class:
# settings.py
+ Extensions - Django-Components Extensions
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¤
Install extensions¤
Extensions are configured in the Django settings under COMPONENTS.extensions.
Extensions can be set by either as an import string or by passing in a class:
# settings.py
class MyExtension(ComponentExtension):
name = "my_extension"
@@ -206,187 +206,210 @@
# All `Component.ColorLogger` classes will inherit from this class.
ComponentConfig = ColorLoggerComponentConfig
-
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:
Where:
python manage.py components - is the Django entrypointext run - is the subcommand to run extension commandsmy_ext - is the extension namehello - is the command name
Define commands¤
To define a command, subclass from ComponentCommand. This subclass should define:
name - the command's namehelp - the command's help texthandle - the logic to execute when the command is run
from django_components import ComponentCommand, ComponentExtension
-
-class HelloCommand(ComponentCommand):
- name = "hello"
- help = "Say hello"
-
- def handle(self, *args, **kwargs):
- print("Hello, world!")
+
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:
# ❌ 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 attribute, which is copied from the original slot:
# ✅ 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
-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 attribute of the ComponentCommand class.
The arguments are parsed with argparse into a dictionary of arguments and options. These are then available as keyword arguments to the handle method of the command.
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:
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 for more information.
django-components defines types as CommandArg, CommandArgGroup, CommandSubcommand, and CommandParserInput to help with type checking.
Note
If a command doesn't have the handle method defined, the command will print a help message and exit.
Argument groups¤
Arguments can be grouped using CommandArgGroup to provide better organization and help messages.
Read more on argparse argument groups.
from django_components import CommandArg, CommandArgGroup, ComponentCommand, ComponentExtension
+ # 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:
Where:
python manage.py components - is the Django entrypointext run - is the subcommand to run extension commandsmy_ext - is the extension namehello - is the command name
Define commands¤
To define a command, subclass from ComponentCommand. This subclass should define:
name - the command's namehelp - the command's help texthandle - the logic to execute when the command is run
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 attribute of the ComponentCommand class.
The arguments are parsed with argparse into a dictionary of arguments and options. These are then available as keyword arguments to the handle method of the command.
from django_components import CommandArg, 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 class.
However, instead of defining the subcommands in the commands attribute of the extension, you define them in the subcommands attribute of the parent command:
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:
Or the 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.:
You should instead pass all the arguments to the subcommand:
Help message¤
By default, all commands will print their help message when run with the --help / -h flag.
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() function, which allows you to simulate running the command in tests.
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 module to redirect the output to a string:
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 decorator.
Thus, a full test example can then look like this:
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 attribute of your ComponentExtension class. Each URL is defined using the 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:
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/<int:id>/", handler=my_view, name="another_view"),
- ]
-
Warning
The URLRoute objects are different from objects created with Django's django.urls.path(). Do NOT use URLRoute objects in Django's urlpatterns and vice versa!
django-components uses a custom 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
For example, if you have defined a URL with the path my-view/<str:name>/ in an extension named my_extension, it can be accessed at:
Nested URLs¤
Extensions can also define nested URLs to allow for more complex routing structures.
To define nested URLs, set the children attribute of the URLRoute object to a list of child URLRoute objects:
class MyExtension(ComponentExtension):
- name = "my_extension"
-
- urls = [
- URLRoute(
- path="parent/",
- name="parent_view",
- children=[
- URLRoute(path="child/<str:name>/", handler=my_view, name="child_view"),
- ],
- ),
- ]
-
In this example, the URL
would call the my_view handler with the parameter name set to "John".
Extra URL data¤
The 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() accepts, but which are not defined on the URLRoute object.
To address this, the URLRoute object has an extra attribute, which is a dictionary that can be used to pass any extra kwargs to django.urls.path():
URLRoute(
- path="my-view/<str:name>/",
- handler=my_view,
- name="my_view",
- extra={"kwargs": {"foo": "bar"} },
-)
-
Is the same as:
django.urls.path(
- "my-view/<str:name>/",
- view=my_view,
- name="my_view",
- kwargs={"foo": "bar"},
-)
-
because URLRoute is converted to Django's route like so:
django.urls.path(
- route.path,
- view=route.handler,
- name=route.name,
- **route.extra,
+ 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:
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 for more information.
django-components defines types as CommandArg, CommandArgGroup, CommandSubcommand, and CommandParserInput to help with type checking.
Note
If a command doesn't have the handle method defined, the command will print a help message and exit.
Argument groups¤
Arguments can be grouped using CommandArgGroup to provide better organization and help messages.
Read more on argparse argument groups.
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 class.
However, instead of defining the subcommands in the commands attribute of the extension, you define them in the subcommands attribute of the parent command:
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:
Or the 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.:
You should instead pass all the arguments to the subcommand:
Help message¤
By default, all commands will print their help message when run with the --help / -h flag.
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() function, which allows you to simulate running the command in tests.
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 module to redirect the output to a string:
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 decorator.
Thus, a full test example can then look like this:
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 attribute of your ComponentExtension class. Each URL is defined using the 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:
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/<int:id>/", handler=my_view, name="another_view"),
+ ]
+
Warning
The URLRoute objects are different from objects created with Django's django.urls.path(). Do NOT use URLRoute objects in Django's urlpatterns and vice versa!
django-components uses a custom 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
For example, if you have defined a URL with the path my-view/<str:name>/ in an extension named my_extension, it can be accessed at:
Nested URLs¤
Extensions can also define nested URLs to allow for more complex routing structures.
To define nested URLs, set the children attribute of the URLRoute object to a list of child URLRoute objects:
class MyExtension(ComponentExtension):
+ name = "my_extension"
+
+ urls = [
+ URLRoute(
+ path="parent/",
+ name="parent_view",
+ children=[
+ URLRoute(path="child/<str:name>/", handler=my_view, name="child_view"),
+ ],
+ ),
+ ]
+
In this example, the URL
would call the my_view handler with the parameter name set to "John".
Extra URL data¤
The 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() accepts, but which are not defined on the URLRoute object.
To address this, the URLRoute object has an extra attribute, which is a dictionary that can be used to pass any extra kwargs to django.urls.path():
\ No newline at end of file
+Is the same as:
django.urls.path(
+ "my-view/<str:name>/",
+ view=my_view,
+ name="my_view",
+ kwargs={"foo": "bar"},
+)
+because URLRoute is converted to Django's route like so: