Showcase: Tab component and template-centric components

[JuroOravec]

With the recent additions, django-components is now getting closer to be on par with React and Vue in terms of templating capabilities!

What I mean is that now it's possible to write complex templates where components are fully defined in the template, meaning that most of the HTML attributes and templating can be colocated. Really excited about this! 🎉

Here's an example of what is now possible with django-components:

{% component "tabs" attrs:class="p-6 h-full" %}
  {% component "tab_item" header="Tab 1" %}
    <p>
      hello from tab 1
    </p>
    {% component "button" %}
      Click me!
    {% endcomponent %}
  {% endcomponent %}

  {% component "tab_item" header="Tab 2" %}
    Hello this is tab 2
  {% endcomponent %}
{% endcomponent %}

Which renders:

While it may not look like much at first, stop and think... How is it possible?!

With simple components, we would assume that each component only renders and inserts a string in its place. Yet, we see that the tab headers (e.g. Tab 1) are rendered in a different place than where they were defined.

What actually happens is that the tabs component uses the information from tab_item components. This is actually a major improvement in how components can be written with django-components.

Previously, to achieve this layout, I had to define the HTML for individual tabs in Python code, and then pass around the pre-rendered HTML as variables:

class TabEntry(NamedTuple):
    header: str
    content: str

tabs = [
	TabEntry(
		header="Tab 1",
		content=Template("""
		    <p>
		      hello from tab 1
		    </p>
		    {% component "button" %}
		      Click me!
		    {% endcomponent %}
		""").render(Context({})),
	),

	TabEntry(
		header="Tab 2",
		content="Hello this is tab 2",
	),
]

Tabs.render(
	kwargs={
		"tabs": tabs,
	}
)

This new approach has multiple advantages:

• The templating (AKA where you position the components) and all relevant info like HTML attributes can be colocated inside the HTML file.
• The nested HTML (like the content of Tab 1) can access the original Context.
  • If I defined the tabs inside Python, I would need to wire the original Context to the tabs. Since django-components does NOT expose the Context instance, one would have to override the render methods or otherwise intercept. With the new approach, we get the access to the Context for free!
• Personally I find it easier readable.

For anyone curious, the source code is below:

tabs.py

from typing import NamedTuple

from django.utils.safestring import mark_safe
from django_components import component, types as t

from app_home.helpers.components import Component


class TabEntry(NamedTuple):
    header: str
    content: str
    disabled: bool = False


@component.register("_tabs")
class _TabsImpl(Component):
    template_name = "tabs.html"

    class Media:
        js = "tabs.js"

    def setup_context(
        self,
        *_args,
        tabs: list[TabEntry],
        # Unique name to identify this tabs instance, so we can open/close the tabs
        # based on the query params.
        name: str | None = None,
        attrs: dict | None = None,
        header_attrs: dict | None = None,
        content_attrs: dict | None = None,
    ):
        return {
            "attrs": attrs,
            "tabs": tabs,
            "header_attrs": header_attrs,
            "content_attrs": content_attrs,
            "tabs_data": {"name": name},
        }


# 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.
@component.register("tabs")
class Tabs(Component):
    template: t.django_html = """
        {% provide "_tab" tabs=tabs enabled=True %}
            {% slot "content" default %}{% endslot %}
        {% endprovide %}
    """

    def setup_context(
        self,
        *_args,
        # Unique name to identify this tabs instance, so we can open/close the tabs
        # based on the query params.
        name: str | None = None,
        attrs: dict | None = None,
        header_attrs: dict | None = None,
        content_attrs: dict | None = None,
    ):
        return {
            "tabs": [],
            "name": name,
            "attrs": attrs,
            "header_attrs": header_attrs,
            "content_attrs": content_attrs,
            "tabs_data": {"name": name},
        }

    def on_render_postprocess(self, context, template, content):
        # 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"],
            },
        )


# Use this component to define individual tabs inside the default slot
# inside the `tab` component.
@component.register("tab_item")
class TabItemComp(Component):
    template: t.django_html = """
        {% provide "_tab" tabs=empty_tabs enabled=False %}
            {% slot "content" default %}{% endslot %}
        {% endprovide %}
    """

    def setup_context(
        self,
        *_args,
        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 tab_item
        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}'"
            )

        return {
            "empty_tabs": [],
            "parent_tabs": tab_ctx.tabs,
            "header": header,
            "disabled": disabled,
        }

    def on_render_after(self, context, template, content):
        parent_tabs: list[dict] = context["parent_tabs"]
        parent_tabs.append({
            "header": context["header"],
            "disabled": context["disabled"],
            "content": mark_safe(content.strip()),
        })

tabs.html

<div
  x-data="tabs"
  data-init="{{ tabs_data|json|escape }}"
  {% html_attrs attrs %}
>
  <ul class="flex border-b">
    {% for tab in tabs %}
      {% if not tab.disabled %}
      <li
        @click="setOpenTab( {{ forloop.counter }} )"
        :class="{
          'border-b-2 border-blue-700': openTab === {{ forloop.counter }}
        }"
        {% html_attrs header_attrs %}
      >
        <a
          href="#"
          :class="openTab === {{ forloop.counter }} ? activeClasses : inactiveClasses"
          class="bg-white inline-block py-2 px-4 font-semibold"
        >
          {{ tab.header }}
        </a>
      </li>
      {% else %}
      <li class="mr-1">
        <p class="text-gray-300 bg-white inline-block py-2 px-4 font-semibold">
          {{ tab.header }}
        </p>
      </li>
      {% endif %}
    {% endfor %}
  </ul>
  <div class="w-full h-full relative overflow-y-scroll" x-ref="container">
    <article class="px-4 py-5 sm:p-6 absolute w-full">
      {% for tab in tabs %}
      <div
        x-show="openTab === {{ forloop.counter }}"
        {% html_attrs content_attrs %}
      >
        {{ tab.content }}
      </div>
      {% endfor %}
    </article>
  </div>
