| Name | django-template-partials JSON |
| Version |
24.4
JSON |
| download |
| home_page | None |
| Summary | django-template-partials |
| upload_time | 2024-08-16 10:51:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# django-template-partials
[](https://pypi.org/project/django-template-partials/)
Reusable named inline partials for the Django Template Language.
## Watch the talk
I introduced `django-template-partials` in my DjangoCon Europe 2023 talk in Edinburgh.
For a quick introduction, you can watch the video on YouTube. 🍿
[](https://www.youtube.com/watch?v=_3oGI4RC52s)
## Installation
Install with pip:
```bash
pip install django-template-partials
```
Then add to `INSTALLED_APPS` and you're good go.
```python
INSTALLED_APPS = [
"template_partials",
...,
]
```
See <a href="#advanced-configuration">Advanced configuration (below)</a> for
more options.
Please see the [CHANGELOG](https://github.com/carltongibson/django-template-partials/blob/main/CHANGELOG.md) if you are upgrading from a previous version.
## Basic Usage
Once installed, load the `partials` tags and define a re-usable partial at the top of your template:
```html
{% load partials %}
{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef %}
```
For extra readability, you can optionally add the name to your `{% endblock %}` tag. For
example:
```html
{% load partials %}
{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef test-partial %}
```
### Fragment Re-use
With the partial defined, you can reuse it multiple times later:
```
{% block main %}
BEGINNING
{% partial test-partial %}
MIDDLE
{% partial test-partial %}
END
{% endblock main %}
```
The partial content will be rendered in each time the named partial is used.
### Via the template loader
`django-template-partials` is also integrated with the template loader, so you
can pass a template plus a partial name to the loader to have just that part
rendered:
```python
# In view handler…
self.template_name = "example.html#test-partial"
```
The rest of your view logic remains the same.
This means that you can also use the partial with the `include` tag:
```html+django
{% include "example.html#test-partial" %}
```
### Outputting inline
You might want to wrap an existing part of your page, and continue rendering
the content inside your partial, use the `inline` argument in that situation:
```html
{% block main %}
{% partialdef inline-partial inline=True %}
CONTENT
{% endpartialdef %}
{% endblock main %}
```
### Controlling the context
A template partial is rendered with the current context.
This means it works in, for example, a loop as expected:
```html+django
{% for object in object_list %}
{% partial test-partial %}
{% endfor %}
```
If you need to adjust the context, use the `with` tag as normal:
```html+django
{% with name=value othername=othervalue %}
{% partial test-partial %}
{% endwith %}
```
#### Capturing output
Rendering a partial — say a pagination widget — may be computationally expensive.
It's out-of-scope for `django-template-partials` to capture the generated HTML
to the context, but other options exist, such as the [Slipper's library
fragment tag](https://mitchel.me/slippers/docs/template-tags-filters/#fragment),
that allows exactly this behaviour.
### Adding partials to template builtins.
Maybe you don't want to load the partials tags in every template…
```html+django
{% load partials %}
```
The [Django Template Language's OPTIONS](https://docs.djangoproject.com/en/4.2/topics/templates/#django.template.backends.django.DjangoTemplates)
allow you to add to the `builtins` that are loaded for every template. You can
add the partials tags there:
```
OPTIONS = {
"builtins": ["template_partials.templatetags.partials"],
}
```
That's the basics. Enjoy! 🚀
<h2 id="advanced-configuration">Advanced configuration</h2>
By default, adding `"template_partials"` to your `INSTALLED_APPS` will
configure any Django template backend to use the partials template loader.
If you need to control this behaviour, you can use an alternative
`SimpleAppConfig`, which **will not** adjust your `TEMPLATES` setting:
```python
INSTALLED_APPS = [
"template_partials.apps.SimpleAppConfig",
...,
]
```
If you use `SimpleAppConfig`, you will need to configure the template loader yourself.
A `wrap_loaders()` function is available, and can be used to configure any
specific template engine instance with the template partials loader.
You can use the backend's [`NAME`](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-TEMPLATES-NAME)
to `wrap_loaders()` to add the partial loader just for that backend:
```python
from template_partials.apps import wrap_loaders
TEMPLATES = [
...,
{
"BACKEND": "...",
"NAME": "myname",
"OPTIONS": {
...,
},
},
...,
]
wrap_loaders("myname")
```
If the `NAME` isn't provided, the penultimate element of the `BACKEND` value is
used - for example, `"django.template.backends.django.DjangoTemplates"` would
be equivalent to a `NAME` of `"django"`.
Under the hood, `wrap_loaders()` is equivalent to explicitly defining the
`loaders` by-hand. Assuming defaults…
```python
from django.conf import settings
default_loaders = [
"django.template.loaders.filesystem.Loader",
"django.template.loaders.app_directories.Loader",
]
cached_loaders = [("django.template.loaders.cached.Loader", default_loaders)]
partial_loaders = [("template_partials.loader.Loader", cached_loaders)]
settings.TEMPLATES[...]['OPTIONS']['loaders'] = partial_loaders
```
… where `TEMPLATES[...]` is the entry in `TEMPLATES` with the `NAME` matching
that passed to `wrap_loaders()`.
## Running the tests
Fork, then clone the repo:
```sh
git clone git@github.com:your-username/django-template-partials.git
```
Set up a venv:
```sh
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .[tests]
```
Then you can run the tests with the `just` command runner:
```sh
just test
```
Or with coverage:
```sh
just coverage
```
If you don't have `just` installed, you can look in the `justfile` for a
commands that are run.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-template-partials",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Carlton Gibson <carlton.gibson@noumenal.es>",
"download_url": "https://files.pythonhosted.org/packages/1c/ff/2a7ddae12ca8e5fea1a41af05924c04f1bb4aec7157b04a88b829dd93d4a/django_template_partials-24.4.tar.gz",
"platform": null,
"description": "# django-template-partials\n\n[](https://pypi.org/project/django-template-partials/)\n\nReusable named inline partials for the Django Template Language.\n\n## Watch the talk\n\nI introduced `django-template-partials` in my DjangoCon Europe 2023 talk in Edinburgh.\n\nFor a quick introduction, you can watch the video on YouTube. \ud83c\udf7f\n\n[](https://www.youtube.com/watch?v=_3oGI4RC52s)\n\n## Installation\n\nInstall with pip:\n\n```bash\npip install django-template-partials\n```\n\nThen add to `INSTALLED_APPS` and you're good go.\n\n```python\nINSTALLED_APPS = [\n \"template_partials\",\n ...,\n]\n```\n\nSee <a href=\"#advanced-configuration\">Advanced configuration (below)</a> for\nmore options.\n\nPlease see the [CHANGELOG](https://github.com/carltongibson/django-template-partials/blob/main/CHANGELOG.md) if you are upgrading from a previous version.\n\n## Basic Usage\n\nOnce installed, load the `partials` tags and define a re-usable partial at the top of your template:\n\n```html\n{% load partials %}\n\n{% partialdef test-partial %}\nTEST-PARTIAL-CONTENT\n{% endpartialdef %}\n```\n\nFor extra readability, you can optionally add the name to your `{% endblock %}` tag. For\nexample:\n\n```html\n{% load partials %}\n\n{% partialdef test-partial %}\nTEST-PARTIAL-CONTENT\n{% endpartialdef test-partial %}\n```\n\n### Fragment Re-use\n\nWith the partial defined, you can reuse it multiple times later:\n\n```\n{% block main %}\nBEGINNING\n{% partial test-partial %}\nMIDDLE\n{% partial test-partial %}\nEND\n{% endblock main %}\n```\n\nThe partial content will be rendered in each time the named partial is used.\n\n\n### Via the template loader\n\n`django-template-partials` is also integrated with the template loader, so you\ncan pass a template plus a partial name to the loader to have just that part\nrendered:\n\n```python\n# In view handler\u2026\nself.template_name = \"example.html#test-partial\"\n```\n\nThe rest of your view logic remains the same.\n\nThis means that you can also use the partial with the `include` tag:\n\n```html+django\n{% include \"example.html#test-partial\" %}\n```\n\n### Outputting inline\n\nYou might want to wrap an existing part of your page, and continue rendering\nthe content inside your partial, use the `inline` argument in that situation:\n\n```html\n{% block main %}\n{% partialdef inline-partial inline=True %}\nCONTENT\n{% endpartialdef %}\n{% endblock main %}\n```\n\n### Controlling the context\n\nA template partial is rendered with the current context.\n\nThis means it works in, for example, a loop as expected:\n\n```html+django\n{% for object in object_list %}\n {% partial test-partial %}\n{% endfor %}\n```\n\nIf you need to adjust the context, use the `with` tag as normal:\n\n```html+django\n{% with name=value othername=othervalue %}\n {% partial test-partial %}\n{% endwith %}\n```\n\n#### Capturing output\n\nRendering a partial \u2014 say a pagination widget \u2014 may be computationally expensive.\n\nIt's out-of-scope for `django-template-partials` to capture the generated HTML\nto the context, but other options exist, such as the [Slipper's library\nfragment tag](https://mitchel.me/slippers/docs/template-tags-filters/#fragment),\nthat allows exactly this behaviour.\n\n\n### Adding partials to template builtins.\n\nMaybe you don't want to load the partials tags in every template\u2026\n\n```html+django\n{% load partials %}\n```\n\nThe [Django Template Language's OPTIONS](https://docs.djangoproject.com/en/4.2/topics/templates/#django.template.backends.django.DjangoTemplates)\nallow you to add to the `builtins` that are loaded for every template. You can\nadd the partials tags there:\n\n```\nOPTIONS = {\n \"builtins\": [\"template_partials.templatetags.partials\"],\n}\n```\n\n\nThat's the basics. Enjoy! \ud83d\ude80\n\n\n<h2 id=\"advanced-configuration\">Advanced configuration</h2>\n\nBy default, adding `\"template_partials\"` to your `INSTALLED_APPS` will\nconfigure any Django template backend to use the partials template loader.\n\nIf you need to control this behaviour, you can use an alternative\n`SimpleAppConfig`, which **will not** adjust your `TEMPLATES` setting:\n\n```python\nINSTALLED_APPS = [\n \"template_partials.apps.SimpleAppConfig\",\n ...,\n]\n```\n\nIf you use `SimpleAppConfig`, you will need to configure the template loader yourself.\n\nA `wrap_loaders()` function is available, and can be used to configure any\nspecific template engine instance with the template partials loader.\n\nYou can use the backend's [`NAME`](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-TEMPLATES-NAME)\nto `wrap_loaders()` to add the partial loader just for that backend:\n\n```python\nfrom template_partials.apps import wrap_loaders\n\nTEMPLATES = [\n ...,\n {\n \"BACKEND\": \"...\",\n \"NAME\": \"myname\",\n \"OPTIONS\": {\n ...,\n },\n },\n ...,\n]\n\nwrap_loaders(\"myname\")\n```\n\nIf the `NAME` isn't provided, the penultimate element of the `BACKEND` value is\nused - for example, `\"django.template.backends.django.DjangoTemplates\"` would\nbe equivalent to a `NAME` of `\"django\"`.\n\nUnder the hood, `wrap_loaders()` is equivalent to explicitly defining the\n`loaders` by-hand. Assuming defaults\u2026\n\n```python\nfrom django.conf import settings\n\ndefault_loaders = [\n \"django.template.loaders.filesystem.Loader\",\n \"django.template.loaders.app_directories.Loader\",\n]\ncached_loaders = [(\"django.template.loaders.cached.Loader\", default_loaders)]\npartial_loaders = [(\"template_partials.loader.Loader\", cached_loaders)]\n\nsettings.TEMPLATES[...]['OPTIONS']['loaders'] = partial_loaders\n```\n\n\u2026 where `TEMPLATES[...]` is the entry in `TEMPLATES` with the `NAME` matching\nthat passed to `wrap_loaders()`.\n\n\n## Running the tests\n\nFork, then clone the repo:\n\n```sh\ngit clone git@github.com:your-username/django-template-partials.git\n```\n\nSet up a venv:\n\n```sh\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e .[tests]\n```\n\nThen you can run the tests with the `just` command runner:\n\n```sh\njust test\n```\n\nOr with coverage:\n\n```sh\njust coverage\n```\n\nIf you don't have `just` installed, you can look in the `justfile` for a\ncommands that are run.\n",
"bugtrack_url": null,
"license": null,
"summary": "django-template-partials",
"version": "24.4",
"project_urls": {
"Changelog": "https://github.com/carltongibson/django-template-partials/blob/main/CHANGELOG.md",
"Docs": "https://github.com/carltongibson/django-template-partials?tab=readme-ov-file#basic-usage",
"Repository": "https://github.com/carltongibson/django-template-partials/"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3172d8eea70683b25230e0d2647b5cf6f2db4a7e7d35cb6170506d9618196374",
"md5": "7c9e04c2fa99a208c58be98aaa61a7c3",
"sha256": "ee59d3839385d7f648907c3fa8d5923fcd66cd8090f141fe2a1c338b917984e2"
},
"downloads": -1,
"filename": "django_template_partials-24.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c9e04c2fa99a208c58be98aaa61a7c3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 8439,
"upload_time": "2024-08-16T10:51:28",
"upload_time_iso_8601": "2024-08-16T10:51:28.437087Z",
"url": "https://files.pythonhosted.org/packages/31/72/d8eea70683b25230e0d2647b5cf6f2db4a7e7d35cb6170506d9618196374/django_template_partials-24.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1cff2a7ddae12ca8e5fea1a41af05924c04f1bb4aec7157b04a88b829dd93d4a",
"md5": "c52c08f4c4e165c30b5c76722729354f",
"sha256": "25b67301470fc274ecc419e5e5fd4686a5020b1c038fd241a70eb087809034b6"
},
"downloads": -1,
"filename": "django_template_partials-24.4.tar.gz",
"has_sig": false,
"md5_digest": "c52c08f4c4e165c30b5c76722729354f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14538,
"upload_time": "2024-08-16T10:51:30",
"upload_time_iso_8601": "2024-08-16T10:51:30.204835Z",
"url": "https://files.pythonhosted.org/packages/1c/ff/2a7ddae12ca8e5fea1a41af05924c04f1bb4aec7157b04a88b829dd93d4a/django_template_partials-24.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 10:51:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "carltongibson",
"github_project": "django-template-partials",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-template-partials"
}
