{"id":13725002,"url":"https://github.com/carltongibson/django-template-partials","last_synced_at":"2025-05-14T12:11:07.349Z","repository":{"id":174141622,"uuid":"642059763","full_name":"carltongibson/django-template-partials","owner":"carltongibson","description":"Reusable named inline partials for the Django Template Language.","archived":false,"fork":false,"pushed_at":"2025-03-23T06:18:03.000Z","size":59,"stargazers_count":544,"open_issues_count":13,"forks_count":29,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-01T15:46:26.769Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carltongibson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-17T18:22:35.000Z","updated_at":"2025-04-01T11:38:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"97bb60e9-1680-4074-ba0b-9ecd4600855d","html_url":"https://github.com/carltongibson/django-template-partials","commit_stats":null,"previous_names":["carltongibson/django-template-partials"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carltongibson%2Fdjango-template-partials","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carltongibson%2Fdjango-template-partials/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carltongibson%2Fdjango-template-partials/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carltongibson%2Fdjango-template-partials/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carltongibson","download_url":"https://codeload.github.com/carltongibson/django-template-partials/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154987,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:09.527Z","updated_at":"2025-04-10T03:45:35.862Z","avatar_url":"https://github.com/carltongibson.png","language":"Python","funding_links":[],"categories":["Python","Third Party Packages 📦 \u003ca name = \"tools\"\u003e\u003c/a\u003e","Django"],"sub_categories":["Helper Libraries","Phaser"],"readme":"# django-template-partials\n\n[![pypi](https://img.shields.io/pypi/v/django-template-partials.svg)](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. 🍿\n\n[![DjangoCon Europe 2023 | Yak-shaving to Where the Puck is Going to Be.](https://img.youtube.com/vi/_3oGI4RC52s/0.jpg)](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 \u003ca href=\"#advanced-configuration\"\u003eAdvanced configuration (below)\u003c/a\u003e 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 `{% endpartialdef %}` 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…\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 %}\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 — say a pagination widget — 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…\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! 🚀\n\n\n\u003ch2 id=\"advanced-configuration\"\u003eAdvanced configuration\u003c/h2\u003e\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…\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… 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarltongibson%2Fdjango-template-partials","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarltongibson%2Fdjango-template-partials","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarltongibson%2Fdjango-template-partials/lists"}