django-slots 0.2.7
django_slots = inclusion tag + blocks
License: BSD-3-Clause
Requires Python: >=3.10,<4.0
Keywords: slot,component,block,template,django

# django_slots

Allows multiline strings to be captured and passed to template tags.

## Demo

1. Register a component
  
```python
# app/templatetags/component_tags.py
from django_slots import Library, Component

register = Library()


@register.block_component
class Details(Component):
  pass
```

2. Create a template

```html+django
{# app/templates/components/details.html #}
<details>
<summary>{{ summary|default:slots.summary }}</summary>
{{ slot }}
</details>
```

Usage:

```html+django
{% load component_tags %}
{% load slot_tags %}

{% details summary="the summary" %}
  the default slot
{% /details %}

{% details %}
  {% slot summary %}the <b>summary</b>{% /slot %}
  the default slot
{% /details %}
```

## Installation

```shell
pip install django-slots
```

```python
INSTALLED_APPS = [
    # ...
    
    'django_slots',
]
```

## Slots

Use `{% slot name %}{% /slot %}` to capture and name a slot. These slots will be available in the template in a dictionary called `slots`. eg `{{ slots.name }}`.

Any lines not surrounded by a slot tag will be available in the component template as `{{ slot }}`.

## Template

The default the template path is `components/<component_name>.html`.

Use `template_name` attribute or `get_template_name()` method to override.

## Change name

By default, the template tag name will be the Component class name converted to snake case. Use the `name` attribute to override.

eg:

```python
from django_slots import Component, Library

register = Library()


@register.inline_component
class Button(Component):
    name = 'btn'
```

```html+django
{% btn %}
```

## Change name format

By default, inline tags are named `"{name}/"` and block tags are named `"{name}", "/{name}"`. To change this format specify `inline_tag_name` and `block_tag_names` attributes.

eg:

```python
from django_slots import Component, Library

register = Library()


class AppComponent(Component):
    inline_tag_name = "{name}end"
    block_tag_names = "{name}", "end{name}"    

    
@register.component
class Button(AppComponent):
    pass
```

```html+django
{% buttonend %}

{% button %}{% endbutton %}
```

## Inline only template tag

Use `@register.inline_component` to only allow `{% inline/ %}` use.

## Block only template tag

Use `@register.block_component` to only allow `{% block %}{% /block %}` use.

## Validate arguments

Implement `def get_content_data(slots, **kwargs)` to validate arguments. 

eg:

```python
from django_slots import Component, Library

register = Library()


@register.component
class Button(Component):
    STYLE = ["primary", "secondary"]
    def get_context_data(self, slots, *, style: str):
        if style not in self.STYLE:
            raise self.validation_error(f"style {style!r} not in {self.STYLE!r}")
        return super().get_context_data(slots, style=style)
```

## Namespace components

Components can be namespaced which is useful for creating a third party app.

```python
from django_slots import Library, Component

register = Library()


class NHSUKComponent(Component):
    namespace = 'nhsuk'


@register.component
class Button(NHSUKComponent):
    pass
```

```html+django
{% nhsuk:button %}
  Save and continue
{% /nhsuk:button %}
```

See https://github.com/nwjlyons/nhsuk-components