Support template_name as keyword argument in template tag (#219)

* Support template_name as keyword argument in template tag

The django_simple_nav template tag now accepts template_name as a
keyword argument (template_name="...") in addition to the existing
positional argument form. Both forms are supported, but documentation
has been updated to show only the keyword argument form.

https://claude.ai/code/session_01VkJgufDXZnESprP8XK9b2y

* Deduplicate template_name check in tag parser

https://claude.ai/code/session_01VkJgufDXZnESprP8XK9b2y

* Simplify template_name arg parsing

Replace loop with direct handling since there's at most one extra arg.

https://claude.ai/code/session_01VkJgufDXZnESprP8XK9b2y

* Add changelog entry for template_name kwarg support

https://claude.ai/code/session_01VkJgufDXZnESprP8XK9b2y

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Changed
+
+- The `django_simple_nav` template tag now accepts `template_name` as a keyword argument (e.g. `template_name="footer_nav.html"`). Positional usage is still supported.
+
 ## [0.15.0]
 
 ### Added

docs/reference.md

@@ -8,13 +8,13 @@ This page documents the runtime behaviors that aren't captured in the API docs.
 
 ```htmldjango
 {% load django_simple_nav %}
-{% django_simple_nav nav [template_name] %}
+{% django_simple_nav nav [template_name="..."] %}
 ```
 
 | Argument | Required | Description |
 |---|---|---|
 | `nav` | yes | A dotted import path string to a `Nav` class (e.g. `"config.nav.MainNav"`), a dotted path to a callable that accepts `request` and returns a `Nav` (e.g. `"config.nav.main_nav"`), or a `Nav` instance from the template context. See [Programmatic Navigation](usage.md#programmatic-navigation). |
-| `template_name` | no | Override the template used to render the navigation. |
+| `template_name` | no | Override the template used to render the navigation. Passed as a keyword argument: `template_name="my_template.html"`. |
 
 Expects `request` in the template context.
 

docs/usage.md

@@ -146,7 +146,7 @@ You can pass a `Nav` instance or override the template, just like the Django tem
 
 ```jinja
 {{ django_simple_nav(nav) }}
-{{ django_simple_nav("config.nav.MainNav", "footer_nav.html.j2") }}
+{{ django_simple_nav("config.nav.MainNav", template_name="footer_nav.html.j2") }}
 ```
 
 In Jinja2 navigation templates, use bracket notation to access child items — `item['items']` instead of `item.items` — because `item.items` calls the dict `.items()` method in Jinja2:
@@ -161,7 +161,7 @@ In Jinja2 navigation templates, use bracket notation to access child items — `
 
 ## Overriding the Template at Render Time
 
-To render the same navigation with a different template — say, a header and a footer with different markup — pass a second argument to the template tag:
+To render the same navigation with a different template — say, a header and a footer with different markup — pass `template_name` to the template tag:
 
 ```htmldjango
 {% load django_simple_nav %}
@@ -171,7 +171,7 @@ To render the same navigation with a different template — say, a header and a
 </header>
 
 <footer>
-  {% django_simple_nav "config.nav.MainNav" "footer_nav.html" %}
+  {% django_simple_nav "config.nav.MainNav" template_name="footer_nav.html" %}
 </footer>
 ```
 
@@ -243,7 +243,7 @@ When a `Nav` is rendered, the call chain is:
 2. **`get_template(template_name=None)`** — loads the template; override for inline templates or custom loading
 3. **`get_template_name()`** — returns the template name; override for dynamic selection
 
-If `template_name` is passed (e.g. from the template tag's second argument), it skips `get_template_name()` and uses that name directly.
+If `template_name` is passed (e.g. via `template_name="..."` in the template tag), it skips `get_template_name()` and uses that name directly.
 
 ## Passing a Nav Instance from a View
 

src/django_simple_nav/templatetags/django_simple_nav.py

@@ -15,17 +15,27 @@
 
 @register.tag(name="django_simple_nav")
 def do_django_simple_nav(parser: Parser, token: Token) -> DjangoSimpleNavNode:
-    try:
-        args = token.split_contents()[1:]
-        if len(args) == 0:
-            raise ValueError
-    except ValueError as err:
-        raise template.TemplateSyntaxError(
-            f"{token.split_contents()[0]} tag requires arguments"
-        ) from err
+    tag_name, *args = token.split_contents()
+
+    if not args:
+        raise template.TemplateSyntaxError(f"{tag_name} tag requires arguments")
 
     nav = args[0]
-    template_name = args[1] if len(args) > 1 else None
+    template_name = None
+
+    if len(args) > 2:
+        raise template.TemplateSyntaxError(f"{tag_name} received too many arguments")
+
+    if len(args) == 2:
+        arg = args[1]
+        if "=" in arg:
+            key, template_name = arg.split("=", 1)
+            if key != "template_name":
+                raise template.TemplateSyntaxError(
+                    f"Unknown argument to {tag_name}: {key}"
+                )
+        else:
+            template_name = arg
 
     return DjangoSimpleNavNode(nav, template_name)
 

tests/test_templatetags.py

@@ -37,6 +37,17 @@ def test_templatetag_with_template_name(req):
     assert "This is an alternate template." in rendered_template
 
 
+def test_templatetag_with_template_name_kwarg(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.DummyNav' template_name='tests/alternate.html' %}"
+    )
+    req.user = AnonymousUser()
+
+    rendered_template = template.render(Context({"request": req}))
+
+    assert "This is an alternate template." in rendered_template
+
+
 def test_templatetag_with_nav_instance(req):
     class PlainviewNav(DummyNav):
         items = [
@@ -72,6 +83,25 @@ class DeadParrotNav(DummyNav):
     assert "This is an alternate template." in rendered_template
 
 
+def test_templatetag_with_nav_instance_and_template_name_kwarg(req):
+    class DeadParrotNav(DummyNav):
+        items = [
+            NavItem(title="He's pinin' for the fjords!", url="/notlob/"),
+        ]
+
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav new_nav template_name='tests/alternate.html' %}"
+    )
+    req.user = baker.make(get_user_model(), first_name="Norwegian", last_name="Blue")
+
+    rendered_template = template.render(
+        Context({"request": req, "new_nav": DeadParrotNav()})
+    )
+
+    assert "He's pinin' for the fjords!" in rendered_template
+    assert "This is an alternate template." in rendered_template
+
+
 def test_templatetag_with_template_name_on_nav_instance(req):
     class PinkmanNav(DummyNav):
         template_name = "tests/alternate.html"
@@ -202,6 +232,17 @@ def test_templatetag_with_callable_and_template_name(req):
     assert "This is an alternate template." in rendered_template
 
 
+def test_templatetag_with_callable_and_template_name_kwarg(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.dynamic_nav' template_name='tests/alternate.html' %}"
+    )
+    req.user = AnonymousUser()
+
+    rendered_template = template.render(Context({"request": req}))
+
+    assert "This is an alternate template." in rendered_template
+
+
 def test_templatetag_with_bad_callable(req):
     template = Template(
         "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.bad_callable' %}"
@@ -210,3 +251,23 @@ def test_templatetag_with_bad_callable(req):
 
     with pytest.raises(TemplateSyntaxError):
         template.render(Context({"request": req}))
+
+
+def test_templatetag_with_unknown_kwarg():
+    with pytest.raises(TemplateSyntaxError, match="Unknown argument"):
+        Template(
+            "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.DummyNav' foo='bar' %}"
+        )
+
+
+def test_templatetag_with_template_name_kwarg_variable(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.DummyNav' template_name=my_template %}"
+    )
+    req.user = AnonymousUser()
+
+    rendered_template = template.render(
+        Context({"request": req, "my_template": "tests/alternate.html"})
+    )
+
+    assert "This is an alternate template." in rendered_template