Extension hooks¤

Overview of all the extension hooks available in Django Components.

Hooks¤

on_component_class_created ¤

on_component_class_created(ctx: OnComponentClassCreatedContext) -> None

See source code

Called when a new Component class is created.

This hook is called after the Component class is fully defined but before it's registered.

Use this hook to perform any initialization or validation of the Component class.

Example:

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"

Available data:

name	type	description
`component_cls`	`Type[Component]`	The created Component class

on_component_class_deleted ¤

on_component_class_deleted(ctx: OnComponentClassDeletedContext) -> None

See source code

Called when a Component class is being deleted.

This hook is called before the Component class is deleted from memory.

Use this hook to perform any cleanup related to the Component class.

Example:

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)

Available data:

name	type	description
`component_cls`	`Type[Component]`	The to-be-deleted Component class

on_component_data ¤

on_component_data(ctx: OnComponentDataContext) -> None

See source code

Called when a 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(), Component.get_js_data() and Component.get_css_data().

This hook runs after on_component_input.

Use this hook to modify or validate the component's data before rendering.

Example:

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"

Available data:

name	type	description
`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
`context_data`	`Dict`	Deprecated. Use `template_data` instead. Will be removed in v1.0.
`css_data`	`Dict`	Dictionary of CSS data from `Component.get_css_data()`
`js_data`	`Dict`	Dictionary of JavaScript data from `Component.get_js_data()`
`template_data`	`Dict`	Dictionary of template data from `Component.get_template_data()`

on_component_input ¤

on_component_input(ctx: OnComponentInputContext) -> Optional[str]

See source code

Called when a 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(), Component.get_js_data(), and Component.get_css_data() methods, and the 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:

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, Kwargs, Slots types, these types are NOT yet instantiated.

Instead, component fields like Component.args, Component.kwargs, Component.slots are plain list / dict objects.

Available data:

name	type	description
`args`	`List`	List of positional arguments passed to the component
`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
`context`	`Context`	The Django template Context object
`kwargs`	`Dict`	Dictionary of keyword arguments passed to the component
`slots`	`Dict[str, Slot]`	Dictionary of slot definitions

on_component_registered ¤

on_component_registered(ctx: OnComponentRegisteredContext) -> None

See source code

Called when a Component class is registered with a ComponentRegistry.

This hook is called after a Component class is successfully registered.

Example:

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}'")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The registered Component class
`name`	`str`	The name the component was registered under
`registry`	`ComponentRegistry`	The registry the component was registered to

on_component_rendered ¤

on_component_rendered(ctx: OnComponentRenderedContext) -> Optional[str]

See source code

Called when a 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():

To modify the output, return a new string from this hook. The original output or error will be ignored.
To cause this component to return a new error, raise that error. The original output and error will be ignored.
If you neither raise nor return string, the original output or error will be used.

Examples:

Change the final output of a component:

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 + "<!-- MyExtension comment -->"

Cause the component to raise a new exception:

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:

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}")

Available data:

name	type	description
`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
`error`	`Optional[Exception]`	The error that occurred during rendering, or `None` if rendering was successful
`result`	`Optional[str]`	The rendered component, or `None` if rendering failed

on_component_unregistered ¤

on_component_unregistered(ctx: OnComponentUnregisteredContext) -> None

See source code

Called when a Component class is unregistered from a ComponentRegistry.

This hook is called after a Component class is removed from the registry.

Example:

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}'")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The unregistered Component class
`name`	`str`	The name the component was registered under
`registry`	`ComponentRegistry`	The registry the component was unregistered from

on_css_loaded ¤

on_css_loaded(ctx: OnCssLoadedContext) -> Optional[str]

See source code

Called when a Component's CSS is loaded as a string.

This hook runs only once per Component class and works for both Component.css and Component.css_file.

Use this hook to read or modify the CSS.

To modify the CSS, return a new string from this hook.

Example:

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")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The Component class whose CSS was loaded
`content`	`str`	The CSS content (string)

on_js_loaded ¤

on_js_loaded(ctx: OnJsLoadedContext) -> Optional[str]

See source code

Called when a Component's JS is loaded as a string.

This hook runs only once per Component class and works for both Component.js and Component.js_file.

Use this hook to read or modify the JS.

To modify the JS, return a new string from this hook.

Example:

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")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The Component class whose JS was loaded
`content`	`str`	The JS content (string)

on_registry_created ¤

on_registry_created(ctx: OnRegistryCreatedContext) -> None

See source code

Called when a new ComponentRegistry is created.

This hook is called after a new ComponentRegistry instance is initialized.

Use this hook to perform any initialization needed for the registry.

Example:

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"

Available data:

name	type	description
`registry`	`ComponentRegistry`	The created ComponentRegistry instance

on_registry_deleted ¤

on_registry_deleted(ctx: OnRegistryDeletedContext) -> None

See source code

Called when a ComponentRegistry is being deleted.

This hook is called before a ComponentRegistry instance is deleted.

Use this hook to perform any cleanup related to the registry.

Example:

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)

Available data:

name	type	description
`registry`	`ComponentRegistry`	The to-be-deleted ComponentRegistry instance

on_slot_rendered ¤

on_slot_rendered(ctx: OnSlotRenderedContext) -> Optional[str]

See source code

Called when a {% 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:

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 + "<!-- MyExtension comment -->"

Access slot metadata:

You can access the {% slot %} tag node (SlotNode) and its metadata using ctx.slot_node.

For example, to find the Component class to which belongs the template where the {% slot %} tag is defined, you can use ctx.slot_node.template_component:

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}")

Available data:

name	type	description
`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
`result`	`SlotResult`	The rendered result of the slot
`slot`	`Slot`	The Slot instance that was rendered
`slot_is_default`	`bool`	Whether the slot is default
`slot_is_required`	`bool`	Whether the slot is required
`slot_name`	`str`	The name of the `{% slot %}` tag
`slot_node`	`SlotNode`	The node instance of the `{% slot %}` tag

on_template_compiled ¤

on_template_compiled(ctx: OnTemplateCompiledContext) -> None

See source code

Called when a Component's template is compiled into a Template object.

This hook runs only once per Component class and works for both Component.template and Component.template_file.

Use this hook to read or modify the template (in-place) after it's compiled.

Example:

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}")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The Component class whose template was loaded
`template`	`django.template.base.Template`	The compiled template object

on_template_loaded ¤

on_template_loaded(ctx: OnTemplateLoadedContext) -> Optional[str]

See source code

Called when a Component's template is loaded as a string.

This hook runs only once per Component class and works for both Component.template and 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:

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")

Available data:

name	type	description
`component_cls`	`Type[Component]`	The Component class whose template was loaded
`content`	`str`	The template string
`name`	`Optional[str]`	The name of the template
`origin`	`Optional[django.template.base.Origin]`	The origin of the template