| Name | django-navtag JSON |
| Version |
3.3.1
JSON |
| download |
| home_page | None |
| Summary | A simple Django navigation template tag |
| upload_time | 2025-07-23 01:11:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
django
templates
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
``{% nav %}`` tag
=================
.. image:: https://badge.fury.io/py/django-navtag.svg
:target: https://badge.fury.io/py/django-navtag
.. image:: https://codecov.io/gh/SmileyChris/django-navtag/branch/master/graph/badge.svg
:target: https://codecov.io/gh/SmileyChris/django-navtag
A simple Django template tag to handle navigation item selection.
.. contents::
:local:
:backlinks: none
Installation
------------
Install the package using pip:
.. code:: bash
pip install django-navtag
Usage
-----
Add the app to your ``INSTALLED_APPS`` setting:
.. code:: python
INSTALLED_APPS = (
# ...
'django_navtag',
)
Give your base template a navigation block something like this:
.. code:: jinja
{% load navtag %}
{% block nav %}
{% nav text ' class="selected"' %}
<ul class="nav">
<li{{ nav.home }}><a href="/">Home</a></li>
<li{{ nav.about }}><a href="/about/">About</a></li>
</ul>
{% endblock %}
In your templates, extend the base and set the navigation location:
.. code:: jinja
{% extends "base.html" %}
{% block nav %}
{% nav "home" %}
{{ block.super }}
{% endblock %}
.. note::
This works for multiple levels of template inheritance, due to the fact
that only the first ``{% nav %}`` call found will change the ``nav``
context variable.
Hierarchical navigation
-----------------------
To create a sub-menu you can check against, simply dot-separate the item:
.. code:: jinja
{% nav "about_menu.info" %}
This will be pass for both ``{% if nav.about_menu %}`` and
``{% if nav.about_menu.info %}``.
Using a different context variable
----------------------------------
By default, this tag creates a ``nav`` context variable. To use an alternate
context variable name, call ``{% nav [item] for [var_name] %}``:
.. code:: jinja
{% block nav %}
{% nav "home" for sidenav %}
{{ block.super }}
{% endblock %}
Setting the text output by the nav variable
-------------------------------------------
As shown in the initial example, you can set the text return value of the
``nav`` context variable. Use the format ``{% nav text [content] %}``. For
example:
.. code:: jinja
{% nav text "active" %}
<ul>
<li class="{{ nav.home }}">Home</li>
<li class="{{ nav.contact }}">Contact</li>
</ul>
Alternately, you can use boolean comparison of the context variable rather than
text value:
.. code:: jinja
<section{% if nav.home %} class="wide"{% endif %}>
If using a different context variable name, use the format
``{% nav text [content] for [var_name] %}``.
Comparison operations
---------------------
The ``nav`` object supports comparison operations for more flexible navigation handling:
**Exact matching with** ``==``:
.. code:: jinja
{% nav "products.phones" %}
{% if nav == "products.phones" %}
{# True - exact match #}
{% endif %}
{% if nav == "products" %}
{# False - not exact #}
{% endif %}
**Special patterns with** ``!``:
.. code:: jinja
{% nav "products.electronics" %}
{% if nav == "products!" %}
{# True - matches any child of products #}
{% endif %}
{% if nav == "products!clearance" %}
{# True - matches children except 'clearance' #}
{% endif %}
**Component checking with** ``in``:
.. code:: jinja
{% nav "products.electronics.phones" %}
{% if "products" in nav %}
{# True - component exists #}
{% endif %}
{% if "electronics" in nav %}
{# True - component exists #}
{% endif %}
{% if "tablets" in nav %}
{# False - component doesn't exist #}
{% endif %}
These operations also work with sub-navigation:
.. code:: jinja
{% nav "products.electronics.phones" %}
{% if nav.products == "electronics.phones" %}
{# True #}
{% endif %}
{% if "electronics" in nav.products %}
{# True #}
{% endif %}
Iteration
---------
The ``nav`` object supports iteration over its active path components:
.. code:: jinja
{% nav "products.electronics.phones" %}
{% for component in nav %}
{{ component }}
{# Outputs: products, electronics, phones #}
{% endfor %}
This also works with sub-navigation:
.. code:: jinja
{% nav "products.electronics.phones" %}
{% for component in nav.products %}
{{ component }}
{# Outputs: electronics, phones #}
{% endfor %}
The ``{% navlink %}`` tag
-------------------------
The ``{% navlink %}`` tag provides a convenient way to create navigation links that automatically change based on the active navigation state. It works as a block tag that renders different HTML elements depending on whether the navigation item is active.
Basic usage:
.. code:: jinja
{% load navtag %}
{% nav text 'active' %}
{% nav "products" %}
<ul class="nav">
{% navlink 'home' 'home_url' %}Home{% endnavlink %}
{% navlink 'products' 'product_list' %}Products{% endnavlink %}
{% navlink 'contact' 'contact_url' %}Contact{% endnavlink %}
</ul>
The tag will render:
- ``<a href="..." class="active">...</a>`` - when the nav item is active
- ``<a href="...">...</a>`` - when the nav item is a parent of the active item
- ``<span>...</span>`` - when the nav item is not active
The second parameter uses Django's built-in ``{% url %}`` tag syntax, so you can pass URL names with arguments:
.. code:: jinja
{% navlink 'product' 'product_detail' product_id=product.id %}
{{ product.name }}
{% endnavlink %}
Custom attributes
~~~~~~~~~~~~~~~~~
You can customize the attribute added to active links using ``{% nav text %}`` with an attribute format:
.. code:: jinja
{% nav text ' aria-selected="true"' %}
{% nav "home" %}
{% navlink 'home' 'home_url' %}Home{% endnavlink %}
{# Renders: <a href="/" aria-selected="true">Home</a> #}
Special matching patterns
~~~~~~~~~~~~~~~~~~~~~~~~~
The ``{% navlink %}`` tag supports special patterns for more precise matching:
**Children-only pattern** (``item!``):
.. code:: jinja
{% nav "courses.special" %}
{% navlink 'courses' 'course_list' %}All Courses{% endnavlink %}
{# Renders as link with class="active" #}
{% navlink 'courses!' 'course_detail' %}Course Details{% endnavlink %}
{# Renders as link with class="active" - only when nav is a child of courses #}
When ``courses`` is active (not a child), the first link is active but the second becomes a ``<span>``.
**Exclusion pattern** (``item!exclude``):
.. code:: jinja
{% nav "courses.special" %}
{% navlink 'courses!list' 'course_detail' %}Course (not list){% endnavlink %}
{# Renders as link - active for any child except 'list' #}
{% navlink 'courses!special' 'course_detail' %}Course (not special){% endnavlink %}
{# Renders as span - 'special' is excluded #}
You can also use these patterns with ``{% if %}`` statements:
.. code:: jinja
{% if nav == "courses!" %}
{# True - matches any child of courses #}
{% endif %}
Alternate nav context
~~~~~~~~~~~~~~~~~~~~~
To use a different navigation context variable, prefix the nav item with the variable name:
.. code:: jinja
{% nav "products" for mainnav %}
{% nav "settings" for sidenav %}
{% navlink 'mainnav:products' 'product_list' %}Products{% endnavlink %}
{% navlink 'sidenav:settings' 'user_settings' %}Settings{% endnavlink %}
Raw data
{
"_id": null,
"home_page": null,
"name": "django-navtag",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "django, templates",
"author": null,
"author_email": "Chris Beaven <smileychris@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/21/e4/7b3e28d0502ceae70f60581b931eb47409e45b9874b5b0a736246c37e56b/django_navtag-3.3.1.tar.gz",
"platform": null,
"description": "``{% nav %}`` tag\n=================\n\n.. image:: https://badge.fury.io/py/django-navtag.svg\n :target: https://badge.fury.io/py/django-navtag\n\n.. image:: https://codecov.io/gh/SmileyChris/django-navtag/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/SmileyChris/django-navtag\n\n\nA simple Django template tag to handle navigation item selection.\n\n.. contents::\n :local:\n :backlinks: none\n\n\nInstallation\n------------\n\nInstall the package using pip:\n\n.. code:: bash\n\n pip install django-navtag\n\nUsage\n-----\n\nAdd the app to your ``INSTALLED_APPS`` setting:\n\n.. code:: python\n\n INSTALLED_APPS = (\n # ...\n 'django_navtag',\n )\n\nGive your base template a navigation block something like this:\n\n.. code:: jinja\n\n {% load navtag %}\n\n {% block nav %}\n {% nav text ' class=\"selected\"' %}\n <ul class=\"nav\">\n <li{{ nav.home }}><a href=\"/\">Home</a></li>\n <li{{ nav.about }}><a href=\"/about/\">About</a></li>\n </ul>\n {% endblock %}\n\nIn your templates, extend the base and set the navigation location:\n\n.. code:: jinja\n\n {% extends \"base.html\" %}\n\n {% block nav %}\n {% nav \"home\" %}\n {{ block.super }}\n {% endblock %}\n\n.. note::\n This works for multiple levels of template inheritance, due to the fact\n that only the first ``{% nav %}`` call found will change the ``nav``\n context variable.\n\n\nHierarchical navigation\n-----------------------\n\nTo create a sub-menu you can check against, simply dot-separate the item:\n\n.. code:: jinja\n\n {% nav \"about_menu.info\" %}\n\nThis will be pass for both ``{% if nav.about_menu %}`` and\n``{% if nav.about_menu.info %}``.\n\n\nUsing a different context variable\n----------------------------------\n\nBy default, this tag creates a ``nav`` context variable. To use an alternate\ncontext variable name, call ``{% nav [item] for [var_name] %}``:\n\n.. code:: jinja\n\n {% block nav %}\n {% nav \"home\" for sidenav %}\n {{ block.super }}\n {% endblock %}\n\n\nSetting the text output by the nav variable\n-------------------------------------------\n\nAs shown in the initial example, you can set the text return value of the\n``nav`` context variable. Use the format ``{% nav text [content] %}``. For\nexample:\n\n.. code:: jinja\n\n {% nav text \"active\" %}\n <ul>\n <li class=\"{{ nav.home }}\">Home</li>\n <li class=\"{{ nav.contact }}\">Contact</li>\n </ul>\n\nAlternately, you can use boolean comparison of the context variable rather than\ntext value:\n\n.. code:: jinja\n\n <section{% if nav.home %} class=\"wide\"{% endif %}>\n\nIf using a different context variable name, use the format\n``{% nav text [content] for [var_name] %}``.\n\n\nComparison operations\n---------------------\n\nThe ``nav`` object supports comparison operations for more flexible navigation handling:\n\n**Exact matching with** ``==``:\n\n.. code:: jinja\n\n {% nav \"products.phones\" %}\n \n {% if nav == \"products.phones\" %}\n {# True - exact match #}\n {% endif %}\n \n {% if nav == \"products\" %}\n {# False - not exact #}\n {% endif %}\n\n**Special patterns with** ``!``:\n\n.. code:: jinja\n\n {% nav \"products.electronics\" %}\n \n {% if nav == \"products!\" %}\n {# True - matches any child of products #}\n {% endif %}\n \n {% if nav == \"products!clearance\" %}\n {# True - matches children except 'clearance' #}\n {% endif %}\n\n**Component checking with** ``in``:\n\n.. code:: jinja\n\n {% nav \"products.electronics.phones\" %}\n \n {% if \"products\" in nav %}\n {# True - component exists #}\n {% endif %}\n \n {% if \"electronics\" in nav %}\n {# True - component exists #}\n {% endif %}\n \n {% if \"tablets\" in nav %}\n {# False - component doesn't exist #}\n {% endif %}\n\nThese operations also work with sub-navigation:\n\n.. code:: jinja\n\n {% nav \"products.electronics.phones\" %}\n \n {% if nav.products == \"electronics.phones\" %}\n {# True #}\n {% endif %}\n \n {% if \"electronics\" in nav.products %}\n {# True #}\n {% endif %}\n\n\nIteration\n---------\n\nThe ``nav`` object supports iteration over its active path components:\n\n.. code:: jinja\n\n {% nav \"products.electronics.phones\" %}\n \n {% for component in nav %}\n {{ component }}\n {# Outputs: products, electronics, phones #}\n {% endfor %}\n\nThis also works with sub-navigation:\n\n.. code:: jinja\n\n {% nav \"products.electronics.phones\" %}\n \n {% for component in nav.products %}\n {{ component }}\n {# Outputs: electronics, phones #}\n {% endfor %}\n\n\nThe ``{% navlink %}`` tag\n-------------------------\n\nThe ``{% navlink %}`` tag provides a convenient way to create navigation links that automatically change based on the active navigation state. It works as a block tag that renders different HTML elements depending on whether the navigation item is active.\n\nBasic usage:\n\n.. code:: jinja\n\n {% load navtag %}\n \n {% nav text 'active' %}\n {% nav \"products\" %}\n \n <ul class=\"nav\">\n {% navlink 'home' 'home_url' %}Home{% endnavlink %}\n {% navlink 'products' 'product_list' %}Products{% endnavlink %}\n {% navlink 'contact' 'contact_url' %}Contact{% endnavlink %}\n </ul>\n\nThe tag will render:\n\n- ``<a href=\"...\" class=\"active\">...</a>`` - when the nav item is active\n- ``<a href=\"...\">...</a>`` - when the nav item is a parent of the active item\n- ``<span>...</span>`` - when the nav item is not active\n\nThe second parameter uses Django's built-in ``{% url %}`` tag syntax, so you can pass URL names with arguments:\n\n.. code:: jinja\n\n {% navlink 'product' 'product_detail' product_id=product.id %}\n {{ product.name }}\n {% endnavlink %}\n\nCustom attributes\n~~~~~~~~~~~~~~~~~\n\nYou can customize the attribute added to active links using ``{% nav text %}`` with an attribute format:\n\n.. code:: jinja\n\n {% nav text ' aria-selected=\"true\"' %}\n {% nav \"home\" %}\n \n {% navlink 'home' 'home_url' %}Home{% endnavlink %}\n {# Renders: <a href=\"/\" aria-selected=\"true\">Home</a> #}\n\nSpecial matching patterns\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``{% navlink %}`` tag supports special patterns for more precise matching:\n\n**Children-only pattern** (``item!``):\n\n.. code:: jinja\n\n {% nav \"courses.special\" %}\n \n {% navlink 'courses' 'course_list' %}All Courses{% endnavlink %}\n {# Renders as link with class=\"active\" #}\n \n {% navlink 'courses!' 'course_detail' %}Course Details{% endnavlink %}\n {# Renders as link with class=\"active\" - only when nav is a child of courses #}\n\nWhen ``courses`` is active (not a child), the first link is active but the second becomes a ``<span>``.\n\n**Exclusion pattern** (``item!exclude``):\n\n.. code:: jinja\n\n {% nav \"courses.special\" %}\n \n {% navlink 'courses!list' 'course_detail' %}Course (not list){% endnavlink %}\n {# Renders as link - active for any child except 'list' #}\n \n {% navlink 'courses!special' 'course_detail' %}Course (not special){% endnavlink %}\n {# Renders as span - 'special' is excluded #}\n\nYou can also use these patterns with ``{% if %}`` statements:\n\n.. code:: jinja\n\n {% if nav == \"courses!\" %}\n {# True - matches any child of courses #}\n {% endif %}\n\nAlternate nav context\n~~~~~~~~~~~~~~~~~~~~~\n\nTo use a different navigation context variable, prefix the nav item with the variable name:\n\n.. code:: jinja\n\n {% nav \"products\" for mainnav %}\n {% nav \"settings\" for sidenav %}\n \n {% navlink 'mainnav:products' 'product_list' %}Products{% endnavlink %}\n {% navlink 'sidenav:settings' 'user_settings' %}Settings{% endnavlink %}\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple Django navigation template tag",
"version": "3.3.1",
"project_urls": {
"Homepage": "https://github.com/SmileyChris/django-navtag"
},
"split_keywords": [
"django",
" templates"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3fc4b0247979cc1ce9732096ee04300c5b05d392eafe5d511b1c46d5f524ea47",
"md5": "34b82c3fae40be281a6b88058d00778f",
"sha256": "36a2901658f035f013cfa65b49e925f7dec346dafafaa84a3999b206e106bac4"
},
"downloads": -1,
"filename": "django_navtag-3.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34b82c3fae40be281a6b88058d00778f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8814,
"upload_time": "2025-07-23T01:11:01",
"upload_time_iso_8601": "2025-07-23T01:11:01.515898Z",
"url": "https://files.pythonhosted.org/packages/3f/c4/b0247979cc1ce9732096ee04300c5b05d392eafe5d511b1c46d5f524ea47/django_navtag-3.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "21e47b3e28d0502ceae70f60581b931eb47409e45b9874b5b0a736246c37e56b",
"md5": "71b26f11e70cfc1e7d71e655073412b5",
"sha256": "33099889d5b7df29c6028901226df1e8631f31567df94355fcd472b6af891462"
},
"downloads": -1,
"filename": "django_navtag-3.3.1.tar.gz",
"has_sig": false,
"md5_digest": "71b26f11e70cfc1e7d71e655073412b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10056,
"upload_time": "2025-07-23T01:11:02",
"upload_time_iso_8601": "2025-07-23T01:11:02.917468Z",
"url": "https://files.pythonhosted.org/packages/21/e4/7b3e28d0502ceae70f60581b931eb47409e45b9874b5b0a736246c37e56b/django_navtag-3.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 01:11:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SmileyChris",
"github_project": "django-navtag",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django-navtag"
}
