{"id":17086054,"url":"https://github.com/smileychris/django-navtag","last_synced_at":"2026-04-03T10:39:34.280Z","repository":{"id":57421001,"uuid":"11489112","full_name":"SmileyChris/django-navtag","owner":"SmileyChris","description":"Keep that navigation logic in the presentation layer where it belongs.","archived":false,"fork":false,"pushed_at":"2021-04-11T22:32:09.000Z","size":41,"stargazers_count":33,"open_issues_count":0,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-12T21:07:15.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.python.org/pypi/django-navtag","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/SmileyChris.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-17T22:25:45.000Z","updated_at":"2024-11-03T06:46:59.000Z","dependencies_parsed_at":"2022-09-04T02:20:24.886Z","dependency_job_id":null,"html_url":"https://github.com/SmileyChris/django-navtag","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-navtag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-navtag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-navtag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmileyChris%2Fdjango-navtag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmileyChris","download_url":"https://codeload.github.com/SmileyChris/django-navtag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631677,"owners_count":21136562,"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-10-14T13:26:59.060Z","updated_at":"2026-04-03T10:39:34.264Z","avatar_url":"https://github.com/SmileyChris.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"``{% 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    \u003cul class=\"nav\"\u003e\n        \u003cli{{ nav.home }}\u003e\u003ca href=\"/\"\u003eHome\u003c/a\u003e\u003c/li\u003e\n        \u003cli{{ nav.about }}\u003e\u003ca href=\"/about/\"\u003eAbout\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\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    \u003cul\u003e\n    \u003cli class=\"{{ nav.home }}\"\u003eHome\u003c/li\u003e\n    \u003cli class=\"{{ nav.contact }}\"\u003eContact\u003c/li\u003e\n    \u003c/ul\u003e\n\nAlternately, you can use boolean comparison of the context variable rather than\ntext value:\n\n.. code:: jinja\n\n    \u003csection{% if nav.home %} class=\"wide\"{% endif %}\u003e\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    \u003cul class=\"nav\"\u003e\n        {% navlink 'home' 'home_url' %}Home{% endnavlink %}\n        {% navlink 'products' 'product_list' %}Products{% endnavlink %}\n        {% navlink 'contact' 'contact_url' %}Contact{% endnavlink %}\n    \u003c/ul\u003e\n\nThe tag will render:\n\n- ``\u003ca href=\"...\" class=\"active\"\u003e...\u003c/a\u003e`` - when the nav item is active\n- ``\u003ca href=\"...\"\u003e...\u003c/a\u003e`` - when the nav item is a parent of the active item\n- ``\u003cspan\u003e...\u003c/span\u003e`` - 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: \u003ca href=\"/\" aria-selected=\"true\"\u003eHome\u003c/a\u003e #}\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 ``\u003cspan\u003e``.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmileychris%2Fdjango-navtag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmileychris%2Fdjango-navtag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmileychris%2Fdjango-navtag/lists"}