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.