</div>

The example above uses:

• Custom subclass of django-component's Component class.
  • This subclass has hooks for before/after rendering, and for post-processing the rendered template. I plan to make an MR to add the hooks.
• The provide/inject feature
• html_attrs and the prop:key=val syntax to allow users to provide arbitrary HTML attributes.
• AlpineJS for JS (omitted)
• Tailwind CSS

How it works is that:

1. The tabs component expects only tab_item components in it's slot.
2. At the start of rendering, tabs component "provides" an empty array
3. For each tab_item component that is rendered inside the tabs slot, tab_item "injects" the array from the parent tabs component. And at the end of rendering of tab_item, using one of the hooks, tab_item adds its own rendered content into the tabs array, to which it still holds a reference.
4. Once the tabs's slot is rendered, we use the postprocess hook. At this point, the "provided" array is populated with the rendered content of tab_items.
5. We pass the pre-rendered tabs to _TabsImpl. At this point, it's the same biz as before - we pass data as props, and component renders it.

[EmilStenstrom]

Hi! Can I ask some questions about the code in tabs.py? The intent is trying to figure out if there's more we can do to simplify writing components like this:

• How come you use setup_context instead of get_context_data?
• A large part of all the code is just the setup_context definitions, could we do something smarter there?
• The difference between a Tab and TabImpl seems excessive, wouldn't it be easier to combine them?
• What's the difference between on_render_postprocess and on_render_after?

[JuroOravec]

Sure!

How come you use setup_context instead of get_context_data?

setup_context is just renamed get_context_data, it's a leftover of the fact that in my fork I was also playing with the idea of using a function signature closer to Vue / React, where the first arg is an object of props.

---

A large part of all the code is just the setup_context definitions, could we do something smarter there?

Hm, so theoretically some of it could be now simplified thanks to #629 - instead of defining full function signature for each setup_context , one could now re-use the definitions for args / kwargs via the types. So then setup_context's signature could be simply setup_context(self, *args, **kwargs). So e.g.:

class TabsKwargs(TypedDict):
	...

@component.register("tabs")
class Tabs(Component[TabsArgs, TabsKwargs, TabsData, TabsSlots]):
	template = ...

    def setup_context(self, *args, **kwargs):
		name = kwargs.get("name", None)
        return {
            "tabs": [],
            "name": name,
            "attrs": kwargs.get("attrs", None),
            "header_attrs": kwargs.get("header_attrs", None),
            "content_attrs": kwargs.get("content_attrs", None),
            "tabs_data": {"name": name},
        }

Then, a lot of repetition comes from passing the same value from the input of setup_context to the context, aka all those

return {
    "attrs": kwargs.get("attrs", None),
    "header_attrs": kwargs.get("header_attrs", None),
    "content_attrs": kwargs.get("content_attrs", None),
}

Personally I think it's good to have explicitly defined data. One thing that could help, that I'm also cooking up, and which is inspired by django-viewcomponent, is that they made the component instance accessible via self context var ({{ self }}).

In combination with the fact that component inputs are accessible via self.input.args, self.input.kwargs, self.input.slots, it means that one could skip returning the inputs un-modified in get_context_data, one could instead access the original unmodified inputs inside the template like so:

name: {{ self.input.kwargs.name }}

So this would be practically the same as the template $props and $slots attributes in Vue.

With these combined, we could shorten the setup_context definition to

class TabsKwargs(TypedDict):
	...

@component.register("tabs")
class Tabs(Component[TabsArgs, TabsKwargs, TabsData, TabsSlots]):
	template = ...

    def setup_context(self, *args, **kwargs):
		name = kwargs.get("name", None)
        return {
            "tabs": [],
            "name": name,
            "tabs_data": {"name": name},
        }

---

The difference between a Tab and TabImpl seems excessive, wouldn't it be easier to combine them?

Possibly could be merged, though then I would need to take different approach. Because for this to work, I need to render 2 templates: First renders the slot fill with TabItems, the second one is the actual implementation.

And the approach I took was to let django_components do its biz and render the template, and then use the outputs of that to render another template.

Theoretically, I could have done something like this, so we'd render the short template snippet inside on_before_render which would indirectly make the TabItems inject and populate the tabs provided list.

@component.register("tabs")
class Tabs(Component):
    template_name: "tabs.html"

    def setup_context() ...

    def on_before_render(self, context, template, content):
		# Render TabItems in the given slot, which populates context["tabs"]
		Template("""
			{% provide "_tab" tabs=empty_tabs enabled=False %}
			    {% slot "content" default %}{% endslot %}
			{% endprovide %}
		""").render(context)

But for this to work, I think we'd also need to put the content slot inside tabs.html, otherwise django_components would complain that it received a slot it did not declare. A workaround for that could be to include inside tabs.html something like this:

{% if False %}
	{% slot "content" default / %}
{% endif %}

So overall, I could have merged Tabs and TabsImpl, but it wold be more hacky it feels.

---

What's the difference between on_render_postprocess and on_render_after?

I dropped on_render_postprocess. But initially I included both, with a reasoning that:

• on_render_postprocess would be explicitly used for modifying the rendered content
• on_render_after would be used for side-effects that don't need to modify the rendered content.

But in the end, I decided to merge them into on_render_after, with the logic that IF on_render_after returns something, then it overwrites the rendered content.