tag_formatter - Django-Components" > tag_formatter - Django-Components" >
Skip to content

tag_formatter ¤

Classes:

Functions:

  • get_tag_formatter –

    Returns an instance of the currently configured component tag formatter.

ComponentFormatter ¤

ComponentFormatter(tag: str)

Bases: TagFormatterABC

The original django_component's component tag formatter, it uses the {% component %} and {% endcomponent %} tags, and the component name is given as the first positional arg.

Example as block: 

{% component "mycomp" abc=123 %}
    {% fill "myfill" %}
        ...
    {% endfill %}
{% endcomponent %}

Example as inlined tag: 

{% component "mycomp" abc=123 / %}

Source code in src/django_components/tag_formatter.py 
228
229
def __init__(self, tag: str):
    self.tag = tag

InternalTagFormatter ¤

InternalTagFormatter(tag_formatter: TagFormatterABC)

Internal wrapper around user-provided TagFormatters, so that we validate the outputs.

Source code in src/django_components/tag_formatter.py 
175
176
def __init__(self, tag_formatter: TagFormatterABC):
    self.tag_formatter = tag_formatter

ShorthandComponentFormatter ¤

Bases: TagFormatterABC

The component tag formatter that uses {% <name> %} / {% end<name> %} tags.

This is similar to django-web-components and django-slippers syntax.

Example as block: 

{% mycomp abc=123 %}
    {% fill "myfill" %}
        ...
    {% endfill %}
{% endmycomp %}

Example as inlined tag: 

{% mycomp abc=123 / %}

TagFormatterABC ¤

Bases: ABC

Abstract base class for defining custom tag formatters.

Tag formatters define how the component tags are used in the template.

Read more about Tag formatter.

For example, with the default tag formatter (ComponentFormatter), components are written as:

{% component "comp_name" %}
{% endcomponent %}

While with the shorthand tag formatter (ShorthandComponentFormatter), components are written as: 

{% comp_name %}
{% endcomp_name %}

Example:

Implementation for ShorthandComponentFormatter:

from djagno_components import TagFormatterABC, TagResult

class ShorthandComponentFormatter(TagFormatterABC):
    def start_tag(self, name: str) -> str:
        return name

    def end_tag(self, name: str) -> str:
        return f"end{name}"

    def parse(self, tokens: List[str]) -> TagResult:
        tokens = [*tokens]
        name = tokens.pop(0)
        return TagResult(name, tokens)

Methods:

  • end_tag –

    Formats the end tag of a block component.

  • parse –

    Given the tokens (words) passed to a component start tag, this function extracts

  • start_tag –

    Formats the start tag of a component.

end_tag abstractmethod ¤

end_tag(name: str) -> str

Formats the end tag of a block component.

Parameters:

  • name (str) –

    Component's registered name. Required.

Returns:

  • str ( str ) –

    The formatted end tag.

Source code in src/django_components/tag_formatter.py 
115
116
117
118
119
120
121
122
123
124
125
126
@abc.abstractmethod
def end_tag(self, name: str) -> str:
    """
    Formats the end tag of a block component.

    Args:
        name (str): Component's registered name. Required.

    Returns:
        str: The formatted end tag.
    """
    ...

parse abstractmethod ¤

parse(tokens: List[str]) -> TagResult

Given the tokens (words) passed to a component start tag, this function extracts the component name from the tokens list, and returns TagResult, which is a tuple of (component_name, remaining_tokens).

Parameters:

  • tokens ([List(str]) –

    List of tokens passed to the component tag.

Returns:

  • TagResult ( TagResult ) –

    Parsed component name and remaining tokens.

Example:

Assuming we used a component in a template like this:

{% component "my_comp" key=val key2=val2 %}
{% endcomponent %}

This function receives a list of tokens:

['component', '"my_comp"', 'key=val', 'key2=val2']
  • component is the tag name, which we drop.
  • "my_comp" is the component name, but we must remove the extra quotes.
  • The remaining tokens we pass unmodified, as that's the input to the component.

So in the end, we return:

TagResult('my_comp', ['key=val', 'key2=val2'])
Source code in src/django_components/tag_formatter.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
@abc.abstractmethod
def parse(self, tokens: List[str]) -> TagResult:
    """
    Given the tokens (words) passed to a component start tag, this function extracts
    the component name from the tokens list, and returns
    [`TagResult`](../api#django_components.TagResult),
    which is a tuple of `(component_name, remaining_tokens)`.

    Args:
        tokens [List(str]): List of tokens passed to the component tag.

    Returns:
        TagResult: Parsed component name and remaining tokens.

    **Example:**

    Assuming we used a component in a template like this:

    ```django
    {% component "my_comp" key=val key2=val2 %}
    {% endcomponent %}
    ```

    This function receives a list of tokens:

    ```python
    ['component', '"my_comp"', 'key=val', 'key2=val2']
    ```

    - `component` is the tag name, which we drop.
    - `"my_comp"` is the component name, but we must remove the extra quotes.
    - The remaining tokens we pass unmodified, as that's the input to the component.

    So in the end, we return:

    ```python
    TagResult('my_comp', ['key=val', 'key2=val2'])
    ```
    """
    ...

start_tag abstractmethod ¤

start_tag(name: str) -> str

Formats the start tag of a component.

Parameters:

  • name (str) –

    Component's registered name. Required.

Returns:

  • str ( str ) –

    The formatted start tag.

Source code in src/django_components/tag_formatter.py 
102
103
104
105
106
107
108
109
110
111
112
113
@abc.abstractmethod
def start_tag(self, name: str) -> str:
    """
    Formats the start tag of a component.

    Args:
        name (str): Component's registered name. Required.

    Returns:
        str: The formatted start tag.
    """
    ...

TagResult ¤

Bases: NamedTuple

The return value from TagFormatter.parse().

Read more about Tag formatter.

Attributes:

  • component_name (str) –

    Component name extracted from the template tag

  • tokens (List[str]) –

    Remaining tokens (words) that were passed to the tag, with component name removed

component_name instance-attribute ¤

component_name: str

Component name extracted from the template tag

For example, if we had tag

{% component "my_comp" key=val key2=val2 %}

Then component_name would be my_comp.

tokens instance-attribute ¤

tokens: List[str]

Remaining tokens (words) that were passed to the tag, with component name removed

For example, if we had tag

{% component "my_comp" key=val key2=val2 %}

Then tokens would be ['key=val', 'key2=val2'].

get_tag_formatter ¤

get_tag_formatter(registry: ComponentRegistry) -> InternalTagFormatter

Returns an instance of the currently configured component tag formatter.

Source code in src/django_components/tag_formatter.py 
312
313
314
315
316
317
318
319
320
321
322
def get_tag_formatter(registry: "ComponentRegistry") -> InternalTagFormatter:
    """Returns an instance of the currently configured component tag formatter."""
    # Allow users to configure the component TagFormatter
    formatter_cls_or_str = registry.settings.tag_formatter

    if isinstance(formatter_cls_or_str, str):
        tag_formatter: TagFormatterABC = import_string(formatter_cls_or_str)
    else:
        tag_formatter = formatter_cls_or_str

    return InternalTagFormatter(tag_formatter)