Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A template tag constructor library for Django.
Python
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
docs
tagcon
LICENSE
MANIFEST.in
README.rst
setup.py

README.rst

django-tagcon

Django-Tagcon is a template tag constructor library for Django. It supports a range of features to make writing template tags easier:

  • Syntax modeled on Django's friendly syntaxes for models and forms
  • Standardized argument handling -- never write tag boilerplate again!
  • Positional and optional arguments
  • Required arguments and argument defaults
  • Comma-separated sequence arguments (e.g., 1, 2, 3)
  • Flag arguments (that take no value)
  • Argument validation support (clean methods similar to forms)
  • Automatic tag naming based on the class name (with optional override)
  • Automatic tag registration with the module's register Library
  • Easy resolution of context variable arguments, including filters
  • Support for yielding strings from the render method

Installation

Just drop tagcon.py somewhere on Python's module path.

Please note that this library is developed against Django's Subversion trunk, as that's what The Onion's internal Django branch is based upon; it should work in the latest formal release of Django, though, and the author considers it a bug if it doesn't.

Example

A simple example with a single optional argument:

from django.contrib.auth.models import User
from django.template import Library
import tagcon

register = Library()

class UserListTag(tagcon.TemplateTag):
    limit = tagcon.IntegerArg(default=10)

    def render(self, context):
        self.resolve(context)
        yield "<ul>"
        for user in User.objects.all()[:self.args.limit]:
            yield "<li>%s</li>" % (user.username,)
        yield "</ul>"

And then, in a template (after loading the library):

{% user_list %}

or:

{% user_list limit 20 %}

History

The idea for a new, less painfully verbose and more consistent template tag syntax for Django came up a few years ago at the Lawrence Journal-World, where the author first implemented what he then called "newtags". Newtags was a modification of the template-handling code in LJW's internal Django branch; the syntax was modeled somewhat after Django's model syntax, as this seemed like a natural fit. As this was the Dark Age around Django 0.91, the implementation was eventually abandoned and became impossibly out of sync with upstream Django.

A few years later the author found himself at The Onion, helping to expand and manage a Django-based library that included an increasing number of template tags. He decided to again write a library for easier template tag construction -- but this time based upon modern Django, and implemented as a separate library.

To-Do

Lots, including documentation and proper tests. (We are using this code in production at The Onion, though, for what that's worth.) Unlike most other tools that I've worked on over time and never released for want of polishing, I figured it was better to just push it out first and polish later.

In particular, I'm not entirely comfortable with the underscore syntax to denote positional arguments; I'm open to better ideas there.

Contact

Something went wrong with that request. Please try again.