Metadata-Version: 2.4
Name: django-sandwich-tag
Version: 0.2.1
Summary: A django template tag that simplifies nested templates.
Author-email: Jacob Tumak <jtumak.dev@gmail.com>
License: MIT License
        
        Copyright (c) 2025, Jacob Tumak
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: Homepage, https://github.com/jacobtumak/django-sandwich-tag
Project-URL: Repository, https://github.com/jacobtumak/django-sandwich-tag
Keywords: sandwich,sandwich_tag,django-sandwich-tag
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django<6.0,>=4.2
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-sugar; extra == "test"
Provides-Extra: utils
Requires-Dist: tox; extra == "utils"
Requires-Dist: invoke; extra == "utils"
Requires-Dist: bumpver; extra == "utils"
Requires-Dist: pip-tools; extra == "utils"
Provides-Extra: format
Requires-Dist: black; extra == "format"
Requires-Dist: isort; extra == "format"
Provides-Extra: lint
Requires-Dist: flake8; extra == "lint"
Requires-Dist: flake8-bugbear; extra == "lint"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Dynamic: license-file

# Django Sandwich Tags

**A django template tag that simplifies nested templates.**

---
[![PyPI Version](https://img.shields.io/pypi/v/django-sandwich-tag.svg)](https://pypi.python.org/pypi/django-sandwich-tag) ![Tests](https://github.com/jacobtumak/django-sandwich-tag/actions/workflows/pytest.yaml/badge.svg?tag=0.2.1) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/jacobtumak/sandwich)

Version: 0.2.1

## Overview

The `sandwich` template tag is a Django template tag that allows for easy composition of templates by wrapping a child template inside a parent template. This is particularly useful when building reusable UI components where a consistent layout needs to be enforced while allowing for dynamic content injection. It complements Django's built-in template inheritance by enabling support for nestable, reusable templates and components, rather than replacing it.

## Installation

To use the `sandwich` template tag in your Django project, install the package and add it to your Django app's template tag modules.

1. Install the `sandwich` package from PyPI
    ```bash
    $ pip install django-sandwich-tag
    ```

2. Add `'sandwich_tag'` to `INSTALLED_APPS`:
    ```python
    INSTALLED_APPS = [
        ...,
        "sandwich_tag",
           ...,
    ]
    ```
3. Load the template tag in your Django template:

```django
{% load sandwich %}
```

## Usage

### Basic Example

The `sandwich` template tag is used to wrap a block of content inside a parent template. The child content will be injected into the parent template at the placeholder `{{ sandwich_fixings }}`.

#### Example Parent Template (`card_component.html`):

```html
<div class="card">
    <div class="card-header">
        <h2>{{ title }}</h2>
    </div>
    <div class="card-body">
        {{ sandwich_fixings }}
    </div>
</div>
```

#### Example Usage in Another Template:

```django
{% sandwich "card_component.html" title="Welcome" %}
    <p>This content will be wrapped inside a card component.</p>
{% endsandwich %}
```

### Passing Additional Context

Additional key-value pairs can be passed to the `sandwich` tag, which will be available in the parent template:

```django
{% sandwich "card_component.html" title="User Info" theme="dark" %}
    <p>This content inherits the "theme" variable.</p>
{% endsandwich %}
```

### Using a Template Object Instead of a String

You can also pass a `Template` object instead of a template filename:

```django
{% sandwich some_template_object title="Dynamic Title" %}
    <p>Using a template object dynamically.</p>
{% endsandwich %}
```

## How It Works

1. The `sandwich` tag takes a required `template` argument, which specifies the parent template.
2. The child block content is rendered separately and passed as `sandwich_fixings`.
3. The parent template is rendered with any additional key-value arguments provided.

## Complements Django's Template Inheritance

Django's template inheritance system is great for structuring large applications, but it lacks a built-in way to create deeply nestable, reusable templates or UI components. `sandwich` fills this gap by allowing content blocks to be dynamically wrapped in different parent templates while maintaining flexibility in context passing. This makes it an excellent tool for building modular front-end structures in Django applications.

## Error Handling

- If the `template` argument is missing, a `TemplateSyntaxError` is raised.
- If `template` is provided both as a positional and keyword argument, an error is raised.
- If `template` is not a string or a `Template` object, an error is raised.

Enjoy building templates with `sandwich`! 🥪

---

## License

This package is released under the MIT License.

   
## Get Me Some of That
* [Source Code](https://github.com/jacobtumak/django-sandwich-tag)

* [Issues](https://github.com/jacobtumak/django-sandwich-tag/issues)
* [PyPI](https://pypi.org/project/django-sandwich-tag)

[MIT License](https://github.com/jacobtumak/django-sandwich-tag/blob/master/LICENSE)


### Acknowledgments
This project would be impossible to maintain without the help of our generous [contributors](https://github.com/jacobtumak/django-sandwich-tag/graphs/contributors)

#### Technology Colophon

Without django and the django dev team, the universe would have fewer rainbows and ponies.

This package was originally created with [`cookiecutter`](https://www.cookiecutter.io/) 
and the [`cookiecutter-powder-pypackage`](https://github.com/JacobTumak/CookiePowder) project template.


## For Developers
Initialise the development environment using the invoke task
   ```bash
   inv tox.venv
   ```
Or create it with tox directly
   ```bash
   tox d -e dev .venv
   ```

### Tests
   ```bash
   pytest
   ```
or
   ```bash
   tox r
   ```
or run tox environments in parallel using
   ```bash
   tox p
   ```

### Code Style / Linting
   ```bash
   $ isort
   $ black
   $ flake8
   ```

### Versioning
 * [Semantic Versioning](https://semver.org/)
   ```bash
   $ bumpver show
   ```

 * [GitHub Actions](https://docs.github.com/en/actions) (see [.github/workflows](https://github.com/jacobtumak/django-sandwich-tag/tree/master/.github/workflows))
