slots ¤

Classes:

FillNode –

Node corresponding to {% fill %}
Slot –

This class holds the slot content function along with related metadata.
SlotFill –

SlotFill describes what WILL be rendered.
SlotIsFilled –

Dictionary that returns True if the slot is filled (key is found), False otherwise.
SlotNode –

Node corresponding to {% slot %}
SlotRef –

SlotRef allows to treat a slot as a variable. The slot is rendered only once

Functions:

resolve_fills –

Given a component body (django.template.NodeList), find all slot fills,

FillNode ¤

FillNode(nodelist: NodeList, kwargs: RuntimeKwargs, trace_id: str, node_id: Optional[str] = None)

Bases: BaseNode

Node corresponding to {% fill %}

Source code in src/django_components/slots.py

def __init__(
    self,
    nodelist: NodeList,
    kwargs: RuntimeKwargs,
    trace_id: str,
    node_id: Optional[str] = None,
):
    super().__init__(nodelist=nodelist, args=None, kwargs=kwargs, node_id=node_id)

    self.trace_id = trace_id

Slot `dataclass` ¤

Slot(content_func: SlotFunc[TSlotData])

Bases: Generic[TSlotData]

This class holds the slot content function along with related metadata.

SlotFill `dataclass` ¤

SlotFill(name: str, is_filled: bool, slot: Slot[TSlotData])

Bases: Generic[TSlotData]

SlotFill describes what WILL be rendered.

The fill may be provided by the user from the outside (is_filled=True), or it may be the default content of the slot (is_filled=False).

Attributes:

name (str) –

Name of the slot.

name `instance-attribute` ¤

name: str

Name of the slot.

SlotIsFilled ¤

SlotIsFilled(fills: Dict, *args: Any, **kwargs: Any)

Bases: dict

Dictionary that returns True if the slot is filled (key is found), False otherwise.

Source code in src/django_components/slots.py

def __init__(self, fills: Dict, *args: Any, **kwargs: Any) -> None:
    escaped_fill_names = {_escape_slot_name(fill_name): True for fill_name in fills.keys()}
    super().__init__(escaped_fill_names, *args, **kwargs)

SlotNode ¤

SlotNode(
    nodelist: NodeList,
    trace_id: str,
    node_id: Optional[str] = None,
    kwargs: Optional[RuntimeKwargs] = None,
    is_required: bool = False,
    is_default: bool = False,
)

Bases: BaseNode

Node corresponding to {% slot %}

Source code in src/django_components/slots.py

def __init__(
    self,
    nodelist: NodeList,
    trace_id: str,
    node_id: Optional[str] = None,
    kwargs: Optional[RuntimeKwargs] = None,
    is_required: bool = False,
    is_default: bool = False,
):
    super().__init__(nodelist=nodelist, args=None, kwargs=kwargs, node_id=node_id)

    self.is_required = is_required
    self.is_default = is_default
    self.trace_id = trace_id

SlotRef ¤

SlotRef(slot: SlotNode, context: Context)

SlotRef allows to treat a slot as a variable. The slot is rendered only once the instance is coerced to string.

This is used to access slots as variables inside the templates. When a SlotRef is rendered in the template with {{ my_lazy_slot }}, it will output the contents of the slot.

Source code in src/django_components/slots.py

def __init__(self, slot: "SlotNode", context: Context):
    self._slot = slot
    self._context = context

resolve_fills ¤

resolve_fills(context: Context, nodelist: NodeList, component_name: str) -> Dict[SlotName, Slot]

Given a component body (django.template.NodeList), find all slot fills, whether defined explicitly with {% fill %} or implicitly.

So if we have a component body:

{% component "mycomponent" %}
    {% fill "first_fill" %}
        Hello!
    {% endfill %}
    {% fill "second_fill" %}
        Hello too!
    {% endfill %}
{% endcomponent %}

Then this function finds 2 fill nodes: "first_fill" and "second_fill", and formats them as slot functions, returning:

{
    "first_fill": SlotFunc(...),
    "second_fill": SlotFunc(...),
}

If no fill nodes are found, then the content is treated as default slot content.

{
    DEFAULT_SLOT_KEY: SlotFunc(...),
}

This function also handles for-loops, if/else statements, or include tags to generate fill tags:

{% component "mycomponent" %}
    {% for slot_name in slots %}
        {% fill name=slot_name %}
            {% slot name=slot_name / %}
        {% endfill %}
    {% endfor %}
{% endcomponent %}

Source code in src/django_components/slots.py

def resolve_fills(
    context: Context,
    nodelist: NodeList,
    component_name: str,
) -> Dict[SlotName, Slot]:
    """
    Given a component body (`django.template.NodeList`), find all slot fills,
    whether defined explicitly with `{% fill %}` or implicitly.

    So if we have a component body:
    ```django
    {% component "mycomponent" %}
        {% fill "first_fill" %}
            Hello!
        {% endfill %}
        {% fill "second_fill" %}
            Hello too!
        {% endfill %}
    {% endcomponent %}
    ```

    Then this function finds 2 fill nodes: "first_fill" and "second_fill",
    and formats them as slot functions, returning:

    ```python
    {
        "first_fill": SlotFunc(...),
        "second_fill": SlotFunc(...),
    }
    ```

    If no fill nodes are found, then the content is treated as default slot content.

    ```python
    {
        DEFAULT_SLOT_KEY: SlotFunc(...),
    }
    ```

    This function also handles for-loops, if/else statements, or include tags to generate fill tags:

    ```django
    {% component "mycomponent" %}
        {% for slot_name in slots %}
            {% fill name=slot_name %}
                {% slot name=slot_name / %}
            {% endfill %}
        {% endfor %}
    {% endcomponent %}
    ```
    """
    slots: Dict[SlotName, Slot] = {}

    if not nodelist:
        return slots

    maybe_fills = _extract_fill_content(nodelist, context, component_name)

    # The content has no fills, so treat it as default slot, e.g.:
    # {% component "mycomponent" %}
    #   Hello!
    #   {% if True %} 123 {% endif %}
    # {% endcomponent %}
    if maybe_fills is False:
        # Ignore empty content between `{% component %} ... {% endcomponent %}` tags
        nodelist_is_empty = not len(nodelist) or all(
            isinstance(node, TextNode) and not node.s.strip() for node in nodelist
        )

        if not nodelist_is_empty:
            slots[DEFAULT_SLOT_KEY] = _nodelist_to_slot_render_func(
                DEFAULT_SLOT_KEY,
                nodelist,
                data_var=None,
                default_var=None,
            )

    # The content has fills
    else:
        # NOTE: If slot fills are explicitly defined, we use them even if they are empty (or only whitespace).
        #       This is different from the default slot, where we ignore empty content.
        for fill in maybe_fills:
            slots[fill.name] = _nodelist_to_slot_render_func(
                slot_name=fill.name,
                nodelist=fill.fill.nodelist,
                data_var=fill.data_var,
                default_var=fill.default_var,
                extra_context=fill.extra_context,
            )

    return slots

slots ¤

FillNode ¤

Slot dataclass ¤

SlotFill dataclass ¤

name instance-attribute ¤

SlotIsFilled ¤

SlotNode ¤

SlotRef ¤

resolve_fills ¤

Slot `dataclass` ¤

SlotFill `dataclass` ¤

name `instance-attribute` ¤